binocular_distance_msT_binocular_distance_msBinocularDistanceMsBinocularDistanceMs (Operator)

Name

binocular_distance_msT_binocular_distance_msBinocularDistanceMsBinocularDistanceMs — Compute the distance values for a rectified stereo image pair using multi-scanline optimization.

Signature

binocular_distance_ms(ImageRect1, ImageRect2 : Distance, Score : CamParamRect1, CamParamRect2, RelPoseRect, MinDisparity, MaxDisparity, SurfaceSmoothing, EdgeSmoothing, GenParamName, GenParamValue : )

Description

binocular_distance_msbinocular_distance_msBinocularDistanceMsBinocularDistanceMsBinocularDistanceMs computes the distance values for a rectified stereo image pair using multi-scanline optimization. The operator first calculates the disparities between two rectified images ImageRect1ImageRect1ImageRect1ImageRect1imageRect1 and ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 similar to binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMs. The resulting disparity values are then transformed into distance values of the corresponding 3D world points to the rectified stereo camera system as in disparity_to_distancedisparity_to_distanceDisparityToDistanceDisparityToDistanceDisparityToDistance. The distances are returned in the single-channel image DistanceDistanceDistanceDistancedistance in which each gray value represents the distance of the respective 3D world point to the stereo camera system.

binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMs requires a reference image ImageRect1ImageRect1ImageRect1ImageRect1imageRect1 and a search image ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 which both must be rectified, i.e., corresponding pixels must have the same row coordinate. If this assumption is violated, the images can be rectified by using the operators calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerasCalibrateCameras, gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMap, and map_imagemap_imageMapImageMapImageMapImage.

For the transformation of the disparity to the distance, the internal camera parameters of the rectified camera 1 CamParamRect1CamParamRect1CamParamRect1CamParamRect1camParamRect1 and of the rectified camera 2 CamParamRect2CamParamRect2CamParamRect2CamParamRect2camParamRect2, as well as the relative pose of the cameras RelPoseRectRelPoseRectRelPoseRectRelPoseRectrelPoseRect must be specified. The relative pose defines a point transformation from the rectified camera system 2 to the rectified camera system 1. These parameters can be obtained from the operators calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerasCalibrateCameras and gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMap.

A detailed description of the remaining parameters can be found in the documentation of binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMs.

Attention

If using cameras with telecentric lenses, the DistanceDistanceDistanceDistancedistance is not defined as the distance of a point to the camera but as the distance from the point to the plane, defined by the y-axes of both cameras and their baseline (see gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMap).

For a stereo setup of mixed type (i.e., for a stereo setup in which one of the original cameras is a perspective camera and the other camera is a telecentric camera; see gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMap), the rectifying plane of the two cameras is in a position with respect to the object that would lead to very unintuitive distances. Therefore, binocular_distance_msbinocular_distance_msBinocularDistanceMsBinocularDistanceMsBinocularDistanceMs does not support a stereo setup of mixed type. For stereo setups of mixed type, please use reconstruct_surface_stereoreconstruct_surface_stereoReconstructSurfaceStereoReconstructSurfaceStereoReconstructSurfaceStereo, in which the reference coordinate system can be chosen arbitrarily. Alternatively, binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMs and disparity_image_to_xyzdisparity_image_to_xyzDisparityImageToXyzDisparityImageToXyzDisparityImageToXyz might be used.

Additionally, stereo setups that contain cameras with and without hypercentric lenses at the same time are not supported.

Execution Information

Supports OpenCL compute devices.
Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Automatically parallelized on tuple level.
Automatically parallelized on internal data level.

Parameters

ImageRect1ImageRect1ImageRect1ImageRect1imageRect1 (input_object) singlechannelimage → object (byte*) *allowed for compute devices

Rectified image of camera 1.

ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 (input_object) singlechannelimage → object (byte*) *allowed for compute devices

Rectified image of camera 2.

DistanceDistanceDistanceDistancedistance (output_object) singlechannelimage → object (real)

Distance image.

ScoreScoreScoreScorescore (output_object) singlechannelimage → object (real)

Score of the calculated disparity.

CamParamRect1CamParamRect1CamParamRect1CamParamRect1camParamRect1 (input_control) campar → (real / integer / string)

Internal camera parameters of the rectified camera 1.

CamParamRect2CamParamRect2CamParamRect2CamParamRect2camParamRect2 (input_control) campar → (real / integer / string)

Internal camera parameters of the rectified camera 2.

RelPoseRectRelPoseRectRelPoseRectRelPoseRectrelPoseRect (input_control) pose → (real / integer)

Point transformation from the rectified camera 2 to the rectified camera 1.

Number of elements: 7

MinDisparityMinDisparityMinDisparityMinDisparityminDisparity (input_control) integer → (integer)

Minimum of the expected disparities.

Default value: -30

Typical range of values: -32768 ≤ MinDisparity MinDisparity MinDisparity MinDisparity minDisparity ≤ 32767

MaxDisparityMaxDisparityMaxDisparityMaxDisparitymaxDisparity (input_control) integer → (integer)

Maximum of the expected disparities.

Default value: 30

Typical range of values: -32768 ≤ MaxDisparity MaxDisparity MaxDisparity MaxDisparity maxDisparity ≤ 32767

Restriction: MinDisparity <= MaxDisparity

SurfaceSmoothingSurfaceSmoothingSurfaceSmoothingSurfaceSmoothingsurfaceSmoothing (input_control) integer → (integer)

Smoothing of surfaces.

Default value: 50

Suggested values: 20, 50, 100

Restriction: SurfaceSmoothing >= 0

EdgeSmoothingEdgeSmoothingEdgeSmoothingEdgeSmoothingedgeSmoothing (input_control) integer → (integer)

Smoothing of edges.

Default value: 50

Suggested values: 20, 50, 100

Restriction: EdgeSmoothing >= 0

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control) attribute.name(-array) → (string)

Parameter name(s) for the multi-scanline algorithm.

Default value: []

List of values: 'consistency_check'"consistency_check""consistency_check""consistency_check""consistency_check", 'disparity_offset'"disparity_offset""disparity_offset""disparity_offset""disparity_offset", 'num_levels'"num_levels""num_levels""num_levels""num_levels", 'similarity_measure'"similarity_measure""similarity_measure""similarity_measure""similarity_measure", 'sub_disparity'"sub_disparity""sub_disparity""sub_disparity""sub_disparity"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control) attribute.value(-array) → (string / integer)

Parameter value(s) for the multi-scanline algorithm.

Default value: []

Suggested values: 'census_dense'"census_dense""census_dense""census_dense""census_dense", 'census_sparse'"census_sparse""census_sparse""census_sparse""census_sparse", 'true'"true""true""true""true", 'false'"false""false""false""false"

Result

If the parameter values are correct, binocular_distance_msbinocular_distance_msBinocularDistanceMsBinocularDistanceMsBinocularDistanceMs returns the value 2 (H_MSG_TRUE). If the input is empty (no input images are available) the behavior can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>). If necessary, an exception is raised.