Skip to content

binocular_disparitybinocular_disparityBinocularDisparityBinocularDisparitybinocular_disparitybinocular_disparity🔗

Short description🔗

binocular_disparitybinocular_disparityBinocularDisparityBinocularDisparitybinocular_disparitybinocular_disparity — Compute the disparities of a rectified image pair using correlation techniques.

Signature🔗

binocular_disparity( image ImageRect1, image ImageRect2, out image Disparity, out image Score, string Method, integer MaskWidth, integer MaskHeight, real TextureThresh, integer MinDisparity, integer MaxDisparity, integer NumLevels, real ScoreThresh, string Filter, string SubDisparity )binocular_disparity( ImageRect1, ImageRect2 : Disparity, Score : Method, MaskWidth, MaskHeight, TextureThresh, MinDisparity, MaxDisparity, NumLevels, ScoreThresh, Filter, SubDisparity : )void BinocularDisparity( const HObject& ImageRect1, const HObject& ImageRect2, HObject* Disparity, HObject* Score, const HTuple& Method, const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& TextureThresh, const HTuple& MinDisparity, const HTuple& MaxDisparity, const HTuple& NumLevels, const HTuple& ScoreThresh, const HTuple& Filter, const HTuple& SubDisparity )static void HOperatorSet.BinocularDisparity( HObject imageRect1, HObject imageRect2, out HObject disparity, out HObject score, HTuple method, HTuple maskWidth, HTuple maskHeight, HTuple textureThresh, HTuple minDisparity, HTuple maxDisparity, HTuple numLevels, HTuple scoreThresh, HTuple filter, HTuple subDisparity )def binocular_disparity( image_rect_1: HObject, image_rect_2: HObject, method: str, mask_width: int, mask_height: int, texture_thresh: Union[float, int], min_disparity: int, max_disparity: int, num_levels: int, score_thresh: Union[float, int], filter: MaybeSequence[str], sub_disparity: str ) -> Tuple[HObject, HObject]

Herror binocular_disparity( const Hobject ImageRect1, const Hobject ImageRect2, Hobject* Disparity, Hobject* Score, const char* Method, const Hlong MaskWidth, const Hlong MaskHeight, double TextureThresh, const Hlong MinDisparity, const Hlong MaxDisparity, const Hlong NumLevels, double ScoreThresh, const char* Filter, const char* SubDisparity )

Herror T_binocular_disparity( const Hobject ImageRect1, const Hobject ImageRect2, Hobject* Disparity, Hobject* Score, const Htuple Method, const Htuple MaskWidth, const Htuple MaskHeight, const Htuple TextureThresh, const Htuple MinDisparity, const Htuple MaxDisparity, const Htuple NumLevels, const Htuple ScoreThresh, const Htuple Filter, const Htuple SubDisparity )

HImage HImage::BinocularDisparity( const HImage& ImageRect2, HImage* Score, const HString& Method, Hlong MaskWidth, Hlong MaskHeight, const HTuple& TextureThresh, Hlong MinDisparity, Hlong MaxDisparity, Hlong NumLevels, const HTuple& ScoreThresh, const HTuple& Filter, const HString& SubDisparity ) const

HImage HImage::BinocularDisparity( const HImage& ImageRect2, HImage* Score, const HString& Method, Hlong MaskWidth, Hlong MaskHeight, double TextureThresh, Hlong MinDisparity, Hlong MaxDisparity, Hlong NumLevels, double ScoreThresh, const HString& Filter, const HString& SubDisparity ) const

HImage HImage::BinocularDisparity( const HImage& ImageRect2, HImage* Score, const char* Method, Hlong MaskWidth, Hlong MaskHeight, double TextureThresh, Hlong MinDisparity, Hlong MaxDisparity, Hlong NumLevels, double ScoreThresh, const char* Filter, const char* SubDisparity ) const

HImage HImage::BinocularDisparity( const HImage& ImageRect2, HImage* Score, const wchar_t* Method, Hlong MaskWidth, Hlong MaskHeight, double TextureThresh, Hlong MinDisparity, Hlong MaxDisparity, Hlong NumLevels, double ScoreThresh, const wchar_t* Filter, const wchar_t* SubDisparity ) const (Windows only)

HImage HImage.BinocularDisparity( HImage imageRect2, out HImage score, string method, int maskWidth, int maskHeight, HTuple textureThresh, int minDisparity, int maxDisparity, int numLevels, HTuple scoreThresh, HTuple filter, string subDisparity )

HImage HImage.BinocularDisparity( HImage imageRect2, out HImage score, string method, int maskWidth, int maskHeight, double textureThresh, int minDisparity, int maxDisparity, int numLevels, double scoreThresh, string filter, string subDisparity )

Description🔗

binocular_disparityBinocularDisparity computes pixel-wise correspondences between two rectified images using correlation techniques. Different from binocular_distanceBinocularDistance the results are not transformed into distance values.

The algorithm requires a reference image ImageRect1imageRect1image_rect_1 and a search image ImageRect2imageRect2image_rect_2 which must be rectified, i.e., corresponding epipolar lines are parallel and lie on identical image rows (\(r_{1}=r_{2}\)). In case this assumption is violated the images can be rectified by using the operators calibrate_camerasCalibrateCameras, gen_binocular_rectification_mapGenBinocularRectificationMap, and map_imageMapImage. Hence, given a pixel in the reference image ImageRect1imageRect1image_rect_1 the homologous pixel in ImageRect2imageRect2image_rect_2 is selected by searching along the corresponding row in ImageRect2imageRect2image_rect_2 and matching a local neighborhood within a rectangular window of size MaskWidthmaskWidthmask_width and MaskHeightmaskHeightmask_height. The pixel correspondences are returned in the single-channel Disparitydisparitydisparity image \(d(r_{1},c_{1})\) which specifies for each pixel \((r1,c1)\) of the reference image ImageRect1imageRect1image_rect_1 a suitable matching pixel \((r2,c2)\) of ImageRect2imageRect2image_rect_2 according to the equation \(c_{2} = c_{1} + d(r_{1},c_{1})\). A quality measure for each disparity value is returned in Scorescorescore, containing the best result of the matching function \(S\) of a reference pixel. For the matching, the gray values of the original unprocessed images are used.

The used matching function is defined by the parameter Methodmethodmethod allocating three different kinds of correlation:

  • 'sad'"sad": Summed Absolute Differences

    \[\begin{eqnarray*} S(r,c,d) = \frac{1}{N}\sum\limits_{r'=r-m}^{r+m} \sum\limits_{c'=c-n}^{c+n} \mid g_{1}(r',c')-g_{2}(r',c'+d) \mid \end{eqnarray*}\]

    ,\ with \(0 \le S(r,c,d) \le 255\).

  • 'ssd'"ssd": Summed Squared Differences

    \[\begin{eqnarray*} S(r,c,d) = \frac{1}{N}\sum\limits_{r'=r-m}^{r+m} \sum\limits_{c'=c-n}^{c+n} ( g_{1}(r',c')-g_{2}(r',c'+d) )^{2} \end{eqnarray*}\]

    ,\ with \(0 \le S(r,c,d) \le 65025\).

  • 'ncc'"ncc": Normalized Cross Correlation

    \[\begin{eqnarray*} S(r,c,d) = \frac{\sum\limits_{r'=r-m}^{r+m}\sum\limits_{c'=c-n}^{c+n} (g_{1}(r',c')-\bar{g_{1}}(r,c) ) (g_{2}(r',c'+d)-\bar{g_{2}}(r,c+d)) } {\sqrt{\big(\sum\limits_{r'=r-m}^{r+m}\sum\limits_{c'=c-n}^{c+n} (g_{1}(r',c')-\bar{g_{1}}(r,c) )^{2}\big) \big(\sum\limits_{r'=r-m}^{r+m}\sum\limits_{c'=c-n}^{c+n}(g_{2}(r',c'+d) -\bar{g_{2}}(r,c+d))^{2}\big)}} \end{eqnarray*}\]

    ,\ with \(-1.0 \le S(r,c,d) \le 1.0\).

with

\(r1\), \(c1\), \(r2\), \(c2\): row and column coordinates of the corresponding pixels of the two input images,

\(g1\), \(g2\): gray values of the unprocessed input images,

\(N=(2m+1)(2n+1)\): size of correlation window

\(\bar{g}(r,c) = \frac{1}{N}\sum\limits_{r'=r-m}^{r+m}\sum\limits_{c'=c-n}^{c+n} g(r',c')\): mean value within the correlation window of width \(2m+1\) and height \(2n+1\).

Note that the methods 'sad'"sad" and 'ssd'"ssd" compare the gray values of the pixels within a mask window directly, whereas 'ncc'"ncc" compensates for the mean gray value and its variance within the mask window. Therefore, if the two images differ in brightness and contrast, this method should be preferred. For images with similar brightness and contrast 'sad'"sad" and 'ssd'"ssd" are to be preferred as they are faster because of less complex internal computations.

It should be noted, that the quality of correlation for rising \(S\) is falling in methods 'sad'"sad" and 'ssd'"ssd" (the best quality value is 0) but rising in method 'ncc'"ncc" (the best quality value is 1.0).

The size of the correlation window, referenced by \(2m+1\) and \(2n+1\), has to be odd numbered and is passed in MaskWidthmaskWidthmask_width and MaskHeightmaskHeightmask_height. The search space is confined by the minimum and maximum disparity value MinDisparityminDisparitymin_disparity and MaxDisparitymaxDisparitymax_disparity. Due to pixel values not defined beyond the image border the resulting domain of Disparitydisparitydisparity and Scorescorescore is not set along the image border within a margin of height (MaskHeightmaskHeightmask_height-1)/2 at the top and bottom border and of width (MaskWidthmaskWidthmask_width-1)/2 at the left and right border. For the same reason, the maximum disparity range is reduced at the left and right image border.

Since matching turns out to be highly unreliable when dealing with poorly textured areas, the minimum statistical spread of gray values within the correlation window can be defined in TextureThreshtextureThreshtexture_thresh. This threshold is applied on both input images ImageRect1imageRect1image_rect_1 and ImageRect2imageRect2image_rect_2. In addition, ScoreThreshscoreThreshscore_thresh guarantees the matching quality and defines the maximum ('sad'"sad",'ssd'"ssd") or, respectively, minimum ('ncc'"ncc") score value of the correlation function. Setting Filterfilterfilter to 'left_right_check'"left_right_check", moreover, increases the robustness of the returned matches, as the result relies on a concurrent direct and reverse match, whereas 'none'"none" switches it off.

The number of pyramid levels used to improve the time response of binocular_disparityBinocularDisparity is determined by NumLevelsnumLevelsnum_levels. Following a coarse-to-fine scheme disparity images of higher levels are computed and segmented into rectangular subimages of similar disparity to reduce the disparity range on the next lower pyramid level. TextureThreshtextureThreshtexture_thresh and ScoreThreshscoreThreshscore_thresh are applied on every level and the returned domain of the Disparitydisparitydisparity and Scorescorescore images arises from the intersection of the resulting domains of every single level. Generally, pyramid structures are the more advantageous the more the disparity image can be segmented into regions of homogeneous disparities and the bigger the disparity range is specified. As a drawback, coarse pyramid levels might loose important texture information which can result in deficient disparity values.

Finally, the value 'interpolation'"interpolation" for parameter SubDisparitysubDisparitysub_disparity performs subpixel refinement of disparities. It is switched off by setting the parameter to 'none'"none".

Execution information🔗

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 → object (byte)object (byte)HObject (byte)HImage (byte)HObject (byte)Hobject (byte)

Rectified image of camera 1.

ImageRect2imageRect2image_rect_2 (input_object) singlechannelimage → object (byte)object (byte)HObject (byte)HImage (byte)HObject (byte)Hobject (byte)

Rectified image of camera 2.

Disparitydisparitydisparity (output_object) singlechannelimage → object (real)object (real)HObject (real)HImage (real)HObject (real)Hobject * (real)

Disparity map.

Scorescorescore (output_object) singlechannelimage → object (real)object (real)HObject (real)HImage (real)HObject (real)Hobject * (real)

Evaluation of the disparity values.

Methodmethodmethod (input_control) string → (string)(string)HTuple (HString)HTuple (string)strHtuple (char*)

Matching function.

Default: 'ncc'"ncc"
List of values: 'ncc', 'sad', 'ssd'"ncc", "sad", "ssd"

MaskWidthmaskWidthmask_width (input_control) integer → (integer)(integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Width of the correlation window.

Default: 1111
Suggested values: 5, 7, 9, 11, 215, 7, 9, 11, 21
Restriction: 3 <= MaskWidth && odd(MaskWidth)

MaskHeightmaskHeightmask_height (input_control) integer → (integer)(integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Height of the correlation window.

Default: 1111
Suggested values: 5, 7, 9, 11, 215, 7, 9, 11, 21
Restriction: 3 <= MaskHeight && odd(MaskHeight)

TextureThreshtextureThreshtexture_thresh (input_control) real → (real / integer)(real / integer)HTuple (double / Hlong)HTuple (double / int / long)Union[float, int]Htuple (double / Hlong)

Variance threshold of textured image regions.

Default: 0.00.0
Suggested values: 0.0, 10.0, 30.00.0, 10.0, 30.0
Restriction: 0.0 <= TextureThresh

MinDisparityminDisparitymin_disparity (input_control) integer → (integer)(integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Minimum of the expected disparities.

Default: -30-30
Value range: -32768 ≤ MinDisparity ≤ 32767

MaxDisparitymaxDisparitymax_disparity (input_control) integer → (integer)(integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Maximum of the expected disparities.

Default: 3030
Value range: -32768 ≤ MaxDisparity ≤ 32767

NumLevelsnumLevelsnum_levels (input_control) integer → (integer)(integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Number of pyramid levels.

Default: 11
Suggested values: 1, 2, 3, 41, 2, 3, 4
Restriction: 1 <= NumLevels

ScoreThreshscoreThreshscore_thresh (input_control) real → (real / integer)(real / integer)HTuple (double / Hlong)HTuple (double / int / long)Union[float, int]Htuple (double / Hlong)

Threshold of the correlation function.

Default: 0.50.5
Suggested values: -1.0, 0.0, 0.3, 0.5, 0.7-1.0, 0.0, 0.3, 0.5, 0.7

Filterfilterfilter (input_control) string(-array) → (string)(string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Downstream filters.

Default: 'none'"none"
List of values: 'left_right_check', 'none'"left_right_check", "none"

SubDisparitysubDisparitysub_disparity (input_control) string → (string)(string)HTuple (HString)HTuple (string)strHtuple (char*)

Subpixel interpolation of disparities.

Default: 'none'"none"
List of values: 'interpolation', 'none'"interpolation", "none"

Example🔗

(HDevelop)


* Set internal and external stereo parameters.
* Note that, typically, these values are the result of a prior
* calibration.
gen_cam_par_area_scan_division (0.01, -665, 5.2e-006, 5.2e-006, \
                                622, 517, 1280, 1024, CamParam1)
gen_cam_par_area_scan_division (0.01, -731, 5.2e-006, 5.2e-006, \
                                654, 519, 1280, 1024, CamParam2)
create_pose (0.1535,-0.0037,0.0447,0.17,319.84,359.89, \
             'Rp+T', 'gba', 'point', RelPose)

* Compute the mapping for rectified images.
gen_binocular_rectification_map (Map1, Map2, CamParam1, CamParam2, RelPose, \
                                 1, 'viewing_direction', 'bilinear', \
                                 CamParamRect1,CamParamRect2, \
                                 Cam1PoseRect1, Cam2PoseRect2,RelPoseRect)

* Compute the disparities in online images.
while (1)
  grab_image_async (Image1, AcqHandle1, -1)
  map_image (Image1, Map1, ImageRect1)
 grab_image_async (Image2, AcqHandle2, -1)
  map_image (Image2, Map2, ImageRect2)
 binocular_disparity(ImageRect1, ImageRect2, Disparity, Score, 'sad', \
                      11, 11, 20, -40, 20, 2, 25, 'left_right_check', \
                      'interpolation')
endwhile
(C++)
// Set internal and external stereo parameters.
// Note that, typically, these values are the result of a prior
// calibration.
gen_cam_par_area_scan_division (0.01, -665, 5.2e-006, 5.2e-006,
                                622, 517, 1280, 1024, &CamParam1)\;
gen_cam_par_area_scan_division (0.01, -731, 5.2e-006, 5.2e-006,
                                654, 519, 1280, 1024, &CamParam2)\;
create_pose (0.1535,-0.0037,0.0447,0.17,319.84,359.89,
             "Rp+T", "gba", "point", &RelPose)\;
// Compute the mapping for rectified images.
gen_binocular_rectification_map(&Map1,&Map2,CamParam1,CamParam2,RelPose,1,
                                "viewing_direction","bilinear",
                                &CamParamRect1,&CamParamRect2,
                                &CamPoseRect1,&CamPoseRect2,&RelPosRect)\;

// Compute the disparities in online images.
while (1)
{
  grab_image_async(&Image1,AcqHandle1,-1)\;
  map_image(Image1,Map1,&ImageRect1)\;
 grab_image_async(&Image2,AcqHandle2,-1)\;
  map_image(Image2,Map2,&ImageRect2)\;
 binocular_disparity(ImageRect1,ImageRect2,&Disparity,&Score,"sad",
                      11,11,20,-40,20,2,25,"left_right_check",
                      "interpolation")\;
}

Result🔗

binocular_disparityBinocularDisparity returns 2 (H_MSG_TRUE) if all parameter values are correct. If necessary, an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

map_imageMapImage

Possible successors

thresholdThreshold, disparity_to_distanceDisparityToDistance, disparity_image_to_xyzDisparityImageToXyz

Alternatives

binocular_disparity_mgBinocularDisparityMg, binocular_disparity_msBinocularDisparityMs, binocular_distanceBinocularDistance, binocular_distance_mgBinocularDistanceMg, binocular_distance_msBinocularDistanceMs

See also

map_imageMapImage, gen_binocular_rectification_mapGenBinocularRectificationMap, binocular_calibrationBinocularCalibration

Module🔗

3D Metrology