binocular_distance_msT_binocular_distance_msBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms (Operator)

Name

binocular_distance_msT_binocular_distance_msBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms — 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_msBinocularDistanceMsBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms computes the distance values for a rectified stereo image pair using multi-scanline optimization. The operator first calculates the disparities between two rectified images ImageRect1ImageRect1ImageRect1ImageRect1imageRect1image_rect_1 and ImageRect2ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 similar to binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMsbinocular_disparity_ms. 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_distanceDisparityToDistanceDisparityToDistanceDisparityToDistancedisparity_to_distance. The distances are returned in the single-channel image DistanceDistanceDistanceDistancedistancedistance in which each gray value represents the distance of the respective 3D world point to the stereo camera system.

binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMsbinocular_disparity_ms requires a reference image ImageRect1ImageRect1ImageRect1ImageRect1imageRect1image_rect_1 and a search image ImageRect2ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 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_camerasCalibrateCamerasCalibrateCamerasCalibrateCamerascalibrate_cameras, gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map, and map_imagemap_imageMapImageMapImageMapImagemap_image.

For the transformation of the disparity to the distance, the internal camera parameters of the rectified camera 1 CamParamRect1CamParamRect1CamParamRect1CamParamRect1camParamRect1cam_param_rect_1 and of the rectified camera 2 CamParamRect2CamParamRect2CamParamRect2CamParamRect2camParamRect2cam_param_rect_2, as well as the relative pose of the cameras RelPoseRectRelPoseRectRelPoseRectRelPoseRectrelPoseRectrel_pose_rect 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_camerasCalibrateCamerasCalibrateCamerasCalibrateCamerascalibrate_cameras and gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map.

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

Attention

If using cameras with telecentric lenses, the DistanceDistanceDistanceDistancedistancedistance 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_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map).

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_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map), 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_msBinocularDistanceMsBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms does not support a stereo setup of mixed type. For stereo setups of mixed type, please use reconstruct_surface_stereoreconstruct_surface_stereoReconstructSurfaceStereoReconstructSurfaceStereoReconstructSurfaceStereoreconstruct_surface_stereo, in which the reference coordinate system can be chosen arbitrarily. Alternatively, binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMsbinocular_disparity_ms and disparity_image_to_xyzdisparity_image_to_xyzDisparityImageToXyzDisparityImageToXyzDisparityImageToXyzdisparity_image_to_xyz 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

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

Rectified image of camera 1.

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

Rectified image of camera 2.

DistanceDistanceDistanceDistancedistancedistance (output_object) singlechannelimage → object (real)

Distance image.

ScoreScoreScoreScorescorescore (output_object) singlechannelimage → object (real)

Score of the calculated disparity.

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

Internal camera parameters of the rectified camera 1.

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

Internal camera parameters of the rectified camera 2.

RelPoseRectRelPoseRectRelPoseRectRelPoseRectrelPoseRectrel_pose_rect (input_control) pose → (real / integer)

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

Number of elements: 7

MinDisparityMinDisparityMinDisparityMinDisparityminDisparitymin_disparity (input_control) integer → (integer)

Minimum of the expected disparities.

Default value: -30

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

MaxDisparityMaxDisparityMaxDisparityMaxDisparitymaxDisparitymax_disparity (input_control) integer → (integer)

Maximum of the expected disparities.

Default value: 30

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

Restriction: MinDisparity <= MaxDisparity

SurfaceSmoothingSurfaceSmoothingSurfaceSmoothingSurfaceSmoothingsurfaceSmoothingsurface_smoothing (input_control) integer → (integer)

Smoothing of surfaces.

Default value: 50

Suggested values: 20, 50, 100

Restriction: SurfaceSmoothing >= 0

EdgeSmoothingEdgeSmoothingEdgeSmoothingEdgeSmoothingedgeSmoothingedge_smoothing (input_control) integer → (integer)

Smoothing of edges.

Default value: 50

Suggested values: 20, 50, 100

Restriction: EdgeSmoothing >= 0

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (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""consistency_check", 'disparity_offset'"disparity_offset""disparity_offset""disparity_offset""disparity_offset""disparity_offset", 'num_levels'"num_levels""num_levels""num_levels""num_levels""num_levels", 'similarity_measure'"similarity_measure""similarity_measure""similarity_measure""similarity_measure""similarity_measure", 'sub_disparity'"sub_disparity""sub_disparity""sub_disparity""sub_disparity""sub_disparity"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (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_dense", 'census_sparse'"census_sparse""census_sparse""census_sparse""census_sparse""census_sparse", 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"