binocular_distance_mgT_binocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mg (Operator)

Name

binocular_distance_mgT_binocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mg — Compute the distance values for a rectified stereo image pair using multigrid methods.

Signature

binocular_distance_mg(ImageRect1, ImageRect2 : Distance, Score : CamParamRect1, CamParamRect2, RelPoseRect, GrayConstancy, GradientConstancy, Smoothness, InitialGuess, CalculateScore, MGParamName, MGParamValue : )

Description

binocular_distance_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mg computes the distance values for a rectified stereo image pair using multigrid methods. The operator first calculates the disparities between two rectified images ImageRect1ImageRect1ImageRect1imageRect1image_rect_1 and ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 similar to binocular_disparity_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgbinocular_disparity_mg. 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. Different from binocular_distancebinocular_distanceBinocularDistanceBinocularDistancebinocular_distance this operator uses a variational approach based on multigrid methods. This approach returns distance values also for image parts that contain no texture.

The input images ImageRect1ImageRect1ImageRect1imageRect1image_rect_1 and ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 must be a pair of rectified stereo images, i.e., corresponding points must have the same row coordinate. In case 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 algorithm and of the remaining parameters can be found in the documentation of binocular_disparity_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgbinocular_disparity_mg.

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_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mg 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_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgbinocular_disparity_mg 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

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(-array) → object (byte / uint2 / real)

Rectified image of camera 1.

ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 (input_object) singlechannelimage(-array) → object (byte / uint2 / real)

Rectified image of camera 2.

DistanceDistanceDistancedistancedistance (output_object) singlechannelimage(-array) → object (real)

Distance image.

ScoreScoreScorescorescore (output_object) singlechannelimage(-array) → object (real)

Score of the calculated disparity if CalculateScoreCalculateScoreCalculateScorecalculateScorecalculate_score is set to 'true'"true""true""true""true".

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

GrayConstancyGrayConstancyGrayConstancygrayConstancygray_constancy (input_control) real → (real)

Weight of the gray value constancy in the data term.

Default: 1.0

Suggested values: 0.0, 1.0, 2.0, 10.0

Restriction: GrayConstancy >= 0.0

GradientConstancyGradientConstancyGradientConstancygradientConstancygradient_constancy (input_control) real → (real)

Weight of the gradient constancy in the data term.

Default: 30.0

Suggested values: 0.0, 1.0, 5.0, 10.0, 30.0, 50.0, 70.0

Restriction: GradientConstancy >= 0.0

SmoothnessSmoothnessSmoothnesssmoothnesssmoothness (input_control) real → (real)

Weight of the smoothness term in relation to the data term.

Default: 5.0

Suggested values: 1.0, 3.0, 5.0, 10.0

Restriction: Smoothness > 0.0

InitialGuessInitialGuessInitialGuessinitialGuessinitial_guess (input_control) real → (real)

Initial guess of the disparity.

Default: 0.0

Suggested values: -30.0, -20.0, -10.0, 0.0, 10.0, 20.0, 30.0

CalculateScoreCalculateScoreCalculateScorecalculateScorecalculate_score (input_control) string → (string)

Should the quality measure be returned in ScoreScoreScorescorescore?

Default: 'false' "false" "false" "false" "false"

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

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

Parameter name(s) for the multigrid algorithm.

Default: 'default_parameters' "default_parameters" "default_parameters" "default_parameters" "default_parameters"

List of values: 'default_parameters'"default_parameters""default_parameters""default_parameters""default_parameters", 'initial_level'"initial_level""initial_level""initial_level""initial_level", 'iterations'"iterations""iterations""iterations""iterations", 'mg_cycle_type'"mg_cycle_type""mg_cycle_type""mg_cycle_type""mg_cycle_type", 'mg_post_relax'"mg_post_relax""mg_post_relax""mg_post_relax""mg_post_relax", 'mg_pre_relax'"mg_pre_relax""mg_pre_relax""mg_pre_relax""mg_pre_relax", 'mg_solver'"mg_solver""mg_solver""mg_solver""mg_solver", 'pyramid_factor'"pyramid_factor""pyramid_factor""pyramid_factor""pyramid_factor"

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

Parameter value(s) for the multigrid algorithm.

Default: 'fast_accurate' "fast_accurate" "fast_accurate" "fast_accurate" "fast_accurate"

Suggested values: 'very_accurate'"very_accurate""very_accurate""very_accurate""very_accurate", 'accurate'"accurate""accurate""accurate""accurate", 'fast_accurate'"fast_accurate""fast_accurate""fast_accurate""fast_accurate", 'fast'"fast""fast""fast""fast", 'v'"v""v""v""v", 'w'"w""w""w""w", 'none'"none""none""none""none", 'gauss_seidel'"gauss_seidel""gauss_seidel""gauss_seidel""gauss_seidel", 'multigrid'"multigrid""multigrid""multigrid""multigrid", 'full_multigrid'"full_multigrid""full_multigrid""full_multigrid""full_multigrid", 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, -1, -2, -3, -4, -5

Result

If the parameter values are correct, binocular_distance_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mg 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.