imaq.VideoDevice

Acquire one frame at a time from video device

Syntax

obj = imaq.VideoDevice
obj = imaq.VideoDevice(adaptorname)
obj = imaq.VideoDevice(adaptorname, deviceid)
obj = imaq.VideoDevice(adaptorname, deviceid, format)
obj = imaq.VideoDevice(adaptorname, deviceid, format, P1, V1, ...)
frame = step(obj)
[frame metadata] = step(obj)


Description

The VideoDevice System object™ allows single-frame image acquisition and code generation from MATLAB^®. You use the imaq.VideoDevice function to create the System object. It supports the same adaptors and hardware that the videoinput object supports; however, it has different functions and properties associated with it. For example, the System object uses the step function to acquire single frames.

obj = imaq.VideoDevice creates a VideoDevice System object, obj, that acquires images from a specified image acquisition device. When you specify no parameters, by default, it selects the first available device for the first adaptor returned by imaqhwinfo.

obj = imaq.VideoDevice(adaptorname) creates a VideoDevice System object, obj, using the first device of the specified adaptorname. adaptorname is a character vector that specifies the name of the adaptor used to communicate with the device. Use the imaqhwinfo function to determine the adaptors available on your system.

obj = imaq.VideoDevice(adaptorname, deviceid) creates a VideoDevice System object, obj, with the default format for specified adaptorname and deviceid. deviceid is a numeric scalar value that identifies a particular device available through the specified adaptorname. Use the imaqhwinfo(adaptorname) syntax to determine the devices available and corresponding values for deviceid.

obj = imaq.VideoDevice(adaptorname, deviceid, format) creates a VideoDevice System object, obj, where format is a character vector that specifies a particular video format supported by the device or a device configuration file (also known as a camera file).

obj = imaq.VideoDevice(adaptorname, deviceid, format, P1, V1, ...) Creates a VideoDevice System object, obj, with the specified property values. If an invalid property name or property value is specified, the object is not created.

Specifying properties at the time of object creation is optional. They can also be specified after the object is created. See the table below for a list of applicable properties.

frame = step(obj) acquires a single frame from the VideoDevice System object, obj.

[frame metadata] = step(obj) acquires a single image frame from the VideoDevice System object, obj, plus metadata from the Kinect^® for Windows^® Depth sensor. You can return Kinect for Windows skeleton data using the VideoDevice System object on the Kinect Depth sensor. For information on how to do this, see Kinect for Windows Metadata.

Properties

You can specify properties at the time of object creation, or they can be specified and changed after the object is created. Properties that can be used with the VideoDevice System object include:

Property	Description
Device	Device from which to acquire images. Specify the image acquisition device to use to acquire a frame. It consists of the device name, adaptor, and device ID. The default device is the first device returned by imaqhwinfo.
VideoFormat	Video format to be used by the image acquisition device. Specify the video format to use while acquiring the frame. The default value of VideoFormat is the default format returned by imaqhwinfo for the selected device. To specify a Video Format using a device file, set the VideoFormat property to 'From device file' This option exists only if your device supports device configuration files.
DeviceFile	Name of file specifying video format. This property is only visible when VideoFormat is set to 'From device file'.
DeviceProperties	Object containing properties specific to the image acquisition device.
ROI	Region-of-interest for acquisition. This is set to the default ROI value for the specified device, which is the maximum resolution possible for the specified format. You can change the value to change the size of the captured image. The format is 1-based, that is, it is specified in pixels in a 1-by-4 element vector [x y width height]. Note that this differs from the videoinput object and the From Video Device block, which are 0-based.
HardwareTriggering	Turn hardware triggering on/off. Set this property to 'on' to enable hardware triggering to acquire images. The property is visible only when the device supports hardware triggering.
TriggerConfiguration	Specifies the trigger source and trigger condition before acquisition. The triggering condition must be met via the trigger source before a frame is acquired. This property is visible only when HardwareTriggering is set to 'on'.
ReturnedColorSpace	Specify the color space of the returned image. The default value of the property depends on the device and the video format selected. Possible values are {rgb|grayscale|YCbCr} when the default returned color space for the device is not grayscale. Possible values are {rgb|grayscale|YCbCr|bayer} when the default returned color space for the device is grayscale.
BayerSensorAlignment	Character vector indicating the 2x2 sensor alignment. Specifies Bayer patterns returned by hardware. Specify the sensor alignment for Bayer demosaicing. The default value of this property is 'grbg'. Possible values are {grbg|gbrg|rggb|bggr}. Visible only if ReturnedColorSpace is set to 'bayer'.
ReturnedDataType	The returned data type of the acquired frame. The default ReturnedDataType is single.
ReadAllFrames	Specify whether to read one image frame or all available frames. Set to 'on' to capture all available image frames. When set to the default of 'off', the system object takes a snapshot of one frame, which is the equivalent of the getsnapshot function in the toolbox. When the option is on, all available image frames are captured, which is the equivalent of the getdata function in the toolbox.

The setting of properties for the System object supports tab completion for enumerated properties while coding in MATLAB. Using the tab completion is an easy way to see available property values. After you type the property name, type a comma, then a space, then the first quote mark for the value, then hit tab to see the possible values.

You can also use the set function with the object name and property name to get a list of available values for that property. For example:

set(obj, 'ReturnedColorSpace')

gets the list of available color space settings for the VideoDevice System object, obj.

Note that once you have done a step, in order to change a property or set a new one, you need to release the object using the release function, before setting the new property.

Note

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.

Functions

You can use these functions with the VideoDevice System object.

Function	Purpose
step	Acquire a single frame from the image acquisition device. frame = step(obj); acquires a single frame from the VideoDevice System object, obj. Note that the first time you call step, it acquires exclusive use of the hardware and will start streaming data.
release	Release VideoDevice resources and allow property value changes. release(obj) releases system resources (such as memory, file handles, or hardware connections) of System object, obj, and allows all its properties and input characteristics to be changed.
isLocked	Returns a value that indicates if the VideoDevice resource is locked. (Use release to unlock.) L = isLocked(obj) returns a logical value, L, which indicates whether properties are locked for the System object, obj. The object performs an internal initialization the first time the step function is executed. This initialization locks properties and input specifications. Once this occurs, the isLocked function returns a value of true.
preview	Activate a live image preview window. preview(obj) creates a Video Preview window that displays live video data for the VideoDevice System object, 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 VideoDevice System object ROI property. If not specified, it uses the default resolution for the device.
closepreview	Close live image preview window. closepreview(obj) closes the live preview window for VideoDevice System object, obj.
imaqhwinfo	Returns information about the object. imaqhwinfo(obj) displays information about the VideoDevice System object, obj.

Examples

Construct a VideoDevice System object associated with the Winvideo adaptor with device ID of 1.

vidobj = imaq.VideoDevice('winvideo', 1);

Set an object-level property, such as ReturnedColorSpace. The syntax for an object-level property uses the object name, property name, and property value.

vidobj.ReturnedColorSpace = 'grayscale';

Set a device-specific property, such as Brightness. The syntax for a device-specific property uses the DeviceProperties object, the property name, and property value.

vidobj.DeviceProperties.Brightness = 150;

Preview the image.

preview(vidobj)

Acquire a single frame.

frame = step(vidobj);

Display the acquired frame.

imshow(frame)

Release the hardware resource.

release(vidobj);

Clear the VideoDevice System object.

clear vidobj;

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

See Code Generation with VideoDevice System Object.

Version History

Introduced in R2012a