Main Content


Most recently acquired image data


data = peekdata(obj,frames)


data = peekdata(obj,frames) returns data containing the latest number of frames specified by frames. 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. obj must be a 1-by-1 video input object.

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


Image height, as specified in the object's ROIPosition property


Image width, as specified in the object's ROIPosition property


Number of color bands, as specified in the NumberOfBands property


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.

peekdata is a nonblocking function that immediately returns image frames and execution control to the MATLAB workspace. Not all requested data might be returned.


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.

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



Object State




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.



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.



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.

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.

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.


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


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.

Version History

Introduced before R2006a