Calculates absolute difference between an array and a scalar.
\cvdefC{void cvAbsDiffS(const CvArr* src, CvArr* dst, CvScalar value);}
-\cvdefPy{AbsDiffS(src1,value,dst)-> None}
+\cvdefPy{AbsDiffS(src,value,dst)-> None}
\ifC
\begin{lstlisting}
#define cvAbs(src, dst) cvAbsDiffS(src, dst, cvScalarAll(0))
Computes the per-element sum of two arrays.
\cvdefC{void cvAdd(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{Add(src1,src2,sdt,mask=NULL)-> None}
+\cvdefPy{Add(src1,src2,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src1}{The first source array}
Computes the sum of an array and a scalar.
\cvdefC{void cvAddS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{AddS(src1,value,dst,mask=NULL)-> None}
+\cvdefPy{AddS(src,value,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src}{The source array}
Calculates per-element bit-wise conjunction of an array and a scalar.
\cvdefC{void cvAndS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{AndS(src1,value,dst,mask=NULL)-> None}
+\cvdefPy{AndS(src,value,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src}{The source array}
Prior to the actual operation, the scalar is converted to the same type as that of the array(s). In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size.
+\ifC
The following sample demonstrates how to calculate the absolute value of floating-point array elements by clearing the most-significant bit:
\begin{lstlisting}
\begin{lstlisting}
1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0
\end{lstlisting}
-
+\fi
\cvCPyFunc{Avg}
Calculates average (mean) of array elements.
\[
\begin{array}{l}
N = \sum_I (\texttt{mask}(I) \ne 0)\\
-M_c = \frac{\sum_{ I, \, \texttt{mask}(I) \ne 0} \texttt{arr}(I)_c}{N}
+M_c = \frac{\sum_{I, \, \texttt{mask}(I) \ne 0} \texttt{arr}(I)_c}{N}
\end{array}
\]
Calculates average (mean) of array elements.
\cvdefC{void cvAvgSdv(const CvArr* arr, CvScalar* mean, CvScalar* stdDev, const CvArr* mask=NULL);}
-\cvdefPy{AvgSdv(arr,mask=NULL)-> mean, stdDev}
+\cvdefPy{AvgSdv(arr,mask=NULL)-> (mean, stdDev)}
\begin{description}
\cvarg{arr}{The array}
\begin{description}
\cvarg{vects}{The input vectors, all of which must have the same type and the same size. The vectors do not have to be 1D, they can be 2D (e.g., images) and so forth}
+\ifC
\cvarg{count}{The number of input vectors}
+\fi
\cvarg{covMat}{The output covariance matrix that should be floating-point and square}
\cvarg{avg}{The input or output (depending on the flags) array - the mean (average) vector of the input vectors}
\cvarg{flags}{The operation flags, a combination of the following values
\end{description}
-The function calculates the cubic root of the argument, and normally it is faster than \texttt{pow(value,1./3)}. In addition, negative arguments are handled properly. Special values ($ \pm \infty $, NaN) are not handled.
+The function calculates the cubic root of the argument, and normally it is faster than \texttt{pow(value,1./3)}. In addition, negative arguments are handled properly. Special values ($\pm \infty $, NaN) are not handled.
\cvCPyFunc{ClearND}
Clears a specific array element.
\end{description}
+\ifC % {
\cvCPyFunc{CloneSparseMat}
Creates full copy of sparse array.
\end{description}
The function creates a copy of the input array and returns pointer to the copy.
+\fi % }
\cvCPyFunc{Cmp}
Performs per-element comparison of two arrays.
\cvdefC{void cvCmp(const CvArr* src1, const CvArr* src2, CvArr* dst, int cmpOp);}
-\cvdefPy{Cmp(src1,src2,dst,cmOp)-> None}
+\cvdefPy{Cmp(src1,src2,dst,cmpOp)-> None}
\begin{description}
\cvarg{src1}{The first source array}
Performs per-element comparison of an array and a scalar.
\cvdefC{void cvCmpS(const CvArr* src, double value, CvArr* dst, int cmpOp);}
-\cvdefPy{CmpS(src1,value,dst,cmpOp)-> None}
+\cvdefPy{CmpS(src,value,dst,cmpOp)-> None}
\begin{description}
\cvarg{src}{The source array, must have a single channel}
\texttt{dst(I)} is set to 0xff (all \texttt{1}-bits) if the specific relation between the elements is true and 0 otherwise. All the arrays must have the same size (or ROI size).
+\ifPy % {
+\cvCPyFunc{Convert}
+Converts one array to another.
+
+\cvdefPy{Convert(src,dst)-> None}
+
+\begin{description}
+\cvarg{src}{Source array}
+\cvarg{dst}{Destination array}
+\end{description}
+
+
+The type of conversion is done with rounding and saturation, that is if the
+result of scaling + conversion can not be represented exactly by a value
+of the destination array element type, it is set to the nearest representable
+value on the real axis.
+
+All the channels of multi-channel arrays are processed independently.
+
+\fi % }
+
\cvCPyFunc{ConvertScale}
Converts one array to another with optional linear transformation.
\cvdefC{void cvConvertScale(const CvArr* src, CvArr* dst, double scale=1, double shift=0);}
\cvdefPy{ConvertScale(src,dst,scale=1.0,shift=0.0)-> None}
+\ifC
\begin{lstlisting}
#define cvCvtScale cvConvertScale
#define cvScale cvConvertScale
#define cvConvert(src, dst ) cvConvertScale((src), (dst), 1, 0 )
\end{lstlisting}
+\fi
\begin{description}
\cvarg{src}{Source array}
special case that can be used to scale and shift a matrix or an image
and that is caled \cvCPyCross{Scale}.
+
\cvCPyFunc{ConvertScaleAbs}
Converts input array elements to another 8-bit unsigned integer with optional linear transformation.
\cvdefC{void cvConvertScaleAbs(const CvArr* src, CvArr* dst, double scale=1, double shift=0);}
\cvdefPy{ConvertScaleAbs(src,dst,scale=1.0,shift=0.0)-> None}
-\begin{lstlisting}
-#define cvCvtScaleAbs cvConvertScaleAbs
-\end{lstlisting}
+\begin{description}
+\cvarg{src}{Source array}
+\cvarg{dst}{Destination array (should have 8u depth)}
+\cvarg{scale}{ScaleAbs factor}
+\cvarg{shift}{Value added to the scaled source array elements}
+\end{description}
+
+The function is similar to \cvCPyCross{ConvertScale}, but it stores absolute values of the conversion results:
+
+\[
+\texttt{dst}(I) = |\texttt{scale} \texttt{src}(I) + (\texttt{shift}_0,\texttt{shift}_1,...)|
+\]
+
+The function supports only destination arrays of 8u (8-bit unsigned integers) type; for other types the function can be emulated by a combination of \cvCPyCross{ConvertScale} and \cvCPyCross{Abs} functions.
+
+\cvCPyFunc{CvtScaleAbs}
+Converts input array elements to another 8-bit unsigned integer with optional linear transformation.
+
+\cvdefC{void cvCvtScaleAbs(const CvArr* src, CvArr* dst, double scale=1, double shift=0);}
+\cvdefPy{CvtScaleAbs(src,dst,scale=1.0,shift=0.0)-> None}
\begin{description}
\cvarg{src}{Source array}
\end{description}
+
The function is similar to \cvCPyCross{ConvertScale}, but it stores absolute values of the conversion results:
\[
Copies one array to another.
\cvdefC{void cvCopy(const CvArr* src, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{Copy(src,dst,msk=NULL)-> None}
+\cvdefPy{Copy(src,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src}{The source array}
Allocates array data
\cvdefC{void cvCreateData(CvArr* arr);}
-\cvdefPy{CreateData(arr)}
+\cvdefPy{CreateData(arr) -> None}
\begin{description}
\cvarg{arr}{Array header}
\cvarg{channels}{Number of channels per pixel. See \cross{IplImage} for details. This function only creates images with interleaved channels.}
\end{description}
+\ifC
This call is a shortened form of
\begin{lstlisting}
header = cvCreateImageHeader(size, depth, channels);
cvCreateData(header);
\end{lstlisting}
-
+\fi
\cvCPyFunc{CreateImageHeader}
Creates an image header but does not allocate the image data.
\cvarg{channels}{Number of channels (see \cvCPyCross{CreateImage})}
\end{description}
+\ifC
This call is an analogue of
\begin{lstlisting}
hdr=iplCreateImageHeader(channels, 0, depth,
0,0,0,0);
\end{lstlisting}
but it does not use IPL functions by default (see the \texttt{CV\_TURN\_ON\_IPL\_COMPATIBILITY} macro).
+\fi
\cvCPyFunc{CreateMat}\label{cvCreateMat}
Creates a matrix header and allocates the matrix data.
\cvdefC{CvMat* cvCreateMat(\par int rows,\par int cols,\par int type);}
-\cvdefPy{CreateMat(row, cols, type) -> mat}
+\cvdefPy{CreateMat(rows, cols, type) -> mat}
\begin{description}
\cvarg{rows}{Number of rows in the matrix}
\cvarg{type}{The type of the matrix elements in the form \texttt{CV\_<bit depth><S|U|F>C<number of channels>}, where S=signed, U=unsigned, F=float. For example, CV\_8UC1 means the elements are 8-bit unsigned and the there is 1 channel, and CV\_32SC2 means the elements are 32-bit signed and there are 2 channels.}
\end{description}
+\ifC
This is the concise form for:
\begin{lstlisting}
CvMat* mat = cvCreateMatHeader(rows, cols, type);
cvCreateData(mat);
\end{lstlisting}
+\fi
\cvCPyFunc{CreateMatHeader}
Creates a matrix header but does not allocate the matrix data.
Creates the header and allocates the data for a multi-dimensional dense array.
\cvdefC{CvMatND* cvCreateMatND(\par int dims,\par const int* sizes,\par int type);}
-\cvdefPy{CreateMatND(dims, type)}
+\cvdefPy{CreateMatND(dims, type) -> None}
\begin{description}
\ifPy
This is a short form for:
+\ifC
\begin{lstlisting}
CvMatND* mat = cvCreateMatNDHeader(dims, sizes, type);
cvCreateData(mat);
\end{lstlisting}
+\fi
\cvCPyFunc{CreateMatNDHeader}
Creates a new matrix header but does not allocate the matrix data.
\cvdefC{CvMatND* cvCreateMatNDHeader(\par int dims,\par const int* sizes,\par int type);}
-\cvdefPy{CreateMatNDHeader(dims, type)}
+\cvdefPy{CreateMatNDHeader(dims, type) -> None}
\begin{description}
\ifPy
The function allocates a header for a multi-dimensional dense array. The array data can further be allocated using \cvCPyCross{CreateData} or set explicitly to user-allocated data via \cvCPyCross{SetData}.
+\ifC % {
\cvCPyFunc{CreateSparseMat}
Creates sparse array.
\end{description}
The function allocates a multi-dimensional sparse array. Initially the array contain no elements, that is \cvCPyCross{Get} or \cvCPyCross{GetReal} returns zero for every index.
-
+\fi % }
\cvCPyFunc{CrossProduct}
Calculates the cross product of two 3D vectors.
\end{array}
\]
+\subsection{CvtPixToPlane}
+
+Synonym for \cross{Split}.
+
\cvCPyFunc{DCT}
Performs a forward or inverse Discrete Cosine transform of a 1D or 2D floating-point array.
\cvdefC{void cvDCT(const CvArr* src, CvArr* dst, int flags);}
\cvdefPy{DCT(src,dst,flags)-> None}
-\begin{lstlisting}
-#define CV_DXT_FORWARD 0
-#define CV_DXT_INVERSE 1
-#define CV_DXT_ROWS 4
-\end{lstlisting}
-
\begin{description}
\cvarg{src}{Source array, real 1D or 2D array}
\cvarg{dst}{Destination array of the same size and same type as the source}
\cvdefC{void cvDFT(const CvArr* src, CvArr* dst, int flags, int nonzeroRows=0);}
\cvdefPy{DFT(src,dst,flags,nonzeroRows=0)-> None}
-\begin{lstlisting}
-#define CV_DXT_FORWARD 0
-#define CV_DXT_INVERSE 1
-#define CV_DXT_SCALE 2
-#define CV_DXT_ROWS 4
-#define CV_DXT_INV_SCALE (CV_DXT_SCALE|CV_DXT_INVERSE)
-#define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE
-\end{lstlisting}
-
\begin{description}
\cvarg{src}{Source array, real or complex}
\cvarg{dst}{Destination array of the same size and same type as the source}
\cvarg{CV\_DXT\_INVERSE}{do an inverse 1D or 2D transform. The result is not scaled. \texttt{CV\_DXT\_FORWARD} and \texttt{CV\_DXT\_INVERSE} are mutually exclusive, of course.}
\cvarg{CV\_DXT\_SCALE}{scale the result: divide it by the number of array elements. Usually, it is combined with \texttt{CV\_DXT\_INVERSE}, and one may use a shortcut \texttt{CV\_DXT\_INV\_SCALE}.}
\cvarg{CV\_DXT\_ROWS}{do a forward or inverse transform of every individual row of the input matrix. This flag allows the user to transform multiple vectors simultaneously and can be used to decrease the overhead (which is sometimes several times larger than the processing itself), to do 3D and higher-dimensional transforms and so forth.}
+\cvarg{CV\_DXT\_INVERSE\_SCALE}{same as \texttt{CV\_DXT\_INVERSE + CV\_DXT\_SCALE}}
\end{description}}
\cvarg{nonzeroRows}{Number of nonzero rows in the source array
(in the case of a forward 2d transform), or a number of rows of interest in
Here is the example of how to compute 2D convolution using DFT.
+\ifC
\begin{lstlisting}
CvMat* A = cvCreateMat(M1, N1, CVg32F);
CvMat* B = cvCreateMat(M2, N2, A->type);
-// it is also possible to have only abs(M2-M1)+1 \times abs(N2-N1)+1
+// it is also possible to have only abs(M2-M1)+1 times abs(N2-N1)+1
// part of the full convolution result
CvMat* conv = cvCreateMat(A->rows + B->rows - 1, A->cols + B->cols - 1,
A->type);
cvCopy(&tmp, conv);
\end{lstlisting}
+\fi
\ifC
\cvdefC{
void cvEigenVV(\par CvArr* mat,\par CvArr* evects,\par CvArr* evals,\par double eps=0,
-\par int lowindex = 0, \par int highindex = 0);}
+\par int lowindex = -1, \par int highindex = -1);}
\cvdefPy{EigenVV(mat,evects,evals,eps,lowindex,highindex)-> None}
\begin{description}
\end{lstlisting}
If either low- or highindex is supplied the other is required, too.
-Indexing is 1-based. Example: To calculate the largest eigenvector/-value set
-lowindex = highindex = 1.
+Indexing is 0-based. Example: To calculate the largest eigenvector/-value set
+\texttt{lowindex=highindex=0}. To calculate all the eigenvalues, leave \texttt{lowindex=highindex=-1}.
For legacy reasons this function always returns a square matrix the same size
as the source matrix with eigenvectors and a vector the length of the source
matrix with eigenvalues. The selected eigenvectors/-values are always in the
\cvdefC{void cvFlip(const CvArr* src, CvArr* dst=NULL, int flipMode=0);}
\cvdefPy{Flip(src,dst=NULL,flipMode=0)-> None}
-\begin{lstlisting}
-#define cvMirror cvFlip
-\end{lstlisting}
-
\begin{description}
\cvarg{src}{Source array}
\cvarg{dst}{Destination array.
\item reversing the order of 1d point arrays (flipMode > 0)
\end{itemize}
+\ifPy
+
+\cvCPyFunc{fromarray}
+
+Create a CvMat from an object that supports the array interface.
+
+\cvdefPy{fromarray(object, allowND = False) -> CvMat}
+
+\begin{description}
+\cvarg{object}{Any object that supports the array interface}
+\cvarg{allowND}{If true, will return a CvMatND}
+\end{description}
+
+If the object supports the
+\href{http://docs.scipy.org/doc/numpy/reference/arrays.interface.html}{array interface},
+return a \cross{CvMat} (\texttt{allowND = False}) or \cross{CvMatND} (\texttt{allowND = True}).
+
+If \texttt{allowND = False}, then the object's array must be either 2D or 3D. If it is 2D, then the returned CvMat has a single channel. If it is 3D, then the returned CvMat will have N channels, where N is the last dimension of the array. In this case, N cannot be greater than OpenCV's channel limit, \texttt{CV\_CN\_MAX}.
+
+If \texttt{allowND = True}, then \texttt{fromarray} returns a single-channel \cross{CvMatND} with the same shape as the original array.
+
+For example, \href{http://numpy.scipy.org/}{NumPy} arrays support the array interface, so can be converted to OpenCV objects:
+
+\begin{lstlisting}
+>>> import cv, numpy
+>>> a = numpy.ones((480, 640))
+>>> mat = cv.fromarray(a)
+>>> print cv.GetDims(mat), cv.CV_MAT_CN(cv.GetElemType(mat))
+(480, 640) 1
+>>> a = numpy.ones((480, 640, 3))
+>>> mat = cv.fromarray(a)
+>>> print cv.GetDims(mat), cv.CV_MAT_CN(cv.GetElemType(mat))
+(480, 640) 3
+>>> a = numpy.ones((480, 640, 3))
+>>> mat = cv.fromarray(a, allowND = True)
+>>> print cv.GetDims(mat), cv.CV_MAT_CN(cv.GetElemType(mat))
+(480, 640, 3) 1
+\end{lstlisting}
+
+\fi
+
\cvCPyFunc{GEMM}
Performs generalized matrix multiplication.
\cvarg{CV\_GEMM\_B\_T}{transpose src2}
\cvarg{CV\_GEMM\_C\_T}{transpose src3}
\end{description}
+
For example, \texttt{CV\_GEMM\_A\_T+CV\_GEMM\_C\_T} corresponds to
\[
\texttt{alpha} \, \texttt{src1} ^T \, \texttt{src2} + \texttt{beta} \, \texttt{src3} ^T
All the matrices should have the same data type and coordinated sizes. Real or complex floating-point matrices are supported.
+\ifC % {
+
\cvCPyFunc{Get?D}
Return a specific array element.
\end{description}
The functions return a specific array element. In the case of a sparse array the functions return 0 if the requested node does not exist (no new node is created by the functions).
+\else % }{
+
+\cvCPyFunc{Get1D}
+Return a specific array element.
+
+\cvdefPy{Get1D(arr, idx) -> scalar}
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx}{Zero-based element index}
+\end{description}
+
+Return a specific array element. Array must have dimension 3.
+
+\cvCPyFunc{Get2D}
+Return a specific array element.
+
+\cvdefPy{ Get2D(arr, idx0, idx1) -> scalar }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx0}{Zero-based element row index}
+\cvarg{idx1}{Zero-based element column index}
+\end{description}
+
+Return a specific array element. Array must have dimension 2.
+
+\cvCPyFunc{Get3D}
+Return a specific array element.
+
+\cvdefPy{ Get3D(arr, idx0, idx1, idx2) -> scalar }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx0}{Zero-based element index}
+\cvarg{idx1}{Zero-based element index}
+\cvarg{idx2}{Zero-based element index}
+\end{description}
+
+Return a specific array element. Array must have dimension 3.
+\cvCPyFunc{GetND}
+Return a specific array element.
+
+\cvdefPy{ GetND(arr, indices) -> scalar }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{indices}{List of zero-based element indices}
+\end{description}
+
+Return a specific array element. The length of array indices must be the same as the dimension of the array.
+
+\fi % }
+
+\ifC % {
\cvCPyFunc{GetCol(s)}
Returns array column or column span.
cvGetCol(arr, submat, col); // ~ cvGetCols(arr, submat, col, col + 1);
\end{lstlisting}
+\else % }{
+
+\cvCPyFunc{GetCol}
+Returns array column.
+
+\cvdefPy{GetCol(arr,col)-> submat}
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{col}{Zero-based index of the selected column}
+\cvarg{submat}{resulting single-column array}
+\end{description}
+
+The function \texttt{GetCol} returns a single column from the input array.
+
+\cvCPyFunc{GetCols}
+Returns array column span.
+
+\cvdefPy{GetCols(arr,startCol,endCol)-> submat}
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{startCol}{Zero-based index of the starting column (inclusive) of the span}
+\cvarg{endCol}{Zero-based index of the ending column (exclusive) of the span}
+\cvarg{submat}{resulting multi-column array}
+\end{description}
+
+The function \texttt{GetCols} returns a column span from the input array.
+
+\fi % }
+
\cvCPyFunc{GetDiag}
Returns one of array diagonals.
Returns matrix header for arbitrary array.
\cvdefC{CvMat* cvGetMat(const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0);}
-\cvdefPy{GetMat(arr) -> cvmat }
+\cvdefPy{GetMat(arr, allowND=0) -> cvmat }
\begin{description}
\cvarg{arr}{Input array}
\ifC
\cvarg{header}{Pointer to \cross{CvMat} structure used as a temporary buffer}
\cvarg{coi}{Optional output parameter for storing COI}
-\cvarg{allowND}{If non-zero, the function accepts multi-dimensional dense arrays (CvMatND*) and returns 2D (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension or more than 2 dimensions). The array must be continuous.}
\fi
+\cvarg{allowND}{If non-zero, the function accepts multi-dimensional dense arrays (CvMatND*) and returns 2D (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension or more than 2 dimensions). The array must be continuous.}
\end{description}
The function returns a matrix header for the input array that can be a matrix -
\cvCPyFunc{GetReal?D}
Return a specific element of single-channel array.
-\begin{lstlisting}
-double cvGetReal1D(const CvArr* arr, int idx0);
-double cvGetReal2D(const CvArr* arr, int idx0, int idx1);
-double cvGetReal3D(const CvArr* arr, int idx0, int idx1, int idx2);
+\cvdefC{
+double cvGetReal1D(const CvArr* arr, int idx0); \newline
+double cvGetReal2D(const CvArr* arr, int idx0, int idx1); \newline
+double cvGetReal3D(const CvArr* arr, int idx0, int idx1, int idx2); \newline
double cvGetRealND(const CvArr* arr, int* idx);
-\end{lstlisting}
+}
\begin{description}
\cvarg{arr}{Input array. Must have a single channel.}
\fi
+\ifC %{
\cvCPyFunc{GetRow(s)}
Returns array row or row span.
cvGetRow(arr, submat, row ) ~ cvGetRows(arr, submat, row, row + 1, 1);
\end{lstlisting}
+\else % }{
+
+\cvCPyFunc{GetRow}
+Returns array row.
+
+\cvdefPy{GetRow(arr,row)-> submat}
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{row}{Zero-based index of the selected row}
+\cvarg{submat}{resulting single-row array}
+\end{description}
+
+The function \texttt{GetRow} returns a single row from the input array.
+
+\cvCPyFunc{GetRows}
+Returns array row span.
+
+\cvdefPy{GetRows(arr,startRow,endRow,deltaRow=1)-> submat}
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{startRow}{Zero-based index of the starting row (inclusive) of the span}
+\cvarg{endRow}{Zero-based index of the ending row (exclusive) of the span}
+\cvarg{deltaRow}{Index step in the row span.}
+\cvarg{submat}{resulting multi-row array}
+\end{description}
+
+The function \texttt{GetRows} returns a row span from the input array.
+
+\fi % }
\cvCPyFunc{GetSize}
Returns size of matrix or image ROI.
\end{description}
-The function calculates the inverse square root of the argument, and normally it is faster than \texttt{1./sqrt(value)}. If the argument is zero or negative, the result is not determined. Special values ($ \pm \infty $ , NaN) are not handled.
+The function calculates the inverse square root of the argument, and normally it is faster than \texttt{1./sqrt(value)}. If the argument is zero or negative, the result is not determined. Special values ($\pm \infty $ , NaN) are not handled.
+
+\cvCPyFunc{Inv}
+
+Synonym for \cross{Invert}
\cvCPyFunc{Invert}
Finds the inverse or pseudo-inverse of a matrix.
\cvdefC{double cvInvert(const CvArr* src, CvArr* dst, int method=CV\_LU);}
\cvdefPy{Invert(src,dst,method=CV\_LU)-> double}
-\begin{lstlisting}
-#define cvInv cvInvert
-\end{lstlisting}
\begin{description}
\cvarg{src}{The source matrix}
\cvarg{value}{The input floating-point value}
\end{description}
-The function returns 1 if the argument is $ \pm \infty $ (as defined by IEEE754 standard), 0 otherwise.
+The function returns 1 if the argument is $\pm \infty $ (as defined by IEEE754 standard), 0 otherwise.
\cvCPyFunc{IsNaN}
Determines if the argument is Not A Number.
Finds per-element maximum of array and scalar.
\cvdefC{void cvMaxS(const CvArr* src, double value, CvArr* dst);}
-\cvdefPy{MaxS(src1,value,dst)-> None}
+\cvdefPy{MaxS(src,value,dst)-> None}
\begin{description}
\cvarg{src}{The first source array}
\cvdefPy{Merge(src0,src1,src2,src3,dst)-> None}
\begin{description}
-\cvarg{src0...src3}{Input channels}
+\cvarg{src0}{Input channel 0}
+\cvarg{src1}{Input channel 1}
+\cvarg{src2}{Input channel 2}
+\cvarg{src3}{Input channel 3}
\cvarg{dst}{Destination array}
\end{description}
\cvdefC{void cvMinMaxLoc(const CvArr* arr, double* minVal, double* maxVal,
CvPoint* minLoc=NULL, CvPoint* maxLoc=NULL, const CvArr* mask=NULL);}
-\cvdefPy{MinMaxLoc(arr,mask=NULL)-> minVal,maxVal,minLoc,maxLoc}
+\cvdefPy{MinMaxLoc(arr,mask=NULL)-> (minVal,maxVal,minLoc,maxLoc)}
\begin{description}
\cvarg{arr}{The source array, single-channel or multi-channel with COI set}
Finds per-element minimum of an array and a scalar.
\cvdefC{void cvMinS(const CvArr* src, double value, CvArr* dst);}
-\cvdefPy{MinS(src1,value,dst)-> None}
+\cvdefPy{MinS(src,value,dst)-> None}
\begin{description}
\cvarg{src}{The first source array}
All the arrays must have a single channel, the same data type and the same size (or ROI size).
+\subsection{Mirror}
+Synonym for \cross{Flip}.
+
\cvCPyFunc{MixChannels}
Copies several channels from input arrays to certain channels of output arrays
\end{lstlisting}
\fi
+\subsection{MulAddS}
+
+Synonym for \cross{ScaleAdd}.
+
\cvCPyFunc{Mul}
Calculates the per-element product of two arrays.
Performs per-element multiplication of two Fourier spectrums.
\cvdefC{void cvMulSpectrums(\par const CvArr* src1,\par const CvArr* src2,\par CvArr* dst,\par int flags);}
-\cvdefPy{MulSpectrums(src1,src2,dst,flags)-> None)}
+\cvdefPy{MulSpectrums(src1,src2,dst,flags)-> None}
\begin{description}
\cvarg{src1}{The first source array}
Calculates the product of an array and a transposed array.
\cvdefC{void cvMulTransposed(const CvArr* src, CvArr* dst, int order, const CvArr* delta=NULL, double scale=1.0);}
-\cvdefPy{MulTransposed(src,dst,order,delta=NULL)-> None}
+\cvdefPy{MulTransposed(src,dst,order,delta=NULL,scale)-> None}
\begin{description}
\cvarg{src}{The source matrix}
Calculates absolute array norm, absolute difference norm, or relative difference norm.
\cvdefC{double cvNorm(const CvArr* arr1, const CvArr* arr2=NULL, int normType=CV\_L2, const CvArr* mask=NULL);}
-\cvdefPy{Norm(arr1,arr2,normType+CV\_L2,mask=NULL)-> double}
+\cvdefPy{Norm(arr1,arr2,normType=CV\_L2,mask=NULL)-> double}
\begin{description}
\cvarg{arr1}{The first source image}
\cvdefPy{Not(src,dst)-> None}
\begin{description}
-\cvarg{src1}{The source array}
+\cvarg{src}{The source array}
\cvarg{dst}{The destination array}
\end{description}
Calculates a per-element bit-wise disjunction of an array and a scalar.
\cvdefC{void cvOrS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{OrS(src1,value,dst,mask=NULL)-> None}
+\cvdefPy{OrS(src,value,dst,mask=NULL)-> None}
\begin{description}
-\cvarg{src1}{The source array}
+\cvarg{src}{The source array}
\cvarg{value}{Scalar to use in the operation}
\cvarg{dst}{The destination array}
\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
That is, for a non-integer power exponent the absolute values of input array elements are used. However, it is possible to get true values for negative values using some extra operations, as the following example, computing the cube root of array elements, shows:
+\ifC
\begin{lstlisting}
CvSize size = cvGetSize(src);
-CvMat* mask = cvCreateMat(size.height, size.width, CVg8UC1);
-cvCmpS(src, 0, mask, CVgCMPgLT); /* find negative elements */
+CvMat* mask = cvCreateMat(size.height, size.width, CV_8UC1);
+cvCmpS(src, 0, mask, CV_CMP_LT); /* find negative elements */
cvPow(src, dst, 1./3);
cvSubRS(dst, cvScalarAll(0), dst, mask); /* negate the results of negative inputs */
cvReleaseMat(&mask);
\end{lstlisting}
+\else
+\begin{lstlisting}
+>>> import cv
+>>> src = cv.CreateMat(1, 10, cv.CV_32FC1)
+>>> mask = cv.CreateMat(src.rows, src.cols, cv.CV_8UC1)
+>>> dst = cv.CreateMat(src.rows, src.cols, cv.CV_32FC1)
+>>> cv.CmpS(src, 0, mask, cv.CV_CMP_LT) # find negative elements
+>>> cv.Pow(src, dst, 1. / 3)
+>>> cv.SubRS(dst, cv.ScalarAll(0), dst, mask) # negate the results of negative inputs
+\end{lstlisting}
+\fi
For some values of \texttt{power}, such as integer values, 0.5, and -0.5, specialized faster algorithms are used.
\cvCPyFunc{Ptr?D}
Return pointer to a particular array element.
-\begin{lstlisting}
-uchar* cvPtr1D(const CvArr* arr, int idx0, int* type=NULL);
-uchar* cvPtr2D(const CvArr* arr, int idx0, int idx1, int* type=NULL);
-uchar* cvPtr3D(const CvArr* arr, int idx0, int idx1, int idx2, int* type=NULL);
+\cvdefC{
+uchar* cvPtr1D(const CvArr* arr, int idx0, int* type=NULL); \newline
+uchar* cvPtr2D(const CvArr* arr, int idx0, int idx1, int* type=NULL); \newline
+uchar* cvPtr3D(const CvArr* arr, int idx0, int idx1, int idx2, int* type=NULL); \newline
uchar* cvPtrND(const CvArr* arr, int* idx, int* type=NULL, int createNode=1, unsigned* precalcHashval=NULL);
-\end{lstlisting}
+}
\begin{description}
\cvarg{arr}{Input array}
\cvarg{image}{A pointer to the image header}
\end{description}
-This produces a similar result to the following, but in addition it releases the ROI structure.
+This produces a similar result to the following
+\ifC
+, but in addition it releases the ROI structure.
\begin{lstlisting}
cvSetImageROI(image, cvRect(0, 0, image->width, image->height ));
cvSetImageCOI(image, 0);
\end{lstlisting}
+\else
+
+\begin{lstlisting}
+cv.SetImageROI(image, (0, 0, image.width, image.height))
+cv.SetImageCOI(image, 0)
+\end{lstlisting}
+\fi
\cvCPyFunc{Reshape}
\cvarg{newSizes}{Array of new dimension sizes. Only $\texttt{newDims}-1$ values are used, because the total number of elements must remain the same.
Thus, if $\texttt{newDims} = 1$, \texttt{newSizes} array is not used.}
\else
+\cvarg{newCn}{New number of channels. $\texttt{newCn} = 0$ means that the number of channels remains unchanged.}
\cvarg{newDims}{List of new dimensions.}
\fi
\end{description}
-The function is an advanced version of \cvCPyCross{Reshape} that can work with multi-dimensional arrays as well (though it can work with ordinary images and matrices) and change the number of dimensions.
\ifC
+The function is an advanced version of \cvCPyCross{Reshape} that can work with multi-dimensional arrays as well (though it can work with ordinary images and matrices) and change the number of dimensions.
+
Below are the two samples from the \cvCPyCross{Reshape} description rewritten using \cvCPyCross{ReshapeMatND}:
\begin{lstlisting}
\end{lstlisting}
\fi
-\ifC
-\subsection{cvRound, cvFloor, cvCeil}\label{cvRound}
-\fi
\ifPy
-\subsection{cv.Round, cv.Floor, cv.Ceil}\label{cv.Round}
+Returns a new \cross{CvMatND} that shares the same data as \texttt{arr}
+but has different dimensions or number of channels. The only requirement
+is that the total length of the data is unchanged.
+
+\begin{lstlisting}
+>>> import cv
+>>> mat = cv.CreateMatND([24], cv.CV_32FC1)
+>>> print cv.GetDims(cv.ReshapeMatND(mat, 0, [8, 3]))
+(8, 3)
+>>> m2 = cv.ReshapeMatND(mat, 4, [3, 2])
+>>> print cv.GetDims(m2)
+(3, 2)
+>>> print m2.channels
+4
+\end{lstlisting}
\fi
+
+\ifC
+\cvfunc{cvRound, cvFloor, cvCeil}\label{cvRound}
+
Converts a floating-point number to an integer.
\cvdefC{
value that is not smaller than the argument. On some architectures the
functions work much faster than the standard cast
operations in C. If the absolute value of the argument is greater than
-$2^{31}$, the result is not determined. Special values ($ \pm \infty$ , NaN)
+$2^{31}$, the result is not determined. Special values ($\pm \infty$ , NaN)
+are not handled.
+
+\else
+
+\cvCPyFunc{Round}
+
+Converts a floating-point number to the nearest integer value.
+
+\cvdefPy{Round(value) -> int}
+
+\begin{description}
+\cvarg{value}{The input floating-point value}
+\end{description}
+
+On some architectures this function is much faster than the standard cast
+operations. If the absolute value of the argument is greater than
+$2^{31}$, the result is not determined. Special values ($\pm \infty$ , NaN)
+are not handled.
+
+\cvCPyFunc{Floor}
+
+Converts a floating-point number to the nearest integer value that is not larger than the argument.
+
+\cvdefPy{Floor(value) -> int}
+
+\begin{description}
+\cvarg{value}{The input floating-point value}
+\end{description}
+
+On some architectures this function is much faster than the standard cast
+operations. If the absolute value of the argument is greater than
+$2^{31}$, the result is not determined. Special values ($\pm \infty$ , NaN)
+are not handled.
+
+\cvCPyFunc{Ceil}
+
+Converts a floating-point number to the nearest integer value that is not smaller than the argument.
+
+\cvdefPy{Ceil(value) -> int}
+
+\begin{description}
+\cvarg{value}{The input floating-point value}
+\end{description}
+
+On some architectures this function is much faster than the standard cast
+operations. If the absolute value of the argument is greater than
+$2^{31}$, the result is not determined. Special values ($\pm \infty$ , NaN)
are not handled.
+\fi
+
\cvCPyFunc{ScaleAdd}
Calculates the sum of a scaled array and another array.
\cvdefC{void cvScaleAdd(const CvArr* src1, CvScalar scale, const CvArr* src2, CvArr* dst);}
-\cvdefPy{ScaleAdd(src1,sclae,src2,dst)-> None}
-\begin{lstlisting}
-#define cvMulAddS cvScaleAdd
-\end{lstlisting}
+\cvdefPy{ScaleAdd(src1,scale,src2,dst)-> None}
\begin{description}
\cvarg{src1}{The first source array}
Sets every element of an array to a given value.
\cvdefC{void cvSet(CvArr* arr, CvScalar value, const CvArr* mask=NULL);}
-\cvdefPy{Set(arr,value,msk=NULL)-> None}
+\cvdefPy{Set(arr,value,mask=NULL)-> None}
\begin{description}
\cvarg{arr}{The destination array}
If array \texttt{arr} is of \texttt{IplImage} type, then is ROI used, but COI must not be set.
+\ifC % {
\cvCPyFunc{Set?D}
Change the particular array element.
-\begin{lstlisting}
-void cvSet1D(CvArr* arr, int idx0, CvScalar value);
-void cvSet2D(CvArr* arr, int idx0, int idx1, CvScalar value);
-void cvSet3D(CvArr* arr, int idx0, int idx1, int idx2, CvScalar value);
+\cvdefC{
+void cvSet1D(CvArr* arr, int idx0, CvScalar value); \newline
+void cvSet2D(CvArr* arr, int idx0, int idx1, CvScalar value); \newline
+void cvSet3D(CvArr* arr, int idx0, int idx1, int idx2, CvScalar value); \newline
void cvSetND(CvArr* arr, int* idx, CvScalar value);
-\end{lstlisting}
+}
\begin{description}
\cvarg{arr}{Input array}
The functions assign the new value to a particular array element. In the case of a sparse array the functions create the node if it does not exist yet.
+\else % }{
+
+\cvCPyFunc{Set1D}
+Set a specific array element.
+
+\cvdefPy{ Set1D(arr, idx, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx}{Zero-based element index}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. Array must have dimension 1.
+
+\cvCPyFunc{Set2D}
+Set a specific array element.
+
+\cvdefPy{ Set2D(arr, idx0, idx1, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx0}{Zero-based element row index}
+\cvarg{idx1}{Zero-based element column index}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. Array must have dimension 2.
+
+\cvCPyFunc{Set3D}
+Set a specific array element.
+
+\cvdefPy{ Set3D(arr, idx0, idx1, idx2, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx0}{Zero-based element index}
+\cvarg{idx1}{Zero-based element index}
+\cvarg{idx2}{Zero-based element index}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. Array must have dimension 3.
+
+\cvCPyFunc{SetND}
+Set a specific array element.
+
+\cvdefPy{ SetND(arr, indices, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{indices}{List of zero-based element indices}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. The length of array indices must be the same as the dimension of the array.
+\fi % }
+
\cvCPyFunc{SetData}
Assigns user data to the array header.
Initializes a scaled identity matrix.
\cvdefC{void cvSetIdentity(CvArr* mat, CvScalar value=cvRealScalar(1));}
-\cvdefPy{SetIdentity(mat,value=cvRealScalar(1))-> None}
+\cvdefPy{SetIdentity(mat,value=1)-> None}
\begin{description}
-\cvarg{arr}{The matrix to initialize (not necesserily square)}
+\cvarg{mat}{The matrix to initialize (not necesserily square)}
\cvarg{value}{The value to assign to the diagonal elements}
\end{description}
Most OpenCV functions support the use of ROI and treat the image rectangle as a separate image. For example, all of the pixel coordinates are counted from the top-left (or bottom-left) corner of the ROI, not the original image.
+\ifC % {
\cvCPyFunc{SetReal?D}
Change a specific array element.
-\begin{lstlisting}
-void cvSetReal1D(CvArr* arr, int idx0, double value);
-void cvSetReal2D(CvArr* arr, int idx0, int idx1, double value);
-void cvSetReal3D(CvArr* arr, int idx0, int idx1, int idx2, double value);
+\cvdefC{
+void cvSetReal1D(CvArr* arr, int idx0, double value); \newline
+void cvSetReal2D(CvArr* arr, int idx0, int idx1, double value); \newline
+void cvSetReal3D(CvArr* arr, int idx0, int idx1, int idx2, double value); \newline
void cvSetRealND(CvArr* arr, int* idx, double value);
-\end{lstlisting}
+}
\begin{description}
\cvarg{arr}{Input array}
In the case of a sparse array the functions create the node if it does not yet exist.
+\else % }{
+
+\cvCPyFunc{SetReal1D}
+Set a specific array element.
+
+\cvdefPy{ SetReal1D(arr, idx, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx}{Zero-based element index}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. Array must have dimension 1.
+
+\cvCPyFunc{SetReal2D}
+Set a specific array element.
+
+\cvdefPy{ SetReal2D(arr, idx0, idx1, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx0}{Zero-based element row index}
+\cvarg{idx1}{Zero-based element column index}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. Array must have dimension 2.
+
+\cvCPyFunc{SetReal3D}
+Set a specific array element.
+
+\cvdefPy{ SetReal3D(arr, idx0, idx1, idx2, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{idx0}{Zero-based element index}
+\cvarg{idx1}{Zero-based element index}
+\cvarg{idx2}{Zero-based element index}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. Array must have dimension 3.
+
+\cvCPyFunc{SetRealND}
+Set a specific array element.
+
+\cvdefPy{ SetRealND(arr, indices, value) -> None }
+
+\begin{description}
+\cvarg{arr}{Input array}
+\cvarg{indices}{List of zero-based element indices}
+\cvarg{value}{The value to assign to the element}
+\end{description}
+
+Sets a specific array element. The length of array indices must be the same as the dimension of the array.
+\fi % }
+
\cvCPyFunc{SetZero}
Clears the array.
CvArr* dst2, CvArr* dst3);}
\cvdefPy{Split(src,dst0,dst1,dst2,dst3)-> None}
-\begin{lstlisting}
-#define cvCvtPixToPlane cvSplit
-\end{lstlisting}
-
\begin{description}
\cvarg{src}{Source array}
-\cvarg{dst0...dst3}{Destination channels}
+\cvarg{dst0}{Destination channel 0}
+\cvarg{dst1}{Destination channel 1}
+\cvarg{dst2}{Destination channel 2}
+\cvarg{dst3}{Destination channel 3}
\end{description}
The function divides a multi-channel array into separate
Computes the difference between a scalar and an array.
\cvdefC{void cvSubRS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{SubRS(src1,value,dst,mask=NULL)-> None}
+\cvdefPy{SubRS(src,value,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src}{The first source array}
Computes the difference between an array and a scalar.
\cvdefC{void cvSubS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{SubS(src1,value,dst,mask=NULL)-> None}
+\cvdefPy{SubS(src,value,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src}{The source array}
Performs singular value decomposition of a real floating-point matrix.
\cvdefC{void cvSVD(\par CvArr* A, \par CvArr* W, \par CvArr* U=NULL, \par CvArr* V=NULL, \par int flags=0);}
-\cvdefPy{SVD(A,flags=0)-> W,U,V}
+\cvdefPy{SVD(A,W, U = None, V = None, flags=0)-> None}
\begin{description}
\cvarg{A}{Source $\texttt{M} \times \texttt{N}$ matrix}
\cvdefC{void cvTranspose(const CvArr* src, CvArr* dst);}
\cvdefPy{Transpose(src,dst)-> None}
-\begin{lstlisting}
-#define cvT cvTranspose
-\end{lstlisting}
-
\begin{description}
\cvarg{src}{The source matrix}
\cvarg{dst}{The destination matrix}
Performs per-element bit-wise "exclusive or" operation on an array and a scalar.
\cvdefC{void cvXorS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL);}
-\cvdefPy{XorS(src1,value,dst,mask=NULL)-> None}
+\cvdefPy{XorS(src,value,dst,mask=NULL)-> None}
\begin{description}
\cvarg{src}{The source array}
Prior to the actual operation, the scalar is converted to the same type as that of the array(s). In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size
+\ifC
The following sample demonstrates how to conjugate complex vector by switching the most-significant bit of imaging part:
\begin{lstlisting}
int i, negMask = 0x80000000;
cvXorS(&A, cvScalar(0, *(float*)&negMask, 0, 0 ), &A, 0);
for(i = 0; i < 4; i++ )
- printf("(%.1f, %.1f) ", a[i*2], a[i*2+1]);
+ printf("(\%.1f, \%.1f) ", a[i*2], a[i*2+1]);
\end{lstlisting}
\begin{lstlisting}
(1.0,0.0) (0.0,-1.0) (-1.0,0.0) (0.0,1.0)
\end{lstlisting}
+\fi
\cvCPyFunc{mGet}
Returns the particular element of single-channel floating-point matrix.
See also: \cvCppCross{add}, \cvCppCross{subtract}, \cvCppCross{scaleAdd}, \cvCppCross{convertScale},
\cross{Matrix Expressions}, \hyperref[cppfunc.saturatecast]{saturate\_cast}.
-\subsection{cv::bitwise\_and}\label{cppfunc.bitwise.and}
+\cvfunc{bitwise\_and}\label{cppfunc.bitwise.and}
Calculates per-element bit-wise conjunction of two arrays and an array and a scalar.
\cvdefCpp{void bitwise\_and(const Mat\& src1, const Mat\& src2,\par Mat\& dst, const Mat\& mask=Mat());\newline
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.not]{bitwise\_not}, \hyperref[cppfunc.bitwise.xor]{bitwise\_xor}
-\subsection{cv::bitwise\_not}\label{cppfunc.bitwise.not}
+\cvfunc{bitwise\_not}\label{cppfunc.bitwise.not}
Inverts every bit of array
\cvdefCpp{void bitwise\_not(const Mat\& src, Mat\& dst);\newline
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.or]{bitwise\_or}, \hyperref[cppfunc.bitwise.xor]{bitwise\_xor}
-\subsection{cv::bitwise\_or}\label{cppfunc.bitwise.or}
+\cvfunc{bitwise\_or}\label{cppfunc.bitwise.or}
Calculates per-element bit-wise disjunction of two arrays and an array and a scalar.
\cvdefCpp{void bitwise\_or(const Mat\& src1, const Mat\& src2,\par Mat\& dst, const Mat\& mask=Mat());\newline
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.not]{bitwise\_not}, \hyperref[cppfunc.bitwise.or]{bitwise\_or}
-\subsection{cv::bitwise\_xor}\label{cppfunc.bitwise.xor}
+\cvfunc{bitwise\_xor}\label{cppfunc.bitwise.xor}
Calculates per-element bit-wise "exclusive or" operation on two arrays and an array and a scalar.
\cvdefCpp{void bitwise\_xor(const Mat\& src1, const Mat\& src2,\par Mat\& dst, const Mat\& mask=Mat());\newline
\end{description}
The functions \texttt{checkRange} check that every array element is
-neither NaN nor $ \pm \infty $. When \texttt{minVal < -DBL\_MAX} and \texttt{maxVal < DBL\_MAX}, then the functions also check that
+neither NaN nor $\pm \infty $. When \texttt{minVal < -DBL\_MAX} and \texttt{maxVal < DBL\_MAX}, then the functions also check that
each value is between \texttt{minVal} and \texttt{maxVal}. in the case of multi-channel arrays each channel is processed independently.
If some values are out of range, position of the first outlier is stored in \texttt{pos} (when $\texttt{pos}\ne0$), and then the functions either return false (when \texttt{quiet=true}) or throw an exception.
\cvdefCpp{int countNonZero( const Mat\& mtx );\newline
int countNonZero( const MatND\& mtx );}
\begin{description}
-\cvarg{mtx}Single-channel array
+\cvarg{mtx}{Single-channel array}
\end{description}
The function \texttt{cvCountNonZero} returns the number of non-zero elements in mtx:
\cvdefCpp{float cubeRoot(float val);}
\begin{description}
-\cvarg{val}The function argument
+\cvarg{val}{The function argument}
\end{description}
The function \texttt{cubeRoot} computes $\sqrt[3]{\texttt{val}}$.
\begin{description}
\cvarg{src}{The source floating-point array}
\cvarg{dst}{The destination array; will have the same size and same type as \texttt{src}}
-\cvarg{flags}\cvarg{flags}{Transformation flags, a combination of the following values
+\cvarg{flags}{Transformation flags, a combination of the following values
\begin{description}
\cvarg{DCT\_INVERSE}{do an inverse 1D or 2D transform instead of the default forward transform.}
\cvarg{DCT\_ROWS}{do a forward or inverse transform of every individual row of the input matrix. This flag allows user to transform multiple vectors simultaneously and can be used to decrease the overhead (which is sometimes several times larger than the processing itself), to do 3D and higher-dimensional transforms and so forth.}
See also: \cvCppCross{norm}, \cvCppCross{Mat::convertScale}, \cvCppCross{MatND::convertScale}, \cvCppCross{SparseMat::convertScale}
-\cvCppFunc{PCA}
+\cvclass{PCA}
Class for Principal Component Analysis
\begin{lstlisting}
{
public:
// default constructor
- PCA();newline
+ PCA();
// computes PCA for a set of vectors stored as data rows or columns.
- PCA(const Mat& data, const Mat& mean, int flags, int maxComponents=0);newline
+ PCA(const Mat& data, const Mat& mean, int flags, int maxComponents=0);
// computes PCA for a set of vectors stored as data rows or columns
- PCA& operator()(const Mat& data, const Mat& mean, int flags, int maxComponents=0);newline
+ PCA& operator()(const Mat& data, const Mat& mean, int flags, int maxComponents=0);
// projects vector into the principal components space
- Mat project(const Mat& vec) const;newline
- void project(const Mat& vec, Mat& result) const;newline
+ Mat project(const Mat& vec) const;
+ void project(const Mat& vec, Mat& result) const;
// reconstructs the vector from its PC projection
- Mat backProject(const Mat& vec) const;newline
- void backProject(const Mat& vec, Mat& result) const;newline
+ Mat backProject(const Mat& vec) const;
+ void backProject(const Mat& vec, Mat& result) const;
// eigenvectors of the PC space, stored as the matrix rows
- Mat eigenvectors;newline
+ Mat eigenvectors;
// the corresponding eigenvalues; not used for PCA compression/decompression
- Mat eigenvalues;newline
+ Mat eigenvalues;
// mean vector, subtracted from the projected vector
// or added to the reconstructed vector
Mat mean;
See also: \cvCppCross{calcCovarMatrix}, \cvCppCross{mulTransposed}, \cvCppCross{SVD}, \cvCppCross{dft}, \cvCppCross{dct}
+\cvCppFunc{PCA::PCA}
+PCA constructors
+
+\cvdefCpp{
+PCA::PCA();\newline
+PCA::PCA(const Mat\& data, const Mat\& mean, int flags, int maxComponents=0);
+}
+\begin{description}
+\cvarg{data}{the input samples, stored as the matrix rows or as the matrix columns}
+\cvarg{mean}{the optional mean value. If the matrix is empty (\texttt{Mat()}), the mean is computed from the data.}
+\cvarg{flags}{operation flags. Currently the parameter is only used to specify the data layout.}
+\begin{description}
+ \cvarg{CV\_PCA\_DATA\_AS\_ROWS}{Indicates that the input samples are stored as matrix rows.}
+ \cvarg{CV\_PCA\_DATA\_AS\_COLS}{Indicates that the input samples are stored as matrix columns.}
+\end{description}
+\cvarg{maxComponents}{The maximum number of components that PCA should retain. By default, all the components are retained.}
+\end{description}
+
+The default constructor initializes empty PCA structure. The second constructor initializes the structure and calls \cvCppCross{PCA::operator ()}.
+
+\cvCppFunc{PCA::operator ()}
+Performs Principal Component Analysis of the supplied dataset.
+
+\cvdefCpp{
+PCA\& PCA::operator()(const Mat\& data, const Mat\& mean, int flags, int maxComponents=0);
+}
+\begin{description}
+\cvarg{data}{the input samples, stored as the matrix rows or as the matrix columns}
+\cvarg{mean}{the optional mean value. If the matrix is empty (\texttt{Mat()}), the mean is computed from the data.}
+\cvarg{flags}{operation flags. Currently the parameter is only used to specify the data layout.}
+\begin{description}
+ \cvarg{CV\_PCA\_DATA\_AS\_ROWS}{Indicates that the input samples are stored as matrix rows.}
+ \cvarg{CV\_PCA\_DATA\_AS\_COLS}{Indicates that the input samples are stored as matrix columns.}
+\end{description}
+\cvarg{maxComponents}{The maximum number of components that PCA should retain. By default, all the components are retained.}
+\end{description}
+
+The operator performs PCA of the supplied dataset. It is safe to reuse the same PCA structure for multiple dataset. That is, if the structure has been previously used with another dataset, the existing internal data is reclaimed and the new \texttt{eigenvalues}, \texttt{eigenvectors} and \texttt{mean} are allocated and computed.
+
+The computed eigenvalues are sorted from the largest to the smallest and the corresponding eigenvectors are stored as \texttt{PCA::eigenvectors} rows.
+
+\cvCppFunc{PCA::project}
+Project vector(s) to the principal component subspace
+
+\cvdefCpp{
+Mat PCA::project(const Mat\& vec) const;\newline
+void PCA::project(const Mat\& vec, Mat\& result) const;
+}
+\begin{description}
+\cvarg{vec}{the input vector(s). They have to have the same dimensionality and the same layout as the input data used at PCA phase. That is, if \texttt{CV\_PCA\_DATA\_AS\_ROWS} had been specified, then \texttt{vec.cols==data.cols} (that's vectors' dimensionality) and \texttt{vec.rows} is the number of vectors to project; and similarly for the \texttt{CV\_PCA\_DATA\_AS\_COLS} case.}
+\cvarg{result}{the output vectors. Let's now consider \texttt{CV\_PCA\_DATA\_AS\_COLS} case. In this case the output matrix will have as many columns as the number of input vectors, i.e. \texttt{result.cols==vec.cols} and the number of rows will match the number of principal components (e.g. \texttt{maxComponents} parameter passed to the constructor).}
+\end{description}
+
+The methods project one or more vectors to the principal component subspace, where each vector projection is represented by coefficients in the principal component basis. The first form of the method returns the matrix that the second form writes to the result. So the first form can be used as a part of expression, while the second form can be more efficient in a processing loop.
+
+\cvCppFunc{PCA::backProject}
+Reconstruct vectors from their PC projections.
+
+\cvdefCpp{
+Mat PCA::backProject(const Mat\& vec) const;\newline
+void PCA::backProject(const Mat\& vec, Mat\& result) const;
+}
+\begin{description}
+\cvarg{vec}{Coordinates of the vectors in the principal component subspace. The layout and size are the same as of \texttt{PCA::project} output vectors.}
+\cvarg{result}{The reconstructed vectors. The layout and size are the same as of \texttt{PCA::project} input vectors.}
+\end{description}
+
+The methods are inverse operations to \cvCppCross{PCA::project}. They take PC coordinates of projected vectors and reconstruct the original vectors. Of course, unless all the principal components have been retained, the reconstructed vectors will be different from the originals, but typically the difference will be small is if the number of components is large enough (but still much smaller than the original vector dimensionality) - that's why PCA is used after all.
+
\cvCppFunc{perspectiveTransform}
Performs perspective matrix transformation of vectors.
See also: \cvCppCross{sqrt}, \cvCppCross{exp}, \cvCppCross{log}, \cvCppCross{cartToPolar}, \cvCppCross{polarToCart}
+
+\subsection{RNG}\label{RNG}
+
+Random number generator class.
+
+\begin{lstlisting}
+class CV_EXPORTS RNG
+{
+public:
+ enum { A=4164903690U, UNIFORM=0, NORMAL=1 };
+
+ // constructors
+ RNG();
+ RNG(uint64 state);
+
+ // returns 32-bit unsigned random number
+ unsigned next();
+
+ // return random numbers of the specified type
+ operator uchar();
+ operator schar();
+ operator ushort();
+ operator short();
+ operator unsigned();
+ // returns a random integer sampled uniformly from [0, N).
+ unsigned operator()(unsigned N);
+ unsigned operator()();
+ operator int();
+ operator float();
+ operator double();
+ // returns a random number sampled uniformly from [a, b) range
+ int uniform(int a, int b);
+ float uniform(float a, float b);
+ double uniform(double a, double b);
+
+ // returns Gaussian random number with zero mean.
+ double gaussian(double sigma);
+
+ // fills array with random numbers sampled from the specified distribution
+ void fill( Mat& mat, int distType, const Scalar& a, const Scalar& b );
+ void fill( MatND& mat, int distType, const Scalar& a, const Scalar& b );
+
+ // internal state of the RNG (could change in the future)
+ uint64 state;
+};
+\end{lstlisting}
+
+The class \texttt{RNG} implements random number generator. It encapsulates the RNG state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia (\url{http://en.wikipedia.org/wiki/Multiply-with-carry}). Gaussian-distribution random numbers are generated using Ziggurat algorithm (\url{http://en.wikipedia.org/wiki/Ziggurat_algorithm}), introduced by G. Marsaglia and W. W. Tsang.
+
+\cvCppFunc{RNG::RNG}
+RNG constructors
+
+\cvdefCpp{
+RNG::RNG();\newline
+RNG::RNG(uint64 state);
+}
+\begin{description}
+\cvarg{state}{the 64-bit value used to initialize the RNG}
+\end{description}
+
+These are the RNG constructors. The first form sets the state to some pre-defined value, equal to \texttt{2**32-1} in the current implementation. The second form sets the state to the specified value. If the user passed \texttt{state=0}, the constructor uses the above default value instead, to avoid the singular random number sequence, consisting of all zeros.
+
+\cvCppFunc{RNG::next}
+Returns the next random number
+
+\cvdefCpp{
+unsigned RNG::next();
+}
+
+The method updates the state using MWC algorithm and returns the next 32-bit random number.
+
+
+\cvCppFunc{RNG::operator T}
+Returns the next random number of the specified type
+
+\cvdefCpp{
+RNG::operator uchar();
+RNG::operator schar();
+RNG::operator ushort();
+RNG::operator short();
+RNG::operator unsigned();
+RNG::operator int();
+RNG::operator float();
+RNG::operator double();
+}
+
+Each of the methods updates the state using MWC algorithm and returns the next random number of the specified type. In the case of integer types the returned number is from the whole available value range for the specified type. In the case of floating-point types the returned value is from \texttt{[0,1)} range.
+
+\cvCppFunc{RNG::operator ()}
+Returns the next random number
+
+\cvdefCpp{
+unsigned RNG::operator ()();\newline
+unsigned RNG::operator ()(unsigned N);
+}
+\begin{description}
+\cvarg{N}{The upper non-inclusive boundary of the returned random number}
+\end{description}
+
+The methods transforms the state using MWC algorithm and returns the next random number. The first form is equivalent to \cvCppCross{RNG::next}, the second form returns the random number modulo \texttt{N}, i.e. the result will be in the range \texttt{[0, N)}.
+
+\cvCppFunc{RNG::uniform}
+Returns the next random number sampled from the uniform distribution
+
+\cvdefCpp{
+int RNG::uniform(int a, int b);\newline
+float RNG::uniform(float a, float b);\newline
+double RNG::uniform(double a, double b);
+}
+\begin{description}
+\cvarg{a}{The lower inclusive boundary of the returned random numbers}
+\cvarg{b}{The upper non-inclusive boundary of the returned random numbers}
+\end{description}
+
+The methods transforms the state using MWC algorithm and returns the next uniformly-distributed random number of the specified type, deduced from the input parameter type, from the range \texttt{[a, b)}. There is one nuance, illustrated by the following sample:
+
+\begin{lstlisting}
+cv::RNG rng;
+
+// will always produce 0
+double a = rng.uniform(0, 1);
+
+// will produce double from [0, 1)
+double a1 = rng.uniform((double)0, (double)1);
+
+// will produce float from [0, 1)
+double b = rng.uniform(0.f, 1.f);
+
+// will produce double from [0, 1)
+double c = rng.uniform(0., 1.);
+
+// will likely cause compiler error because of ambiguity:
+// RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
+double d = rng.uniform(0, 0.999999);
+\end{lstlisting}
+
+That is, the compiler does not take into account type of the variable that you assign the result of \texttt{RNG::uniform} to, the only thing that matters to it is the type of \texttt{a} and \texttt{b} parameters. So if you want a floating-point random number, but the range boundaries are integer numbers, either put dots in the end, if they are constants, or use explicit type cast operators, as in \texttt{a1} initialization above.
+
+
+\cvCppFunc{RNG::gaussian}
+Returns the next random number sampled from the Gaussian distribution
+
+\cvdefCpp{
+double RNG::gaussian(double sigma);
+}
+\begin{description}
+\cvarg{sigma}{The standard deviation of the distribution}
+\end{description}
+
+The methods transforms the state using MWC algorithm and returns the next random number from the Gaussian distribution \texttt{N(0,sigma)}. That is, the mean value of the returned random numbers will be zero and the standard deviation will be the specified \texttt{sigma}.
+
+
+\cvCppFunc{RNG::fill}
+Fill arrays with random numbers
+
+\cvdefCpp{
+void RNG::fill( Mat\& mat, int distType, const Scalar\& a, const Scalar\& b );\newline
+void RNG::fill( MatND\& mat, int distType, const Scalar\& a, const Scalar\& b );
+}
+\begin{description}
+\cvarg{mat}{2D or N-dimensional matrix. Currently matrices with more than 4 channels are not supported by the methods. Use \cvCppCross{reshape} as a possible workaround.}
+\cvarg{distType}{The distribution type, \texttt{RNG::UNIFORM} or \texttt{RNG::NORMAL}}
+\cvarg{a}{The first distribution parameter. In the case of uniform distribution this is inclusive lower boundary. In the case of normal distribution this is mean value.}
+\cvarg{b}{The second distribution parameter. In the case of uniform distribution this is non-inclusive upper boundary. In the case of normal distribution this is standard deviation.}
+\end{description}
+
+Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In the case of multiple-channel images every channel is filled independently, i.e. RNG can not generate samples from multi-dimensional Gaussian distribution with non-diagonal covariation matrix directly. To do that, first, generate matrix from the distribution $N(0, I_n)$, i.e. Gaussian distribution with zero mean and identity covariation matrix, and then transform it using \cvCppCross{transform} and the specific covariation matrix.
+
\cvCppFunc{randu}
Generates a single uniformly-distributed random number or array of random numbers
See also: \cvCppCross{reduce}, \cross{Matrix Expressions}
\ifplastex
-\subsection{saturate\_cast}\label{cppfunc.saturatecast}
+\cvfunc{saturate\_cast}\label{cppfunc.saturatecast}
\else
-\subsection{cv::saturate\_cast}\label{cppfunc.saturatecast}
+\subsection{saturate\_cast}\label{cppfunc.saturatecast}
\fi
Template function for accurate conversion from one primitive type to another
See also: \cvCppCross{add}, \cvCppCross{addWeighted}, \cvCppCross{scaleAdd}, \cvCppCross{convertScale},
\cross{Matrix Expressions}, \hyperref[cppfunc.saturatecast]{saturate\_cast}.
-\cvCppFunc{SVD}
+\cvclass{SVD}
Class for computing Singular Value Decomposition
\begin{lstlisting}
class SVD
{
public:
- enum { MODIFY_A=1, NO_UV=2, FULL_UV=4 };newline
+ enum { MODIFY_A=1, NO_UV=2, FULL_UV=4 };
// default empty constructor
- SVD();newline
- // decomposes m into u, w and vt: m = u*w*vt;newline
+ SVD();
+ // decomposes A into u, w and vt: A = u*w*vt;
// u and vt are orthogonal, w is diagonal
- SVD( const Mat& m, int flags=0 );newline
- // decomposes m into u, w and vt.
- SVD& operator ()( const Mat& m, int flags=0 );newline
+ SVD( const Mat& A, int flags=0 );
+ // decomposes A into u, w and vt.
+ SVD& operator ()( const Mat& A, int flags=0 );
- // finds such vector x, norm(x)=1, so that m*x = 0,
- // where m is singular matrix
- static void solveZ( const Mat& m, Mat& dst );newline
+ // finds such vector x, norm(x)=1, so that A*x = 0,
+ // where A is singular matrix
+ static void solveZ( const Mat& A, Mat& x );
// does back-subsitution:
- // dst = vt.t()*inv(w)*u.t()*rhs ~ inv(m)*rhs
- void backSubst( const Mat& rhs, Mat& dst ) const;newline
+ // x = vt.t()*inv(w)*u.t()*rhs ~ inv(A)*rhs
+ void backSubst( const Mat& rhs, Mat& x ) const;
Mat u, w, vt;
};
See also: \cvCppCross{invert}, \cvCppCross{solve}, \cvCppCross{eigen}, \cvCppCross{determinant}
+\cvCppFunc{SVD::SVD}
+SVD constructors
+
+\cvdefCpp{
+SVD::SVD();\newline
+SVD::SVD( const Mat\& A, int flags=0 );
+}
+\begin{description}
+\cvarg{A}{The decomposed matrix}
+\cvarg{flags}{Operation flags}
+\begin{description}
+ \cvarg{SVD::MODIFY\_A}{The algorithm can modify the decomposed matrix. It can save some space and speed-up processing a bit}
+ \cvarg{SVD::NO\_UV}{Only singular values are needed. The algorithm will not compute \texttt{U} and \texttt{V} matrices}
+ \cvarg{SVD::FULL\_UV}{When the matrix is not square, by default the algorithm produces \texttt{U} and \texttt{V} matrices of sufficiently large size for the further \texttt{A} reconstruction. If, however, \texttt{FULL\_UV} flag is specified, \texttt{U} and \texttt{V} will be full-size square orthogonal matrices.}
+\end{description}
+\end{description}
+
+The first constructor initializes empty \texttt{SVD} structure. The second constructor initializes empty \texttt{SVD} structure and then calls \cvCppCross{SVD::operator ()}.
+
+
+\cvCppFunc{SVD::operator ()}
+Performs SVD of a matrix
+
+\cvdefCpp{
+SVD\& SVD::operator ()( const Mat\& A, int flags=0 );
+}
+\begin{description}
+\cvarg{A}{The decomposed matrix}
+\cvarg{flags}{Operation flags}
+\begin{description}
+ \cvarg{SVD::MODIFY\_A}{The algorithm can modify the decomposed matrix. It can save some space and speed-up processing a bit}
+ \cvarg{SVD::NO\_UV}{Only singular values are needed. The algorithm will not compute \texttt{U} and \texttt{V} matrices}
+ \cvarg{SVD::FULL\_UV}{When the matrix is not square, by default the algorithm produces \texttt{U} and \texttt{V} matrices of sufficiently large size for the further \texttt{A} reconstruction. If, however, \texttt{FULL\_UV} flag is specified, \texttt{U} and \texttt{V} will be full-size square orthogonal matrices.}
+\end{description}
+\end{description}
+
+The operator performs singular value decomposition of the supplied matrix. The \texttt{U}, transposed \texttt{V} and the diagonal of \texttt{W} are stored in the structure. The same \texttt{SVD} structure can be reused many times with different matrices. Each time, if needed, the previous \texttt{u}, \texttt{vt} and \texttt{w} are reclaimed and the new matrices are created, which is all handled by \cvCppCross{Mat::create}.
+
+\cvCppFunc{SVD::solveZ}
+Solves under-determined singular linear system
+
+\cvdefCpp{
+static void SVD::solveZ( const Mat\& A, Mat\& x );
+}
+\begin{description}
+\cvarg{A}{The left-hand-side matrix.}
+\cvarg{x}{The found solution}
+\end{description}
+
+The method finds unit-length solution \textbf{x} of the under-determined system $A x = 0$. Theory says that such system has infinite number of solutions, so the algorithm finds the unit-length solution as the right singular vector corresponding to the smallest singular value (which should be 0). In practice, because of round errors and limited floating-point accuracy, the input matrix can appear to be close-to-singular rather than just singular. So, strictly speaking, the algorithm solves the following problem:
+
+\[
+x^* = \arg \min_{x: \|x\|=1} \|A \cdot x \|
+\]
+
+\cvCppFunc{SVD::backSubst}
+Performs singular value back substitution
+
+\cvdefCpp{
+void SVD::backSubst( const Mat\& rhs, Mat\& x ) const;
+}
+\begin{description}
+\cvarg{rhs}{The right-hand side of a linear system $\texttt{A} \texttt{x} = \texttt{rhs}$ being solved, where \texttt{A} is the matrix passed to \cvCppCross{SVD::SVD} or \cvCppCross{SVD::operator ()}}
+\cvarg{x}{The found solution of the system}
+\end{description}
+
+The method computes back substitution for the specified right-hand side:
+
+\[
+\texttt{x} = \texttt{vt}^T \cdot diag(\texttt{w})^{-1} \cdot \texttt{u}^T \cdot \texttt{rhs} \sim \texttt{A}^{-1} \cdot \texttt{rhs}
+\]
+
+Using this technique you can either get a very accurate solution of convenient linear system, or the best (in the least-squares terms) pseudo-solution of an overdetermined linear system. Note that explicit SVD with the further back substitution only makes sense if you need to solve many linear systems with the same left-hand side (e.g. \texttt{A}). If all you need is to solve a single system (possibly with multiple \texttt{rhs} immediately available), simply call \cvCppCross{solve} add pass \texttt{cv::DECOMP\_SVD} there - it will do absolutely the same thing.
+
\cvCppFunc{sum}
Calculates sum of array elements
projects / opencv.git / blobdiff