peekdata

Most recently acquired image data

Syntax

data = peekdata(obj,frames)

Description

data = peekdata(obj,frames) returns video data containing the latest number of frames specified by frames.

peekdata is a nonblocking function that immediately returns image frames and execution control to the MATLAB^® workspace. All requested data might not be returned.

peekdata can be used only after the start command is issued and while the object is running. peekdata can also be called once after obj has stopped running.

Note

peekdata provides a look at the data; it does not remove data from the memory buffer. The object's FramesAvailable property value is not affected by the number of frames returned by peekdata.

Examples

Obtain Recent Video Data

Construct a video input object.

obj = videoinput("gentl",1);

Initiate an acquisition.

start(obj);

Check how many frames of data are available.

obj.FramesAvailable

ans =
     10

Obtain the ten most recent frames, if available.

frames = 10;
data = peekdata(obj,frames);

Check that running peekdata does not remove data from the memory buffer.

obj.FramesAvailable

ans =
     10

Remove the video input object from memory.

delete(obj)

Input Arguments

obj — Video input object

object created with videoinput

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

Example: videoinput("matrox")

frames — Number of frames of data

positive integer

Number of frames of data, specified as a positive integer.

The number of frames available to peekdata is determined by recalling the last frame returned by a previous peekdata call, and the number of frames that were acquired since then.

When the obj Running property is on and the Logging property is off, peekdata is limited to one image frame.

If frames is greater than the number of frames currently acquired, all available frames are returned with a warning message stating that the requested number of frames was not available.

Example: 12

Data Types: single | double

Output Arguments

data — Image data

H-by-W-by-B-by-F array

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

The behavior of peekdata depends on the settings of the Running and Logging properties.

Running	Logging	Object State	Result
On	Off	The object has been started but is waiting for a trigger. (TriggerType is set to 'manual' or 'hardware'). No data has been acquired so none is available.	peekdata returns a single frame of data and issues a warning, if you requested more than one frame.
On	On	The object has been started, a trigger has executed, and the object is actively acquiring data.	peekdata returns the n most recently acquired frames of data. The frames are not removed from the buffer.
Off	Off	The object has stopped running because it acquired the requested number of frames or you called the stop function.	peekdata can be called once to return the n most recently acquired frames of data, assuming FramesAvailable is greater than 0. Otherwise, peekdata returns an error. The frames returned are not removed from the memory buffer.

Note

The peekdata function does not return any data while running in disk logging mode.

Version History

Introduced before R2006a