Main Content

Using Properties on a VideoDevice System Object

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:

PropertyDescription
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.

obj.Device

shows the list of available devices for VideoDevice System object, obj.

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.

obj.VideoFormat

shows the list of available video formats.

DeviceFileName of file specifying video format. This property is only visible when VideoFormat is set to 'From device file'.
DevicePropertiesObject containing properties specific to the image acquisition device.

obj.DeviceProperties.<property_name> = 
    <property_value>

shows a device-specific property for VideoDevice System object, obj.

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], where x is x offset and y is y offset.

Note that this differs from the videoinput object and the From Video Device block, which are 0-based.

HardwareTriggeringTurn 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.
TriggerConfigurationSpecifies 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'. 

obj.TriggerConfiguration

shows the list of available hardware trigger configurations.

ReturnedColorSpaceSpecify 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

obj.ReturnedColorSpace

shows the list of available color space settings.

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

obj.BayerSensorAlignment

shows the list of available sensor alignments.

ReturnedDataTypeThe returned data type of the acquired frame. The default ReturnedDataType is single.

obj.ReturnedDataType

shows the list of available data types.

ReadAllFramesSpecify 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.

Note

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.

Once you have created a VideoDevice System object, you can set either object-level properties or device-specific properties on it.

To set an object-level property, use this syntax:

vidobj.ReturnedColorSpace = 'grayscale';

You can see that the syntax for setting an object-level property is to use <object_name>.<property_name> = <property_value>, where the value may be a character vector or a numeric.

Another example of an object-level property is setting the region-of-interest, or ROI, to change the dimensions of the acquired image. The ROI format is specified in pixels in a 1-by-4 element vector [x y width height].

vidobj.ROI = [1 1 200 200];

Note

This ROI value is 1-based. This differs from the videoinput object and the From Video Device block, which are 0-based.

To set a device-specific property, use this syntax:

vidobj.DeviceProperties.Brightness = 150;

You can see that the syntax for setting a device-specific property is to use dot notation with the object name, the DeviceProperties object, and the property name and then make it equal to the property value.

Another example of a device-specific property is setting the frame rate for a device that supports it.

vidobj.DeviceProperties.FrameRate = '30';

Note

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.