Improve the documentation for affine transform estimation.

modules/calib3d/src/levmarq.cpp

@@ -44,7 +44,7 @@
 #include <stdio.h>
 
 /*
-   This is translation to C++ of the Matlab's LMSolve package by Miroslav Balda.
+   This is a translation to C++ from the Matlab's LMSolve package by Miroslav Balda.
    Here is the original copyright:
    ============================================================================
 

modules/calib3d/src/precomp.hpp

@@ -74,7 +74,7 @@ namespace cv
  * \frac{\ln(1-p)}{\ln\left(1-(1-ep)^\mathrm{modelPoints}\right)}
  * \f]
  *
- * If the computed number of iterations is less than maxIters, then 1 is returned.
+ * If the computed number of iterations is larger than maxIters, then maxIters is returned.
  */
 int RANSACUpdateNumIters( double p, double ep, int modelPoints, int maxIters );
 

modules/calib3d/src/ptsetreg.cpp

@@ -396,6 +396,19 @@ Ptr<PointSetRegistrator> createLMeDSPointSetRegistrator(const Ptr<PointSetRegist
 }
 
 
+/*
+ * Compute
+ *  x    a b c   X     t1
+ *  y  = d e f * Y  +  t2
+ *  z    g h i   Z     t3
+ *
+ *  - every element in _m1 contains (X,Y,Z), which are called source points
+ *  - every element in _m2 contains (x,y,z), which are called destination points
+ *  - _model is of size 3x4, which contains
+ *     a b c t1
+ *     d e f t2
+ *     g h i t3
+ */
 class Affine3DEstimatorCallback : public PointSetRegistrator::Callback
 {
 public:
@@ -499,6 +512,18 @@ public:
     }
 };
 
+/*
+ * Compute
+ *  x     a  b   X    c
+ *     =       *    +
+ *  y     d  e   Y    f
+ *
+ *  - every element in _m1 contains (X,Y), which are called source points
+ *  - every element in _m2 contains (x,y), which are called destination points
+ *  - _model is of size 2x3, which contains
+ *    a b c
+ *    d e f
+ */
 class Affine2DEstimatorCallback : public PointSetRegistrator::Callback
 {
 public:
@@ -600,6 +625,18 @@ public:
     }
 };
 
+/*
+ * Compute
+ *  x    c -s    X    t1
+ *    =       *     +
+ *  y    s  c    Y    t2
+ *
+ *  - every element in _m1 contains (X,Y), which are called source points
+ *  - every element in _m2 contains (x,y), which are called destination points
+ *  - _model is of size 2x3, which contains
+ *    c  -s  t1
+ *    s   c  t2
+ */
 class AffinePartial2DEstimatorCallback : public Affine2DEstimatorCallback
 {
 public:
@@ -766,7 +803,7 @@ public:
 
 int estimateAffine3D(InputArray _from, InputArray _to,
                      OutputArray _out, OutputArray _inliers,
-                     double param1, double param2)
+                     double ransacThreshold, double confidence)
 {
     CV_INSTRUMENT_REGION()
 
@@ -782,10 +819,10 @@ int estimateAffine3D(InputArray _from, InputArray _to,
     dTo = dTo.reshape(3, count);
 
     const double epsilon = DBL_EPSILON;
-    param1 = param1 <= 0 ? 3 : param1;
-    param2 = (param2 < epsilon) ? 0.99 : (param2 > 1 - epsilon) ? 0.99 : param2;
+    ransacThreshold = ransacThreshold <= 0 ? 3 : ransacThreshold;
+    confidence = (confidence < epsilon) ? 0.99 : (confidence > 1 - epsilon) ? 0.99 : confidence;
 
-    return createRANSACPointSetRegistrator(makePtr<Affine3DEstimatorCallback>(), 4, param1, param2)->run(dFrom, dTo, _out, _inliers);
+    return createRANSACPointSetRegistrator(makePtr<Affine3DEstimatorCallback>(), 4, ransacThreshold, confidence)->run(dFrom, dTo, _out, _inliers);
 }
 
 Mat estimateAffine2D(InputArray _from, InputArray _to, OutputArray _inliers,