Convert Disparity to Height Image

Use this tool to convert a disparity image obtained from stereo sensors to a calibrated height image.

The tool "Convert Disparity to Height Image" computes the corresponding Z-coordinates of the disparity image and stores them as gray values.

Prerequisites

The stereo sensor must be conform to GenICam standards, e.g., those regarding multi-source devices. For a correct conversion of the disparity it is required to set the tool parameters for the coordinate scale, the focal length factor, and the baseline to the correct values. You can obtain the correct values for your images from the parameters of the camera that is used to acquire the images.

The tool was tested with a roboception rc_visard stereo sensor.

Querying the Required Parameter Values for the Conversion

The correct values for the tool parameters "Scan3dCoordinateScale", "Scan3dFocalLength", and "Scan3dBaseline" can be obtained from the configuration of your connected camera.

Querying the Values From the Image Source Manager

If you are using the Image Source Manager for the image acquisition, you can access the camera parameters in the configuration area of the Image Source Manager, i.e., in the "Image Sources" tab of the MERLIC RTE Setup.

  1. Open the "Image Sources" tab via the keyboard shortcut F7. Alternatively, open the MERLIC RTE Setup via the button "Runtime Environment Setup" in the MERLIC Creator menu and change to the "Image Sources" tab.
  2. Select the camera device in the list of image sources and activate the respective configuration to establish a connection to the camera. The camera parameters will be instantly displayed on the right of the "Image Sources" tab. If the camera has been added multiple times with different configuration, you have to activate the configuration that contains the camera with the desired configuration.
  3. Check the values of the respective camera parameters in the configuration area:
    • "Scan3dCoordinateScale"
    • "Scan3dFocalLength"
    • "Scan3dBaseline"
  4. Adopt the values of these camera parameters for the respective parameters of this tool, e.g., set the value of the tool parameter "Scan3dCoordinateScale" to the same value as the one that is given for the camera parameter "Scan3dCoordinateScale".
Querying the Values from the Tool "Acquire Image from Camera"

If you are using the tool Acquire Image from Camera for the image acquisition, you can check the parameter values directly in that tool.

  1. Go to the tool Acquire Image from Camera and make sure that the connection to the respective camera is activated.
  2. Open the configuration area on the left of the tool to display the camera parameters.
  3. Query the values of the respective camera parameters in the configuration area:
    • "Scan3dCoordinateScale"
    • "Scan3dFocalLength"
    • "Scan3dBaseline"
  4. Adopt the values of these camera parameters for the respective parameters of this tool, e.g., set the value of the tool parameter "Scan3dCoordinateScale" to the same value as the one that is given for the camera parameter "Scan3dCoordinateScale".

This requires that the camera is configured correctly to return disparity images. You can find additional information about 3D sensor specific configuration on our website.

If your camera follows a different naming convention or provides different parameters it may still be possible to query the necessary values. Example: The rc_visard stereo sensor provides a focal length factor via its various interfaces as well as a focal length in pixels. Both relate to the image width for supporting different image resolutions. The focal length in pixels can be obtained by multiplying the focal length factor by the image width in pixels. Refer to the documentation of your camera for more information.

Parameters

Basic Parameters

Disparity Image:

This parameter represents the disparity image to be converted.

Scan3dCoordinateScale:

This parameter defines a coordinate scale, i.e., the scale factor for transforming the pixels from relative coordinates to world coordinates. It must be set to a value greater than 0. By default, it is set to 0.0625. However, to make sure that the converted image is returned with the correct coordinates, you have to set the value for this parameter manually to the value that is given for the corresponding camera parameter "Scan3dCoordinateScale". This means that you have to check the value of this camera parameter in the configuration area of the respective image acquisition source that is used to acquire the images, i.e., the Image Source Manager or the tool Acquire Image from Camera, and set the same value for this parameter.

Scan3dFocalLength:

This parameter defines the focal length in pixel units. It must be set to a value greater than 0. By default, it is set to 540 pixel. However, to make sure that the converted image is returned with the correct coordinates, you have to set the value for this parameter manually to the value that is given for the corresponding camera parameter "Scan3dCoordinateScale". This means that you have to check the value of this camera parameter in the configuration area of the respective image acquisition source that is used to acquire the images, i.e., the Image Source Manager or the tool Acquire Image from Camera, and set the same value for this parameter.

Scan3dBaseline:

This parameter defines the baseline, i.e., the distance between the projection centers of the cameras. It must be set to a value greater than 0. By default, it is set to 0.065 meters. However, to make sure that the converted image is returned with the correct coordinates, you have to set the value for this parameter manually to the value that is given for the corresponding camera parameter "Scan3dBaseline". This means that you have to check the value of this camera parameter in the configuration area of the respective image acquisition source that is used to acquire the images, i.e., the Image Source Manager or the tool Acquire Image from Camera, and set the same value for this parameter.

Results

Basic Results

Calibrated Height Image:

This result represents the converted height image that can be used in subsequent tools for further processing. This height image is calibrated, i.e., its gray values represent height information in metric units.

Tool State:

"Tool State" returns information about the state of the tool and thus can be used for error handling. Please see the topic Tool State Result for more information about the different tool state results.

Additional Results

Processing Time:

This result returns the duration of the most recent execution of the tool in milliseconds. The result is provided as additional result. Therefore, it is hidden by default but it can be displayed via the button beside the tool results. For more information see the section Processing Time in the tool reference overview.

Application Examples

This tool is used in the following MERLIC Vision App examples:

  • check_correct_filling_on_3d_height_images.mvapp