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_msBinocularDistanceMsBinocularDistanceMsbinocular_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 ImageRect1ImageRect1ImageRect1imageRect1image_rect_1 and ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 similar to binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsbinocular_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_distanceDisparityToDistanceDisparityToDistancedisparity_to_distance. 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_msBinocularDisparityMsBinocularDisparityMsbinocular_disparity_ms requires a reference image ImageRect1ImageRect1ImageRect1imageRect1image_rect_1 and a search image ImageRect2ImageRect2ImageRect2imageRect2image_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_camerasCalibrateCamerasCalibrateCamerascalibrate_cameras, gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map, and map_imagemap_imageMapImageMapImagemap_image.

For the transformation of the disparity to the distance, the internal camera parameters of the rectified camera 1 CamParamRect1CamParamRect1CamParamRect1camParamRect1cam_param_rect_1 and of the rectified camera 2 CamParamRect2CamParamRect2CamParamRect2camParamRect2cam_param_rect_2, as well as the relative pose of the cameras RelPoseRectRelPoseRectRelPoseRectrelPoseRectrel_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_camerasCalibrateCamerasCalibrateCamerascalibrate_cameras and gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map.

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

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_mapGenBinocularRectificationMapGenBinocularRectificationMapgen_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_mapGenBinocularRectificationMapGenBinocularRectificationMapgen_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_msBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms does not support a stereo setup of mixed type. For stereo setups of mixed type, please use reconstruct_surface_stereoreconstruct_surface_stereoReconstructSurfaceStereoReconstructSurfaceStereoreconstruct_surface_stereo, in which the reference coordinate system can be chosen arbitrarily. Alternatively, binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsbinocular_disparity_ms and disparity_image_to_xyzdisparity_image_to_xyzDisparityImageToXyzDisparityImageToXyzdisparity_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

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

Rectified image of camera 1.

ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 (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.

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

Internal camera parameters of the rectified camera 1.

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

Internal camera parameters of the rectified camera 2.

RelPoseRectRelPoseRectRelPoseRectrelPoseRectrel_pose_rect (input_control) pose → (real / integer)

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

Number of elements: 7

MinDisparityMinDisparityMinDisparityminDisparitymin_disparity (input_control) integer → (integer)

Minimum of the expected disparities.

Default: -30

Value range: -32768 ≤ MinDisparity MinDisparity MinDisparity minDisparity min_disparity ≤ 32768

Restriction: MinDisparity <= MaxDisparity

MaxDisparityMaxDisparityMaxDisparitymaxDisparitymax_disparity (input_control) integer → (integer)

Maximum of the expected disparities.

Default: 30

Value range: -32768 ≤ MaxDisparity MaxDisparity MaxDisparity maxDisparity max_disparity ≤ 32768

Restriction: MinDisparity <= MaxDisparity

SurfaceSmoothingSurfaceSmoothingSurfaceSmoothingsurfaceSmoothingsurface_smoothing (input_control) integer → (integer)

Smoothing of surfaces.

Default: 50

Suggested values: 20, 50, 100

Restriction: SurfaceSmoothing >= 0

EdgeSmoothingEdgeSmoothingEdgeSmoothingedgeSmoothingedge_smoothing (input_control) integer → (integer)

Smoothing of edges.

Default: 50

Suggested values: 20, 50, 100

Restriction: EdgeSmoothing >= 0

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

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

Default: []

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"

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

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

Default: []

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_msBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms 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>)set_system("no_object_result",<Result>). If necessary, an exception is raised.