Detailed Contents
1. Introduction
2. Starting DigImage
3. Basic Operation
4. Sample Session
5. Command Files
6. Movies
7. Coordinate Systems
8. Warnings, Errors and Crashes
9. Utilities
10. Macros
11. Other Considerations
12. Updates
Appendix A: Menus
Index
If the images are already available on the hard disk, it not only makes the structure of any command files much simpler, but also greatly simplifies and speeds up the debugging process. Not only is it unnecessary to wait for DigImage to acquire the images from the VTR while debugging the command file, but it also saves wear and tear on the video tape. As a result the image quality deteriorates less. Further, the processing will often be faster when processing from hard disk as the images may be accessed without the overhead of controlling the video recorder. Finally, if you are running under Windows 95, it becomes feasible for the processing to be done in the background while you are doing something else in the foreground (DigImage has to stop any other processes from executing while it is controlling the video recorder, but not for normal processing).
The main purpose of this section is to introduce the concepts and strategies behind processing sequences from DigImage movie files previously recorded on hard disk.
If we are going to process a sequence of images from the hard disk, it is clearly necessary to record the sequence on the hard disk first. One option would be to use the [;VG: Grab sequence of images] option to acquire as many images as there are free buffers and then write these images out to a sequence of files (say IMAGE.001, IMAGE.002 etc.) using [;KS Save buffer to file] or [;KW Write window to file]. If the number of images required is more than the number of buffers available, it will be necessary to loop around the acquisition until all the images have been saved. This can be a very time consuming process, especially if it is necessary to sample at relatively high sampling frequencies as in a single pass DigImage may be able to acquire only 4 or 16 images depending on which model of frame grabber card you have.
The alternative is to create a DigImage movie file. The menu providing these facilities may be found in [;KM: Movies]. An identical menu may be found under [;TM: Movies] for backward compatibility with versions of DigImage prior to 2.0.
Movies
B Create blank movie
D Details of movie
E Extract single frame from movie
I Insert single frame in movie
M Play back movie on computer monitor
P Play back movie
R Record movie - single pass
S Record movie - multi pass
f1 Specific Help shift_f1 General Help
Q Return to parent menu
->
There are two options for recording a movie: [R Record movie - single pass] and [S Record movie - multi pass]. Both can operate on the entire image, a window to it, or at a reduced spatial resolution. Sampling rates and recording periods are specified by the user. The options differ in the precise manner in which the images are obtained and, as a result, the maximum sampling frequency which may be achieved.
Under [R Record movie - single pass] DigImage will grab images from the incoming video signal and copy the specified portion of the digitised image to the hard disk. The maximum sampling rate which can be achieved depends on the size and resolution of the region to be recorded, the speed of the computer and the speed of the hard disk. Unfortunately the Data Translation cards are ISA bus cards which limits them to a bus speed of about 8MHz (we have found that they function without problem at 10MHz on some computers). For a full resolution image, this limits the sampling rate to around one image every 0.8s. If you specify a sampling rate faster than can be achieved, DigImage will simply record the images as rapidly as possible; as the actual time of sampling is recorded along with the image, it is possible to determine the precise time of sampling retrospectively.
Synchronisation for the start of acquisition with [R Record movie - single pass] may be either manual or with the computer controlling the video recorder. Manual synchronisation allows direct recording from the video camera to the hard disk when low sampling rates are all that is required. By recording directly onto hard disk in this manner it is possible to avoid the additional noise and image deterioration introduced by the video recorder. When absolute intensity information is required, it is highly desirable to avoid using the video recorder both because of the nonlinear response of video tape and the (weak) automatic gain in the video recorder's circuitry. We suggest, however, that if you are recording directly to disk you also record the camera output on video tape.
The [S Record movie - multi pass] option always requires control over the video recorder. By exercising this control, DigImage is able to acquire images for the movie using any sample spacing down to recording every frame. The recording is achieved by playing the sequence of tape and acquiring as many of the required samples as it can on the first pass. The tape is rewound and on the second and subsequent passes as many of the images to be sampled which have not already been acquired will be grabbed and written out to the hard disk.
The number of passes which will be required for [S Record movie - multi pass] depends on the resolution of the image, the speed of the computer etc. In the worst case up to around 25 passes may be required. If the sequence is relatively short and has a high sampling rate then it may be preferable to acquire it using [;VGC Grab constant spaced sequence] which can acquire either 4 or 16 images (depending on which model of the frame grabber card is used) in a single pass, regardless of the spacing. For long sequences, however, it will always be preferable to use one of the movie options.
The movie files themselves can be very large. At the start of each file there is header information totally just under 100KBytes, then each image can occupy up to 256KBytes (for full resolution). In order to optimise recording and processing speed, the images are not compressed. For this reason careful management of the contents of your hard disk may be required.
Once a movie has been recorded (or created in another manner), individual images may be extracted from the movie using [;KME Extract single frame from movie]. By providing this option with the name of the movie file, the time for which the image is to be extracted, and the buffer in which it is to be placed, individual images may be achieved at random. If only a window was recorded in the original movie, then exactly the same window will be output to the buffer. If the movie was recorded at reduced spatial resolution, then the image retrieved will be smaller than the original.
To view the contents of the movie, either [;KMM Play back movie on computer monitor] or [;KMP Play back movie] may be used. The first of these will display it on the computer's own monitor, but is only capable of displaying a full-screen movie. The second displays on the frame grabber monitor using buffer 0.
In addition to extracting images, individual images may be written back out to an existing movie file using [;KMI Insert single frame in movie]. This will overwrite any existing image at the time specified. Only the region of the image specified by the header information will be written to the file. If you want to create a movie by writing individual frames, then you can create a blank movie using [;KMB Create blank movie] and subsequently write the frames to that movie. Initially the blank movie will contain only the specified header information, but as you insert frames in it the length will grow. Since individual frames are stored in sequence order, writing the last frame for the movie first will create a file of the maximum size.
To find out details (such as length, sample spacing etc.) of an existing movie, use [;KMD Details of movie].
The true power of movie files is unleashed through the use of command files. A set of five basic command files are supplied to simplify this procedure. These command files may be found in the DIGIMAGE\MACROS directory:
The first four of these command files are fairly self explanatory. The fifth, ProcMovi.CMD needs a little further explanation and is the main subject of this section.
Suppose we have recorded a movie and, as part of the processing of it, we need to subtract off a reference image from each and every frame. Rather than writing a command file to loop explicitly around each and every frame, we shall construct a command file to process one image (from a buffer, not the movie) and tailor this to work with ProcMovi.CMD. We start by turning on the journal facility described in section 5.8 and subtract a reference image stored in buffer !!M (the last buffer) from the one stored in buffer 1 (say). The result will replace the contents of buffer 1. Once closed, the journal file, named SubRef.CMD, will contain
# Journal file: SubRef.CMD # Opened using <f6> from Main Menu # File to be started from Main Menu ; Return to main menu G: Grab/Display # ]] Grab & Display Menu M: Manipulate image # ]] Image Manipulation A: ALU operations # ]] ALU operations: 38 # ]] Select Input Look Up Table 0 Positive image: p <-- p # ]] Select Result Look Up Table 2 Zero if A-B negative # >> "A" buffer ? 1 # The source image # >> "B" buffer ? !!M # The reference image # >> Result buffer ? 1 # >> Zoom factor 1 to 8 (1/2/4/8) ? 1 choice made from 1248 # >> Vertical offset ? 0 # >> Horizontal offset ? 0 # ]] Image Manipulation ; Return to main menu # ]] Main Menu # Journal file closed by <shift><f6> |
If we simply replace the reference to buffer 1 by !!0, then we may run ProcMovi.CMD to modify the entire movie. This is most conveniently done from a command file containing
!P 0 0 0 1 1 1 1 "TestMovi.MOV" "SubRef.CMD" "TestMovi.MOV" ProcMovi |
Clearly there are a number of parameters to ProcMovi.CMD which need explanation.
| Type | Description | Value here |
| Numeric | Specifies the time in the movie at which the processing loop is to start. | |
| Numeric | Specifies the time in the movie at which the processing loop is to end. If set to zero, then the last time stored in the movie will be used. | |
| Numeric | Time step. This need not correspond to the time step stored in the movie. It specifies the spacing between the images to be processed by ProcMovi.CMD. If set to zero, then the time spacing stored in the movie will be used. | |
| Numeric | First buffer. ProcMovi.CMD will require one or more buffer to undertake its processing. Typically the more buffers you assign to it the faster the processing. Which buffers are available is specified by the range determined by this and the next parameter. If they are equal, then only one buffer will be used. Note that you should not try to use buffer 0. | |
| Numeric | Last buffer. This parameter specifies the highest buffer number to be used by ProcMovi.CMD. | |
| Numeric | Loop around command file. The command file used with ProcMovi.CMD may be designed either to process a single buffer, or loop around a group of buffers. If this parameter is set to zero, then ProcMovi.CMD assumes the called command file will do the looping, while a nonzero value will cause ProcMovi.CMD to call the command file for each buffer in the specified range. Here our command file does not have any internal looping, so we get ProcMovi.CMD to do it. | |
| Numeric | Write to output movie. In some cases the result of the command file is an image which needs to be saved to some movie, while on other occasions a numeric value may be all that is required. A nonzero value for this parameter informs ProcMovi.CMD that the resultant image should be saved to the movie specified by the third string parameter. A zero value indicates no image need be saved. | |
| String | Source movie. This string parameter (delimited by quotes) specifies the name of the movie to be processed. | |
| String | Command file. This string parameter specifies the name of the command file to be run for each image or group of images extracted from the source movie by ProcMovi.CMD. The command file is passed a number of parameters by ProcMovi.CMD, depending on whether the command file is called once for each of the buffers in the specified range, or only once for each group of buffers. Details of these parameters are given in the next table. | |
| String | Output movie. This parameter is required only if an output movie is required as indicated by the final numeric parameter. As with our example here, the output may overwrite the original movie, or be written to a different movie, perhaps of a different format. If the output movie does not exist prior to invoking ProcMovi.CMD, then it will be created automatically with the same format as the source movie. |
As an alternative to passing the parameters on the !P line, it is, as normal, possible to assign the values to the corresponding variables (!!0 to !!6 and !0 to !2) prior to calling ProcMovi.CMD.
The command file specified by the second string is passed a number of parameters by ProcMovi.CMD. The content of these parameters depends on whether the command file is designed to process a single buffer or a group of buffers. For processing a single buffer (which requires the sixth numeric parameter, !!5, to be nonzero), the command file will receive
| Variable | Description |
| !!0 | The buffer to be processed by the command file. |
| !!1 | The time corresponding to this buffer. |
When processing a group of buffers (the sixth numeric parameter, !!5, zero)
| Variable | Description |
| !!0 | The first buffer to be processed by the command file. |
| !!1 | The last buffer to be processed by the command file. |
| !!2 | The time corresponding to the first buffer. |
| !!3 | The time step between the buffers. |
A second sample command file is listed below. This command file processes a movie for light attenuation by dye, removing the background variations in illumination in the same manner as described in section 4.3 It is assumed here that the movie and a background illumination image have already been saved to disk.
##### # BackMovi.cmd ##### !!L>0 :Nested ##### # The user interface ##### !^ Name of movie to correct ? !0:=!K !^ Name of file containing background ? !1:=!K !^ Name of output movie ? !2:=!K ##### # Restore background image ##### ; Return to main menu K: Save/Restore Buffer # ]] Save and Restore Buffer R Restore buffer from file # >> Restore to which buffer ? !!M # >> Name of file containing image ? !1 ##### # Now process movie ##### !!9:=!!M-1 # The second last buffer !P 0 0 0 1 !!9 0 1 "!0" "BackMovi.CMD" "!2" BackMovi.CMD !:End ##### # The processing code ##### !!:Nested ; Return to main menu E: Enhance image # ]] Enhance Images D Correct Dye image for background variations # >> Buffer containing background ? !!M # >> Correct which foreground image !P !!0 !!1 YesRange.CMD # >> Buffer to store first corrected image in... !!0 # >> Intensity scale factor (around 1) ? 1.00000 # >> Intensity black offset (around 0) ? 0.000000 # >> Use Rational (F/B) or Logarithmic (log(F/B)) correction ? R choice made from RL S choice made from WS ; Return to main menu # ]] Main Menu !!:End |
In this example the command file called by ProcMovi.CMD processes a group of images rather than a single image. Within the command file we have made use of the YesRange.CMD macro to simplify the specification of buffers. We have also used a little trick so that the same command file both calls and is called by ProcMovi.CMD. The psuedo variable !!L returns a value indicating the depth to which command files are nested. If the instance of the command file currently executing was called directly from the keyboard, then !!L is zero. In our above example that means the user interface is executed, the background image loaded and the !P call made to ProcMovi.CMD. During this call, ProcMovi.CMD will itself call our command file BackMovi.CMD, but this time !!L will be 2. The user interface will therefore be skipped, and the processing code executed, processing a group of images extracted from the movie by ProcMovi.CMD.
Often it is desirable to utilise ensemble mean information. To this end, the macro CombMovi.CMD has been created to allow multiple source movies to be processed to produce a single output movie and/or collect data from the ensemble. The following table lists the parameters required by this macro:
| Variable name | Type | Description |
| !!0 | Numeric (Real) | Start time of movie |
| !!1 | Numeric (Real) | Stop time of movie. If both the start time and stop time are set to zero then CombMovi will use [;KMD Details of movie] to determine the time limits. |
| !!2 | Numeric (Real) | Time step for movie. If the time step is set to zero, then CombMovi will use [;KMD Details of movie] to determine the time step. |
| !!3 | Numeric (Integer) | First movie identification number. This is used by !0 either as a number (if !!4>=0) or a parameter to a command file (if !!4<0). |
| !!4 | Numeric (Integer) | Last movie identification number. If !!4>=0, then !0 will be interpreted as a string with any reference to !!0 being substituted to obtain the name of the movie. If !!4<0, then !0 will be called as a command file to return the name of the movie; the absolute value of !!4 will be used in this case as the limiting movie id number. |
| !!5 | Numeric (Buffer) | Buffer to be used for the first movie in the list. |
| !!6 | Numeric (Logical) | If nonzero then indicates that the image returned by the !1 command file is to be saved in the movie indicated by !2. |
| !0 | String | If !!4 >=0 then !0 contains a string expression used to create the names of the movies in the list to be processed. This string should be quoted in terms of !!0 using @!@!0 to avoid !!0 being substituted in the initial call to CombMovi.CMD. If !!4<0, then !0 contains the name of the command file used to return the name of each of the movies in the list. This command file is called with !!0 set to the ordinal number of the movie, the name of which should be assigned to !0 prior to exitting. |
| !1 | String | The command file to be executed. This command file is executed once for each time step. The buffers containing the first and last movies are passed in !!0 and !!1 with any resulting image written to !!2. The current time step is indicated by !!3.NOTE: The command file is called with !PA within CombMovi so that !!a to !!z are treated as global. If you wish to have them global from your calling command file, then you should invoke ProcMovi with !PA. |
| !2 | String | The movie into which the resultant image is saved, if and only if !!5 is nonzero. If the output movie does not already exist then it will be created using the same format as the source movie. |
The following sample command file, MeanMovi.CMD, takes a range of input movies and combines them into a single output movie representing the ensemble mean.
#### # MeanMovi.CMD # Example command file utilising the CombMovi.CMD macro to # produce the ensemble mean of a series of movies stored # in files with a four digit numeric tail to the file name. ##### !!L>0 :Nested !^ The input movie names may be expressed as AAAANNNN where A is !^ an alphanumeric character and N a decimal digit. !^ !^ Base name (AAAA) for the input movie? !0:=!K !^ First value for the NNNN identification number ? !!0:=!!K !^ Last value for the NNNN identification number ? !!1:=!!K !^ Name for the output (averaged) movie ? !1:=!K # Parameters for CombMovi.CMD # !!0 Start time of movie # !!1 Stop time of movie. # !!2 Time step for movie. # !!3 First movie identification number. # !!4 Last movie identification number. # !!5 Buffer to be used for the first movie in the list. # !!6 Save images # !0 String or command file for movie names # !1 Processing command file # !2 Output movie name (optional) !P 0 0 0 !!0 !!1 1 1 "!0@!@!0" "MeanMovi" "!1" CombMovi !:End !!:Nested ; Return to main menu E: Enhance image # ]] Enhance Images A Average of buffers !P !!0 !!1 YesRange.CMD # >> Buffer to place average in ? !!2 S choice made from WS # >> Averaging buffers... !!:End |
In this example we have again made use of a conditional user interface. The call to CombMovi.CMD makes use of the macro's ability to determine the size and time step of the input movie(s) and create an output movie. The list of input movies is supplied in the string form (hence the final movie index is positive) and this string is constructed from a user-specified stub and a four digit numeric tail. Note that the ! characters must be "escaped" by @ to enable them to be passed to CombMovi without prior substitution.
Goto next document (Coordinates)
DigImage documentation page
DigImage home page
Stuart Dalziel's home page