preview

Preview of live video data

Syntax

preview(obj)

preview(himage,himage)

hpreview = preview(...)

Description

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 input object ROIPosition property.

Components of a Video Preview Window

The Video Preview window remains active until it is either stopped using stoppreview or closed using closepreview. If you delete the object, by calling delete(obj), the Video Preview window stops previewing and closes automatically.

preview(himage,himage) displays live video data for video input object obj in the image object specified by the handle himage. preview scales 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. For more information on customized GUIs, see Previewing Data in Custom GUIs.

hpreview = preview(...) returns hpreview, a handle to the image object containing the previewed data.

Examples

Preview Image From Video Input

This example shows you how to preview image from video input, close preview window and stop previewing.

Create a customized GUI.

figure("Name","My Custom Preview Window"); 
uicontrol("String","Close","Callback","close(gcf)"); 

To check the available adaptors on your system first, use the imaqhwinfo function.

imaqhwinfo

ans = struct with fields:
    InstalledAdaptors: {'demo'  'gentl'  'gige'  'kinect'  'matrox'  'winvideo'}
        MATLABVersion: '25.1 (R2025a)'
          ToolboxName: 'Image Acquisition Toolbox'
       ToolboxVersion: '25.1 (R2025a)'

Check the supported format for the adaptor of interest.

info = imaqhwinfo("winvideo");
info.DeviceInfo(2).SupportedFormats

ans = 1×19 cell
    {'RGB24_1024x576'}    {'RGB24_1280x720'}    {'RGB24_1600x896'}    {'RGB24_160x120'}    {'RGB24_160x88'}    {'RGB24_176x144'}    {'RGB24_1920x1080'}    {'RGB24_2304x1296'}    {'RGB24_2304x1536'}    {'RGB24_320x176'}    {'RGB24_320x240'}    {'RGB24_352x288'}    {'RGB24_432x240'}    {'RGB24_640x360'}    {'RGB24_640x480'}    {'RGB24_800x448'}    {'RGB24_800x600'}    {'RGB24_864x480'}    {'RGB24_960x720'}

Create a video object using the videoinput function. Configure the adaptorname, deviceid, and format to correspond with your device's adaptor setting.

obj = videoinput("winvideo",2,"RGB24_800X600");
vidRes = obj.VideoResolution; 
nBands = obj.NumberOfBands; 
hImage = image(zeros(vidRes(2),vidRes(1),nBands) ); 
im = preview(obj, hImage); 

Stop the preview and close the live image preview window after 10 seconds.

pause(10);
stoppreview(obj)
closepreview(obj)

Input Arguments

obj — Video object

object

Video input object, specified as a videoinput object or an imaq.VideoDevice System object™.

himage — Image object to display preview data

Image object

Image object to display preview data, specified as an image object handle.

Output Arguments

hpreview — Image object

Image object

Image object containing the previewed data, returned as an image object handle. To obtain a handle to the figure window containing the image object, use the ancestor function. For more information about using image objects, see image. For more information about the image object returned, see Custom Update Function.

More About

Video Preview Window Behavior

The behavior of the Video Preview window depends on the video input object's current state and trigger configuration.

Object State	Preview Window Behavior
Running=off	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 FrameGrabInterval property is ignored until a trigger occurs.)
Running=on	If TriggerType is set to immediate or manual, the Video Preview window continues to update the image displayed. If TriggerType is set to hardware, the Video Preview window stops updating the image displayed until a trigger occurs.
Logging=on	Video Preview window might drop some data frames, but this will not affect the frames logged to memory or disk.

Note

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

Custom Update Function

preview creates application-defined data for the image object, hpreview, assigning it the name 'UpdatePreviewWindowFcn' and setting its value to an empty array ([]). You can configure the value of the 'UpdatePreviewWindowFcn' application data and retrieve its value using the MATLAB^® setappdata and getappdata functions, respectively.

The 'UpdatePreviewWindowFcn' will not necessarily be called for every frame that is acquired. If a new frame is acquired and the '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 FramesAcquiredFcn instead.

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.

• hpreview — A handle to the image object that is being updated

The event structure contains the following fields:

Field	Description
Data	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 in the ROIPosition property, and B is the number of color bands, as specified in the NumberOfBands property.
Resolution	Character vector specifying current image width and height, as defined by the ROIPosition property.
Status	Character vector describing the current acquisition status of the video input object.
Timestamp	Character vector specifying the timestamp associated with the current image frame.
FrameRate	Character vector specifying the current frame rate of the video input object in frames per second.

Version History

Introduced before R2006a