Controlling Logging Parameters

Data Logging

The following subsections describe how to control various aspects of data logging.

Specifying the logging mode
Specifying the number of frames to log
Determining how many frames have been logged since the object was started
Determining how many frames are currently available in the memory buffer
Delaying data logging after a trigger executes
Specifying multiple trigger executions

Specifying Logging Mode

Using the video input object LoggingMode property, you can control where the toolbox logs acquired frames of data.

The default value for the LoggingMode property is 'memory'. In this mode, the toolbox logs data to a buffer in memory. If you want to bring image data into the MATLAB^® workspace, you must log frames to memory. The functions provided by the toolbox to move data into the workspace all work with the memory buffer. For more information, see Bringing Image Data into the MATLAB Workspace.

You can also log data to a disk file by setting the LoggingMode property to 'disk' or to 'disk&memory'. By logging frames to a disk file, you create a permanent record of the frames you acquire. For example, this code sets the value of the LoggingMode property of the video input object vid to 'disk&memory'.

vid.LoggingMode = 'disk&memory';

Because the toolbox stores the image frames in Audio Video Interleaved (AVI) format, you can view the logged frames in any standard media player. For more information, see Logging Image Data to Disk.

Note

To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.

Specifying the Number of Frames to Log

In the Image Acquisition Toolbox™ software, you specify the amount of data you want to acquire as the number of frames per trigger.

You specify the desired size of your acquisition as the value of the video input object FramesPerTrigger property. By default, the value of this property is 10 frames per trigger, but you can specify any value. The following figure illustrates an acquisition using the default value for the FramesPerTrigger property. To see an example of an acquisition, see Acquiring 100 Frames.

Specifying the Amount of Data to Log

Note

While you can specify any size acquisition, the number of frames you can acquire is limited by the amount of memory you have available on your system for image storage. A large acquisition can potentially fill all available system memory. For large acquisitions, you might want to remove frames from the buffer as they are logged. For more information, see Moving Multiple Frames into the Workspace. To learn how to empty the memory buffer, see Freeing Memory.

Specifying a Noncontiguous Acquisition

Although FramesPerTrigger specifies the number of frames to acquire, these frames do not have to be captured contiguously from the video stream. You can specify that the toolbox skip a certain number of frames between frames it acquires. To do this, set the value of the FrameGrabInterval property.

Note

The FrameGrabInterval property controls the interval at which the toolbox acquires frames from the video stream (measured in frames). This property does not control the rate at which frames are provided by the device, otherwise known as the frame rate.

The following figure illustrates how the FrameGrabInterval property affects an acquisition.

Impact of FrameGrabInterval on Data Logging

Determining How Much Data Has Been Logged

To determine how many frames have been acquired by a video input object, check the value of the FramesAcquired property. This property tells how many frames the object has acquired since it was started. To determine how many frames are currently available in the memory buffer, see Determining How Many Frames Are Available.

Acquiring 100 Frames

This example illustrates how you can specify the amount of data to be acquired and determine how much data has been acquired. (For an example of configuring a time-based acquisition, see Acquiring 10 Seconds of Image Data.)

Create an image acquisition object — This example creates a video input object for a Windows^® image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
```
vid = videoinput('winvideo',1);
```
Configure properties — Specify the amount of data you want to acquire as the number of frames per trigger. By default, a video input object acquires 10 frames per trigger. For this example, set the value of this property to 100.
```
vid.FramesPerTrigger = 100
```
Start the image acquisition object -— Call the start function to start the image acquisition object.
```
start(vid)
```
The object executes an immediate trigger and begins acquiring frames of data. To verify if the video input object is logging data, use the islogging function.
```
islogging(vid)
ans =

     1
```
The start function returns control to the command line immediately but the object continues logging the data to the memory buffer. After acquiring the specified number of frames, the object stops running and logging.
Check how many frames have been acquired — To verify that the specified number of frames has been acquired, check the value of the FramesAcquired property. Note that the object continuously updates the value of the FramesAcquired property as the acquisition progresses. If you view the value of this property several times during an acquisition, you can see the number of frames acquired increase until logging stops.
```
vid.FramesAcquired
ans =

    100
```
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
```

Determining How Many Frames Are Available

The FramesAcquired property tells how many frames the object has logged since it was started, described in Determining How Much Data Has Been Logged. Once you move frames from the memory buffer into the MATLAB workspace, the number of frames stored in the memory buffer will differ from the FramesAcquired value. To determine how many frames are currently available in the memory buffer, check the value of the FramesAvailable property.

Note

The FramesAvailable property tells the number of frames in the memory buffer, not in the disk log, if LoggingMode is configured to 'disk' or 'disk&memory'. Because it takes longer to write frames to a disk file than to memory, the number of frames stored in the disk log might lag behind those stored in the memory buffer. To see how many frames are available in the disk log, look at the value of the DiskLoggerFrameCount property. See Logging Image Data to Disk for more information.

This example illustrates the distinction between the FramesAcquired and the FramesAvailable properties:

Create an image acquisition object — This example creates a video input object for a Windows image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
```
vid = videoinput('winvideo',1);
```
Configure properties — For this example, configure an acquisition of 15 frames.
```
vid.FramesPerTrigger = 15
```
Start the image acquisition object — Call the start function to start the image acquisition object.
```
start(vid)
```
The object executes an immediate trigger and begins acquiring frames of data. The start function returns control to the command line immediately but the object continues logging the data to the memory buffer. After logging the specified number of frames, the object stops running.
Check how many frames have been acquired — To determine how many frames the object has acquired and how many frames are available in the memory buffer, check the value of the FramesAcquired and FramesAvailable properties.
```
vid.FramesAcquired
ans =

    15

vid.FramesAvailable

ans = 

    15
```
The object updates the value of these properties continuously as it acquires frames of data. The following figure illustrates how the object puts acquired frames in the memory buffer as the acquisition progresses.
Frames Available After Initial Trigger Execution
Remove frames from the memory buffer — When you remove frames from the memory buffer, the object decrements the value of the FramesAvailable property by the number of frames removed.
To remove frames from the memory buffer, call the getdata function, specifying the number of frames to retrieve. For more information about using getdata, see Bringing Image Data into the MATLAB Workspace.
```
data = getdata(vid,5);
```
After you execute the getdata function, check the values of the FramesAcquired and FramesAvailable properties again. Notice that the FramesAcquired property remains unchanged but the object has decremented the value of the FramesAvailable property by the number of frames removed from the memory buffer.
```
vid.FramesAcquired

ans =

    15

vid.FramesAvailable

ans =

    10
```
The following figure illustrates the contents of the memory buffer after frames are removed.
Contents of Memory Buffer Before and After Removing Frames
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
```

Delaying Data Logging After a Trigger

In some image acquisition setups, you might not want to log the first few frames returned from your camera or other imaging device. For example, some cameras require a short warmup time when activated. The quality of the first few images returned by these cameras might be too dark to be useful for your application.

To account for this characteristic of your setup, you can specify that the toolbox skip a specified number of frames after a trigger executes. You use the TriggerFrameDelay property to specify the number of frames you want to skip before logging begins.

For example, to specify a delay of five frames before data logging begins after a trigger executes, you would set the value of the TriggerFrameDelay property to 5. The number of frames captured is defined by the FramesPerTrigger property and is unaffected by the delay.

vid.TriggerFrameDelay = 5;

This figure illustrates this scenario.

Specifying a Delay Before Data Logging Begins

Specifying Multiple Triggers

When a trigger occurs, a video input object acquires the number of frames specified by the FramesPerTrigger property and logs the data to a memory buffer, a disk file, or both.

When it acquires the specified number of frames, the video input object stops running. To execute another trigger, you must restart the video input object. Restarting an object causes it to delete all the data it has stored in the memory buffer from the previous trigger. To execute multiple triggers, retaining the data from each trigger, you must specify a value for the TriggerRepeat property.

Note that the TriggerRepeat property specifies the number of additional times a trigger executes. For example, to execute a trigger three times, you would set the value of the TriggerRepeat property to 2. In the following, vid is a video input object created with the videoinput function.

vid.TriggerRepeat = 2;

This figure illustrates an acquisition with three executions of a manual trigger. In the figure, the FramesPerTrigger property is set to 3.

Executing Multiple Triggers