Merge pull request #28773 from rmsalinas:imgproc_find_truco_contours

imgproc: add findTRUContours - lock-free parallel contour extraction #28773

Integrates the TRUCO algorithm (Threaded Raster Unrestricted Contour Ownership, @cite TRUCO2026) as a transparent fast path inside `cv::findContours`. No API change is required: existing code automatically benefits when `mode=RETR_LIST` and no hierarchy output is requested.

### How it works

When `mode=RETR_LIST` and the caller does not request hierarchy, `findContours` delegates to the TRUCO parallel engine instead of Suzuki-Abe. All ContourApproximationModes are supported; approximation is applied in parallel after extraction. In all other cases the original Suzuki-Abe path is used unchanged.

### Key design ideas
- Row-strip domain decomposition parallelised via `cv::parallel_for_`
- Start-point ownership rule + speculative downward tracing eliminate tile stitching and synchronisation primitives (lock-free)
- 8-bit state space instead of the 32-bit integer labeling required by Suzuki-Abe, giving higher SIMD throughput and lower memory-bandwidth pressure
- Paged contour buffer (`TRUCOPagedContour`) avoids heap reallocation on the hot tracing path
- SIMD-accelerated row scanning via `cv::v_uint8` intrinsics
- Thread count controlled globally via `cv::setNumThreads()`, consistent with OpenCV conventions

### Output correctness

Significant effort has gone into ensuring the output is identical to the original `findContours` in every respect: same contour set, same ordering, and same approximation results for all methods. A dedicated test suite (`test_contours_truco.cpp`) verifies exact match against Suzuki-Abe across all four `ContourApproximationModes` and thread counts from 1 to 39, using noise images, circles, nested rectangles, and mixed scenes.

### Performance vs. Suzuki-Abe (from submitted paper)
- single-thread: ~1.8–1.9× faster (8-bit SIMD advantage)
- 20 threads: ~14–20× faster on i7-13700H (6P+8E, 20T)
- 20 threads: ~10–12× faster on Xeon Silver 4510 (12C/24T)

### 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.
- [x] The feature is well documented and sample code can be built with the project CMake

modules/imgproc/perf/perf_contours.cpp

@@ -141,4 +141,78 @@ PERF_TEST_P(TestMinEnclosingCircleWorstCase, minEnclosingCircle_sequential,
     SANITY_CHECK_NOTHING();
 }
 
+// ============================================================
+// findTRUContours performance tests
+// ============================================================
+
+typedef TestBaseWithParam< tuple<Size, int, int> > TestFindTRUContours;
+
+PERF_TEST_P(TestFindTRUContours, findTRUContours,
+    Combine(
+        Values(sz1080p, sz2160p),   // image size
+        Values(128, 512, 2048),     // circle count
+        Values(1, 0)                // nthreads: 1=single-thread baseline, 0=all available
+    )
+)
+{
+    Size img_size  = get<0>(GetParam());
+    int num_circles = get<1>(GetParam());
+    int nthreads   = get<2>(GetParam());
+
+    RNG rng(12345);
+    Mat img = Mat::zeros(img_size, CV_8UC1);
+    for (int i = 0; i < num_circles; ++i)
+    {
+        Point center(rng.uniform(50, img_size.width  - 50),
+                     rng.uniform(50, img_size.height - 50));
+        int radius = rng.uniform(10, 200);
+        circle(img, center, radius, Scalar::all(255), FILLED);
+    }
+
+    Mat binary;
+    adaptiveThreshold(img, binary, 255, ADAPTIVE_THRESH_MEAN_C, THRESH_BINARY, 11, 0);
+
+    vector<vector<Point>> contours;
+    int prev_nthreads=cv::getNumThreads();
+    cv::setNumThreads(nthreads);
+    TEST_CYCLE() findContours(binary, contours, RETR_LIST, CHAIN_APPROX_NONE);
+    cv::setNumThreads(prev_nthreads);
+
+    SANITY_CHECK_NOTHING();
+}
+
+// Baseline: same image, findContours(RETR_LIST, CHAIN_APPROX_NONE) for direct comparison
+typedef TestBaseWithParam< tuple<Size, int> > TestFindContoursBaseline;
+
+PERF_TEST_P(TestFindContoursBaseline, findContours_baseline_for_TRUCO,
+    Combine(
+        Values(sz1080p, sz2160p),
+        Values(128, 512, 2048)
+    )
+)
+{
+    Size img_size   = get<0>(GetParam());
+    int num_circles = get<1>(GetParam());
+
+    RNG rng(12345);
+    Mat img = Mat::zeros(img_size, CV_8UC1);
+    for (int i = 0; i < num_circles; ++i)
+    {
+        Point center(rng.uniform(50, img_size.width  - 50),
+                     rng.uniform(50, img_size.height - 50));
+        int radius = rng.uniform(10, 200);
+        circle(img, center, radius, Scalar::all(255), FILLED);
+    }
+
+    Mat binary;
+    adaptiveThreshold(img, binary, 255, ADAPTIVE_THRESH_MEAN_C, THRESH_BINARY, 11, 0);
+
+    vector<vector<Point>> contours;
+    vector<Vec4i> hierarchy;
+
+    TEST_CYCLE() findContours(binary, contours, hierarchy, RETR_LIST, CHAIN_APPROX_NONE);
+
+    SANITY_CHECK_NOTHING();
+}
+
 } } // namespace