binocular_distance_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mgT_binocular_distance_mg
Short description
binocular_distance_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mgT_binocular_distance_mg — Compute the distance values for a rectified stereo image pair using
multigrid methods.
Signature
binocular_distance_mg( image ImageRect1, image ImageRect2, out image Distance, out image Score, campar CamParamRect1, campar CamParamRect2, pose RelPoseRect, real GrayConstancy, real GradientConstancy, real Smoothness, real InitialGuess, string CalculateScore, attribute.name MGParamName, attribute.value MGParamValue )binocular_distance_mg( ImageRect1, ImageRect2 : Distance, Score : CamParamRect1, CamParamRect2, RelPoseRect, GrayConstancy, GradientConstancy, Smoothness, InitialGuess, CalculateScore, MGParamName, 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 )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 )def binocular_distance_mg( image_rect_1: HObject, image_rect_2: HObject, cam_param_rect_1: Sequence[Union[int, float, str]], cam_param_rect_2: Sequence[Union[int, float, str]], rel_pose_rect: Sequence[Union[int, float]], gray_constancy: float, gradient_constancy: float, smoothness: float, initial_guess: float, calculate_score: str, mgparam_name: MaybeSequence[str], mgparam_value: MaybeSequence[Union[str, float, int]] ) -> Tuple[HObject, HObject]
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 )
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)
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_mgBinocularDistanceMg computes the distance values for a
rectified stereo image pair using multigrid methods. The operator
first calculates the disparities between two rectified images
ImageRect1imageRect1image_rect_1 and ImageRect2imageRect2image_rect_2 similar to
binocular_disparity_mgBinocularDisparityMg. 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_distanceDisparityToDistance. The distances are returned in the
single-channel image Distancedistancedistance in which each gray value
represents the distance of the respective 3D world point to the
stereo camera system. Different from binocular_distanceBinocularDistance
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 ImageRect1imageRect1image_rect_1 and ImageRect2imageRect2image_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_camerasCalibrateCameras, gen_binocular_rectification_mapGenBinocularRectificationMap
and map_imageMapImage.
For the transformation of the disparity to the distance, the
internal camera parameters of the rectified camera 1
CamParamRect1camParamRect1cam_param_rect_1 and of the rectified camera 2
CamParamRect2camParamRect2cam_param_rect_2, as well as the relative pose of the cameras
RelPoseRectrelPoseRectrel_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_camerasCalibrateCameras and
gen_binocular_rectification_mapGenBinocularRectificationMap.
A detailed description of the algorithm and of the remaining
parameters can be found in the documentation of
binocular_disparity_mgBinocularDisparityMg.
Attention
If using cameras with telecentric lenses, the Distancedistancedistance 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_mapGenBinocularRectificationMap).
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_mapGenBinocularRectificationMap), 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_mgBinocularDistanceMg does not support a stereo setup of
mixed type. For stereo setups of mixed type, please use
reconstruct_surface_stereoReconstructSurfaceStereo, in which the reference
coordinate system can be chosen arbitrarily. Alternatively,
binocular_disparity_mgBinocularDisparityMg and disparity_image_to_xyzDisparityImageToXyz
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 internal data level.
Parameters
ImageRect1imageRect1image_rect_1 (input_object) singlechannelimage(-array) → object (byte / uint2 / real)object (byte / uint2 / real)HObject (byte / uint2 / real)HImage (byte / uint2 / real)HObject (byte / uint2 / real)Hobject (byte / uint2 / real)
Rectified image of camera 1.
ImageRect2imageRect2image_rect_2 (input_object) singlechannelimage(-array) → object (byte / uint2 / real)object (byte / uint2 / real)HObject (byte / uint2 / real)HImage (byte / uint2 / real)HObject (byte / uint2 / real)Hobject (byte / uint2 / real)
Rectified image of camera 2.
Distancedistancedistance (output_object) singlechannelimage(-array) → object (real)object (real)HObject (real)HImage (real)HObject (real)Hobject * (real)
Distance image.
Scorescorescore (output_object) singlechannelimage(-array) → object (real)object (real)HObject (real)HImage (real)HObject (real)Hobject * (real)
Score of the calculated disparity if
CalculateScorecalculateScorecalculate_score is set to 'true'"true".
CamParamRect1camParamRect1cam_param_rect_1 (input_control) campar → (real / integer / string)(real / integer / string)HTuple (double / Hlong / HString)HCamPar, HTuple (double / int / long / string)Sequence[Union[int, float, str]]Htuple (double / Hlong / char*)
Internal camera parameters of the rectified camera 1.
CamParamRect2camParamRect2cam_param_rect_2 (input_control) campar → (real / integer / string)(real / integer / string)HTuple (double / Hlong / HString)HCamPar, HTuple (double / int / long / string)Sequence[Union[int, float, str]]Htuple (double / Hlong / char*)
Internal camera parameters of the rectified camera 2.
RelPoseRectrelPoseRectrel_pose_rect (input_control) pose → (real / integer)(real / integer)HTuple (double / Hlong)HPose, HTuple (double / int / long)Sequence[Union[int, float]]Htuple (double / Hlong)
Point transformation from the rectified camera 2 to
the rectified camera 1.
Number of elements: 7
GrayConstancygrayConstancygray_constancy (input_control) real → (real)(real)HTuple (double)HTuple (double)floatHtuple (double)
Weight of the gray value constancy in the data term.
Default: 1.01.0
Suggested values: 0.0, 1.0, 2.0, 10.00.0, 1.0, 2.0, 10.0
Restriction: GrayConstancy >= 0.0
GradientConstancygradientConstancygradient_constancy (input_control) real → (real)(real)HTuple (double)HTuple (double)floatHtuple (double)
Weight of the gradient constancy in the data term.
Default: 30.030.0
Suggested values: 0.0, 1.0, 5.0, 10.0, 30.0, 50.0, 70.00.0, 1.0, 5.0, 10.0, 30.0, 50.0, 70.0
Restriction: GradientConstancy >= 0.0
Smoothnesssmoothnesssmoothness (input_control) real → (real)(real)HTuple (double)HTuple (double)floatHtuple (double)
Weight of the smoothness term in relation to the
data term.
Default: 5.05.0
Suggested values: 1.0, 3.0, 5.0, 10.01.0, 3.0, 5.0, 10.0
Restriction: Smoothness > 0.0
InitialGuessinitialGuessinitial_guess (input_control) real → (real)(real)HTuple (double)HTuple (double)floatHtuple (double)
Initial guess of the disparity.
Default: 0.00.0
Suggested values: -30.0, -20.0, -10.0, 0.0, 10.0, 20.0, 30.0-30.0, -20.0, -10.0, 0.0, 10.0, 20.0, 30.0
CalculateScorecalculateScorecalculate_score (input_control) string → (string)(string)HTuple (HString)HTuple (string)strHtuple (char*)
Should the quality measure be returned in
Scorescorescore?
Default: 'false'"false"
Suggested values: 'true', 'false'"true", "false"
MGParamNameMGParamNamemgparam_name (input_control) attribute.name(-array) → (string)(string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)
Parameter name(s) for the multigrid algorithm.
Default: 'default_parameters'"default_parameters"
List of values: 'default_parameters', 'initial_level', 'iterations', 'mg_cycle_type', 'mg_post_relax', 'mg_pre_relax', 'mg_solver', 'pyramid_factor'"default_parameters", "initial_level", "iterations", "mg_cycle_type", "mg_post_relax", "mg_pre_relax", "mg_solver", "pyramid_factor"
MGParamValueMGParamValuemgparam_value (input_control) attribute.value(-array) → (string / real / integer)(string / real / integer)HTuple (HString / double / Hlong)HTuple (string / double / int / long)MaybeSequence[Union[str, float, int]]Htuple (char* / double / Hlong)
Parameter value(s) for the multigrid algorithm.
Default: 'fast_accurate'"fast_accurate"
Suggested values: 'very_accurate', 'accurate', 'fast_accurate', 'fast', 'v', 'w', 'none', 'gauss_seidel', '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"very_accurate", "accurate", "fast_accurate", "fast", "v", "w", "none", "gauss_seidel", "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_mgBinocularDistanceMg
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>). If necessary, an
exception is raised.
Combinations with other operators
Combinations
Possible predecessors
map_imageMapImage
Possible successors
thresholdThreshold
Alternatives
binocular_distanceBinocularDistance, binocular_distance_msBinocularDistanceMs, binocular_disparityBinocularDisparity, binocular_disparity_mgBinocularDisparityMg, binocular_disparity_msBinocularDisparityMs
See also
map_imageMapImage, gen_binocular_rectification_mapGenBinocularRectificationMap, binocular_calibrationBinocularCalibration, disparity_to_distanceDisparityToDistance, distance_to_disparityDistanceToDisparity, disparity_image_to_xyzDisparityImageToXyz
Module
3D Metrology