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 : )

Herror T_binocular_distance_mg(const Hobject ImageRect1, const Hobject ImageRect2, Hobject* Distance, Hobject* Score, const Htuple CamParamRect1, const Htuple CamParamRect2, const Htuple RelPoseRect, const Htuple GrayConstancy, const Htuple GradientConstancy, const Htuple Smoothness, const Htuple InitialGuess, const Htuple CalculateScore, const Htuple MGParamName, const Htuple MGParamValue)

void BinocularDistanceMg(const HObject& ImageRect1, const HObject& ImageRect2, HObject* Distance, HObject* Score, const HTuple& CamParamRect1, const HTuple& CamParamRect2, const HTuple& RelPoseRect, const HTuple& GrayConstancy, const HTuple& GradientConstancy, const HTuple& Smoothness, const HTuple& InitialGuess, const HTuple& CalculateScore, const HTuple& MGParamName, const HTuple& MGParamValue)

HImage HImage::BinocularDistanceMg(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const HString& CalculateScore, const HTuple& MGParamName, const HTuple& MGParamValue) const

HImage HImage::BinocularDistanceMg(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const HString& CalculateScore, const HString& MGParamName, const HString& MGParamValue) const

HImage HImage::BinocularDistanceMg(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const char* CalculateScore, const char* MGParamName, const char* MGParamValue) const

HImage HImage::BinocularDistanceMg(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const wchar_t* CalculateScore, const wchar_t* MGParamName, const wchar_t* MGParamValue) const   (Windows only)

HImage HCamPar::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const HString& CalculateScore, const HTuple& MGParamName, const HTuple& MGParamValue) const

HImage HCamPar::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const HString& CalculateScore, const HString& MGParamName, const HString& MGParamValue) const

HImage HCamPar::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const char* CalculateScore, const char* MGParamName, const char* MGParamValue) const

HImage HCamPar::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const wchar_t* CalculateScore, const wchar_t* MGParamName, const wchar_t* MGParamValue) const   (Windows only)

HImage HPose::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const HString& CalculateScore, const HTuple& MGParamName, const HTuple& MGParamValue) const

HImage HPose::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const HString& CalculateScore, const HString& MGParamName, const HString& MGParamValue) const

HImage HPose::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const char* CalculateScore, const char* MGParamName, const char* MGParamValue) const

HImage HPose::BinocularDistanceMg(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, double GrayConstancy, double GradientConstancy, double Smoothness, double InitialGuess, const wchar_t* CalculateScore, const wchar_t* MGParamName, const wchar_t* MGParamValue) const   (Windows only)

static void HOperatorSet.BinocularDistanceMg(HObject imageRect1, HObject imageRect2, out HObject distance, out HObject score, HTuple camParamRect1, HTuple camParamRect2, HTuple relPoseRect, HTuple grayConstancy, HTuple gradientConstancy, HTuple smoothness, HTuple initialGuess, HTuple calculateScore, HTuple MGParamName, HTuple MGParamValue)

HImage HImage.BinocularDistanceMg(HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, HPose relPoseRect, double grayConstancy, double gradientConstancy, double smoothness, double initialGuess, string calculateScore, HTuple MGParamName, HTuple MGParamValue)

HImage HImage.BinocularDistanceMg(HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, HPose relPoseRect, double grayConstancy, double gradientConstancy, double smoothness, double initialGuess, string calculateScore, string MGParamName, string MGParamValue)

HImage HCamPar.BinocularDistanceMg(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect2, HPose relPoseRect, double grayConstancy, double gradientConstancy, double smoothness, double initialGuess, string calculateScore, HTuple MGParamName, HTuple MGParamValue)

HImage HCamPar.BinocularDistanceMg(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect2, HPose relPoseRect, double grayConstancy, double gradientConstancy, double smoothness, double initialGuess, string calculateScore, string MGParamName, string MGParamValue)

HImage HPose.BinocularDistanceMg(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, double grayConstancy, double gradientConstancy, double smoothness, double initialGuess, string calculateScore, HTuple MGParamName, HTuple MGParamValue)

HImage HPose.BinocularDistanceMg(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, double grayConstancy, double gradientConstancy, double smoothness, double initialGuess, string calculateScore, string MGParamName, string 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

Parameters

ImageRect1ImageRect1ImageRect1ImageRect1imageRect1 (input_object)  singlechannelimage(-array) objectHImageHImageHobject (byte / uint2 / real)

Rectified image of camera 1.

ImageRect2ImageRect2ImageRect2ImageRect2imageRect2 (input_object)  singlechannelimage(-array) objectHImageHImageHobject (byte / uint2 / real)

Rectified image of camera 2.

DistanceDistanceDistanceDistancedistance (output_object)  singlechannelimage(-array) objectHImageHImageHobject * (real)

Distance image.

ScoreScoreScoreScorescore (output_object)  singlechannelimage(-array) objectHImageHImageHobject * (real)

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

CamParamRect1CamParamRect1CamParamRect1CamParamRect1camParamRect1 (input_control)  campar HCamPar, HTupleHTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)

Internal camera parameters of the rectified camera 1.

CamParamRect2CamParamRect2CamParamRect2CamParamRect2camParamRect2 (input_control)  campar HCamPar, HTupleHTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)

Internal camera parameters of the rectified camera 2.

RelPoseRectRelPoseRectRelPoseRectRelPoseRectrelPoseRect (input_control)  pose HPose, HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

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

Number of elements: 7

GrayConstancyGrayConstancyGrayConstancyGrayConstancygrayConstancy (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

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 HTupleHTupleHtuple (real) (double) (double) (double)

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 HTupleHTupleHtuple (real) (double) (double) (double)

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 HTupleHTupleHtuple (real) (double) (double) (double)

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 HTupleHTupleHtuple (string) (string) (HString) (char*)

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) HTupleHTupleHtuple (string) (string) (HString) (char*)

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) HTupleHTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

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.

Possible Predecessors

map_imagemap_imageMapImageMapImageMapImage

Possible Successors

thresholdthresholdThresholdThresholdThreshold

Alternatives

binocular_distancebinocular_distanceBinocularDistanceBinocularDistanceBinocularDistance, binocular_distance_msbinocular_distance_msBinocularDistanceMsBinocularDistanceMsBinocularDistanceMs, binocular_disparitybinocular_disparityBinocularDisparityBinocularDisparityBinocularDisparity, binocular_disparity_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgBinocularDisparityMg, binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsBinocularDisparityMs

See also

map_imagemap_imageMapImageMapImageMapImage, gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapGenBinocularRectificationMap, binocular_calibrationbinocular_calibrationBinocularCalibrationBinocularCalibrationBinocularCalibration, disparity_to_distancedisparity_to_distanceDisparityToDistanceDisparityToDistanceDisparityToDistance, distance_to_disparitydistance_to_disparityDistanceToDisparityDistanceToDisparityDistanceToDisparity, disparity_image_to_xyzdisparity_image_to_xyzDisparityImageToXyzDisparityImageToXyzDisparityImageToXyz

Module

3D Metrology