binocular_distance_msT_binocular_distance_msBinocularDistanceMsBinocularDistanceMsbinocular_distance_ms (Operator)
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 : )
Herror T_binocular_distance_ms(const Hobject ImageRect1, const Hobject ImageRect2, Hobject* Distance, Hobject* Score, const Htuple CamParamRect1, const Htuple CamParamRect2, const Htuple RelPoseRect, const Htuple MinDisparity, const Htuple MaxDisparity, const Htuple SurfaceSmoothing, const Htuple EdgeSmoothing, const Htuple GenParamName, const Htuple GenParamValue)
void BinocularDistanceMs(const HObject& ImageRect1, const HObject& ImageRect2, HObject* Distance, HObject* Score, const HTuple& CamParamRect1, const HTuple& CamParamRect2, const HTuple& RelPoseRect, const HTuple& MinDisparity, const HTuple& MaxDisparity, const HTuple& SurfaceSmoothing, const HTuple& EdgeSmoothing, const HTuple& GenParamName, const HTuple& GenParamValue)
HImage HImage::BinocularDistanceMs(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const HTuple& GenParamName, const HTuple& GenParamValue) const
HImage HImage::BinocularDistanceMs(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const HString& GenParamName, const HString& GenParamValue) const
HImage HImage::BinocularDistanceMs(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const char* GenParamName, const char* GenParamValue) const
HImage HImage::BinocularDistanceMs(const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const wchar_t* GenParamName, const wchar_t* GenParamValue) const
(
Windows only)
HImage HCamPar::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const HTuple& GenParamName, const HTuple& GenParamValue) const
HImage HCamPar::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const HString& GenParamName, const HString& GenParamValue) const
HImage HCamPar::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const char* GenParamName, const char* GenParamValue) const
HImage HCamPar::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect2, const HPose& RelPoseRect, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const wchar_t* GenParamName, const wchar_t* GenParamValue) const
(
Windows only)
HImage HPose::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const HTuple& GenParamName, const HTuple& GenParamValue) const
HImage HPose::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const HString& GenParamName, const HString& GenParamValue) const
HImage HPose::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const char* GenParamName, const char* GenParamValue) const
HImage HPose::BinocularDistanceMs(const HImage& ImageRect1, const HImage& ImageRect2, HImage* Score, const HCamPar& CamParamRect1, const HCamPar& CamParamRect2, Hlong MinDisparity, Hlong MaxDisparity, Hlong SurfaceSmoothing, Hlong EdgeSmoothing, const wchar_t* GenParamName, const wchar_t* GenParamValue) const
(
Windows only)
static void HOperatorSet.BinocularDistanceMs(HObject imageRect1, HObject imageRect2, out HObject distance, out HObject score, HTuple camParamRect1, HTuple camParamRect2, HTuple relPoseRect, HTuple minDisparity, HTuple maxDisparity, HTuple surfaceSmoothing, HTuple edgeSmoothing, HTuple genParamName, HTuple genParamValue)
HImage HImage.BinocularDistanceMs(HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, HPose relPoseRect, int minDisparity, int maxDisparity, int surfaceSmoothing, int edgeSmoothing, HTuple genParamName, HTuple genParamValue)
HImage HImage.BinocularDistanceMs(HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, HPose relPoseRect, int minDisparity, int maxDisparity, int surfaceSmoothing, int edgeSmoothing, string genParamName, string genParamValue)
HImage HCamPar.BinocularDistanceMs(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect2, HPose relPoseRect, int minDisparity, int maxDisparity, int surfaceSmoothing, int edgeSmoothing, HTuple genParamName, HTuple genParamValue)
HImage HCamPar.BinocularDistanceMs(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect2, HPose relPoseRect, int minDisparity, int maxDisparity, int surfaceSmoothing, int edgeSmoothing, string genParamName, string genParamValue)
HImage HPose.BinocularDistanceMs(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, int minDisparity, int maxDisparity, int surfaceSmoothing, int edgeSmoothing, HTuple genParamName, HTuple genParamValue)
HImage HPose.BinocularDistanceMs(HImage imageRect1, HImage imageRect2, out HImage score, HCamPar camParamRect1, HCamPar camParamRect2, int minDisparity, int maxDisparity, int surfaceSmoothing, int edgeSmoothing, string genParamName, string genParamValue)
def binocular_distance_ms(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]], min_disparity: int, max_disparity: int, surface_smoothing: int, edge_smoothing: int, gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[str, int]]) -> Tuple[HObject, HObject]
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 → objectHImageHObjectHObjectHobject (byte*) *allowed for compute devices
Rectified image of camera 1.
ImageRect2ImageRect2ImageRect2imageRect2image_rect_2 (input_object) singlechannelimage → objectHImageHObjectHObjectHobject (byte*) *allowed for compute devices
Rectified image of camera 2.
DistanceDistanceDistancedistancedistance (output_object) singlechannelimage → objectHImageHObjectHObjectHobject * (real)
Distance image.
ScoreScoreScorescorescore (output_object) singlechannelimage → objectHImageHObjectHObjectHobject * (real)
Score of the calculated disparity.
CamParamRect1CamParamRect1CamParamRect1camParamRect1cam_param_rect_1 (input_control) campar → HCamPar, HTupleSequence[Union[int, float, str]]HTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)
Internal camera parameters of the rectified camera 1.
CamParamRect2CamParamRect2CamParamRect2camParamRect2cam_param_rect_2 (input_control) campar → HCamPar, HTupleSequence[Union[int, float, str]]HTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)
Internal camera parameters of the rectified camera 2.
RelPoseRectRelPoseRectRelPoseRectrelPoseRectrel_pose_rect (input_control) pose → HPose, HTupleSequence[Union[int, float]]HTupleHtuple (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
MinDisparityMinDisparityMinDisparityminDisparitymin_disparity (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
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 → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
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 → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Smoothing of surfaces.
Default:
50
Suggested values:
20, 50, 100
Restriction:
SurfaceSmoothing >= 0
EdgeSmoothingEdgeSmoothingEdgeSmoothingedgeSmoothingedge_smoothing (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Smoothing of edges.
Default:
50
Suggested values:
20, 50, 100
Restriction:
EdgeSmoothing >= 0
GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) attribute.name(-array) → HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)
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) → HTupleMaybeSequence[Union[str, int]]HTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)
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.
Possible Predecessors
map_imagemap_imageMapImageMapImagemap_image
Possible Successors
thresholdthresholdThresholdThresholdthreshold
Alternatives
binocular_distancebinocular_distanceBinocularDistanceBinocularDistancebinocular_distance,
binocular_distance_mgbinocular_distance_mgBinocularDistanceMgBinocularDistanceMgbinocular_distance_mg,
binocular_disparitybinocular_disparityBinocularDisparityBinocularDisparitybinocular_disparity,
binocular_disparity_mgbinocular_disparity_mgBinocularDisparityMgBinocularDisparityMgbinocular_disparity_mg,
binocular_disparity_msbinocular_disparity_msBinocularDisparityMsBinocularDisparityMsbinocular_disparity_ms
See also
map_imagemap_imageMapImageMapImagemap_image,
gen_binocular_rectification_mapgen_binocular_rectification_mapGenBinocularRectificationMapGenBinocularRectificationMapgen_binocular_rectification_map,
binocular_calibrationbinocular_calibrationBinocularCalibrationBinocularCalibrationbinocular_calibration,
disparity_to_distancedisparity_to_distanceDisparityToDistanceDisparityToDistancedisparity_to_distance,
distance_to_disparitydistance_to_disparityDistanceToDisparityDistanceToDisparitydistance_to_disparity,
disparity_image_to_xyzdisparity_image_to_xyzDisparityImageToXyzDisparityImageToXyzdisparity_image_to_xyz
Module
3D Metrology