getdata

Acquired image frames to MATLAB workspace

Syntax

data = getdata(obj)
data = getdata(obj,n)
data = getdata(obj,n,type)
data = getdata(obj,n,type,format)
[data,time] = getdata(...)
[data, time, metadata] = getdata(...)


Description

data = getdata(obj) returns data, which contains the number of frames specified in the FramesPerTrigger property of the video input object obj. obj must be a 1-by-1 video input object.

data is returned as an H-by-W-by-B-by-F matrix where

H	Image height, as specified in the object's ROIPosition property
W	Image width, as specified in the object's ROIPosition property
B	Number of color bands, as specified in the NumberOfBands property
F	The number of frames returned

data is returned to the MATLAB^® workspace in its native data type using the color space specified by the ReturnedColorSpace property.

You can use the MATLAB image or imagesc functions to view the returned data. Use imaqmontage to view multiple frames at once.

data = getdata(obj,n) returns n frames of data associated with the video input object obj.

data = getdata(obj,n,type) returns n frames of data associated with the video input object obj, where type is one of the character vectors in the following table that specify the data type used to store the returned data.

Type Character Vector	Data Type
'uint8'	Unsigned 8-bit integer
'uint16'	Unsigned 16-bit integer
'uint32'	Unsigned 32-bit integer
'single'	Single precision
'double'	Double precision
'native'	Uses native data type. This is the default.

If type is not specified, 'native' is used as the default. If there is no MATLAB data type that matches the object's native data type, getdata chooses a MATLAB data type that preserves numerical accuracy. For example, the components of 12-bit RGB color data would each be returned as uint8 data.

data = getdata(obj,n,type,format) returns n frames of data associated with the video input object obj, where format is one of the character vectors in the following table that specify the MATLAB format of data.

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.

Format Character Vector	Description
'numeric'	Returns data as an H-by-W-by-B-by-F array. This is the default format if none is specified.
'cell'	Returns data as an F-by-1 cell array of H-by-W-by-B matrices

[data,time] = getdata(...) returns time, an F-by-1 matrix, where F is the number of frames returned in data. Each element of time indicates the relative time, in seconds, of the corresponding frame in data, relative to the first trigger.

time = 0 is defined as the point at which data logging begins. When data logging begins, the object's Logging property is set to 'On'. time is measured continuously with respect to 0 until the acquisition stops. When the acquisition stops, the object's Running property is set to 'Off'.

[data, time, metadata] = getdata(...) returns metadata, an F-by-1 array of structures, where F is the number of frames returned in data. Each structure contains information about the corresponding frame in data. The metadata structure contains these fields:

Metadata Field	Description
'AbsTime'	Absolute time the frame was acquired, expressed as a time vector
'FrameNumber'	Number identifying the nth frame since the start command was issued
'RelativeFrame'	Number identifying the nth frame relative to the start of a trigger
'TriggerIndex'	Number of the trigger in which this frame was acquired
'ChunkData'	Struct with fields of frame metadata. (GenICam™ GenTL compliant cameras only) Enable the videosource object chunk data with its ChunkModeActive property; configure selected fields with the ChunkSelector and ChunkEnable properties; view the configuration with the chunkDataInfo function.

In addition to the fields in the above table, some adaptors might provide other adaptor-specific metadata.

getdata is a blocking function that returns execution control to the MATLAB workspace after the requested number of frames becomes available within the time period specified by the object's Timeout property. The object's FramesAvailable property is automatically reduced by the number of frames returned by getdata. If the requested number of frames is greater than the frames to be acquired, getdata returns an error.

It is possible to issue a Ctrl+C while getdata is blocking. This does not stop the acquisition but does return control to MATLAB.

Examples

Construct a video input object associated with a Matrox^® device at ID 1.

obj = videoinput('matrox', 1);

Initiate an acquisition and access the logged data.

start(obj);
data = getdata(obj);

Display all image frames acquired.

imaqmontage(data);

Remove the video input object from memory.

delete(obj)

Version History

Introduced before R2006a