Retrieving Timing Information
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
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
vid. The example uses the MATLAB
to convert the information into a form that is more convenient to
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.
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.
Absolute time the frame was acquired, returned in MATLAB clock format
Frame number relative to when the object was started
Frame number relative to trigger execution
Trigger the event is associated with. For example, when
the object starts, the associated trigger is 0. Upon stop, it is equivalent
Determining the Frame Delay Duration
To illustrate, this example calculates the duration of the delay
specified by the
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
imaqhwinfofunction 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
startfunction to start the image acquisition object.
The object executes an immediate trigger and begins acquiring frames of data. The
startfunction 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
getdatafunction to bring frames into the workspace. Specify a return value to accept the timing information returned by
[data time ] = getdata(vid);
timeis 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