video3d_stream_open :: Quanser C Functions

navigation bar

video3d_stream_open

Opens a video3d stream.

Description

The video3d_stream_open function opens a 3D video stream, such as RGB or depth. RGBD cameras typically can produce a number of video streams, such as RGB, depth and infrared streams. Each stream must be opened in order to use the stream. Multiple streams may be open at the same time, although for certain cameras some of the streams may be mutually exclusive, like depth and infrared streams.

The handle to the video stream returned by this function is used by the other 3D video stream functions in the Multimedia API to refer to the stream. This handle must be closed using the video3d_stream_close function when the stream is no longer in use.

Prototype

t_error
video3d_stream_open(t_video3d handle, t_video3d_stream_type type, t_uint index, t_double frame_rate, t_uint frame_width, t_uint frame_height, t_image_format format, t_image_data_type data_type, t_video3d_stream * stream);

Parameters

t_video3d handle

The handle to the 3D video capture session returned by video3d_open.

t_video3d_stream_type type

The type of video stream to open. Valid stream types are listed in the table below:

Stream Type	Description
VIDEO3D_STREAM_DEPTH	A depth stream containing information about the distance from the camera to the scene for each individual pixel. Depth data is typically presented as a 16-bit grayscale image where each pixel represents a scaled distance value.
VIDEO3D_STREAM_COLOR	A color image stream corresponding to an RGB sensor viewing the scene.
VIDEO3D_STREAM_INFRARED	A grayscale image stream representing an infrared sensor viewing the scene. Many RGBD cameras contain at least one infrared image sensor.
VIDEO3D_STREAM_FISHEYE	A grayscale image stream representing a fisheye image sensor viewing the scene. Many tracking cameras contain at least one fisheye image sensor.
VIDEO3D_STREAM_GYROSCOPE	A 3-DOF coordinate stream representing gyroscope data from an onboard inertial measurement unit (IMU).
VIDEO3D_STREAM_ACCELEROMETER	A 3-DOF coordinate stream representing accelerometer data from an onboard inertial measurement unit (IMU).
VIDEO3D_STREAM_POSE	A 6-DOF coordinate stream representing the pose of the camera derived from the cameras suite of sensors. Pose is typically provided by tracking cameras.

t_uint index

The index of the stream, used to distinguish multiple sensors of the same type within the device. Unfortunately, the index may be zero-based or one-based depending on the sensor type, since certain RGBD cameras are designed this way.

t_double frame_rate

A real number specifying the frame rate at which video input will be captured in Hertz. A value such as 30 Hz or 60 Hz is typical.

t_uint frame_width

The width of the image to be captured in pixels (number of columns).

t_uint frame_height

The height of the image to be captured in pixels (number of rows).

t_image_format format

The format in which to provide video data. Valid image formats are listed in the table below. The format used by MATLAB for colour images is IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB. This parameter is ignored for motion data, like the gyroscope, accelerometer or pose streams.

Format	Description
IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB	A column major, planar, image format for colour images. The red, green and blue components of the image are stored as separate image planes rather than being interleaved. Within each image plane, each column is stored sequentially in memory.
IMAGE_FORMAT_COL_MAJOR_GRAYSCALE	A column major image format for grayscale images. Each column is stored sequentially in memory.
IMAGE_FORMAT_ROW_MAJOR_INTERLEAVED_BGR	A row major BGR image format for colour images that is suitable for OpenCV CV_8UC3 matrices (image data type must be IMAGE_DATA_TYPE_UINT8 in this case). Each row is stored sequentially in memory.
IMAGE_FORMAT_ROW_MAJOR_GRAYSCALE	A row major image format for grayscale images that is suitable for OpenCV CV_8UC1 matrices (image data type must be IMAGE_DATA_TYPE_UINT8 in this case). Each row is stored sequentially in memory.

t_image_data_type data_type

The data type to use for each pixel component in the image. This parameter is typically IMAGE_DATA_TYPE_UINT8. The full set of possible data types is enumerated in the table below:

Data type	Description
IMAGE_DATA_TYPE_UINT8	Each pixel component is an unsigned byte (8-bit) or t_uint8. Hence, pixel values range from 0 to 255. This data type is typically used. Image processing operations on this data type generally have the highest performance.
IMAGE_DATA_TYPE_UINT16	Each pixel component is an unsigned short (16-bit) or t_uint16. Hence, pixel values range from 0 to 65535.
IMAGE_DATA_TYPE_UINT32	Each pixel component is an unsigned integer (32-bit) or t_uint32. Hence, pixel values range from 0 to 4294967295. Image processing operations on this data type are often slower than the `IMAGE_DATA_TYPE_SINGLE` data type.
IMAGE_DATA_TYPE_SINGLE	Each pixel component is a single-precision (32-bit) floating-point value or t_single. Pixel values range from 0 to 1. Pixel values outside that range are not supported.
IMAGE_DATA_TYPE_DOUBLE	Each pixel component is a double-precision (64-bit) floating-point value or t_double. Pixel values range from 0 to 1. Pixel values outside that range are not supported. This data type is not recommended as operations on this data type are generally slowest. Use `IMAGE_DATA_TYPE_SINGLE` or better yet the `IMAGE_DATA_TYPE_UINT8` data type instead.

t_video3d_stream * stream

The address of a t_video3d_stream variable in which the handle to the video stream will be stored. This handle is then passed to the other video3d stream functions to identify the stream.

Return value

The return value is 0 if the 3D video stream is opened successfully. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_IMAGE_STREAM_NOT_FOUND

The specified image stream could not be found. The stream type may not be supported by the camera or the stream index is too large.

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

QERR_OUT_OF_RANGE

The stream index was out of range for the number of streams available of the given type.

QERR_UNSUPPORTED_VIDEO_FORMAT

The video format is not supported. This may be due to the frame rate, frame size or native video formats of the device or source.

Requirements

Include Files	Libraries
quanser_video3d.h	quanser_media.lib;quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_video3d_stream stream;
t_error result;

result = video3d_stream_open(capture, VIDEO3D_STREAM_COLOR, 0, 30.0, 640, 480, IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB, IMAGE_DATA_TYPE_UINT8, &stream);
if (result >= 0) {
    ...
    video3d_stream_close(stream);
}