Merge pull request #27952 from DDmytro:ecc/template-mask-rework

Add optional template mask for findTransformECC #27952

Supersedes #22997

**Summary**
Add optional template mask support to findTransformECC so that only pixels valid in both the template and the image are used in ECC. Backward compatibility is preserved (existing signatures unchanged; one new overload adds templateMask).

**Motivation**

- Real-world frames often contain moving foreground artifacts (e.g., a football over a static field). Masking the object in one frame only is insufficient because its position changes independently of the background. Since we don’t know the warp a priori, we can’t back-project a single mask across frames. The correct approach is to supply both masks and take their intersection.
- Templates may include uninformative/low-texture or noisy regions, or partial overlaps with other objects. Excluding such regions from the alignment improves robustness and convergence.

This PR completes and replaces https://github.com/opencv/opencv/pull/22997

### 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
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] 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/video/test/test_ecc.cpp

@@ -342,6 +342,26 @@ bool CV_ECC_Test_Mask::test(const Mat testImg) {
         // Test with non-default gaussian blur.
         findTransformECC(warpedImage, testImg, mapTranslation, 0, criteria, mask, 1);
 
+        if (!checkMap(mapTranslation, translationGround))
+            return false;
+
+        // Test with template mask.
+        Mat_<unsigned char> warpedMask = Mat_<unsigned char>::ones(warpedImage.rows, warpedImage.cols);
+        for (int i=warpedImage.rows*1/3; i<warpedImage.rows*2/3; i++) {
+            for (int j=warpedImage.cols*1/3; j<warpedImage.cols*2/3; j++) {
+                warpedMask(i, j) = 0;
+            }
+        }
+
+        findTransformECCWithMask(warpedImage, testImg, warpedMask, mask, mapTranslation, 0,
+                    TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, ECC_iterations, ECC_epsilon));
+
+        if (!checkMap(mapTranslation, translationGround))
+            return false;
+
+        // Test with non-default gaussian blur.
+        findTransformECCWithMask(warpedImage, testImg, warpedMask,  mask, mapTranslation, 0, criteria, 1);
+
         if (!checkMap(mapTranslation, translationGround))
             return false;
     }