Previewing Data

Introduction

After you connect MATLAB^® to the image acquisition device you can view the live video stream using the Video Preview window. Previewing the video data can help you make sure that the image being captured is satisfactory.

For example, by looking at a preview, you can verify that the lighting and focus are correct. If you change characteristics of the image, by using video input object and video source object properties, the image displayed in the Video Preview window changes to reflect the new property settings.

The following sections provide more information about using the Video Preview window.

Instead of using the toolbox's Video Preview window, you can display the live video preview stream in any Handle Graphics^® image object you specify. In this way, you can include video previewing in a GUI of your own creation. The following sections describe this capability.

Note

The Image Acquisition Toolbox™ Preview window and the Preview window that is built into the Image Acquisition Tool support 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. If you need the full resolution of the data, use the getsnapshot or getdata functions.

Opening a Video Preview Window

To open a Video Preview window, use the preview function. The Video Preview window displays the live video stream from the device. You can only open one preview window per device. If multiple devices are used, you can open multiple preview windows at the same time.

The following example creates a video input object and then opens a Video Preview window for the video input object.

vid = videoinput('winvideo');
preview(vid);

The following figure shows the Video Preview window created by this example. The Video Preview window displays the live video stream. The size of the preview image is determined by the value of the video input object's ROIPosition property. The Video Preview window displays the video data at 100% magnification.

In addition to the preview image, the Video Preview window includes information about the image, such as the timestamp of the video frame, the video resolution, the frame rate, and the current status of the video input object.

Note

Because video formats typically express resolution as width-by-height, the Video Preview window expresses the size of the image frame as column-by-row, rather than the standard MATLAB row-by-column format.

Note

The Image Acquisition Toolbox Preview window and the Preview window that is built into the Image Acquisition Tool support 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. If you need the full resolution of the data, use the getsnapshot or getdata functions.

Stopping the Preview Video Stream

When you use the preview function to start previewing image data, the Video Preview window displays a view of the live video stream coming from the device. To stop the updating of the live video stream, call the stoppreview function.

This example creates a video input object and opens a Video Preview window. The example then calls the stoppreview function on this video input object. The Video Preview window stops updating the image displayed and stops updating the timestamp. The status displayed in the Video Preview window also changes to indicate that previewing has been stopped.

vid = videoinput('winvideo');
preview(vid)
stoppreview(vid)

To restart the video stream in the Video Preview window, call preview again on the same video input object.

preview(vid)

Closing a Video Preview Window

To close a particular Video Preview window, use the closepreview function, specifying the video input object as an argument. You do not need to stop the live video stream displayed in the Video Preview window before closing it.

closepreview(vid)

To close all currently open Video Preview windows, use the closepreview function without any arguments.

closepreview

Note

When called without an argument, the closepreview function only closes Video Preview windows. The closepreview function does not close any other figure windows in which you have directed the live preview video stream. For more information, see Previewing Data in Custom GUIs.

Previewing Data in Custom GUIs

Instead of using the toolbox's Video Preview window, you can use the preview function to direct the live video stream to any Handle Graphics image object. In this way, you can incorporate the toolbox's previewing capability in a GUI of your own creation. (You can also perform custom processing as the live video is displayed. For information, see Performing Custom Processing of Previewed Data.)

To use this capability, create an image object and then call the preview function, specifying a handle to the image object as an argument. The preview function outputs the live video stream to the image object you specify.

The following example creates a figure window and then creates an image object in the figure, the same size as the video frames. The example then calls the preview function, specifying a handle to the image object.

% Create a video input object.
vid = videoinput('winvideo');

% Create a figure window. This example turns off the default
% toolbar, menubar, and figure numbering.

figure('Toolbar','none',...
       'Menubar', 'none',...
       'NumberTitle','Off',...
       'Name','My Preview Window');

% Create the image object in which you want to display 
% the video preview data. Make the size of the image
% object match the dimensions of the video frames.

vidRes = vid.VideoResolution;
nBands = vid.NumberOfBands;
hImage = image( zeros(vidRes(2), vidRes(1), nBands) );

% Display the video data in your GUI.

preview(vid, hImage);

When you run this example, it creates the GUI shown in the following figure.

Custom Preview

Performing Custom Processing of Previewed Data

When you specify an image object to the preview function (see Previewing Data in Custom GUIs), you can optionally also specify a function that preview executes every time it receives an image frame.

To use this capability, follow these steps:

Create the function you want executed for each image frame, called the update preview window function. For information about this function, see Creating the Update Preview Window Function.
Create an image object.
Configure the value of the image object's 'UpdatePreviewWindowFcn' application-defined data to be a function handle to your update preview window function. For more information, see Specifying the Update Preview Function.
Call the preview function, specifying the handle of the image object as an argument.

Note

If you specify an update preview window function, in addition to whatever processing your function performs, it must display the video data in the image object. You can do this by updating the CData of the image object with the incoming video frames. For some performance guidelines about updating the data displayed in an image object, see Technical Solution 1-1B022.

Creating the Update Preview Window Function

When preview calls the update preview window function you specify, it passes your function the following arguments.

Argument	Description
`obj`	Handle to the video input object being previewed
`event`	A data structure containing the following fields:
	`Data`	Current image frame specified as an H-by-W-by-B array, where H is the image height and W is the image width, as specified in the `ROIPosition` property, and B is the number of color bands, as specified in the `NumberOfBands` property
	`Resolution`	Character vector specifying the current image width and height, as defined by the `ROIPosition` property
	`Status`	Character vector describing the status of the video input object
	`Timestamp`	Character vector specifying the time associated with the current image frame, in the format `hh:mm:ss:ms`
	`FrameRate`	Character vector specifying the current frame rate of the video input object in frames per second
`himage`	Handle to the image object in which the data is to be displayed

The following example creates an update preview window function that displays the timestamp of each incoming video frame as a text label in the custom GUI. The update preview window function uses getappdata to retrieve a handle to the text label uicontrol object from application-defined data in the image object. The custom GUI stores this handle to the text label uicontrol object — see Specifying the Update Preview Function.

Note that the update preview window function also displays the video data by updating the CData of the image object.

function mypreview_fcn(obj,event,himage)
% Example update preview window function.

% Get timestamp for frame.
tstampstr = event.Timestamp;

% Get handle to text label uicontrol.
ht = getappdata(himage,'HandleToTimestampLabel');

% Set the value of the text label.
ht.String = tstampstr;

% Display image data.
himage.CData = event.Data

Specifying the Update Preview Function

To use an update preview window function, store a function handle to your function in the 'UpdatePreviewWindowFcn' application-defined data of the image object. The following example uses the setappdata function to configure this application-defined data to a function handle to the update preview window function described in Creating the Update Preview Window Function.

This example extends the simple custom preview window created in Previewing Data in Custom GUIs. This example adds three push button uicontrol objects to the GUI: Start Preview, Stop Preview, and Close Preview.

In addition, to illustrate using an update preview window function, the example GUI includes a text label uicontrol object to display the timestamp value. The update preview window function updates this text label each time a framed is received. The example uses setappdata to store a handle to the text label uicontrol object in application-defined data in the image object. The update preview window function retrieves this handle to update the timestamp display.

% Create a video input object.
vid = videoinput('winvideo');

% Create a figure window. This example turns off the default
% toolbar and menubar in the figure.
hFig = figure('Toolbar','none',...
       'Menubar', 'none',...
       'NumberTitle','Off',...
       'Name','My Custom Preview GUI');

% Set up the push buttons
uicontrol('String', 'Start Preview',...
    'Callback', 'preview(vid)',...
    'Units','normalized',...
    'Position',[0 0 0.15 .07]);
uicontrol('String', 'Stop Preview',...
    'Callback', 'stoppreview(vid)',...
    'Units','normalized',...
    'Position',[.17 0 .15 .07]);
uicontrol('String', 'Close',...
    'Callback', 'close(gcf)',...
    'Units','normalized',...
    'Position',[0.34 0 .15 .07]);

% Create the text label for the timestamp
hTextLabel = uicontrol('style','text','String','Timestamp', ...
    'Units','normalized',...
    'Position',[0.85 -.04 .15 .08]);

% Create the image object in which you want to
% display the video preview data.
vidRes = vid.VideoResolution;
imWidth = vidRes(1);
imHeight = vidRes(2);
nBands = vid.NumberOfBands;
hImage = image( zeros(imHeight, imWidth, nBands) );

% Specify the size of the axes that contains the image object
% so that it displays the image at the right resolution and
% centers it in the figure window.
figSize = get(hFig,'Position');
figWidth = figSize(3);
figHeight = figSize(4);
gca.unit = 'pixels';
gca.position = [ ((figWidth - imWidth)/2)... 
               ((figHeight - imHeight)/2)...
               imWidth imHeight ];

% Set up the update preview window function.
setappdata(hImage,'UpdatePreviewWindowFcn',@mypreview_fcn);

% Make handle to text label available to update function.
setappdata(hImage,'HandleToTimestampLabel',hTextLabel);

preview(vid, hImage);

When you run this example, it creates the GUI shown in the following figure. Each time preview receives a video frame, it calls the update preview window function that you specified, which updates the timestamp text label in the GUI.

Custom Preview GUI with Timestamp Text Label

Documentation

Previewing Data

Introduction

Opening a Video Preview Window

Stopping the Preview Video Stream

Closing a Video Preview Window

Previewing Data in Custom GUIs

Performing Custom Processing of Previewed Data

Creating the Update Preview Window Function

Specifying the Update Preview Function

Image Acquisition Toolbox Documentation

Support