When you specify an image object to thepreviewfunction (see “Previewing Data in Custom GUIs” on page 2-13), you can optionally also specify a function thatpreviewexecutes every time it receives an image frame.
To use this capability, follow these steps:
1 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” on page 2-16.
2 Create an image object.
3 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” on page 2-17.
4 Call thepreviewfunction, 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 theCDataof 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
Whenpreviewcalls 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 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 theROIPositionproperty, and B is the number of color bands, as specified in theNumberOfBandsproperty
Resolution Text string specifying the current image width and height, as defined by the ROIPositionproperty
Status String describing the status of the video input object
event
Timestamp String specifying the time associated with the current image frame, in the format hh:mm:ss:ms
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 usesgetappdatato retrieve a handle to the text labeluicontrolobject from application-defined data in the image object. The custom GUI stores this handle to the text label uicontrolobject — see “Specifying the Update Preview Function” on page 2-17.
Note that the update preview window function also displays the video data by updating theCDataof 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.
set(ht,'String',tstampstr);
% Display image data.
set(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 thesetappdatafunction to configure this application-defined data to a function handle to the update preview window function described in “Creating the Update Preview Window Function” on page 2-16.
This example extends the simple custom preview window created in
“Previewing Data in Custom GUIs” on page 2-13. This example adds three push buttonuicontrolobjects 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 labeluicontrolobject to display the timestamp
value. The update preview window function updates this text label each time a framed is received. The example usessetappdatato store a handle to the text labeluicontrolobject 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',...
% 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 = get(vid, 'VideoResolution');
imWidth = vidRes(1);
imHeight = vidRes(2);
nBands = get(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);
set(gca,'unit','pixels',...
'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 timepreviewreceives 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