Preview of live video data
himage = preview(...)
preview(obj) creates a Video Preview window that
displays live video data for video input object
obj. The window also
displays the timestamp and video resolution of each frame, the current frame rate, and the
current status of
obj. The Video Preview window displays the video data
at 100% magnification. The size of the preview image is determined by the value of the video
Components of a Video Preview Window
The Video Preview window remains active until it is either stopped
stoppreview or closed using
If you delete the object, by calling
the Video Preview window stops previewing and closes automatically.
live video data for video input object
obj in the
image object specified by the handle
the image data to fill the entire area of the image object but does
not modify the values of any image object properties. Use this syntax
to preview video data in a custom GUI of your own design (see Examples).
himage = preview(...) returns
a handle to the image object containing the previewed data. To obtain
a handle to the figure window containing the image object, use the
For more information about using image objects, see
See the Custom Update Function section for more information about
the image object returned.
The behavior of the Video Preview window depends on the video input object's current state and trigger configuration.
Preview Window Behavior
Displays a live view of the image being acquired from
the device, for all trigger types. The image is updated to reflect
changes made to configurations of object properties. (The
Video Preview window might drop some data frames, but this will not affect the frames logged to memory or disk.
The Image Acquisition Toolbox™ Preview window
supports the display of up to 16-bit image data. The Preview window was designed to only
show 8-bit data, but many cameras return 10-, 12-, 14-, or 16-bit data. The Preview window
display supports these higher bit-depth cameras. However, larger bit data is scaled to
8-bit for the purpose of displaying previewed data. To capture the image data in the
Preview window in its full bit depth for grayscale images, set the
PreviewFullBitDepth property to
Custom Update Function
preview creates application-defined data
for the image object,
himage, assigning it the
'UpdatePreviewWindowFcn' and setting its value
to an empty array (
). You can configure the value
'UpdatePreviewWindowFcn' application data
and retrieve its value using the MATLAB®
'UpdatePreviewWindowFcn' will not necessarily
be called for every frame that is acquired. If a new frame is acquired
'UpdatePreviewWindowFcn' for the previous
frame has not yet finished executing, no update will be generated
for the new frame. If you need to execute a function for every acquired
frame, use the
You can use this function to define custom processing of the
previewed image data. When
preview invokes the
function handle you specify, it passes three arguments to your function:
obj— The video input object being previewed
event— An event structure containing image frame information. For more information, see below.
himage— A handle to the image object that is being updated
The event structure contains the following fields:
Current image frame specified as an H-by-W-by-B matrix
where H and W are the image height and width, respectively, as specified
Character vector specifying current image width and height,
as defined by the
Character vector describing the current acquisition status of the video input object.
Character vector specifying the timestamp associated with the current image frame.
Character vector specifying the current frame rate of the video input object in frames per second.
Create a customized GUI.
figure('Name', 'My Custom Preview Window'); uicontrol('String', 'Close', 'Callback', 'close(gcf)');
Create an image object for previewing.
vidRes = obj.VideoResolution; nBands = obj.NumberOfBands; hImage = image( zeros(vidRes(2), vidRes(1), nBands) ); preview(obj, hImage);
For more information on customized GUIs, see Previewing Data in Custom GUIs.