getdata

Acquire image frames to MATLAB workspace

collapse all in page

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 video frame data specified in the FramesPerTrigger property of the video input object obj.

Note

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.

getdata removes the data from the memory buffer. peekdata does not.

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

example

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

data = getdata(obj,n,type) uses type to specify the data type used to store the returned data.

data = getdata(obj,n,type,format) returns data in the specified format.

[data,time] = getdata(___), for any previous input arguments, also returns the relative time of each corresponding frame in data relative to the first trigger.

[data,time,metadata] = getdata(___) also returns extra information about the frames in data.

example

Examples

collapse all

Construct a video input object.

obj = videoinput("gentl",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)

Construct a video input object.

obj = videoinput("gentl",1);

Initiate an acquisition and access the logged data along with the time and metadata.

start(obj);
[data,time,metadata] = getdata(obj);

View the relative times of the frames.

time
time =     
        0.2861     
        0.3677    
        0.4544    
        0.5412    
        0.6278    
        0.7144 
        0.8012
        0.8878
        0.9745
        1.0612

View the metadata.

metadata
metadata =
   10×1 struct array with fields:
     AbsTime
     FrameNumber
     RelativeFrame
     TriggerIndex

View the details of the first entry in metadata.

metadata(1)
ans =
   struct with fields:
           AbsTime: [2024 8 23 11 12 31.5422]
       FrameNumber: 1
     RelativeFrame: 1
      TriggerIndex: 1

Input Arguments

collapse all

Video input object, specified as the output of the videoinput function. obj must be a 1-by-1 video input object.

Example: videoinput("matrox")

Number of data frames, specified as a positive integer.

Data Types: single | double

Data type returned, specified as one of the following names:

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

Example: "single"

Data Types: char | string

Format of returned data, specified as one of these names:

  • "numeric" — Returns data as an H-by-W-by-B-by-F array.

  • "cell" — Returns data as an F-by-1 cell array of H-by-W-by-B matrices.

Example: "cell"

Data Types: char | string

Output Arguments

collapse all

Image data, returned as an H-by-W-by-B-by-F array, 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

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.

w

Relative times in seconds of corresponding frames relative to the first trigger, returned as an F-by-1 matrix, where F is the number of frames in data. See 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".

Extra information about the frames in data, returned as an F-by-1 array of structures, where F is the number of frames in data. Each structure contains the following 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). This field exists only when the ChunkModeActive property is true.

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 these fields, some adaptors might provide other adaptor-specific metadata.

Version History

Introduced before R2006a

See Also

| | |

Topics