Merge pull request #28802 from 4ekmah:pyr_ecc

Multiscale ECC #28802

OpenCV Extra: https://github.com/opencv/opencv_extra/pull/1338

### 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
- [ ] 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/video/include/opencv2/video/tracking.hpp

@@ -419,6 +419,88 @@ CV_EXPORTS_W double findTransformECCWithMask( InputArray templateImage,
                                  TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 50, 1e-6),
                                  int gaussFiltSize = 5 );
 
+/** @brief struct ECCParameters is used by findTransformECCMultiScale
+
+@param motionType parameter, specifying the type of motion:
+ -   **MOTION_TRANSLATION** sets a translational motion model; warpMatrix is \f$2\times 3\f$ with
+     the first \f$2\times 2\f$ part being the unity matrix and the rest two parameters being
+     estimated.
+ -   **MOTION_EUCLIDEAN** sets a Euclidean (rigid) transformation as motion model; three
+     parameters are estimated; warpMatrix is \f$2\times 3\f$.
+ -   **MOTION_AFFINE** sets an affine motion model (DEFAULT); six parameters are estimated;
+     warpMatrix is \f$2\times 3\f$.
+ -   **MOTION_HOMOGRAPHY** sets a homography as a motion model; eight parameters are
+     estimated;\`warpMatrix\` is \f$3\times 3\f$.
+@param criteria parameter, specifying the termination criteria of the ECC algorithm;
+criteria.epsilon defines the threshold of the increment in the correlation coefficient between two
+iterations (a negative criteria.epsilon makes criteria.maxcount the only termination criterion).
+Default values are shown in the declaration above.
+@param itersPerLevel Criterion extension: distribution of iterations limit over pyramid levels.
+Can be empty, in this case, this algorithm will use criteria.maxCount on each level.
+@param gaussFiltSize An optional value indicating size of gaussian blur filter; (DEFAULT: 5)
+@param nlevels An optional value indicating amount of levels in the pyramid; (DEFAULT: 4)
+@param interpolation Type of warp interpolation. Possible values are INTER_NEAREST and INTER_LINEAR.
+Affects accuracy, especially when motionType == MOTION_TRANSLATION. (DEFAULT: INTER_LINEAR)
+ */
+struct CV_EXPORTS_W_SIMPLE ECCParameters
+{
+    CV_WRAP ECCParameters() {}
+    CV_PROP_RW int motionType = MOTION_AFFINE;
+    CV_PROP_RW cv::TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 50, 1e-6);
+    CV_PROP_RW std::vector<int> itersPerLevel = std::vector<int>();
+    CV_PROP_RW int gaussFiltSize = 5;
+    CV_PROP_RW int nlevels = 4;
+    CV_PROP_RW int interpolation = INTER_LINEAR;
+};
+
+/** @brief Finds the geometric transform (warp) between two images in terms of the ECC criterion @cite EP08. Uses pyramids.
+
+@param reference Single channel reference image; CV_8U, CV_16U, CV_32F, CV_64F type.
+@param sample sample image which should be warped with the final warpMatrix in
+order to provide an image similar to reference, same type as reference.
+@param warpMatrix floating-point \f$2\times 3\f$ or \f$3\times 3\f$ mapping matrix (warp).
+@param eccParams List of the algorithm parameters. See ECCParameters for details.
+@param referenceMask An optional single channel mask to indicate valid values of reference.
+@param sampleMask An optional single channel mask to indicate valid values of sample.
+
+The function estimates the optimum transformation (warpMatrix) with respect to ECC criterion
+(@cite EP08), that is
+
+\f[\texttt{warpMatrix} = \arg\max_{W} \texttt{ECC}(\texttt{templateImage}(x,y),\texttt{inputImage}(x',y'))\f]
+
+where
+
+\f[\begin{bmatrix} x' \\ y' \end{bmatrix} = W \cdot \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\f]
+
+(the equation holds with homogeneous coordinates for homography). It returns the final enhanced
+correlation coefficient, that is the correlation coefficient between the template image and the
+final warped input image. When a \f$3\times 3\f$ matrix is given with motionType =0, 1 or 2, the third
+row is ignored.
+
+Unlike findHomography and estimateRigidTransform, the function findTransformECCMultiScale implements
+an area-based alignment that builds on intensity similarities. In essence, the function updates the
+initial transformation that roughly aligns the images. If this information is missing, the identity
+warp (unity matrix) is used as an initialization. Note that if images undergo strong
+displacements/rotations, an initial transformation that roughly aligns the images is necessary
+(e.g., a simple euclidean/similarity transform that allows for the images showing the same image
+content approximately). Use inverse warping in the second image to take an image close to the first
+one, i.e. use the flag WARP_INVERSE_MAP with warpAffine or warpPerspective. See also the OpenCV
+sample image_alignment.cpp that demonstrates the use of the function. Note that the function throws
+an exception if algorithm does not converges.
+Unlike findTransformECC, the findTransformECCMultiScale uses pyramids, making function more stable
+and able to handle correctly more sophisticated cases.
+
+@sa
+computeECC, estimateAffine2D, estimateAffinePartial2D, findHomography
+*/
+
+CV_EXPORTS_W double findTransformECCMultiScale(InputArray reference,
+                        InputArray sample,
+                        InputOutputArray warpMatrix,
+                        const ECCParameters& eccParams = ECCParameters(),
+                        InputArray referenceMask = noArray(),
+                        InputArray sampleMask = noArray());
+
 /** @example samples/cpp/kalman.cpp
 An example using the standard Kalman filter
 */