fixed and improving formatting in opencv2refman.pdf. added support for n-channel mask in Mat::copyTo() and n-channel images in cv::compare(). fixed 2 compile warnings in opencv_python.

doc/CMakeLists.txt

@@ -29,6 +29,7 @@ add_custom_target(docs
                     ${CMAKE_CURRENT_SOURCE_DIR}/pics ${CMAKE_CURRENT_BINARY_DIR}/doc/opencv1/pics
                   COMMAND ${CMAKE_COMMAND} -E copy_if_different
                     ${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty ${CMAKE_CURRENT_BINARY_DIR}
+                  COMMAND ${PYTHON_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/patch_refman_latex.py" opencv2refman.tex
                   COMMAND ${PDFLATEX_COMPILER} opencv2refman.tex
                   COMMAND ${PDFLATEX_COMPILER} opencv2refman.tex
                   COMMAND ${PDFLATEX_COMPILER} opencv_user.tex

doc/conf.py

@@ -236,6 +236,7 @@ preamble ="""
 \usepackage[scaled=0.85]{beramono}
 \usepackage{mymath}\usepackage{amssymb}\usepackage{amsmath}\usepackage{bbm}\setcounter{secnumdepth}{1}
 \usepackage{colortbl}
+\usepackage{enumitem}
 """
 
 latex_elements = {'preamble': preamble}

doc/patch_refman_latex.py

@@ -0,0 +1,22 @@
+import sys
+
+f=open(sys.argv[1], "rt")
+ll = list(f.readlines())
+f.close()
+f=open(sys.argv[1], "wt")
+singleparam = False
+
+for l in ll:
+    l = l.replace("\\code{~const}}{}", "}{\\code{~const}}")
+    if l.startswith("\\item[{Parameters}] \\leavevmode"):
+        if not l.startswith("\\item[{Parameters}] \\leavevmode\\begin{itemize}"):
+            singleparam = True
+        l = "\\item[{Parameters}] \\leavevmode\\begin{itemize}[label=]\n"
+        if singleparam:
+            l += "\\item {}\n"
+    elif singleparam and l.startswith("\\end{description}\\end{quote}"):
+        l = "\\end{itemize}\n" + l
+        singleparam = False
+    f.write(l)
+
+f.close()

modules/core/doc/basic_structures.rst

@@ -654,50 +654,86 @@ Matrix Expressions
 ------------------
 
 This is a list of implemented matrix operations that can be combined in arbitrary complex expressions
-(here
+(here ``A``, ``B`` stand for matrices ( ``Mat`` ), ``s`` for a scalar ( ``Scalar`` ),
-*A*,*B*
+``alpha`` for a real-valued scalar ( ``double`` )):
-stand for matrices ( ``Mat`` ),
-*s*
-for a scalar ( ``Scalar`` ),
-:math:`\alpha` for a real-valued scalar ( ``double`` )):
 
 *
     Addition, subtraction, negation:
-    :math:`A \pm B,\;A \pm s,\;s \pm A,\;-A` *
+    ``A+B, A-B, A+s, A-s, s+A, s-A, -A``
-    scaling:
+    
-    :math:`A*\alpha`,    :math:`A*\alpha` *
+*   
-    per-element multiplication and division:
+    Scaling:
-    :math:`A.mul(B), A/B, \alpha/A` *
+    ``A*alpha``
-    matrix multiplication:
+    
-    :math:`A*B` *
+*
-    transposition:
+    Per-element multiplication and division:
-    :math:`A.t() \sim A^t` *
+    ``A.mul(B), A/B, alpha/A``
-    matrix inversion and pseudo-inversion, solving linear systems and least-squares problems:
+    
+*
+    Matrix multiplication:
+    ``A*B``
+    
+*
+    Transposition:
+    ``A.t()`` (means ``A``\ :sup:`T`)
+    
+*
+    Matrix inversion and pseudo-inversion, solving linear systems and least-squares problems:
 
-    :math:`A.inv([method]) \sim A^{-1}, A.inv([method])*B \sim X:\,AX=B`
+    ``A.inv([method])`` (~ ``A``\ :sup:`-1`) ``,   A.inv([method])*B`` (~ ``X: AX=B``)
     
 *
     Comparison:
-    :math:`A\gtreqqless B,\;A \ne B,\;A \gtreqqless \alpha,\;A \ne \alpha`. The result of comparison is an 8-bit single channel mask whose elements are set to 255 (if the particular element or pair of elements satisfy the condition) or 0.
+    ``A cmpop B, A cmpop alpha, alpha cmpop A``, where ``cmpop`` is one of ``:  >, >=, ==, !=, <=, <``. The result of comparison is an 8-bit single channel mask whose elements are set to 255 (if the particular element or pair of elements satisfy the condition) or 0.
 
 *
-    Bitwise logical operations: ``A & B, A & s, A | B, A | s, A textasciicircum B, A textasciicircum s, ~ A`` *
+    Bitwise logical operations: ``A logicop B, A logicop s, s logicop A, ~A``, where ``logicop`` is one of ``:  &, |, ^``.
-    element-wise minimum and maximum:
+    
-    :math:`min(A, B), min(A, \alpha), max(A, B), max(A, \alpha)` *
+*
-    element-wise absolute value:
+    Element-wise minimum and maximum:
-    :math:`abs(A)` *
+    ``min(A, B), min(A, alpha), max(A, B), max(A, alpha)``
-    cross-product, dot-product:
+    
-    :math:`A.cross(B), A.dot(B)` *
+*
-    any function of matrix or matrices and scalars that returns a matrix or a scalar, such as ``norm``, ``mean``, ``sum``, ``countNonZero``, ``trace``, ``determinant``, ``repeat``, and others.
+    Element-wise absolute value:
+    ``abs(A)``
+    
+*
+    Cross-product, dot-product:
+    ``A.cross(B)``
+    ``A.dot(B)``
+    
+*
+    Any function of matrix or matrices and scalars that returns a matrix or a scalar, such as ``norm``, ``mean``, ``sum``, ``countNonZero``, ``trace``, ``determinant``, ``repeat``, and others.
 
 *
-    Matrix initializers ( ``eye(), zeros(), ones()``     ), matrix comma-separated initializers, matrix constructors and operators that extract sub-matrices (see :ocv:class:`Mat`     description).
+    Matrix initializers ( ``Mat::eye(), Mat::zeros(), Mat::ones()`` ), matrix comma-separated initializers, matrix constructors and operators that extract sub-matrices (see :ocv:class:`Mat` description).
 
 *
     ``Mat_<destination_type>()`` constructors to cast the result to the proper type.
 
 .. note:: Comma-separated initializers and probably some other operations may require additional explicit ``Mat()`` or ``Mat_<T>()`` constuctor calls to resolve a possible ambiguity.
 
+Here are examples of matrix expressions:
+
+::
+
+    // compute pseudo-inverse of A, equivalent to A.inv(DECOMP_SVD)
+    SVD svd(A);
+    Mat pinvA = svd.vt.t()*Mat::diag(1./svd.w)*svd.u.t();
+    
+    // compute the new vector of parameters in the Levenberg-Marquardt algorithm
+    x -= (A.t()*A + lambda*Mat::eye(A.cols,A.cols,A.type())).inv(DECOMP_CHOLESKY)*(A.t()*err);
+    
+    // sharpen image using "unsharp mask" algorithm
+    Mat blurred; double sigma = 1, threshold = 5, amount = 1;
+    GaussianBlur(img, blurred, Size(), sigma, sigma);
+    Mat lowConstrastMask = abs(img - blurred) < threshold;
+    Mat sharpened = img*(1+amount) + blurred*(-amount);
+    img.copyTo(sharpened, lowContrastMask);
+    
+..
+
+
 Below is the formal description of the ``Mat`` methods.
 
 Mat::Mat
@@ -1488,7 +1524,7 @@ Mat::elemSize
 -----------------
 Returns  the matrix element size in bytes.
 
-.. ocv:function:: size_t Mat::elemSize(void) const
+.. ocv:function:: size_t Mat::elemSize() const
 
 The method returns the matrix element size in bytes. For example, if the matrix type is ``CV_16SC3`` , the method returns ``3*sizeof(short)`` or 6.
 

modules/core/doc/old_basic_structures.rst

@@ -544,13 +544,13 @@ Converts one array to another with optional linear transformation.
 .. ocv:pyoldfunction:: cv.ConvertScale(src, dst, scale=1.0, shift=0.0)-> None
 .. ocv:pyoldfunction:: cv.Convert(src, dst)-> None
 
-::
+    ::
     
-    #define cvCvtScale cvConvertScale
+        #define cvCvtScale cvConvertScale
-    #define cvScale  cvConvertScale
+        #define cvScale  cvConvertScale
-    #define cvConvert(src, dst )  cvConvertScale((src), (dst), 1, 0 )
+        #define cvConvert(src, dst )  cvConvertScale((src), (dst), 1, 0 )
 
-..
+    ..
     
     :param src: Source array 
     

modules/core/src/arithm.cpp

@@ -2093,8 +2093,8 @@ void cv::compare(InputArray _src1, InputArray _src2, OutputArray _dst, int op)
 
     if( kind1 == kind2 && src1.dims <= 2 && src2.dims <= 2 && src1.size() == src2.size() && src1.type() == src2.type() )
     {
-        CV_Assert(src1.channels() == 1);
+        int cn = src1.channels();
-        _dst.create(src1.size(), CV_8UC1);
+        _dst.create(src1.size(), CV_8UC(cn));
         Mat dst = _dst.getMat();
         Size sz = getContinuousSize(src1, src2, dst, src1.channels());
         cmpTab[src1.depth()](src1.data, src1.step, src2.data, src2.step, dst.data, dst.step, sz, &op);
@@ -2120,15 +2120,15 @@ void cv::compare(InputArray _src1, InputArray _src2, OutputArray _dst, int op)
         haveScalar = true;
     }
 
+    
     int cn = src1.channels(), depth1 = src1.depth(), depth2 = src2.depth();
-    if( cn != 1 )
-        CV_Error( CV_StsUnsupportedFormat, "compare() can only process single-channel arrays" );
 
+    _dst.create(src1.dims, src1.size, CV_8UC(cn));
+    src1 = src1.reshape(1); src2 = src2.reshape(1);
+    Mat dst = _dst.getMat().reshape(1);
+    
     size_t esz = src1.elemSize();
     size_t blocksize0 = (size_t)(BLOCK_SIZE + esz-1)/esz;
-
-    _dst.create(src1.dims, src1.size, CV_8U);
-    Mat dst = _dst.getMat();
     BinaryFunc func = cmpTab[depth1];
 
     if( !haveScalar )

modules/core/src/copy.cpp

@@ -207,9 +207,11 @@ void Mat::copyTo( OutputArray _dst, InputArray _mask ) const
         return;
     }
     
-    CV_Assert( mask.type() == CV_8U );
+    int cn = channels(), mcn = mask.channels();
+    CV_Assert( mask.depth() == CV_8U && (mcn == 1 || mcn == cn) );
+    bool colorMask = mcn > 1;
     
-    size_t esz = elemSize();
+    size_t esz = colorMask ? elemSize1() : elemSize();
     BinaryFunc copymask = getCopyMaskFunc(esz);
     
     uchar* data0 = _dst.getMat().data;
@@ -221,7 +223,7 @@ void Mat::copyTo( OutputArray _dst, InputArray _mask ) const
     
     if( dims <= 2 )
     {
-        Size sz = getContinuousSize(*this, dst, mask);
+        Size sz = getContinuousSize(*this, dst, mask, mcn);
         copymask(data, step, mask.data, mask.step, dst.data, dst.step, sz, &esz);
         return;
     }
@@ -229,7 +231,7 @@ void Mat::copyTo( OutputArray _dst, InputArray _mask ) const
     const Mat* arrays[] = { this, &dst, &mask, 0 };
     uchar* ptrs[3];
     NAryMatIterator it(arrays, ptrs);
-    Size sz((int)it.size, 1);
+    Size sz((int)(it.size*mcn), 1);
     
     for( size_t i = 0; i < it.nplanes; i++, ++it )
         copymask(ptrs[0], 0, ptrs[2], 0, ptrs[1], 0, sz, &esz);

modules/imgproc/doc/filtering.rst

@@ -1299,7 +1299,7 @@ The function performs the downsampling step of the Gaussian pyramid construction
 
 .. math::
 
-    \frac{1}{16} \begin{bmatrix} 1 & 4 & 6 & 4 & 1  \\ 4 & 16 & 24 & 16 & 4  \\ 6 & 24 & 36 & 24 & 6  \\ 4 & 16 & 24 & 16 & 4  \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}
+    \frac{1}{256} \begin{bmatrix} 1 & 4 & 6 & 4 & 1  \\ 4 & 16 & 24 & 16 & 4  \\ 6 & 24 & 36 & 24 & 6  \\ 4 & 16 & 24 & 16 & 4  \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}
 
 Then, it downsamples the image by rejecting even rows and columns.
 

modules/python/src2/cv2.cpp

@@ -746,8 +746,8 @@ static inline PyObject* pyopencv_from(const CvDTreeNode* node)
 static bool pyopencv_to(PyObject *o, cv::flann::IndexParams& p, const char *name="<unknown>")
 {
     bool ok = false;
-    PyObject* keys = PyMapping_Keys(o);
+    PyObject* keys = PyObject_CallMethod(o,(char*)"keys",0);
-    PyObject* values = PyMapping_Values(o);
+    PyObject* values = PyObject_CallMethod(o,(char*)"values",0);
     
     if( keys && values )
     {