From 250b5003ee740a6ea4d7523e230128225291fbd2 Mon Sep 17 00:00:00 2001
From: chengolivia <108556565+chengolivia@users.noreply.github.com>
Date: Sat, 17 May 2025 03:19:09 -0400
Subject: [PATCH] Merge pull request #27305 from
 chengolivia:add-check-sgbm-nondeterminism

Add image dimension check to avoid StereoSGBM non-determinism #27305

Addresses #25828

Users noticed that StereoSGBM would occasionally give non-deterministic results for `.compute(imgL, imgR)`.

I and others traced the cause to out-of-bounds access that was not being caught when the input images were not wide enough for the input block size and number of disparities to StereoSGBM. The specific math and logic can be found in the above issue's discussion.

This PR adds a CV_Check to make sure images are wider than 1/2 of the block size + the max disparity the algorithm will search.

The check was only added to the regular `compute` method for StereoSGBM and not to the other modes, as I did not observe the non-deterministic behavior with the other compute modes like HH.

In addition, this PR adds a test case to Calib3d to make sure the check is being thrown in the problem case and that the results are deterministic in the good case.

### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
---
 modules/calib3d/src/stereosgbm.cpp           |  3 ++
 modules/calib3d/test/test_stereomatching.cpp | 32 ++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/modules/calib3d/src/stereosgbm.cpp b/modules/calib3d/src/stereosgbm.cpp
index d2fa18e669..74d5068ac5 100644
--- a/modules/calib3d/src/stereosgbm.cpp
+++ b/modules/calib3d/src/stereosgbm.cpp
@@ -508,6 +508,9 @@ static void computeDisparitySGBM( const Mat& img1, const Mat& img2,
     int SW2 = params.calcSADWindowSize().width/2, SH2 = params.calcSADWindowSize().height/2;
     int npasses = params.isFullDP() ? 2 : 1;
 
+    CV_CheckGT(width - (params.minDisparity + params.numDisparities), params.calcSADWindowSize().width/2,
+     "Your input images are too small for your window size and max disparity, and will result in non-deterministic SGBM results");
+
     if( minX1 >= maxX1 )
     {
         disp1 = Scalar::all(INVALID_DISP_SCALED);
diff --git a/modules/calib3d/test/test_stereomatching.cpp b/modules/calib3d/test/test_stereomatching.cpp
index ad230509df..826c4c8a3b 100644
--- a/modules/calib3d/test/test_stereomatching.cpp
+++ b/modules/calib3d/test/test_stereomatching.cpp
@@ -920,6 +920,38 @@ protected:
 
 TEST(Calib3d_StereoSGBM, regression) { CV_StereoSGBMTest test; test.safe_run(); }
 
+TEST(Calib3d_StereoSGBM, deterministic) {
+    cv::Ptr<cv::StereoSGBM> matcher = cv::StereoSGBM::create(16, 11);
+
+    // Expect throw error (non-determinism case)
+    int widthNarrow = 28;
+    int height = 15;
+
+    cv::Mat leftNarrow(height, widthNarrow, CV_8UC1);
+    cv::Mat rightNarrow(height, widthNarrow, CV_8UC1);
+    randu(leftNarrow, cv::Scalar(0), cv::Scalar(255));
+    randu(rightNarrow, cv::Scalar(0), cv::Scalar(255));
+    cv::Mat disp;
+
+    EXPECT_THROW(matcher->compute(leftNarrow, rightNarrow, disp), cv::Exception);
+
+    // Deterministic case, image is sufficiently large for StereSGBM parameters
+    int widthWide = 40;
+    cv::Mat leftWide(height, widthWide, CV_8UC1);
+    cv::Mat rightWide(height, widthWide, CV_8UC1);
+    randu(leftWide, cv::Scalar(0), cv::Scalar(255));
+    randu(rightWide, cv::Scalar(0), cv::Scalar(255));
+    cv::Mat disp1, disp2;
+    for (int i = 0; i < 10; i++) {
+        matcher->compute(leftWide, rightWide, disp1);
+        matcher->compute(leftWide, rightWide, disp2);
+        cv::Mat dst;
+        cv::bitwise_xor(disp1, disp2, dst);
+        EXPECT_EQ(cv::countNonZero(dst), 0);
+    }
+
+}
+
 TEST(Calib3d_StereoSGBM_HH4, regression)
 {
     String path = cvtest::TS::ptr()->get_data_path() + "cv/stereomatching/datasets/teddy/";