imaq.VideoDevice

Acquire one frame at a time from video device

expand all in page

Description

The imaq.VideoDevice System object™ allows single-frame image acquisition and code generation from MATLAB®. It supports the same adaptors and hardware that the videoinput object supports; however, it has different functions and properties associated with it.

To acquire single frames from video device:

  1. Create the imaq.VideoDevice object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

vidObj = imaq.VideoDevice
vidObj = imaq.VideoDevice(adaptorname)
vidObj = imaq.VideoDevice(adaptorname, deviceid)
vidObj = imaq.VideoDevice(adaptorname, deviceid, format)
vidObj = imaq.VideoDevice(adaptorname, deviceid, format, P1, V1, ...)

Description

vidObj = imaq.VideoDevice creates an imaq.VideoDevice System object, vidObj, 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 the imaqhwinfo function.

vidObj = imaq.VideoDevice(adaptorname) creates an imaq.VideoDevice System object, vidObj, 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.

vidObj = imaq.VideoDevice(adaptorname, deviceid) creates an imaq.VideoDevice System object, vidObj, 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.

vidObj = imaq.VideoDevice(adaptorname, deviceid, format) creates an imaq.VideoDevice System object, vidObj, 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).

example

vidObj = imaq.VideoDevice(adaptorname, deviceid, format, P1, V1, ...) Creates an imaq.VideoDevice System object, vidObj, 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.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Device from which to acquire images, specified as a character vector. It consists of the device name, adaptor, and device ID. The default device is the first device returned by the imaqhwinfo function.

Video format to be used by the image acquisition device, specified as a character vector. 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.

Name of file specifying video format, specified as a character vector.

Dependencies

To enable this property, set the VideoFormat property to 'From device file'.

Properties specific to the image acquisition device, specified as an object.

Region-of-interest for acquisition, specified as an 1-by-4 vector in the format of [x y width height]. 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. Note that this differs from the videoinput object and the From Video Device block, which are 0-based.

Enable hardware triggering to acquire images, specified as 'off' or 'on'. This property is visible only when the device supports hardware triggering.

Trigger source and trigger condition before acquisition, specified as a character vector. The triggering condition must be met via the trigger source before a frame is acquired.

Dependencies

To enable this property, set the HardwareTriggering property to 'on'.

Color space of the returned image, specified as a character vector. 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.

Bayer patterns for sensor alignment returned by the hardware, specified as a 2-by-2 character array. Specify the sensor alignment for Bayer demosaicing.

The returned data type of the acquired frame, specified as a character vector.

Enable reading all available frames, specified as 'off' or 'on'. Set to 'on' to capture all available image frames. When set to the default of 'off', the imaq.VideoDevice takes a snapshot of one frame, which is the equivalent of the getsnapshot function. When the option is 'on', all available image frames are captured, which is the equivalent of the getdata function.

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(vidObj, 'ReturnedColorSpace')

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

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.

Usage

Syntax

frame = vidObj()
[frame metadata] = vidObj()

Description

frame = vidObj() acquires a single frame from the imaq.VideoDevice System object, vidObj. To change a property after calling vidObj, you must first release the VideoDevice using the release function. To reset the internal states of vidObj, use the reset function.

Note

The first time you call imaq.VideoDevice, it acquires exclusive use of the hardware and will start streaming data.

example

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

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

previewPreview of live video data
closepreviewClose video preview window
imaqhwinfoDisplay information about available image acquisition hardware
isLockedDetermine if System object is in use
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Open Live Script

Construct a VideoDevice System object associated with the Winvideo adaptor with a deviceID of 2 and a format of RGB24_800X600. Use your own adaptorname, deviceID and format when executing the command. To check the available adaptors and devices on your system, you can optionally use the imaqhwinfo function first.

imaqhwinfo % Check the available adaptors.
ans = struct with fields:
    InstalledAdaptors: {'demo'  'gentl'  'gige'  'kinect'  'matrox'  'winvideo'}
        MATLABVersion: '25.1 (R2025a)'
          ToolboxName: 'Image Acquisition Toolbox'
       ToolboxVersion: '25.1 (R2025a)'


info = imaqhwinfo('winvideo');
info.DeviceInfo(2).SupportedFormats % Check the supported format.
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'}


vidobj = imaq.VideoDevice('winvideo', 2, 'RGB24_800X600');

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

vidobj.ReturnedColorSpace = 'rgb';
vidobj.ROI = [300 1 400 600];

Preview the image.

preview(vidobj)

Close live image preview window.

closepreview(vidobj)

Acquire five frames.

frame = cell(3,1);
for i = 1:5
    frame{i} = vidobj();
end

Display the last acquired frame.

imshow(frame{5});

Figure contains an axes object. The hidden axes object contains an object of type image.

Release the hardware resource.

release(vidobj);

Clear the VideoDevice System object.

clear vidobj;

Extended Capabilities

expand all

Version History

Introduced in R2012a

See Also

Functions