Merge pull request #20129 from aDanPin:dp/improvement_gapi_stereo_documentation

G-API: Improvement stereo documentation.

* Documentation improvement

* Set valid default values for gapi stereo

* Small doc fix

* Review response

* Review response

* Review response

* Review response

* Revie response

* Review response

* Review response

* Review response

modules/gapi/include/opencv2/gapi/cpu/stereo.hpp

@@ -25,8 +25,8 @@ struct GAPI_EXPORTS StereoInitParam {
 
     int numDisparities = 0;
     int blockSize = 21;
-    double baseline = 70.;
-    double focus = 1000.;
+    double baseline = 63.5;
+    double focus = 3.6;
 };
 
 } // namespace cpu

modules/gapi/include/opencv2/gapi/stereo.hpp

@@ -14,11 +14,28 @@
 namespace cv {
 namespace gapi {
 
+/**
+ * The enum specified format of result that you get from @ref cv::gapi::stereo.
+ */
 enum class StereoOutputFormat {
-    DEPTH_FLOAT16,
-    DEPTH_FLOAT32,
-    DISPARITY_FIXED16_11_5,
-    DISPARITY_FIXED16_12_4
+    DEPTH_FLOAT16, ///< Floating point 16 bit value, CV_16FC1.
+                   ///< This identifier is deprecated, use DEPTH_16F instead.
+    DEPTH_FLOAT32, ///< Floating point 32 bit value, CV_32FC1
+                   ///< This identifier is deprecated, use DEPTH_16F instead.
+    DISPARITY_FIXED16_11_5, ///< 16 bit signed: first bit for sign,
+                            ///< 10 bits for integer part,
+                            ///< 5 bits for fractional part.
+                            ///< This identifier is deprecated,
+                            ///< use DISPARITY_16Q_10_5 instead.
+    DISPARITY_FIXED16_12_4, ///< 16 bit signed: first bit for sign,
+                            ///< 11 bits for integer part,
+                            ///< 4 bits for fractional part.
+                            ///< This identifier is deprecated,
+                            ///< use DISPARITY_16Q_11_4 instead.
+    DEPTH_16F = DEPTH_FLOAT16, ///< Same as DEPTH_FLOAT16
+    DEPTH_32F = DEPTH_FLOAT32, ///< Same as DEPTH_FLOAT32
+    DISPARITY_16Q_10_5 = DISPARITY_FIXED16_11_5, ///< Same as DISPARITY_FIXED16_11_5
+    DISPARITY_16Q_11_4 = DISPARITY_FIXED16_12_4 ///< Same as DISPARITY_FIXED16_12_4
 };
 
 namespace calib3d {
@@ -47,13 +64,12 @@ G_TYPED_KERNEL(GStereo, <GMat(GMat, GMat, const StereoOutputFormat)>, "org.openc
 
 } // namespace calib3d
 
-/** @brief Extract disparity/depth information depending on passed StereoOutputFormat argument.
-The function extracts disparity/depth information depending on passed StereoOutputFormat argument from
-given stereo-pair.
+/** @brief Computes disparity/depth map for the specified stereo-pair.
+The function computes disparity or depth map depending on passed StereoOutputFormat argument.
 
-@param left left 8-bit unsigned 1-channel image of @ref CV_8UC1 type
-@param right right 8-bit unsigned 1-channel image of @ref CV_8UC1 type
-@param of enum to specify output kind: depth or disparity and corresponding type
+@param left 8-bit single-channel left image of @ref CV_8UC1 type.
+@param right 8-bit single-channel right image of @ref CV_8UC1 type.
+@param of enum to specified output kind: depth or disparity and corresponding type
 */
 GAPI_EXPORTS GMat stereo(const GMat& left,
                          const GMat& right,

modules/gapi/test/cpu/gapi_stereo_tests_cpu.cpp

@@ -26,11 +26,14 @@ INSTANTIATE_TEST_CASE_P(CPU_Tests, TestGAPIStereo,
                                 Values(STEREO_CPU),
                                 Values(cv::gapi::StereoOutputFormat::DEPTH_FLOAT16,
                                        cv::gapi::StereoOutputFormat::DEPTH_FLOAT32,
-                                       cv::gapi::StereoOutputFormat::DISPARITY_FIXED16_12_4),
+                                       cv::gapi::StereoOutputFormat::DISPARITY_FIXED16_12_4,
+                                       cv::gapi::StereoOutputFormat::DEPTH_16F,
+                                       cv::gapi::StereoOutputFormat::DEPTH_32F,
+                                       cv::gapi::StereoOutputFormat::DISPARITY_16Q_11_4),
                                 Values(16),
                                 Values(43),
-                                Values(10.),
-                                Values(100.),
+                                Values(63.5),
+                                Values(3.6),
                                 Values(AbsExact().to_compare_obj())));
 
 } // opencv_test