Using VideoDevice System Object to Acquire Frames

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

The basic workflow for using the VideoDevice System object is to create the object, preview the image, set any properties, acquire a frame, and clear the object, as shown here.

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.
```
vidobj.ReturnedColorSpace = 'grayscale';
```
Note that the syntax for setting an object-level property is <object_name>.<property_name> = <property_value>, where the value can be a character vector or a numeric.
Set a device-specific property, such as Brightness.
```
vidobj.DeviceProperties.Brightness = 150;
```
Note that the syntax for setting a device-specific property is to list the object name, the DeviceProperties object, and the property name using dot notation, and then make it equal to the property value.
Preview the image.
```
preview(vidobj)
```
Acquire a single frame using the step function.
```
frame = step(vidobj);
```
Display the acquired frame.
```
imshow(frame)
```
Release the hardware resource.
```
release(vidobj);
```
Clear the VideoDevice System object.
```
clear vidobj;
```

Kinect for Windows Metadata

You can return Kinect^® for Windows^® skeleton data using the VideoDevice System object on the Kinect Depth sensor.

Typically in the Image Acquisition Toolbox™, each camera or image device has one device ID. Because the Kinect for Windows camera has two separate sensors, the Color sensor and the Depth sensor, the toolbox lists two device IDs. The Kinect Color sensor is device 1 and the Kinect depth sensor is device 2.

This example uses a Kinect V1 device. The toolbox also supports Kinect V2. For information on the properties and metadata of Kinect V2 devices, install the Image Acquisition Toolbox Support Package for Kinect For Windows Sensor and see the “Acquire Images with Kinect V2” section in the documentation.

To create a System object using the Color sensor:

vidobjcolor = imaq.VideoDevice('kinect', 1);

To create a System object using the Depth sensor:

vidobjdepth = imaq.VideoDevice('kinect', 2);

The Depth sensor returns skeleton metadata. To access this, you need to add a second output argument for the step function. The Color sensor works the same way as other devices. So acquiring a frame using the Kinect Color sensor is done as shown here:

imageData = step(vidobjcolor);

where imageData is the frame acquired if vidobjcolor is a System object created with Device 1, the Kinect Color sensor.

The Kinect Depth sensor requires a second output argument, as shown here:

[depthData metadata] = step(vidobjdepth);

where depthData is the frame acquired if vidobjdepth is a System object created with Device 2, the Kinect Depth sensor, and metadata is the skeleton metadata returned with the frame.

These metadata fields are related to tracking the skeletons. The metadata is returned as a structure that contains these parameters:

    IsPositionTracked
    IsSkeletonTracked
    JointDepthIndices
    JointImageIndices
    JointTrackingState
    JointWorldCoordinates
    PositionDepthIndices
    PositionImageIndices
    PositionWorldCoordinates
    SegmentationData
    SkeletonTrackingID

You can then look at both outputs. To see the image frame:

imshow(imageData)

To see the metadata output:

metadata

Note

The Kinect for Windows Depth sensor may take some seconds to be ready to begin acquiring skeletal metadata. In order to see values in the metadata output, you need to acquire multiple frames using the step function repeatedly. You can do this by using a for loop.

Note

By default the System object returns data as single precision values with the range 0.0 to 1.0. The value represents the fraction through the sensor’s dynamic range. The Kinect depth sensor has a range of 0 to 8192 mm.

Acquire Image and Body Data Using Kinect V2 is an example that shows how to access the skeletal metadata using the videoinput object (not the VideoDevice System object), and it contains information about the properties you can set on both the Color and Depth sensors, and descriptions of all the metadata fields. The property names and values are the same as they would be for the System object, but you would then need to set the properties as shown in step 3 of the above example (in the current topic) for use with the VideoDevice System object.