Retrieving Timing Information

Introduction

The following sections describe how the toolbox provides acquisition timing information, particularly,

To see an example of retrieving timing information, see Determining the Frame Delay Duration.

Determining When a Trigger Executed

To determine when a trigger executed, check the information returned by a trigger event in the object's event log. You can also get access to this information in a callback function associated with a trigger event. For more information, see Retrieving Event Information.

As a convenience, the toolbox returns the time of the first trigger execution in the video input object's InitialTriggerTime property. This figure indicates which trigger is returned in this property when multiple triggers are configured.

InitialTriggerTime Records First Trigger Execution

The trigger timing information is stored in MATLAB^® clock vector format. The following example displays the time of the first trigger for the video input object vid. The example uses the MATLAB datestr function to convert the information into a form that is more convenient to view.

datestr(datetime(vid.InitialTriggerTime))

ans =

02-Mar-2007 13:00:24

Determining When a Frame Was Acquired

The toolbox provides two ways to determine when a particular frame was acquired:

By the absolute time of the acquisition
By the elapsed time relative to the execution of the trigger

You can use the getdata function to retrieve both types of timing information.

Getting the Relative Acquisition Time

When you use the getdata function, you can optionally specify two return values. One return value contains the image data; the other return value contains a vector of timestamps that measure, in seconds, the time when the frame was acquired relative to the first trigger.

[data time] = getdata(vid);

To see an example, see Determining the Frame Delay Duration.

Getting the Absolute Acquisition Time

When you use the getdata function, you can optionally specify three return values. The first contains the image data, the second contains a vector of relative acquisition times, and the third is an array of structures where each structure contains metadata associated with a particular frame.

[data time meta ] = getdata(vid);

Each structure in the array contains the following four fields. The AbsTime field contains the absolute time the frame was acquired. You can also retrieve this metadata by using event callbacks. See Retrieving Event Information for more information.

Frame Metadata

Field Name	Description
`AbsTime`	Absolute time the frame was acquired, returned in MATLAB clock format `[year month day hour minute seconds]`
`FrameNumber`	Frame number relative to when the object was started
`RelativeFrame`	Frame number relative to trigger execution
`TriggerIndex`	Trigger the event is associated with. For example, when the object starts, the associated trigger is 0. Upon stop, it is equivalent to the `TriggersExecuted` property.

Determining the Frame Delay Duration

To illustrate, this example calculates the duration of the delay specified by the TriggerFrameDelay property.

Create an image acquisition object — This example creates a video input object for a Data Translation^® image acquisition device using the default video format. 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('dt',1);
```
Configure properties — For this example, configure a trigger frame delay large enough to produce a noticeable duration.
```
vid.TriggerFrameDelay = 50
```
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 data logging does not begin until the trigger frame delay expires. After logging the specified number of frames, the object stops running.
Bring the acquired data into the workspace — Call the getdata function to bring frames into the workspace. Specify a return value to accept the timing information returned by getdata.
```
[data time ] = getdata(vid);
```
The variable time is a vector that contains the time each frame was logged, measured in seconds, relative to the execution of the first trigger. Check the first value in the time vector. It should reflect the duration of the delay before data logging started.
```
time

time =

    4.9987
    5.1587
    5.3188
    5.4465
    5.6065
    5.7665
    5.8945
    6.0544
    6.2143
    6.3424
```
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
```