|On this page…|
While a video input object is running, you can log image data being acquired to a disk file. Logging image data to disk provides a record of your data. You can log data to several formats but VideoWriter is recommended, instead of using an AVI file.
For the best performance, logging to disk requires a MATLAB® VideoWriter object, which is a MATLAB function, not an Image Acquisition Toolbox™ function. After you create and configure a VideoWriter object, provide it to the videoinput object's DiskLogger property.
VideoWriter provides a number of different profiles that log the data in different formats. The following example uses the Motion JPEG 2000 profile, which can log single-banded (grayscale) data as well as multi-byte data. Supported profiles are:
'Motion JPEG 2000' — Compressed Motion JPEG 2000 file.
'Archival' — Motion JPEG 2000 file with lossless compression.
'Motion JPEG AVI' — Compressed AVI file using Motion JPEG codec.
'Uncompressed AVI' — Uncompressed AVI file with RGB24 video.
'MPEG-4' — Compressed MPEG-4 file with H.264 encoding (systems with Windows 7 or Mac OS X 10.7 and later).
'Grayscale AVI' — Uncompressed AVI file with grayscale video. Only used for monochrome devices.
'Indexed AVI' — Uncompressed AVI file with indexed video. Only used for monochrome devices.
This example uses a GigE Vision device in a grayscale format (Mono10).
Create a video input object that accesses a GigE Vision image acquisition device and uses grayscale format at 10 bits per pixel.
vidobj = videoinput('gige', 1, 'Mono10');
You can log acquired data to memory, to disk, or both. By default, data is logged to memory. To change the logging mode to disk, configure the video input object's LoggingMode property.
set(vidobj, 'LoggingMode', 'disk')
Create a VideoWriter object with the profile set to Motion JPEG 2000.
logfile = VideoWriter('logfile.mj2, 'Motion JPEG 2000')
Configure the video input object to use the VideoWriter object.
vidobj.DiskLogger = logfile;
Now that the video input object is configured for logging data to a Motion JPEG 2000 file, initiate the acquisition.
Wait for the acquisition to finish.
When logging large amounts of data to disk, disk writing occasionally lags behind the acquisition. To determine whether all frames are written to disk, you can optionally use the DiskLoggerFrameCount property.
while (vidobj.FramesAcquired ~= vidobj.DiskLoggerFrameCount) pause(.1) end
You can verify that the FramesAcquired and DiskLoggerFrameCount properties have identical values by using these commands and comparing the output.
When the video input object is no longer needed, delete it and clear it from the workspace.
delete(vidobj) clear vidobj
Note the following when using VideoWriter.
You should not delete the video input object until logging has been completed as indicated by the DiskLoggerFrameCount property equaling the FramesAcquired property. Doing so will cause disk logging to stop without all of the data being logged.
If START is called multiple times without supplying a new VideoWriter object, the contents of the previous file will be erased when START is called.
Once the VideoWriter object has been passed to the DiskLogger property, you should not modify it.
While a video input object is running, you can log the image data being acquired to a disk file. Logging image data to disk provides a record of your data. You can log data to several formats but we recommend using VideoWriter, as described in the previous section. However, if you need to use an AVI file, this section describes how to do that.
To set up data logging to disk:
Create a disk file to store the data. The toolbox logs the data to disk in Audio Video Interleave (AVI) format because this format provides data compression capabilities that allow for efficient storage. You must use the MATLAB avifile function to create this log file. For more information, see Creating an AVI File Object for Logging.
The following figure shows how the toolbox adds frames to the AVI file when a trigger occurs. With each subsequent trigger, the toolbox appends the acquired frames to the end of the AVI file. The frames must have the same dimensions. For an example of how to set up disk data logging, see Logging Data to Disk Using an AVI File.
Logging Data to a Disk File
To create an AVI file in the MATLAB environment, use the avifile function. You specify the name of the AVI file to the avifile function. For example, to create the AVI file named my_datalog.avi, enter this code at the MATLAB command prompt.
aviobj = avifile('my_datalog.avi');
The avifile function returns an AVI file object. You can use the AVI file object returned by the avifile function, aviobj, to modify characteristics of the AVI file by setting the values of the object's properties. For example, you can specify the codec used for data compression or specify the desired quality of the output.
For more information about AVI file objects, see the MATLAB avifile documentation. For more information about using AVI files to log image data, see the following topics.
When logging images in grayscale format, such as RS170, you must set the value of the AVI object's Colormap property to be a grayscale colormap. Otherwise, the image data in the AVI file will not display correctly.
This example uses the MATLAB gray function to create a grayscale colormap and sets the value of the AVI file object's Colormap property with this colormap.
logfile = avifile('my_datalog.avi','Colormap',gray(256));
When you specify the AVI file object as the value of the DiskLogger property, you are creating a copy of the AVI file object. Do not access the AVI file object using the original variable name, aviobj, while the video input object is using the file for data logging. To avoid file access conflicts, keep in mind these guidelines when using an AVI file for data logging:
Do not close an AVI file object while it is being used for data logging.
Do not use the AVI file addframe function to add frames to the AVI file object while it is being used for data logging.
Do not change the values of any AVI file object properties while it is being used for data logging.
Note: AVI files are limited to a bit-depth of 8 bits per pixel for each band. If you have higher bit data, you should not log it to an AVI file since the AVI format is restricted to 8-bit data. If you do log higher bit data to an AVI file, it will be scaled and then logged as 8-bit data.
When data logging has ended, close the AVI file to make it accessible outside the MATLAB environment. Use the value of the video input object DiskLogger property to reference the AVI file, rather than the variable returned when you created the AVI file object (aviobj). See Logging Data to Disk Using an AVI File for an example.
Before you close the file, make sure that the video input object has finished logging frames to disk. Because logging to disk takes more time than logging to memory, the completion of disk logging can lag behind the completion of memory logging. To determine when logging to disk is complete, check the value of the DiskLoggerFrameCount property; this property tells how many frames have been logged to disk.
This example illustrates how to configure a video input object to log data to a disk file:
my_log = 'my_datalog.avi'; aviobj = avifile(my_log); aviobj Adjustable parameters: Fps: 15.0000 Compression: 'Indeo3' Quality: 75 KeyFramePerSec: 2.1429 VideoName: 'my_datalog.avi' Automatically updated parameters: Filename: 'my_datalog.avi' TotalFrames: 0 Width: 0 Height: 0 Length: 0 ImageType: 'Unknown' CurrentState: 'Open'
Configure properties of the AVI file object — You can optionally configure the properties of the AVI file object. The AVI file object supports properties that control the data compression used, image quality, and other characteristics of the file. The example sets the quality property to a midlevel value. By lowering the quality, the AVI file object creates smaller log files.
aviobj.Quality = 50;
Because this example acquires image data in grayscale format (RS170), you must also specify the colormap used with the AVI object to ensure that the stored data displays correctly.
aviobj.Colormap = gray(256);
Create a video input object — This example creates a video input object for a Matrox® image acquisition device, using the default video format M_RS170. To run this example on your system, use the imaqhwinfo function to get the video input object constructor for your image acquisition device and substitute that syntax for the following code.
vid = videoinput('matrox',1);
Configure video input object properties — Set up disk logging by setting the value of the DiskLogger property to be aviobj, the AVI file object created in step 1. Then, set the LoggingMode property to 'disk' (or 'disk&memory'). This example also sets the TriggerRepeat property.
vid.LoggingMode = 'disk&memory'; vid.DiskLogger = aviobj; vid.TriggerRepeat = 3;
The object executes an immediate trigger, acquires frames of data, repeats the trigger three additional times, and then stops.
To verify that all the frames have been logged to the AVI file, check the value of the DiskLoggerFrameCount property. This property tells the number of frames that have been logged to disk.
vid.DiskLoggerFrameCount ans = 40
Note Because it takes longer to write frames to a disk file than to memory, the value of the DiskLoggerFrameCount property can lag behind the value of the FramesAvailable property, which specifies the number of frames logged to memory.
To verify that a disk file was created, go to the directory in which the log file resides and make sure it exists. The exist function returns 2 if the file exists.
if(exist(my_log)==2) disp('AVI file created.') end
Close the AVI file object — Close the AVI file to make it available outside the MATLAB environment. Closing the AVI file object ensures that the logged data is written to the disk file. Be sure to use the value of the video input object DiskLogger property, vid.DiskLogger, to reference the AVI file object, not the original variable, aviobj, returned by the avifile function.
aviobj = close(vid.DiskLogger);
Use the original variable, aviobj, as the return value when closing an AVI file object.
delete(vid) clear vid