GigE Vision 2.0/GenICam image interface

Gigabit Ethernet for Machine Vision (“GigE Vision®” for short) is an industrial camera interface standard based on UDP/IP (see http://www.gigevision.com). The rc_visard is a GigE Vision® version 2.0 device and is hence compatible with all GigE Vision® 2.0 compliant frameworks and libraries.

GigE Vision® uses GenICam to describe the camera/device features. For more information about this Generic Interface for Cameras see http://www.genicam.org/.

Via this interface the rc_visard provides features such as

  • discovery,
  • IP configuration,
  • configuration of camera related parameters,
  • image grabbing, and
  • time synchronization via IEEE 1588-2008 PrecisionTimeProtocol (PTPv2).

Note

The rc_visard supports jumbo frames of up to 9000 bytes. Setting an MTU of 9000 on your GigE Vision client side is recommended for best performance.

Note

Roboception provides tools and a C++ API with examples for discovery, configuration, and image streaming via the GigE Vision/GenICam interface. See http://www.roboception.com/download.

Important GenICam parameters

The following list gives an overview of the relevant GenICam features of the rc_visard that can be read and/or changed via the GenICam interface. In addition to the standard parameters, which are defined in the Standard Feature Naming Convention (SFNC, see http://www.emva.org/standards-technology/genicam/genicam-downloads/), rc_visard devices also offer custom parameters that account for special features of the Stereo camera and the Stereo matching component.

Important standard GenICam features

ComponentSelector
  • type: Enumeration, one of Intensity, IntensityCombined, Disparity, Confidence, or Error
  • default: -
  • description: Allows the user to select one of the five image streams for configuration (see Provided image streams).
ComponentIDValue (read-only)
  • type: Integer
  • description: The ID of the image stream selected by the ComponentSelector.
ComponentEnable
  • type: Boolean
  • default: -
  • description: If set to true, it enables the image stream selected by ComponentSelector; otherwise, it disables the stream. Using ComponentSelector and ComponentEnable, individual image streams can be switched on and off.
Width, WidthMax (read-only)
  • type: Integer
  • description: Maximum width of an image, which is always 1280 pixels.
Height, HeightMax (read-only)
  • type: Integer
  • description: Maximum height of an image in the streams. This is always 1920 pixels due to the stacked left and right images in the IntensityCombined stream (see Provided image streams).
PixelFormat
  • type: Enumeration, Mono8 or YCbCr411_8 (color sensors only)
  • description: Pixel format of the left and right rectified images that are returned in the components Intensity and IntensityCombined. The YCbCr411_8 format is only available for color cameras.
AcquisitionFrameRate
  • type: Float, ranges from 1 Hz to 25 Hz
  • default: 25 Hz
  • description: Frame rate of the camera (FPS).
ExposureAuto
  • type: Enumeration, one of Continuous or Off
  • default: Continuous
  • description: Can be set to Off for manual exposure mode or to Continuous for auto exposure mode (Exposure).
ExposureTime
  • type: Float, ranges from 66 µs to 18000 µs
  • default: 5000 µs
  • description: The cameras’ exposure time in microseconds for the manual exposure mode (Manual).
GainSelector (read-only)
  • type: Enumeration, is always All
  • default: All
  • description: The rc_visard currently supports only one overall gain setting.
Gain
  • type: Float, ranges from 0 dB to 18 dB
  • default: 0 dB
  • description: The cameras’ gain value in decibel that is used in manual exposure mode (Gain).
BalanceWhiteAuto (color sensors only)
  • type: Enumeration, one of Continuous or Off
  • default: Continuous
  • description: Can be set to Off for manual white balancing mode or to Continuous for auto white balancing. This feature is only available on color sensors (wb_auto).
BalanceRatioSelector (color sensors only)
  • type: Enumeration, one of Red or Blue
  • default: Red
  • description: Selects ratio to be modified by BalanceRatio. Red means red to green ratio and Blue means blue to green ratio. This feature is only available on color sensors.
BalanceRatio (color sensors only)
  • type: Float, ranges from 0.125 to 8
  • default: 1.2 if Red and 2.4 if Blue is selected in BalanceRatioSelector
  • description: Weighting of red or blue to green color channel. This feature is only available on color sensors (wb_ratio).
GevIEEE1588
  • type: Boolean
  • default: false
  • description: Switches PTP synchronization on and off.
Scan3dDistanceUnit (read-only)
  • type: Enumeration, is always Pixel
  • description: Unit for the disparity measurements, which is always Pixel.
Scan3dOutputMode (read-only)
  • type: Enumeration, is always DisparityC
  • description: Mode for the depth measurements, which is always DisparityC.
Scan3dCoordinateScale (read-only)
  • type: Float
  • description: The scale factor that has to be multiplied with the disparity values in the disparity image stream to get the actual disparity measurements. This value is always 0.0625.
Scan3dCoordinateOffset (read-only)
  • type: Float
  • description: The offset that has to be added to the disparity values in the disparity image stream to get the actual disparity measurements. However, this value is always 0 and can therefore be disregarded.
Scan3dInvalidDataFlag (read-only)
  • type: Boolean
  • description: Is always true, which means that invalid data in the disparity image is marked by a specific value defined by the Scan3dInvalidDataValue parameter.
Scan3dInvalidDataValue (read-only)
  • type: Float
  • description: Is the value which stands for invalid disparity. This value is always 0, which means that disparity values of 0 correspond to invalid measurements. To distinguish between invalid disparity measurements and disparity measurements of 0 for objects which are infinitely far away, we set the disparity value for the latter to the smallest possible disparity value of 0.0625. This still corresponds to an object distance of several hundred meters.

Custom GenICam features of the rc_visard

ExposureTimeAutoMax
  • type: Float, ranges from 66 µs to 18000 µs
  • default: 7000 µs
  • description: Maximal exposure time in auto exposure mode (Auto).
FocalLengthFactor (read-only)
  • type: Float
  • description: The focal length scaled to an image width of 1 pixel. To get the focal length in pixels for a certain image, this value must be multiplied by the width of the received image.
Baseline (read-only)
  • type: Float
  • description: The distance in meters between the left and the right camera.
DepthQuality
  • type: Enumeration, one of Low, Medium, High, or StaticHigh
  • default: High
  • description: Quality of the disparity images. Lower quality results in disparity images with lower resolution (Quality).
DepthDispRange
  • type: Integer, ranges from 32 pixels to 512 pixels
  • default: 256 pixels
  • description: Maximum disparity value in pixels (Disparity Range).
DepthFill
  • type: Integer, ranges from 0 pixel to 4 pixels
  • default: 3 pixels
  • description: Value in pixels for Fill-In.
DepthSeg
  • type: Integer, ranges from 0 pixel to 4000 pixels
  • default: 200 pixels
  • description: Value in pixels for Segmentation.
DepthMedian
  • type: Integer, ranges from 1 pixel to 5 pixels
  • default: 1 pixel
  • description: Value in pixels for Median filter smoothing.
DepthMinConf
  • type: Float, ranges from 0.0 to 1.0
  • default: 0.0
  • description: Value for Minimum Confidence filtering.
DepthMinDepth
  • type: Float, ranges from 0.1 m to 100.0 m
  • default: 0.1 m
  • description: Value in meters for Minimum Distance filtering.
DepthMaxDepth
  • type: Float, ranges from 0.1m to 100.0 m
  • default: 100.0 m
  • description: Value in meters for Maximum Distance filtering.
DepthMaxDepthErr
  • type: Float, ranges from 0.01 m to 100.0 m
  • default: 100.0 m
  • description: Value in meters for Maximum Depth Error filtering.

Provided image streams

The rc_visard provides the following five different image streams via the GenICam interface:

Component name PixelFormat Width×Height Description
Intensity
Mono8 (monochrome sensors)
YCbCr411_8 (color sensors)
 1280×960 Left rectified camera image
IntensityCombined
Mono8 (monochrome sensors)
YCbCr411_8 (color sensors)
 1280×1920 Left rectified camera image stacked on right rectified camera image
Disparity Coord3D_C16
640×480
320×240
214×160
 Disparity image in desired resolution, i.e., High, Medium, or Low
Confidence Confidence8 same as Disparity Confidence image
Error custom: 0x81080001 same as Disparity Disparity error image

Each image comes with a buffer timestamp and the PixelFormat given in the above table. This PixelFormat should be used to distinguish between the different image types. Images belonging to the same acquisition timestamp can be found by comparing the GenICam buffer timestamps.

Image stream conversions

The disparity image contains 16 bit unsigned integer values. These values must be multiplied by the scale value given in the GenICam feature Scan3dCoordinateScale to get the disparity values \(d\) in pixels. To compute the 3D object coordinates from the disparity values, the focal length and the baseline are required. These parameters are transmitted as GenICam features FocalLengthFactor and Baseline. The FocalLengthFactor value has to be multiplied by the width of the disparity image to get the focal length \(f\) in pixels for the given disparity image resolution. Knowing these values, the pixel coordinates and the disparities can be transformed into 3D object coordinates in the sensor coordinate frame (see Coordinate frames) using the equations described in Computing depth images and point clouds.

Assuming that \(d_{ik}\) is the 16 bit disparity value at column \(i\) and row \(k\) of a disparity image with \(w\) columns and \(h\) rows, the 3D reconstruction in meters can be written with the GenICam parameters as

\[\begin{split}P_x&=\left(i-\frac{w}{2}\right) \frac{\mathrm{Baseline}}{d_{ik} \cdot \mathrm{Scan3dCoordinateScale}},\\ P_y&=\left(k-\frac{h}{2}\right) \frac{\mathrm{Baseline}}{d_{ik} \cdot \mathrm{Scan3dCoordinateScale}},\\ P_z&=\left(\mathrm{FocalLengthFactor} \cdot w \right) \frac{\mathrm{Baseline}}{d_{ik} \cdot \mathrm{Scan3dCoordinateScale}}.\end{split}\]

The confidence image contains 8 bit unsigned integer values. These values have to be divided by 255 to get the confidence as value between 0 an 1.

The error image contains 8 bit unsigned integer values. The error \(e_{ik}\) must be multiplied by the scale value given in the GenICam feature Scan3dCoordinateScale to get the disparity-error values \(d_{eps}\) in pixels. According to the description in Confidence and error images, the depth error \(z_{eps}\) in meters can be computed with GenICam parameters as

\[z_{eps}=\frac{e_{ik} \cdot \mathrm{Scan3dCoordinateScale} \cdot \mathrm{FocalLengthFactor} \cdot w \cdot \mathrm{Baseline}} {(d_{ik} \cdot \mathrm{Scan3dCoordinateScale})^2}.\]

For more information about disparity, error, and confidence images, please refer to Stereo matching.