Contents

Logging Image Data to Disk

Logging Data to Disk Using VideoWriter

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.

Logging Data to Disk Using VideoWriter

This example uses a GigE Vision device in a grayscale format (Mono10).

  1. 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');
  2. 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.

    vidobj.LoggingMode = 'disk'
  3. Create a VideoWriter object with the profile set to Motion JPEG 2000.

    logfile = VideoWriter('logfile.mj2, 'Motion JPEG 2000')
  4. Configure the video input object to use the VideoWriter object.

    vidobj.DiskLogger = logfile;
  5. Now that the video input object is configured for logging data to a Motion JPEG 2000 file, initiate the acquisition.

    start(vidobj)
  6. Wait for the acquisition to finish.

    wait(vidobj, 5)
  7. 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
  8. You can verify that the FramesAcquired and DiskLoggerFrameCount properties have identical values by using these commands and comparing the output.

    vidobj.FramesAcquired
    vidobj.DiskLoggerFrameCount
  9. When the video input object is no longer needed, delete it and clear it from the workspace.

    delete(vidobj)
    clear vidobj

Guidelines for Using a VideoWriter Object to Log Image Data

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.

Logging Data to Disk Using an AVI File

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:

  1. 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.

  2. Set the value of the video input object LoggingMode property to 'disk' or 'disk&memory'.

  3. Set the value of the video input object DiskLogger property to the AVI file object created in step 1.

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

    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.

Creating an AVI File Object for Logging

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.

Logging Grayscale Images Using an AVI File

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));

Guidelines for Using an AVI File Object to Log Image Data

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.

Closing the DiskLogger AVI file

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.

    Note   When you log frames to disk, the video input object queues the frames for writing but the operating system might not perform the write operation immediately. Closing an AVI file causes the data to be written to the disk.

Logging Data to Disk Using an AVI File

This example illustrates how to configure a video input object to log data to a disk file:

  1. Create a MATLAB AVI file object — Create the MATLAB AVI file that you want to use for data logging, using the avifile function. You specify the name of the AVI file when you create it.

    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'
    
  2. 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);
  3. 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);
  4. 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;
  5. Start the video input object — Start logging data to disk.

    start(vid)

    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
  6. 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.

  7. Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.

    delete(vid)
    clear vid
Was this topic helpful?