Merge pull request #15780 from oleg-alexandrov:master

* Doc bugfix

The documentation page StereoBinaryBM and StereoBinarySGBM says that it returns a disparity that is scaled multiplied by 16. This scaling must be undone before calling reprojectImageTo3D, otherwise the results are wrong. The function reprojectImageTo3D() could do this scaling internally, maybe, but at least the documentation must explain that this has to be done.

* calib3d: update reprojectImageTo3D documentation

* calib3d: add StereoBM/StereoSGBM into notes list

modules/calib3d/include/opencv2/calib3d.hpp

@@ -2206,8 +2206,11 @@ CV_EXPORTS_W void validateDisparity( InputOutputArray disparity, InputArray cost
 /** @brief Reprojects a disparity image to 3D space.
 
 @param disparity Input single-channel 8-bit unsigned, 16-bit signed, 32-bit signed or 32-bit
-floating-point disparity image. If 16-bit signed format is used, the values are assumed to have no
-fractional bits.
+floating-point disparity image.
+The values of 8-bit / 16-bit signed formats are assumed to have no fractional bits.
+If the disparity is 16-bit signed format as computed by
+StereoBM/StereoSGBM/StereoBinaryBM/StereoBinarySGBM and may be other algorithms,
+it should be divided by 16 (and scaled to float) before being used here.
 @param _3dImage Output 3-channel floating-point image of the same size as disparity . Each
 element of _3dImage(x,y) contains 3D coordinates of the point (x,y) computed from the disparity
 map.