binocular_distance_mgT_binocular_distance_mgBinocularDistanceMgBinocularDistanceMg (Operator)

Name

binocular_distance_mgT_binocular_distance_mgBinocularDistanceMgBinocularDistanceMg — 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_mgBinocularDistanceMgBinocularDistanceMgBinocularDistanceMg computes the distance values for a rectified stereo image pair using multigrid methods. The operator first calculates the disparities between two rectified images ImageRect1ImageRect1ImageRect1ImageRect1imageRect1 and ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 similar to binocular_disparity_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgBinocularDisparityMg. 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. Different from binocular_distancebinocular_distanceBinocularDistanceBinocularDistanceBinocularDistance 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 ImageRect1ImageRect1ImageRect1ImageRect1imageRect1 and ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 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_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 algorithm and of the remaining parameters can be found in the documentation of binocular_disparity_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgBinocularDisparityMg.

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_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgBinocularDistanceMg 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_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgBinocularDisparityMg 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

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

Rectified image of camera 1.

ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 (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 CalculateScoreCalculateScoreCalculateScoreCalculateScorecalculateScore is set to 'true'"true""true""true""true".

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

GrayConstancyGrayConstancyGrayConstancyGrayConstancygrayConstancy (input_control) real → (real)

Weight of the gray value constancy in the data term.

Default value: 1.0

Suggested values: 0.0, 1.0, 2.0, 10.0

Restriction: GrayConstancy >= 0.0

GradientConstancyGradientConstancyGradientConstancyGradientConstancygradientConstancy (input_control) real → (real)

Weight of the gradient constancy in the data term.

Default value: 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 value: 5.0

Suggested values: 1.0, 3.0, 5.0, 10.0

Restriction: Smoothness > 0.0

InitialGuessInitialGuessInitialGuessInitialGuessinitialGuess (input_control) real → (real)

Initial guess of the disparity.

Default value: 0.0

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

CalculateScoreCalculateScoreCalculateScoreCalculateScorecalculateScore (input_control) string → (string)

Should the quality measure be returned in ScoreScoreScoreScorescore?

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

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

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

Parameter name(s) for the multigrid algorithm.

Default value: '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"

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

Parameter value(s) for the multigrid algorithm.

Default value: '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_mgBinocularDistanceMgBinocularDistanceMgBinocularDistanceMg 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.