\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
\end{description}
The function calculates per-element bit-wise logical conjunction of two arrays:
\begin{lstlisting}
dst(I)=src1(I)&src2(I) if mask(I)!=0
\end{lstlisting}
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.
\cvCPyFunc{AndS}
Calculates per-element bit-wise conjunction of an array and a scalar.
\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
\end{description}
The function calculates per-element bit-wise conjunction of an array and a scalar:
\begin{lstlisting}
dst(I)=src(I)&value if mask(I)!=0
\end{lstlisting}
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:
If the array is \texttt{IplImage} and COI is set, the function processes the selected channel only and stores the average to the first scalar component $ S_0$ .
\cvarg{mean}{Pointer to the output mean value, may be NULL if it is not needed}
\cvarg{stdDev}{Pointer to the output standard deviation}
\fi
\cvarg{mask}{The optional operation mask}
\ifPy
\cvarg{mean}{Mean value, a CvScalar}
\cvarg{stdDev}{Standard deviation, a CvScalar}
\fi
\end{description}
The function calculates the average value and standard deviation of array elements, independently for each channel:
\[
\begin{array}{l}
N = \sum_I (\texttt{mask}(I) \ne 0)\\
mean_c = \frac{1}{N}\,\sum_{ I, \,\texttt{mask}(I) \ne 0}\texttt{arr}(I)_c\\
stdDev_c = \sqrt{\frac{1}{N}\,\sum_{ I, \,\texttt{mask}(I) \ne 0} (\texttt{arr}(I)_c - mean_c)^2}
\end{array}
\]
If the array is \texttt{IplImage} and COI is set, the function processes the selected channel only and stores the average and standard deviation to the first components of the output scalars ($mean_0$ and $stdDev_0$).
\cvCPyFunc{CalcCovarMatrix}
Calculates covariance matrix of a set of vectors.
\cvdefC{
void cvCalcCovarMatrix(\par const CvArr** vects,\par int count,\par CvArr* covMat,\par CvArr* avg,\par int flags);}
\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
\begin{description}
\cvarg{CV\_COVAR\_SCRAMBLED}{The output covariance matrix is calculated as:
that is, \texttt{covMat} will be a covariance matrix
with the same linear size as the total number of elements in each
input vector. One and only one of \texttt{CV\_COVAR\_SCRAMBLED} and
\texttt{CV\_COVAR\_NORMAL} must be specified}
\cvarg{CV\_COVAR\_USE\_AVG}{If the flag is specified, the function does not calculate \texttt{avg} from the input vectors, but, instead, uses the passed \texttt{avg} vector. This is useful if \texttt{avg} has been already calculated somehow, or if the covariance matrix is calculated by parts - in this case, \texttt{avg} is not a mean vector of the input sub-set of vectors, but rather the mean vector of the whole set.}
\cvarg{CV\_COVAR\_SCALE}{If the flag is specified, the covariance matrix is scaled. In the "normal" mode \texttt{scale} is '1./count'; in the "scrambled" mode \texttt{scale} is the reciprocal of the total number of elements in each input vector. By default (if the flag is not specified) the covariance matrix is not scaled ('scale=1').}
\cvarg{CV\_COVAR\_ROWS}{Means that all the input vectors are stored as rows of a single matrix, \texttt{vects[0]}. \texttt{count} is ignored in this case, and \texttt{avg} should be a single-row vector of an appropriate size.}
\cvarg{CV\_COVAR\_COLS}{Means that all the input vectors are stored as columns of a single matrix, \texttt{vects[0]}. \texttt{count} is ignored in this case, and \texttt{avg} should be a single-column vector of an appropriate size.}
\end{description}}
\end{description}
The function calculates the covariance matrix
and, optionally, the mean vector of the set of input vectors. The function
can be used for PCA, for comparing vectors using Mahalanobis distance and so forth.
\cvCPyFunc{CartToPolar}
Calculates the magnitude and/or angle of 2d vectors.
\cvarg{magnitude}{The destination array of magnitudes, may be set to NULL if it is not needed}
\cvarg{angle}{The destination array of angles, may be set to NULL if it is not needed. The angles are measured in radians $(0$ to $2\pi)$ or in degrees (0 to 360 degrees).}
\cvarg{angleInDegrees}{The flag indicating whether the angles are measured in radians, which is default mode, or in degrees}
\end{description}
The function calculates either the magnitude, angle, or both of every 2d vector (x(I),y(I)):
\begin{lstlisting}
magnitude(I)=sqrt(x(I)^2^+y(I)^2^ ),
angle(I)=atan(y(I)/x(I) )
\end{lstlisting}
The angles are calculated with 0.1 degree accuracy. For the (0,0) point, the angle is set to 0.
\cvCPyFunc{Cbrt}
Calculates the cubic root
\cvdefC{float cvCbrt(float value);}
\cvdefPy{Cbrt(value)-> float}
\begin{description}
\cvarg{value}{The input floating-point value}
\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.
\cvCPyFunc{ClearND}
Clears a specific array element.
\cvdefC{void cvClearND(CvArr* arr, int* idx);}
\cvdefPy{ClearND(arr,idx)-> None}
\begin{description}
\cvarg{arr}{Input array}
\cvarg{idx}{Array of the element indices}
\end{description}
The function \cvCPyCross{ClearND} clears (sets to zero) a specific element of a dense array or deletes the element of a sparse array. If the sparse array element does not exists, the function does nothing.
\cvCPyFunc{CloneImage}
Makes a full copy of an image, including the header, data, and ROI.
\cvarg{src2}{The second source array. Both source arrays must have a single channel.}
\cvarg{dst}{The destination array, must have 8u or 8s type}
\cvarg{cmpOp}{The flag specifying the relation between the elements to be checked
\begin{description}
\cvarg{CV\_CMP\_EQ}{src1(I) "equal to" value}
\cvarg{CV\_CMP\_GT}{src1(I) "greater than" value}
\cvarg{CV\_CMP\_GE}{src1(I) "greater or equal" value}
\cvarg{CV\_CMP\_LT}{src1(I) "less than" value}
\cvarg{CV\_CMP\_LE}{src1(I) "less or equal" value}
\cvarg{CV\_CMP\_NE}{src1(I) "not equal" value}
\end{description}}
\end{description}
The function compares the corresponding elements of two arrays and fills the destination mask array:
\begin{lstlisting}
dst(I)=src1(I) op src2(I),
\end{lstlisting}
\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 type, except the destination, and the same size (or ROI size)
\cvCPyFunc{CmpS}
Performs per-element comparison of an array and a scalar.
\cvdefC{void cvCmpS(const CvArr* src, double value, CvArr* dst, int cmpOp);}
\cvdefPy{CmpS(src,value,dst,cmpOp)-> None}
\begin{description}
\cvarg{src}{The source array, must have a single channel}
\cvarg{value}{The scalar value to compare each array element with}
\cvarg{dst}{The destination array, must have 8u or 8s type}
\cvarg{cmpOp}{The flag specifying the relation between the elements to be checked
\begin{description}
\cvarg{CV\_CMP\_EQ}{src1(I) "equal to" value}
\cvarg{CV\_CMP\_GT}{src1(I) "greater than" value}
\cvarg{CV\_CMP\_GE}{src1(I) "greater or equal" value}
\cvarg{CV\_CMP\_LT}{src1(I) "less than" value}
\cvarg{CV\_CMP\_LE}{src1(I) "less or equal" value}
\cvarg{CV\_CMP\_NE}{src1(I) "not equal" value}
\end{description}}
\end{description}
The function compares the corresponding elements of an array and a scalar and fills the destination mask array:
\begin{lstlisting}
dst(I)=src(I) op scalar
\end{lstlisting}
where \texttt{op} is $=,\; >,\;\ge,\; <,\;\le\; or\;\ne$.
\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.
\cvarg{shift}{Value added to the scaled source array elements}
\end{description}
The function has several different purposes, and thus has several different names. It copies one array to another with optional scaling, which is performed first, and/or optional type conversion, performed after:
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.
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.
\cvarg{depth}{Image depth (see \cvCPyCross{CreateImage})}
\cvarg{channels}{Number of channels (see \cvCPyCross{CreateImage})}
\end{description}
\ifC
This call is an analogue of
\begin{lstlisting}
hdr=iplCreateImageHeader(channels, 0, depth,
channels == 1 ? "GRAY" : "RGB",
channels == 1 ? "GRAY" : channels == 3 ? "BGR" :
channels == 4 ? "BGRA" : "",
IPL_DATA_ORDER_PIXEL, IPL_ORIGIN_TL, 4,
size.width, size.height,
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(rows, cols, type) -> mat}
\begin{description}
\cvarg{rows}{Number of rows in the matrix}
\cvarg{cols}{Number of columns 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.
\cvdefC{CvMat* cvCreateMatHeader(\par int rows,\par int cols,\par int type);}
\cvarg{type}{Type of the matrix elements, see \cvCPyCross{CreateMat}}
\end{description}
The function allocates a new matrix header and returns a pointer to it. The matrix data can then be allocated using \cvCPyCross{CreateData} or set explicitly to user-allocated data via \cvCPyCross{SetData}.
\cvCPyFunc{CreateMatND}
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) -> None}
\begin{description}
\ifPy
\cvarg{dims}{List or tuple of array dimensions, up to 32 in length.}
\else
\cvarg{dims}{Number of array dimensions. This must not exceed CV\_MAX\_DIM (32 by default, but can be changed at build time).}
\cvarg{sizes}{Array of dimension sizes.}
\fi
\cvarg{type}{Type of array elements, see \cvCPyCross{CreateMat}.}
\end{description}
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) -> None}
\begin{description}
\ifPy
\cvarg{dims}{List or tuple of array dimensions, up to 32 in length.}
\else
\cvarg{dims}{Number of array dimensions}
\cvarg{sizes}{Array of dimension sizes}
\fi
\cvarg{type}{Type of array elements, see \cvCPyCross{CreateMat}}
\end{description}
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.
\cvdefC{CvSparseMat* cvCreateSparseMat(int dims, const int* sizes, int type);}
\cvdefPy{CreateSparseMat(dims, type) -> cvmat}
\begin{description}
\ifC
\cvarg{dims}{Number of array dimensions. In contrast to the dense matrix, the number of dimensions is practically unlimited (up to $2^{16}$).}
\cvarg{sizes}{Array of dimension sizes}
\else
\cvarg{dims}{List or tuple of array dimensions.}
\fi
\cvarg{type}{Type of array elements. The same as for CvMat}
\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.
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{description}
\cvarg{src}{Source array, real 1D or 2D array}
\cvarg{dst}{Destination array of the same size and same type as the source}
\cvarg{flags}{Transformation flags, a combination of the following values
\begin{description}
\cvarg{CV\_DXT\_FORWARD}{do a forward 1D or 2D transform.}
\cvarg{CV\_DXT\_INVERSE}{do an inverse 1D or 2D transform.}
\cvarg{CV\_DXT\_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.}
\end{description}}
\end{description}
The function performs a forward or inverse transform of a 1D or 2D floating-point array:
Forward Cosine transform of 1D vector of $N$ elements:
Inverse Cosine transform of 1D vector of N elements:
\[X =\left(C^{(N)}\right)^{-1}\cdot Y =\left(C^{(N)}\right)^T \cdot Y\]
(since $C^{(N)}$ is orthogonal matrix, $C^{(N)}\cdot\left(C^{(N)}\right)^T = I$)
Forward Cosine transform of 2D $M \times N$ matrix:
\[Y = C^{(N)}\cdot X \cdot\left(C^{(N)}\right)^T\]
Inverse Cosine transform of 2D vector of $M \times N$ elements:
\[X =\left(C^{(N)}\right)^T \cdot X \cdot C^{(N)}\]
\cvCPyFunc{DFT}
Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.
\cvdefC{void cvDFT(const CvArr* src, CvArr* dst, int flags, int nonzeroRows=0);}
\cvdefPy{DFT(src,dst,flags,nonzeroRows=0)-> None}
\begin{description}
\cvarg{src}{Source array, real or complex}
\cvarg{dst}{Destination array of the same size and same type as the source}
\cvarg{flags}{Transformation flags, a combination of the following values
\begin{description}
\cvarg{CV\_DXT\_FORWARD}{do a forward 1D or 2D transform. The result is not scaled.}
\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
the destination array (in the case of an inverse 2d transform). If the value
is negative, zero, or greater than the total number of rows, it is
ignored. The parameter can be used to speed up 2d convolution/correlation
when computing via DFT. See the example below.}
\end{description}
The function performs a forward or inverse transform of a 1D or 2D floating-point array:
Forward Fourier transform of 1D vector of N elements:
\[y = F^{(N)}\cdot x, where F^{(N)}_{jk}=exp(-i \cdot2\pi\cdot j \cdot k/N)\],
\[i=sqrt(-1)\]
Inverse Fourier transform of 1D vector of N elements:
\[x'=(F^{(N)})^{-1}\cdot y = conj(F^(N))\cdot y
x = (1/N) \cdot x\]
Forward Fourier transform of 2D vector of M $\times$ N elements:
\[Y = F^{(M)}\cdot X \cdot F^{(N)}\]
Inverse Fourier transform of 2D vector of M $\times$ N elements:
\[X'= conj(F^{(M)})\cdot Y \cdot conj(F^{(N)})
X = (1/(M \cdot N)) \cdot X'\]
In the case of real (single-channel) data, the packed format, borrowed from IPL, is used to represent the result of a forward Fourier transform or input for an inverse Fourier transform:
\[\begin{bmatrix}
Re Y_{0,0}& Re Y_{0,1}& Im Y_{0,1}& Re Y_{0,2}& Im Y_{0,2}&\cdots& Re Y_{0,N/2-1}& Im Y_{0,N/2-1}& Re Y_{0,N/2}\\
Re Y_{1,0}& Re Y_{1,1}& Im Y_{1,1}& Re Y_{1,2}& Im Y_{1,2}&\cdots& Re Y_{1,N/2-1}& Im Y_{1,N/2-1}& Re Y_{1,N/2}\\
Im Y_{1,0}& Re Y_{2,1}& Im Y_{2,1}& Re Y_{2,2}& Im Y_{2,2}&\cdots& Re Y_{2,N/2-1}& Im Y_{2,N/2-1}& Im Y_{1,N/2}\\
\hdotsfor{9}\\
Re Y_{M/2-1,0}& Re Y_{M-3,1}& Im Y_{M-3,1}&\hdotsfor{3}& Re Y_{M-3,N/2-1}& Im Y_{M-3,N/2-1}& Re Y_{M/2-1,N/2}\\
Im Y_{M/2-1,0}& Re Y_{M-2,1}& Im Y_{M-2,1}&\hdotsfor{3}& Re Y_{M-2,N/2-1}& Im Y_{M-2,N/2-1}& Im Y_{M/2-1,N/2}\\
Re Y_{M/2,0}& Re Y_{M-1,1}& Im Y_{M-1,1}&\hdotsfor{3}& Re Y_{M-1,N/2-1}& Im Y_{M-1,N/2-1}& Re Y_{M/2,N/2}
\end{bmatrix}
\]
Note: the last column is present if \texttt{N} is even, the last row is present if \texttt{M} is even.
In the case of 1D real transform the result looks like the first row of the above matrix.
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
The function decrements the data reference counter in a \cross{CvMat} or
\cross{CvMatND} if the reference counter pointer
is not NULL. If the counter reaches zero, the data is deallocated. In the
current implementation the reference counter is not NULL only if the data
was allocated using the \cvCPyCross{CreateData} function. The counter will be NULL in other cases such as:
external data was assigned to the header using \cvCPyCross{SetData}, the matrix
header is part of a larger matrix or image, or the header was converted from an image or n-dimensional matrix header.
\fi
\cvCPyFunc{Det}
Returns the determinant of a matrix.
\cvdefC{double cvDet(const CvArr* mat);}
\cvdefPy{Det(mat)-> double}
\begin{description}
\cvarg{mat}{The source matrix}
\end{description}
The function returns the determinant of the square matrix \texttt{mat}. The direct method is used for small matrices and Gaussian elimination is used for larger matrices. For symmetric positive-determined matrices, it is also possible to run
\cvCPyCross{SVD}
with $U = V =0$ and then calculate the determinant as a product of the diagonal elements of $W$.
In the case of multiple channel arrays, the results for all channels are accumulated. In particular, \texttt{cvDotProduct(a,a)} where \texttt{a} is a complex vector, will return $||\texttt{a}||^2$.
The function can process multi-dimensional arrays, row by row, layer by layer, and so on.
\cvCPyFunc{EigenVV}
Computes eigenvalues and eigenvectors of a symmetric matrix.
\cvarg{dst}{The destination array, it should have \texttt{double} type or the same type as the source}
\end{description}
The function calculates the exponent of every element of the input array:
\[
\texttt{dst} [I] = e^{\texttt{src}(I)}
\]
The maximum relative error is about $7\times10^{-6}$. Currently, the function converts denormalized values to zeros on output.
\cvCPyFunc{FastArctan}
Calculates the angle of a 2D vector.
\cvdefC{float cvFastArctan(float y, float x);}
\cvdefPy{FastArctan(y,x)-> float}
\begin{description}
\cvarg{x}{x-coordinate of 2D vector}
\cvarg{y}{y-coordinate of 2D vector}
\end{description}
The function calculates the full-range angle of an input 2D vector. The angle is
measured in degrees and varies from 0 degrees to 360 degrees. The accuracy is about 0.1 degrees.
\cvCPyFunc{Flip}
Flip a 2D array around vertical, horizontal or both axes.
\cvdefC{void cvFlip(const CvArr* src, CvArr* dst=NULL, int flipMode=0);}
\cvdefPy{Flip(src,dst=NULL,flipMode=0)-> None}
\begin{description}
\cvarg{src}{Source array}
\cvarg{dst}{Destination array.
If $\texttt{dst}=\texttt{NULL}$ the flipping is done in place.}
\cvarg{flipMode}{Specifies how to flip the array:
0 means flipping around the x-axis, positive (e.g., 1) means flipping around y-axis, and negative (e.g., -1) means flipping around both axes. See also the discussion below for the formulas:}
\end{description}
The function flips the array in one of three different ways (row and column indices are 0-based):
\item vertical flipping of the image (flipMode = 0) to switch between top-left and bottom-left image origin, which is a typical operation in video processing under Win32 systems.
\item horizontal flipping of the image with subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (flipMode $>$ 0)
\item simultaneous horizontal and vertical flipping of the image with subsequent shift and absolute difference calculation to check for a central symmetry (flipMode $<$ 0)
\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.
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:
The function performs generalized matrix multiplication:
\[
\texttt{dst} = \texttt{alpha}\, op(\texttt{src1}) \, op(\texttt{src2}) + \texttt{beta}\, op(\texttt{src3}) \quad\text{where $op(X)$ is $X$ or $X^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.
\cvdefC{
CvScalar cvGet1D(const CvArr* arr, int idx0);
CvScalar cvGet2D(const CvArr* arr, int idx0, int idx1);
CvScalar cvGet3D(const CvArr* arr, int idx0, int idx1, int idx2);
CvScalar cvGetND(const CvArr* arr, int* idx);
}
\begin{description}
\cvarg{arr}{Input array}
\cvarg{idx0}{The first zero-based component of the element index}
\cvarg{idx1}{The second zero-based component of the element index}
\cvarg{idx2}{The third zero-based component of the element index}
\cvarg{idx}{Array of the element indices}
\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.
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.
\cvdefC{CvMat* cvGetCol(const CvArr* arr, CvMat* submat, int col);}
\cvdefPy{GetCol(arr,row)-> submat}
\cvdefC{CvMat* cvGetCols(const CvArr* arr, CvMat* submat, int startCol, int endCol);}
\cvdefPy{GetCols(arr,startCol,endCol)-> submat}
\begin{description}
\cvarg{arr}{Input array}
\cvarg{submat}{Pointer to the resulting sub-array header}
\cvarg{col}{Zero-based index of the selected column}
\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}
\end{description}
The functions \texttt{GetCol} and \texttt{GetCols} return the header, corresponding to a specified column span of the input array. \texttt{GetCol} is a shortcut for \cvCPyCross{GetCols}:
\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.
\cvdefC{CvMat* cvGetDiag(const CvArr* arr, CvMat* submat, int diag=0);}
\cvdefPy{GetDiag(arr,diag=0)-> submat}
\begin{description}
\cvarg{arr}{Input array}
\cvarg{submat}{Pointer to the resulting sub-array header}
\cvarg{diag}{Array diagonal. Zero corresponds to the main diagonal, -1 corresponds to the diagonal above the main , 1 corresponds to the diagonal below the main, and so forth.}
\end{description}
The function returns the header, corresponding to a specified diagonal of the input array.
If there is no ROI set, \texttt{cvRect(0,0,image->width,image->height)} is returned.
\cvCPyFunc{GetMat}
Returns matrix header for arbitrary array.
\cvdefC{CvMat* cvGetMat(const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0);}
\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}
\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 -
\cross{CvMat}, an image - \texttt{IplImage} or a multi-dimensional dense array - \cross{CvMatND} (latter case is allowed only if \texttt{allowND != 0}) . In the case of matrix the function simply returns the input pointer. In the case of \texttt{IplImage*} or \cross{CvMatND} it initializes the \texttt{header} structure with parameters of the current image ROI and returns the pointer to this temporary structure. Because COI is not supported by \cross{CvMat}, it is returned separately.
The function provides an easy way to handle both types of arrays - \texttt{IplImage} and \cross{CvMat} - using the same code. Reverse transform from \cross{CvMat} to \texttt{IplImage} can be done using the \cvCPyCross{GetImage} function.
Input array must have underlying data allocated or attached, otherwise the function fails.
If the input array is \texttt{IplImage} with planar data layout and COI set, the function returns the pointer to the selected plane and COI = 0. It enables per-plane processing of multi-channel images with planar data layout using OpenCV functions.
The function moves iterator to the next sparse matrix element and returns pointer to it. In the current version there is no any particular order of the elements, because they are stored in the hash table. The sample below demonstrates how to iterate through the sparse matrix:
Using \cvCPyCross{InitSparseMatIterator} and \cvCPyCross{GetNextSparseNode} to calculate sum of floating-point sparse array.
\cvarg{data}{Output pointer to the whole image origin or ROI origin if ROI is set}
\cvarg{step}{Output full row length in bytes}
\cvarg{roiSize}{Output ROI size}
\end{description}
The function fills output variables with low-level information about the array data. All output parameters are optional, so some of the pointers may be set to \texttt{NULL}. If the array is \texttt{IplImage} with ROI set, the parameters of ROI are returned.
The following example shows how to get access to array elements. GetRawData calculates the absolute value of the elements in a single-channel, floating-point array.
\cvarg{submat}{Pointer to the resulting sub-array header}
\cvarg{row}{Zero-based index of the selected row}
\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. That is, the function extracts every \texttt{deltaRow}-th row from \texttt{startRow} and up to (but not including) \texttt{endRow}.}
\end{description}
The functions return the header, corresponding to a specified row/row span of the input array. Note that \texttt{GetRow} is a shortcut for \cvCPyCross{GetRows}:
\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.
\cvdefC{CvSize cvGetSize(const CvArr* arr);}
\cvdefPy{GetSize(arr)-> CvSize}
\begin{description}
\cvarg{arr}{array header}
\end{description}
The function returns number of rows (CvSize::height) and number of columns (CvSize::width) of the input matrix or image. In the case of image the size of ROI is returned.
\cvCPyFunc{GetSubRect}
Returns matrix header corresponding to the rectangular sub-array of input image or matrix.
dst(I) is set to 0xff (all \texttt{1}-bits) if src(I) is within the range and 0 otherwise. All the arrays must have the same type, except the destination, and the same size (or ROI size).
\cvCPyFunc{InRangeS}
Checks that array elements lie between two scalars.
'dst(I)' is set to 0xff (all \texttt{1}-bits) if 'src(I)' is within the range and 0 otherwise. All the arrays must have the same size (or ROI size).
\ifC
\cvCPyFunc{IncRefData}
Increments array data reference counter.
\cvdefC{int cvIncRefData(CvArr* arr);}
\begin{description}
\cvarg{arr}{Array header}
\end{description}
The function increments \cross{CvMat} or
\cross{CvMatND} data reference counter and returns the new counter value
if the reference counter pointer is not NULL, otherwise it returns zero.
\cvCPyFunc{InitImageHeader}
Initializes an image header that was previously allocated.
\cvdefC{IplImage* cvInitImageHeader(\par IplImage* image,\par CvSize size,\par int depth,\par int channels,\par int origin=0,\par int align=4);}
\begin{description}
\cvarg{image}{Image header to initialize}
\cvarg{size}{Image width and height}
\cvarg{depth}{Image depth (see \cvCPyCross{CreateImage})}
\cvarg{channels}{Number of channels (see \cvCPyCross{CreateImage})}
\cvarg{origin}{Top-left \texttt{IPL\_ORIGIN\_TL} or bottom-left \texttt{IPL\_ORIGIN\_BL}}
\cvarg{align}{Alignment for image rows, typically 4 or 8 bytes}
\end{description}
The returned \texttt{IplImage*} points to the initialized header.
\cvCPyFunc{InitMatHeader}
Initializes a pre-allocated matrix header.
\cvdefC{
CvMat* cvInitMatHeader(\par CvMat* mat,\par int rows,\par int cols,\par int type, \par void* data=NULL,\par int step=CV\_AUTOSTEP);
}
\begin{description}
\cvarg{mat}{A pointer to the matrix header to be initialized}
\cvarg{rows}{Number of rows in the matrix}
\cvarg{cols}{Number of columns in the matrix}
\cvarg{type}{Type of the matrix elements, see \cvCPyCross{CreateMat}.}
\cvarg{data}{Optional: data pointer assigned to the matrix header}
\cvarg{step}{Optional: full row width in bytes of the assigned data. By default, the minimal possible step is used which assumes there are no gaps between subsequent rows of the matrix.}
\end{description}
This function is often used to process raw data with OpenCV matrix functions. For example, the following code computes the matrix product of two matrices, stored as ordinary arrays:
\begin{lstlisting}
double a[] = { 1, 2, 3, 4,
5, 6, 7, 8,
9, 10, 11, 12 };
double b[] = { 1, 5, 9,
2, 6, 10,
3, 7, 11,
4, 8, 12 };
double c[9];
CvMat Ma, Mb, Mc ;
cvInitMatHeader(&Ma, 3, 4, CV_64FC1, a);
cvInitMatHeader(&Mb, 4, 3, CV_64FC1, b);
cvInitMatHeader(&Mc, 3, 3, CV_64FC1, c);
cvMatMulAdd(&Ma, &Mb, 0, &Mc);
// the c array now contains the product of a (3x4) and b (4x3)
\end{lstlisting}
\cvCPyFunc{InitMatNDHeader}
Initializes a pre-allocated multi-dimensional array header.
\cvdefC{CvMatND* cvInitMatNDHeader(\par CvMatND* mat,\par int dims,\par const int* sizes,\par int type,\par void* data=NULL);}
\begin{description}
\cvarg{mat}{A pointer to the array header to be initialized}
\cvarg{dims}{The number of array dimensions}
\cvarg{sizes}{An array of dimension sizes}
\cvarg{type}{Type of array elements, see \cvCPyCross{CreateMat}}
\cvarg{data}{Optional data pointer assigned to the matrix header}
sparse array elements and returns pointer to the first element, or NULL
if the array is empty.
\fi
\cvCPyFunc{InvSqrt}
Calculates the inverse square root.
\cvdefC{float cvInvSqrt(float value);}
\cvdefPy{InvSqrt(value)-> float}
\begin{description}
\cvarg{value}{The input floating-point value}
\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.
\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{description}
\cvarg{src}{The source matrix}
\cvarg{dst}{The destination matrix}
\cvarg{method}{Inversion method
\begin{description}
\cvarg{CV\_LU}{Gaussian elimination with optimal pivot element chosen}
\cvarg{CV\_SVD}{Singular value decomposition (SVD) method}
\cvarg{CV\_SVD\_SYM}{SVD method for a symmetric positively-defined matrix}
\end{description}}
\end{description}
The function inverts matrix \texttt{src1} and stores the result in \texttt{src2}.
In the case of \texttt{LU} method, the function returns the \texttt{src1} determinant (src1 must be square). If it is 0, the matrix is not inverted and \texttt{src2} is filled with zeros.
In the case of \texttt{SVD} methods, the function returns the inversed condition of \texttt{src1} (ratio of the smallest singular value to the largest singular value) and 0 if \texttt{src1} is all zeros. The SVD methods calculate a pseudo-inverse matrix if \texttt{src1} is singular.
\cvCPyFunc{IsInf}
Determines if the argument is Infinity.
\cvdefC{int cvIsInf(double value);}
\cvdefPy{IsInf(value)-> int}
\begin{description}
\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.
\cvCPyFunc{IsNaN}
Determines if the argument is Not A Number.
\cvdefC{int cvIsNaN(double value);}
\cvdefPy{IsNaN(value)-> int}
\begin{description}
\cvarg{value}{The input floating-point value}
\end{description}
The function returns 1 if the argument is Not A Number (as defined by IEEE754 standard), 0 otherwise.
\cvarg{dst}{Destination array of a given depth and of the same number of channels as the source array}
\cvarg{lut}{Look-up table of 256 elements; should have the same depth as the destination array. In the case of multi-channel source and destination arrays, the table should either have a single-channel (in this case the same table is used for all channels) or the same number of channels as the source/destination array.}
\end{description}
The function fills the destination array with values from the look-up table. Indices of the entries are taken from the source array. That is, the function processes each element of \texttt{src} as follows:
The covariance matrix may be calculated using the \cvCPyCross{CalcCovarMatrix} function and further inverted using the \cvCPyCross{Invert} function (CV\_SVD method is the prefered one because the matrix might be singular).
\ifC
\cvCPyFunc{Mat}
Initializes matrix header (lightweight variant).
\cvdefC{CvMat cvMat(\par int rows,\par int cols,\par int type,\par void* data=NULL);}
\begin{description}
\cvarg{rows}{Number of rows in the matrix}
\cvarg{cols}{Number of columns in the matrix}
\cvarg{type}{Type of the matrix elements - see \cvCPyCross{CreateMat}}
\cvarg{data}{Optional data pointer assigned to the matrix header}
\end{description}
Initializes a matrix header and assigns data to it. The matrix is filled \textit{row}-wise (the first \texttt{cols} elements of data form the first row of the matrix, etc.)
This function is a fast inline substitution for \cvCPyCross{InitMatHeader}. Namely, it is equivalent to:
The function is the opposite to \cvCPyCross{Split}. If the destination array has N channels then if the first N input channels are not NULL, they all are copied to the destination array; if only a single source channel of the first N is not NULL, this particular channel is copied into the destination array; otherwise an error is raised. The rest of the source channels (beyond the first N) must always be NULL. For IplImage \cvCPyCross{Copy} with COI set can be also used to insert a single channel into the image.
\cvarg{arr2}{The second source image. If it is NULL, the absolute norm of \texttt{arr1} is calculated, otherwise the absolute or relative norm of \texttt{arr1}-\texttt{arr2} is calculated.}
\cvarg{normType}{Type of norm, see the discussion}
\cvarg{mask}{The optional operation mask}
\end{description}
The function calculates the absolute norm of \texttt{arr1} if \texttt{arr2} is NULL:
\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
\end{description}
The function calculates per-element bit-wise disjunction of two arrays:
\begin{lstlisting}
dst(I)=src1(I)|src2(I)
\end{lstlisting}
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.
\cvCPyFunc{OrS}
Calculates a per-element bit-wise disjunction of an array and a scalar.
\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
\end{description}
The function OrS calculates per-element bit-wise disjunction of an array and a scalar:
\begin{lstlisting}
dst(I)=src(I)|value if mask(I)!=0
\end{lstlisting}
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.
\cvCPyFunc{PerspectiveTransform}
Performs perspective matrix transformation of a vector array.
\cvarg{dst}{The destination array, should be the same type as the source}
\cvarg{power}{The exponent of power}
\end{description}
The function raises every element of the input array to \texttt{p}:
\[
\texttt{dst} [I] = \fork
{\texttt{src}(I)^p}{if \texttt{p} is integer}
{|\texttt{src}(I)^p|}{otherwise}
\]
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:
\cvarg{idx0}{The first zero-based component of the element index}
\cvarg{idx1}{The second zero-based component of the element index}
\cvarg{idx2}{The third zero-based component of the element index}
\cvarg{idx}{Array of the element indices}
\cvarg{type}{Optional output parameter: type of matrix elements}
\cvarg{createNode}{Optional input parameter for sparse matrices. Non-zero value of the parameter means that the requested element is created if it does not exist already.}
\cvarg{precalcHashval}{Optional input parameter for sparse matrices. If the pointer is not NULL, the function does not recalculate the node hash value, but takes it from the specified location. It is useful for speeding up pair-wise operations (TODO: provide an example)}
\end{description}
The functions return a pointer to a specific array element. Number of array dimension should match to the number of indices passed to the function except for \texttt{cvPtr1D} function that can be used for sequential access to 1D, 2D or nD dense arrays.
The functions can be used for sparse arrays as well - if the requested node does not exist they create it and set it to zero.
All these as well as other functions accessing array elements (\cvCPyCross{Get}, \cvCPyCross{GetReal},
\cvCPyCross{Set}, \cvCPyCross{SetReal}) raise an error in case if the element index is out of range.
\fi
\cvCPyFunc{RNG}
Initializes a random number generator state.
\cvdefC{CvRNG cvRNG(int64 seed=-1);}
\cvdefPy{RNG(seed=-1LL)-> CvRNG}
\begin{description}
\cvarg{seed}{64-bit value used to initiate a random sequence}
\end{description}
The function initializes a random number generator
and returns the state. The pointer to the state can be then passed to the
\cvCPyCross{RandInt}, \cvCPyCross{RandReal} and \cvCPyCross{RandArr} functions. In the
current implementation a multiply-with-carry generator is used.
\cvCPyFunc{RandArr}
Fills an array with random numbers and updates the RNG state.
\cvarg{rng}{RNG state initialized by \cvCPyCross{RNG}}
\cvarg{arr}{The destination array}
\cvarg{distType}{Distribution type
\begin{description}
\cvarg{CV\_RAND\_UNI}{uniform distribution}
\cvarg{CV\_RAND\_NORMAL}{normal or Gaussian distribution}
\end{description}}
\cvarg{param1}{The first parameter of the distribution. In the case of a uniform distribution it is the inclusive lower boundary of the random numbers range. In the case of a normal distribution it is the mean value of the random numbers.}
\cvarg{param2}{The second parameter of the distribution. In the case of a uniform distribution it is the exclusive upper boundary of the random numbers range. In the case of a normal distribution it is the standard deviation of the random numbers.}
\end{description}
The function fills the destination array with uniformly
or normally distributed random numbers.
\ifC
In the example below, the function
is used to add a few normally distributed floating-point numbers to
random locations within a 2d array.
\begin{lstlisting}
/* let noisy_screen be the floating-point 2d array that is to be "crapped" */
/* not to forget to release the temporary arrays */
cvReleaseMat(&locations);
cvReleaseMat(&values);
/* RNG state does not need to be deallocated */
\end{lstlisting}
\fi
\cvCPyFunc{RandInt}
Returns a 32-bit unsigned integer and updates RNG.
\cvdefC{unsigned cvRandInt(CvRNG* rng);}
\cvdefPy{RandInt(rng)-> unsigned}
\begin{description}
\cvarg{rng}{RNG state initialized by \texttt{RandInit} and, optionally, customized by \texttt{RandSetRange} (though, the latter function does not affect the discussed function outcome)}
\end{description}
The function returns a uniformly-distributed random
32-bit unsigned integer and updates the RNG state. It is similar to the rand()
function from the C runtime library, but it always generates a 32-bit number
whereas rand() returns a number in between 0 and \texttt{RAND\_MAX}
which is $2^{16}$ or $2^{32}$, depending on the platform.
The function is useful for generating scalar random numbers, such as
points, patch sizes, table indices, etc., where integer numbers of a certain
range can be generated using a modulo operation and floating-point numbers
can be generated by scaling from 0 to 1 or any other specific range.
\ifC
Here is the example from the previous function discussion rewritten using
\cvCPyCross{RandInt}:
\begin{lstlisting}
/* the input and the task is the same as in the previous sample. */
CvRNG rnggstate = cvRNG(0xffffffff);
int i, pointCount = 1000;
/* ... - no arrays are allocated here */
CvSize size = cvGetSize(noisygscreen);
/* make a buffer for normally distributed numbers to reduce call overhead */
\cvarg{dst}{The output single-row/single-column vector that accumulates somehow all the matrix rows/columns.}
\cvarg{dim}{The dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row, 1 means that the matrix is reduced to a single column and -1 means that the dimension is chosen automatically by analysing the dst size.}
\cvarg{op}{The reduction operation. It can take of the following values:
\begin{description}
\cvarg{CV\_REDUCE\_SUM}{The output is the sum of all of the matrix's rows/columns.}
\cvarg{CV\_REDUCE\_AVG}{The output is the mean vector of all of the matrix's rows/columns.}
\cvarg{CV\_REDUCE\_MAX}{The output is the maximum (column/row-wise) of all of the matrix's rows/columns.}
\cvarg{CV\_REDUCE\_MIN}{The output is the minimum (column/row-wise) of all of the matrix's rows/columns.}
\end{description}}
\end{description}
The function reduces matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of an raster image. In the case of \texttt{CV\_REDUCE\_SUM} and \texttt{CV\_REDUCE\_AVG} the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
\ifC
\cvCPyFunc{ReleaseData}
Releases array data.
\cvdefC{void cvReleaseData(CvArr* arr);}
\begin{description}
\cvarg{arr}{Array header}
\end{description}
The function releases the array data. In the case of \cross{CvMat} or \cross{CvMatND} it simply calls cvDecRefData(), that is the function can not deallocate external data. See also the note to \cvCPyCross{CreateData}.
but it does not use IPL functions by default (see the \texttt{CV\_TURN\_ON\_IPL\_COMPATIBILITY} macro).
\cvCPyFunc{ReleaseMat}
Deallocates a matrix.
\cvdefC{void cvReleaseMat(CvMat** mat);}
\begin{description}
\cvarg{mat}{Double pointer to the matrix}
\end{description}
The function decrements the matrix data reference counter and deallocates matrix header. If the data reference counter is 0, it also deallocates the data.
\begin{lstlisting}
if(*mat )
cvDecRefData(*mat);
cvFree((void**)mat);
\end{lstlisting}
\cvCPyFunc{ReleaseMatND}
Deallocates a multi-dimensional array.
\cvdefC{void cvReleaseMatND(CvMatND** mat);}
\begin{description}
\cvarg{mat}{Double pointer to the array}
\end{description}
The function decrements the array data reference counter and releases the array header. If the reference counter reaches 0, it also deallocates the data.
Changes shape of matrix/image without copying data.
\cvdefC{CvMat* cvReshape(const CvArr* arr, CvMat* header, int newCn, int newRows=0);}
\cvdefPy{Reshape(arr, newCn, newRows=0) -> cvmat}
\begin{description}
\cvarg{arr}{Input array}
\ifC
\cvarg{header}{Output header to be filled}
\fi
\cvarg{newCn}{New number of channels. 'newCn = 0' means that the number of channels remains unchanged.}
\cvarg{newRows}{New number of rows. 'newRows = 0' means that the number of rows remains unchanged unless it needs to be changed according to \texttt{newCn} value.}
\end{description}
The function initializes the CvMat header so that it points to the same data as the original array but has a different shape - different number of channels, different number of rows, or both.
\ifC
The following example code creates one image buffer and two image headers, the first is for a 320x240x3 image and the second is for a 960x240x1 image:
\cvarg{sizeofHeader}{Size of output header to distinguish between IplImage, CvMat and CvMatND output headers}
\cvarg{header}{Output header to be filled}
\cvarg{newCn}{New number of channels. $\texttt{newCn}=0$ means that the number of channels remains unchanged.}
\cvarg{newDims}{New number of dimensions. $\texttt{newDims}=0$ means that the number of dimensions remains the same.}
\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}
\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}:
\cvarg{idx0}{The first zero-based component of the element index}
\cvarg{idx1}{The second zero-based component of the element index}
\cvarg{idx2}{The third zero-based component of the element index}
\cvarg{idx}{Array of the element indices}
\cvarg{value}{The assigned value}
\end{description}
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.
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.
\cvdefC{void cvSetData(CvArr* arr, void* data, int step);}
\cvdefPy{SetData(arr, data, step)-> None}
\begin{description}
\cvarg{arr}{Array header}
\cvarg{data}{User data}
\cvarg{step}{Full row length in bytes}
\end{description}
The function assigns user data to the array header. Header should be initialized before using \texttt{cvCreate*Header}, \texttt{cvInit*Header} or \cvCPyCross{Mat} (in the case of matrix) function.
If the original image ROI was \texttt{NULL} and the \texttt{rect} is not the whole image, the ROI structure is allocated.
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.
\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
If \texttt{CV\_LU} method is used, the function returns 1 if \texttt{src1} is non-singular and 0 otherwise; in the latter case \texttt{dst} is not valid.
\cvarg{B}{The matrix to multiply the pseudo-inverse of the original matrix \texttt{A} by. This is an optional parameter. If it is omitted then it is assumed to be an identity matrix of an appropriate size (so that \texttt{X} will be the reconstructed pseudo-inverse of \texttt{A}).}
\cvarg{X}{The destination matrix: result of back substitution}
\cvarg{flags}{Operation flags, should match exactly to the \texttt{flags} passed to \cvCPyCross{SVD}}
\end{description}
The function calculates back substitution for decomposed matrix \texttt{A} (see \cvCPyCross{SVD} description) and matrix \texttt{B}:
\cvarg{W}{Resulting singular value diagonal matrix ($\texttt{M}\times\texttt{N}$ or $\min(\texttt{M}, \texttt{N})\times\min(\texttt{M}, \texttt{N})$) or $\min(\texttt{M},\texttt{N})\times1$ vector of the singular values}
\cvarg{U}{Optional left orthogonal matrix, $\texttt{M}\times\min(\texttt{M}, \texttt{N})$ (when \texttt{CV\_SVD\_U\_T} is not set), or $\min(\texttt{M},\texttt{N})\times\texttt{M}$ (when \texttt{CV\_SVD\_U\_T} is set), or $\texttt{M}\times\texttt{M}$ (regardless of \texttt{CV\_SVD\_U\_T} flag).}
\cvarg{V}{Optional right orthogonal matrix, $\texttt{N}\times\min(\texttt{M}, \texttt{N})$ (when \texttt{CV\_SVD\_V\_T} is not set), or $\min(\texttt{M},\texttt{N})\times\texttt{N}$ (when \texttt{CV\_SVD\_V\_T} is set), or $\texttt{N}\times\texttt{N}$ (regardless of \texttt{CV\_SVD\_V\_T} flag).}
\cvarg{flags}{Operation flags; can be 0 or a combination of the following values:
\begin{description}
\cvarg{CV\_SVD\_MODIFY\_A}{enables modification of matrix \texttt{A} during the operation. It speeds up the processing.}
\cvarg{CV\_SVD\_U\_T}{means that the transposed matrix \texttt{U} is returned. Specifying the flag speeds up the processing.}
\cvarg{CV\_SVD\_V\_T}{means that the transposed matrix \texttt{V} is returned. Specifying the flag speeds up the processing.}
\end{description}}
\end{description}
The function decomposes matrix \texttt{A} into the product of a diagonal matrix and two
orthogonal matrices:
\[
A=U \, W \, V^T
\]
where $W$ is a diagonal matrix of singular values that can be coded as a
1D vector of singular values and $U$ and $V$. All the singular values
are non-negative and sorted (together with $U$ and $V$ columns)
in descending order.
An SVD algorithm is numerically robust and its typical applications include:
\begin{itemize}
\item accurate eigenvalue problem solution when matrix \texttt{A}
is a square, symmetric, and positively defined matrix, for example, when
it is a covariance matrix. $W$ in this case will be a vector/matrix
of the eigenvalues, and $U = V$ will be a matrix of the eigenvectors.
\item accurate solution of a poor-conditioned linear system.
\item least-squares solution of an overdetermined linear system. This and the preceeding is done by using the \cvCPyCross{Solve} function with the \texttt{CV\_SVD} method.
\item accurate calculation of different matrix characteristics such as the matrix rank (the number of non-zero singular values), condition number (ratio of the largest singular value to the smallest one), and determinant (absolute value of the determinant is equal to the product of singular values).
\end{itemize}
\cvCPyFunc{Trace}
Returns the trace of a matrix.
\cvdefC{CvScalar cvTrace(const CvArr* mat);}
\cvdefPy{Trace(mat)-> CvScalar}
\begin{description}
\cvarg{mat}{The source matrix}
\end{description}
The function returns the sum of the diagonal elements of the matrix \texttt{src1}.
\[ tr(\texttt{mat})=\sum_i \texttt{mat}(i,i)\]
\cvCPyFunc{Transform}
Performs matrix transformation of every array element.
\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
\end{description}
The function calculates per-element bit-wise logical conjunction of two arrays:
\begin{lstlisting}
dst(I)=src1(I)^src2(I) if mask(I)!=0
\end{lstlisting}
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.
\cvCPyFunc{XorS}
Performs per-element bit-wise "exclusive or" operation on an array and a scalar.
\cvarg{mask}{Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed}
\end{description}
The function XorS calculates per-element bit-wise conjunction of an array and a scalar:
\begin{lstlisting}
dst(I)=src(I)^value if mask(I)!=0
\end{lstlisting}
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:
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation, and in the case of multi-channel arrays each channel is processed independently.
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.not]{bitwise\_not}, \hyperref[cppfunc.bitwise.xor]{bitwise\_xor}
\cvarg{dst}{The destination array; it is reallocated to be of the same size and
the same type as \texttt{src}; see \texttt{Mat::create}}
\cvarg{mask}{The optional operation mask, 8-bit single channel array;
specifies elements of the destination array to be changed}
\end{description}
The functions \texttt{bitwise\_not} compute per-element bit-wise inversion of the source array:
\[\texttt{dst}(I)=\neg\texttt{src}(I)\]
In the case of floating-point source array its machine-specific bit representation (usually IEEE754-compliant) is used for the operation. in the case of multi-channel arrays each channel is processed independently.
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.or]{bitwise\_or}, \hyperref[cppfunc.bitwise.xor]{bitwise\_xor}
\cvfunc{bitwise\_or}\label{cppfunc.bitwise.or}
Calculates per-element bit-wise disjunction of two arrays and an array and a scalar.
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. in the case of multi-channel arrays each channel is processed independently.
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.not]{bitwise\_not}, \hyperref[cppfunc.bitwise.or]{bitwise\_or}
\cvfunc{bitwise\_xor}\label{cppfunc.bitwise.xor}
Calculates per-element bit-wise "exclusive or" operation on two arrays and an array and a scalar.
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. in the case of multi-channel arrays each channel is processed independently.
See also: \hyperref[cppfunc.bitwise.and]{bitwise\_and}, \hyperref[cppfunc.bitwise.not]{bitwise\_not}, \hyperref[cppfunc.bitwise.or]{bitwise\_or}
\cvCppFunc{calcCovarMatrix}
Calculates covariation matrix of a set of vectors
\cvdefCpp{void calcCovarMatrix( const Mat* samples, int nsamples,\par
of the same size as the total number of elements in each
input vector. One and only one of \texttt{CV\_COVAR\_SCRAMBLED} and
\texttt{CV\_COVAR\_NORMAL} must be specified}
\cvarg{CV\_COVAR\_USE\_AVG}{If the flag is specified, the function does not calculate \texttt{mean} from the input vectors, but, instead, uses the passed \texttt{mean} vector. This is useful if \texttt{mean} has been pre-computed or known a-priori, or if the covariance matrix is calculated by parts - in this case, \texttt{mean} is not a mean vector of the input sub-set of vectors, but rather the mean vector of the whole set.}
\cvarg{CV\_COVAR\_SCALE}{If the flag is specified, the covariance matrix is scaled. In the "normal" mode \texttt{scale} is \texttt{1./nsamples}; in the "scrambled" mode \texttt{scale} is the reciprocal of the total number of elements in each input vector. By default (if the flag is not specified) the covariance matrix is not scaled (i.e. \texttt{scale=1}).}
\cvarg{CV\_COVAR\_ROWS}{[Only useful in the second variant of the function] The flag means that all the input vectors are stored as rows of the \texttt{samples} matrix. \texttt{mean} should be a single-row vector in this case.}
\cvarg{CV\_COVAR\_COLS}{[Only useful in the second variant of the function] The flag means that all the input vectors are stored as columns of the \texttt{samples} matrix. \texttt{mean} should be a single-column vector in this case.}
\end{description}}
\end{description}
The functions \texttt{calcCovarMatrix} calculate the covariance matrix
and, optionally, the mean vector of the set of input vectors.
See also: \cvCppCross{PCA}, \cvCppCross{mulTransposed}, \cvCppCross{Mahalanobis}
\cvarg{quiet}{The flag indicating whether the functions quietly return false when the array elements are out of range, or they throw an exception.}
\cvarg{pos}{The optional output parameter, where the position of the first outlier is stored. In the second function \texttt{pos}, when not NULL, must be a pointer to array of \texttt{src.dims} elements}
\cvarg{minVal}{The inclusive lower boundary of valid values range}
\cvarg{maxVal}{The exclusive upper boundary of valid values range}
\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
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.
\cvCppFunc{compare}
Performs per-element comparison of two arrays or an array and scalar value.
\cvarg{src2}{The second source array; must have the same size and same type as \texttt{src1}}
\cvarg{value}{The scalar value to compare each array element with}
\cvarg{dst}{The destination array; will have the same size as \texttt{src1} and type=\texttt{CV\_8UC1}}
\cvarg{cmpop}{The flag specifying the relation between the elements to be checked
\begin{description}
\cvarg{CMP\_EQ}{$\texttt{src1}(I)=\texttt{src2}(I)$ or $\texttt{src1}(I)=\texttt{value}$}
\cvarg{CMP\_GT}{$\texttt{src1}(I) > \texttt{src2}(I)$ or $\texttt{src1}(I) > \texttt{value}$}
\cvarg{CMP\_GE}{$\texttt{src1}(I)\geq\texttt{src2}(I)$ or $\texttt{src1}(I)\geq\texttt{value}$}
\cvarg{CMP\_LT}{$\texttt{src1}(I) < \texttt{src2}(I)$ or $\texttt{src1}(I) < \texttt{value}$}
\cvarg{CMP\_LE}{$\texttt{src1}(I)\leq\texttt{src2}(I)$ or $\texttt{src1}(I)\leq\texttt{value}$}
\cvarg{CMP\_NE}{$\texttt{src1}(I)\ne\texttt{src2}(I)$ or $\texttt{src1}(I)\ne\texttt{value}$}
\end{description}}
\end{description}
The functions \texttt{compare} compare each element of \texttt{src1} with the corresponding element of \texttt{src2}
or with real scalar \texttt{value}. When the comparison result is true, the corresponding element of destination array is set to 255, otherwise it is set to 0:
\cvarg{beta}{The optional delta added to the scaled values}
\end{description}
On each element of the input array the function \texttt{convertScaleAbs} performs 3 operations sequentially: scaling, taking absolute value, conversion to unsigned 8-bit type:
in the case of multi-channel arrays the function processes each channel independently. When the output is not 8-bit, the operation can be emulated by calling \texttt{Mat::convertTo} method (or by using matrix expressions) and then by computing absolute value of the result, for example:
\begin{lstlisting}
Mat_<float> A(30,30);
randu(A, Scalar(-100), Scalar(100));
Mat_<float> B = A*5 + 3;
B = abs(B);
// Mat_<float> B = abs(A*5+3) will also do the job,
// but it will allocate a temporary matrix
\end{lstlisting}
See also: \cvCppCross{Mat::convertTo}, \cvCppCross{abs}
The function \texttt{cvCountNonZero} returns the number of non-zero elements in mtx:
\[\sum_{I:\;\texttt{mtx}(I)\ne0}1\]
See also: \cvCppCross{mean}, \cvCppCross{meanStdDev}, \cvCppCross{norm}, \cvCppCross{minMaxLoc}, \cvCppCross{calcCovarMatrix}
\cvCppFunc{cubeRoot}
Computes cube root of the argument
\cvdefCpp{float cubeRoot(float val);}
\begin{description}
\cvarg{val}{The function argument}
\end{description}
The function \texttt{cubeRoot} computes $\sqrt[3]{\texttt{val}}$.
Negative arguments are handled correctly, \emph{NaN} and $\pm\infty$ are not handled.
The accuracy approaches the maximum possible accuracy for single-precision data.
\cvCppFunc{cvarrToMat}
Converts CvMat, IplImage or CvMatND to cv::Mat.
\cvdefCpp{Mat cvarrToMat(const CvArr* src, bool copyData=false, bool allowND=true, int coiMode=0);}
\begin{description}
\cvarg{src}{The source \texttt{CvMat}, \texttt{IplImage} or \texttt{CvMatND}}
\cvarg{copyData}{When it is false (default value), no data is copied, only the new header is created.
In this case the original array should not be deallocated while the new matrix header is used. The the parameter is true, all the data is copied, then user may deallocate the original array right after the conversion}
\cvarg{allowND}{When it is true (default value), then \texttt{CvMatND} is converted to \texttt{Mat} if it's possible
(e.g. then the data is contiguous). If it's not possible, or when the parameter is false, the function will report an error}
\cvarg{coiMode}{The parameter specifies how the IplImage COI (when set) is handled.
\begin{itemize}
\item If \texttt{coiMode=0}, the function will report an error if COI is set.
\item If \texttt{coiMode=1}, the function will never report an error; instead it returns the header to the whole original image and user will have to check and process COI manually, see \cvCppCross{extractImageCOI}.
% \item If \texttt{coiMode=2}, the function will extract the COI into the separate matrix. \emph{This is also done when the COI is set and }\texttt{copyData=true}}
\end{itemize}}
\end{description}
The function \texttt{cvarrToMat} converts \cross{CvMat}, \cross{IplImage} or \cross{CvMatND} header to \cvCppCross{Mat} header, and optionally duplicates the underlying data. The constructed header is returned by the function.
When \texttt{copyData=false}, the conversion is done really fast (in O(1) time) and the newly created matrix header will have \texttt{refcount=0}, which means that no reference counting is done for the matrix data, and user has to preserve the data until the new header is destructed. Otherwise, when \texttt{copyData=true}, the new buffer will be allocated and managed as if you created a new matrix from scratch and copy the data there. That is,
\texttt{cvarrToMat(src, true) $\sim$ cvarrToMat(src, false).clone()} (assuming that COI is not set). The function provides uniform way of supporting \cross{CvArr} paradigm in the code that is migrated to use new-style data structures internally. The reverse transformation, from \cvCppCross{Mat} to \cross{CvMat} or \cross{IplImage} can be done by simple assignment:
\begin{lstlisting}
CvMat* A = cvCreateMat(10, 10, CV_32F);
cvSetIdentity(A);
IplImage A1; cvGetImage(A, &A1);
Mat B = cvarrToMat(A);
Mat B1 = cvarrToMat(&A1);
IplImage C = B;
CvMat C1 = B1;
// now A, A1, B, B1, C and C1 are different headers
// for the same 10x10 floating-point array.
// note, that you will need to use "&"
// to pass C & C1 to OpenCV functions, e.g:
printf("%g", cvDet(&C1));
\end{lstlisting}
Normally, the function is used to convert an old-style 2D array (\cross{CvMat} or \cross{IplImage}) to \texttt{Mat}, however, the function can also take \cross{CvMatND} on input and create \cvCppCross{Mat} for it, if it's possible. And for \texttt{CvMatND A} it is possible if and only if \texttt{A.dim[i].size*A.dim.step[i] == A.dim.step[i-1]} for all or for all but one \texttt{i, 0 < i < A.dims}. That is, the matrix data should be continuous or it should be representable as a sequence of continuous matrices. By using this function in this way, you can process \cross{CvMatND} using arbitrary element-wise function. But for more complex operations, such as filtering functions, it will not work, and you need to convert \cross{CvMatND} to \cvCppCross{MatND} using the corresponding constructor of the latter.
The last parameter, \texttt{coiMode}, specifies how to react on an image with COI set: by default it's 0, and then the function reports an error when an image with COI comes in. And \texttt{coiMode=1} means that no error is signaled - user has to check COI presence and handle it manually. The modern structures, such as \cvCppCross{Mat} and \cvCppCross{MatND} do not support COI natively. To process individual channel of an new-style array, you will need either to organize loop over the array (e.g. using matrix iterators) where the channel of interest will be processed, or extract the COI using \cvCppCross{mixChannels} (for new-style arrays) or \cvCppCross{extractImageCOI} (for old-style arrays), process this individual channel and insert it back to the destination array if need (using \cvCppCross{mixChannel} or \cvCppCross{insertImageCOI}, respectively).
See also: \cvCppCross{cvGetImage}, \cvCppCross{cvGetMat}, \cvCppCross{cvGetMatND}, \cvCppCross{extractImageCOI}, \cvCppCross{insertImageCOI}, \cvCppCross{mixChannels}
\cvCppFunc{dct}
Performs a forward or inverse discrete cosine transform of 1D or 2D array
\cvdefCpp{void dct(const Mat\& src, Mat\& dst, int flags=0);}
\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}{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.}
\end{description}}
\end{description}
The function \texttt{dct} performs a forward or inverse discrete cosine transform (DCT) of a 1D or 2D floating-point array:
Forward Cosine transform of 1D vector of $N$ elements:
Inverse Cosine transform of 1D vector of N elements:
\[X =\left(C^{(N)}\right)^{-1}\cdot Y =\left(C^{(N)}\right)^T \cdot Y\]
(since $C^{(N)}$ is orthogonal matrix, $C^{(N)}\cdot\left(C^{(N)}\right)^T = I$)
Forward Cosine transform of 2D $M \times N$ matrix:
\[Y = C^{(N)}\cdot X \cdot\left(C^{(N)}\right)^T\]
Inverse Cosine transform of 2D vector of $M \times N$ elements:
\[X =\left(C^{(N)}\right)^T \cdot X \cdot C^{(N)}\]
The function chooses the mode of operation by looking at the flags and size of the input array:
\begin{itemize}
\item if \texttt{(flags \& DCT\_INVERSE) == 0}, the function does forward 1D or 2D transform, otherwise it is inverse 1D or 2D transform.
\item if \texttt{(flags \& DCT\_ROWS) $\ne$ 0}, the function performs 1D transform of each row.
\item otherwise, if the array is a single column or a single row, the function performs 1D transform
\item otherwise it performs 2D transform.
\end{itemize}
\textbf{Important note}: currently cv::dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation you can pad the array when necessary.
Also, the function's performance depends very much, and not monotonically, on the array size, see \cvCppCross{getOptimalDFTSize}. In the current implementation DCT of a vector of size \texttt{N} is computed via DFT of a vector of size \texttt{N/2}, thus the optimal DCT size $\texttt{N}^*\geq\texttt{N}$ can be computed as:
See also: \cvCppCross{dft}, \cvCppCross{getOptimalDFTSize}, \cvCppCross{idct}
\cvCppFunc{dft}
Performs a forward or inverse Discrete Fourier transform of 1D or 2D floating-point array.
\cvdefCpp{void dft(const Mat\& src, Mat\& dst, int flags=0, int nonzeroRows=0);}
\begin{description}
\cvarg{src}{The source array, real or complex}
\cvarg{dst}{The destination array, which size and type depends on the \texttt{flags}}
\cvarg{flags}{Transformation flags, a combination of the following values
\begin{description}
\cvarg{DFT\_INVERSE}{do an inverse 1D or 2D transform instead of the default forward transform.}
\cvarg{DFT\_SCALE}{scale the result: divide it by the number of array elements. Normally, it is combined with \texttt{DFT\_INVERSE}}.
\cvarg{DFT\_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{DFT\_COMPLEX\_OUTPUT}{then the function performs forward transformation of 1D or 2D real array, the result, though being a complex array, has complex-conjugate symmetry (\emph{CCS}), see the description below. Such an array can be packed into real array of the same size as input, which is the fastest option and which is what the function does by default. However, you may wish to get the full complex array (for simpler spectrum analysis etc.). Pass the flag to tell the function to produce full-size complex output array.}
\cvarg{DFT\_REAL\_OUTPUT}{then the function performs inverse transformation of 1D or 2D complex array, the result is normally a complex array of the same size. However, if the source array has conjugate-complex symmetry (for example, it is a result of forward transformation with \texttt{DFT\_COMPLEX\_OUTPUT} flag), then the output is real array. While the function itself does not check whether the input is symmetrical or not, you can pass the flag and then the function will assume the symmetry and produce the real output array. Note that when the input is packed real array and inverse transformation is executed, the function treats the input as packed complex-conjugate symmetrical array, so the output will also be real array}
\end{description}}
\cvarg{nonzeroRows}{When the parameter $\ne0$, the function assumes that only the first \texttt{nonzeroRows} rows of the input array (\texttt{DFT\_INVERSE} is not set) or only the first \texttt{nonzeroRows} of the output array (\texttt{DFT\_INVERSE} is set) contain non-zeros, thus the function can handle the rest of the rows more efficiently and thus save some time. This technique is very useful for computing array cross-correlation or convolution using DFT}
\end{description}
Forward Fourier transform of 1D vector of N elements:
\[Y = F^{(N)}\cdot X,\]
where $F^{(N)}_{jk}=\exp(-2\pi i j k/N)$ and $i=\sqrt{-1}$
Inverse Fourier transform of 1D vector of N elements:
\[
\begin{array}{l}
X'= \left(F^{(N)}\right)^{-1}\cdot Y = \left(F^{(N)}\right)^* \cdot y \\
X = (1/N) \cdot X,
\end{array}
\]
where $F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T$
Forward Fourier transform of 2D vector of $M \times N$ elements:
\[Y = F^{(M)}\cdot X \cdot F^{(N)}\]
Inverse Fourier transform of 2D vector of $M \times N$ elements:
\[
\begin{array}{l}
X'= \left(F^{(M)}\right)^* \cdot Y \cdot\left(F^{(N)}\right)^*\\
X = \frac{1}{M \cdot N}\cdot X'
\end{array}
\]
In the case of real (single-channel) data, the packed format called \emph{CCS} (complex-conjugate-symmetrical) that was borrowed from IPL and used to represent the result of a forward Fourier transform or input for an inverse Fourier transform:
\[\begin{bmatrix}
Re Y_{0,0}& Re Y_{0,1}& Im Y_{0,1}& Re Y_{0,2}& Im Y_{0,2}&\cdots& Re Y_{0,N/2-1}& Im Y_{0,N/2-1}& Re Y_{0,N/2}\\
Re Y_{1,0}& Re Y_{1,1}& Im Y_{1,1}& Re Y_{1,2}& Im Y_{1,2}&\cdots& Re Y_{1,N/2-1}& Im Y_{1,N/2-1}& Re Y_{1,N/2}\\
Im Y_{1,0}& Re Y_{2,1}& Im Y_{2,1}& Re Y_{2,2}& Im Y_{2,2}&\cdots& Re Y_{2,N/2-1}& Im Y_{2,N/2-1}& Im Y_{1,N/2}\\
\hdotsfor{9}\\
Re Y_{M/2-1,0}& Re Y_{M-3,1}& Im Y_{M-3,1}&\hdotsfor{3}& Re Y_{M-3,N/2-1}& Im Y_{M-3,N/2-1}& Re Y_{M/2-1,N/2}\\
Im Y_{M/2-1,0}& Re Y_{M-2,1}& Im Y_{M-2,1}&\hdotsfor{3}& Re Y_{M-2,N/2-1}& Im Y_{M-2,N/2-1}& Im Y_{M/2-1,N/2}\\
Re Y_{M/2,0}& Re Y_{M-1,1}& Im Y_{M-1,1}&\hdotsfor{3}& Re Y_{M-1,N/2-1}& Im Y_{M-1,N/2-1}& Re Y_{M/2,N/2}
\end{bmatrix}
\]
in the case of 1D transform of real vector, the output will look as the first row of the above matrix.
So, the function chooses the operation mode depending on the flags and size of the input array:
\begin{itemize}
\item if \texttt{DFT\_ROWS} is set or the input array has single row or single column then the function performs 1D forward or inverse transform (of each row of a matrix when \texttt{DFT\_ROWS} is set, otherwise it will be 2D transform.
\item if input array is real and \texttt{DFT\_INVERSE} is not set, the function does forward 1D or 2D transform:
\begin{itemize}
\item when \texttt{DFT\_COMPLEX\_OUTPUT} is set then the output will be complex matrix of the same size as input.
\item otherwise the output will be a real matrix of the same size as input. in the case of 2D transform it will use the packed format as shown above; in the case of single 1D transform it will look as the first row of the above matrix; in the case of multiple 1D transforms (when using \texttt{DCT\_ROWS} flag) each row of the output matrix will look like the first row of the above matrix.
\end{itemize}
\item otherwise, if the input array is complex and either \texttt{DFT\_INVERSE} or \texttt{DFT\_REAL\_OUTPUT} are not set then the output will be a complex array of the same size as input and the function will perform the forward or inverse 1D or 2D transform of the whole input array or each row of the input array independently, depending on the flags \texttt{DFT\_INVERSE} and \texttt{DFT\_ROWS}.
\item otherwise, i.e. when \texttt{DFT\_INVERSE} is set, the input array is real, or it is complex but \texttt{DFT\_REAL\_OUTPUT} is set, the output will be a real array of the same size as input, and the function will perform 1D or 2D inverse transformation of the whole input array or each individual row, depending on the flags \texttt{DFT\_INVERSE} and \texttt{DFT\_ROWS}.
\end{itemize}
The scaling is done after the transformation if \texttt{DFT\_SCALE} is set.
Unlike \cvCppCross{dct}, the function supports arrays of arbitrary size, but only those arrays are processed efficiently, which sizes can be factorized in a product of small prime numbers (2, 3 and 5 in the current implementation). Such an efficient DFT size can be computed using \cvCppCross{getOptimalDFTSize} method.
Here is the sample on how to compute DFT-based convolution of two 2D real arrays:
\begin{lstlisting}
void convolveDFT(const Mat& A, const Mat& B, Mat& C)
// all the temporary buffers will be deallocated automatically
}
\end{lstlisting}
What can be optimized in the above sample?
\begin{itemize}
\item since we passed $\texttt{nonzeroRows}\ne0$ to the forward transform calls and
since we copied \texttt{A}/\texttt{B} to the top-left corners of \texttt{tempA}/\texttt{tempB}, respectively,
it's not necessary to clear the whole \texttt{tempA} and \texttt{tempB};
it is only necessary to clear the \texttt{tempA.cols - A.cols} (\texttt{tempB.cols - B.cols})
rightmost columns of the matrices.
\item this DFT-based convolution does not have to be applied to the whole big arrays,
especially if \texttt{B} is significantly smaller than \texttt{A} or vice versa.
Instead, we can compute convolution by parts. For that we need to split the destination array
\texttt{C} into multiple tiles and for each tile estimate, which parts of \texttt{A} and \texttt{B}
are required to compute convolution in this tile. If the tiles in \texttt{C} are too small,
the speed will decrease a lot, because of repeated work - in the ultimate case, when each tile in \texttt{C} is a single pixel,
the algorithm becomes equivalent to the naive convolution algorithm.
If the tiles are too big, the temporary arrays \texttt{tempA} and \texttt{tempB} become too big
and there is also slowdown because of bad cache locality. So there is optimal tile size somewhere in the middle.
\item if the convolution is done by parts, since different tiles in \texttt{C} can be computed in parallel, the loop can be threaded.
\end{itemize}
All of the above improvements have been implemented in \cvCppCross{matchTemplate} and \cvCppCross{filter2D}, therefore, by using them, you can get even better performance than with the above theoretically optimal implementation (though, those two functions actually compute cross-correlation, not convolution, so you will need to "flip" the kernel or the image around the center using \cvCppCross{flip}).
or a scalar by array, when there is no \texttt{src1}:
\[\texttt{dst(I)= saturate(scale/src2(I))}\]
The result will have the same type as \texttt{src1}. When \texttt{src2(I)=0}, \texttt{dst(I)=0} too.
See also: \cvCppCross{multiply}, \cvCppCross{add}, \cvCppCross{subtract}, \cross{Matrix Expressions}
\cvCppFunc{determinant}
Returns determinant of a square floating-point matrix.
\cvdefCpp{double determinant(const Mat\& mtx);}
\begin{description}
\cvarg{mtx}{The input matrix; must have \texttt{CV\_32FC1} or \texttt{CV\_64FC1} type and square size}
\end{description}
The function \texttt{determinant} computes and returns determinant of the specified matrix. For small matrices (\texttt{mtx.cols=mtx.rows<=3})
the direct method is used; for larger matrices the function uses LU factorization.
For symmetric positive-determined matrices, it is also possible to compute \cvCppCross{SVD}: $\texttt{mtx}=U \cdot W \cdot V^T$ and then calculate the determinant as a product of the diagonal elements of $W$.
See also: \cvCppCross{SVD}, \cvCppCross{trace}, \cvCppCross{invert}, \cvCppCross{solve}, \cross{Matrix Expressions}
\cvCppFunc{eigen}
Computes eigenvalues and eigenvectors of a symmetric matrix.
\cvdefCpp{bool eigen(const Mat\& src, Mat\& eigenvalues, \par int lowindex=-1, int highindex=-1);\newline
\cvarg{src}{The input matrix; must have \texttt{CV\_32FC1} or \texttt{CV\_64FC1} type, square size and be symmetric: $\texttt{src}^T=\texttt{src}$}
\cvarg{eigenvalues}{The output vector of eigenvalues of the same type as \texttt{src}; The eigenvalues are stored in the descending order.}
\cvarg{eigenvectors}{The output matrix of eigenvectors; It will have the same size and the same type as \texttt{src}; The eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues}
\cvarg{lowindex}{Optional index of largest eigenvalue/-vector to calculate.
(See below.)}
\cvarg{highindex}{Optional index of smallest eigenvalue/-vector to calculate.
(See below.)}
\end{description}
The functions \texttt{eigen} compute just eigenvalues, or eigenvalues and eigenvectors of symmetric matrix \texttt{src}:
\begin{lstlisting}
src*eigenvectors(i,:)' = eigenvalues(i)*eigenvectors(i,:)' (in MATLAB notation)
\end{lstlisting}
If either low- or highindex is supplied the other is required, too.
Indexing is 0-based. Example: To calculate the largest eigenvector/-value set
lowindex = highindex = 0.
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
first highindex - lowindex + 1 rows.
See also: \cvCppCross{SVD}, \cvCppCross{completeSymm}, \cvCppCross{PCA}
\cvarg{dst}{The destination array; will have the same size and same type as \texttt{src}}
\end{description}
The function \texttt{exp} calculates the exponent of every element of the input array:
\[
\texttt{dst} [I] = e^{\texttt{src}}(I)
\]
The maximum relative error is about $7\times10^{-6}$ for single-precision and less than $10^{-10}$ for double-precision. Currently, the function converts denormalized values to zeros on output. Special values (NaN, $\pm\infty$) are not handled.
See also: \cvCppCross{log}, \cvCppCross{cartToPolar}, \cvCppCross{polarToCart}, \cvCppCross{phase}, \cvCppCross{pow}, \cvCppCross{sqrt}, \cvCppCross{magnitude}
\cvCppFunc{extractImageCOI}
Extract the selected image channel
\cvdefCpp{void extractImageCOI(const CvArr* src, Mat\& dst, int coi=-1);}
\begin{description}
\cvarg{src}{The source array. It should be a pointer to \cross{CvMat} or \cross{IplImage}}
\cvarg{dst}{The destination array; will have single-channel, and the same size and the same depth as \texttt{src}}
\cvarg{coi}{If the parameter is \texttt{>=0}, it specifies the channel to extract;
If it is \texttt{<0}, \texttt{src} must be a pointer to \texttt{IplImage} with valid COI set - then the selected COI is extracted.}
\end{description}
The function \texttt{extractImageCOI} is used to extract image COI from an old-style array and put the result to the new-style C++ matrix. As usual, the destination matrix is reallocated using \texttt{Mat::create} if needed.
To extract a channel from a new-style matrix, use \cvCppCross{mixChannels} or \cvCppCross{split}
See also: \cvCppCross{mixChannels}, \cvCppCross{split}, \cvCppCross{merge}, \cvCppCross{cvarrToMat}, \cvCppCross{cvSetImageCOI}, \cvCppCross{cvGetImageCOI}
\cvCppFunc{fastAtan2}
Calculates the angle of a 2D vector in degrees
\cvdefCpp{float fastAtan2(float y, float x);}
\begin{description}
\cvarg{x}{x-coordinate of the vector}
\cvarg{y}{y-coordinate of the vector}
\end{description}
The function \texttt{fastAtan2} calculates the full-range angle of an input 2D vector. The angle is
measured in degrees and varies from $0^\circ$ to $360^\circ$. The accuracy is about $0.3^\circ$.
\cvCppFunc{flip}
Flips a 2D array around vertical, horizontal or both axes.
\cvdefCpp{void flip(const Mat\& src, Mat\& dst, int flipCode);}
\begin{description}
\cvarg{src}{The source array}
\cvarg{dst}{The destination array; will have the same size and same type as \texttt{src}}
\cvarg{flipCode}{Specifies how to flip the array:
0 means flipping around the x-axis, positive (e.g., 1) means flipping around y-axis, and negative (e.g., -1) means flipping around both axes. See also the discussion below for the formulas.}
\end{description}
The function \texttt{flip} flips the array in one of three different ways (row and column indices are 0-based):
\item vertical flipping of the image ($\texttt{flipCode}=0$) to switch between top-left and bottom-left image origin, which is a typical operation in video processing in Windows.
\item horizontal flipping of the image with subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry ($\texttt{flipCode} > 0$)
\item simultaneous horizontal and vertical flipping of the image with subsequent shift and absolute difference calculation to check for a central symmetry ($\texttt{flipCode} < 0$)
\item reversing the order of 1d point arrays ($\texttt{flipCode} > 0$ or $\texttt{flipCode}=0$)
\end{itemize}
See also: \cvCppCross{transpose}, \cvCppCross{repeat}, \cvCppCross{completeSymm}
\cvarg{from}{Callback parameter: pointer to the input pixel}
\cvarg{to}{Callback parameter: pointer to the output pixel}
\cvarg{cn}{Callback parameter: the number of channels; can be arbitrary, 1, 100, 100000, ...}
\cvarg{alpha}{ConvertScaleData callback optional parameter: the scale factor}
\cvarg{beta}{ConvertScaleData callback optional parameter: the delta or offset}
\end{description}
The functions \texttt{getConvertElem} and \texttt{getConvertScaleElem} return pointers to the functions for converting individual pixels from one type to another. While the main function purpose is to convert single pixels (actually, for converting sparse matrices from one type to another), you can use them to convert the whole row of a dense matrix or the whole matrix at once, by setting \texttt{cn = matrix.cols*matrix.rows*matrix.channels()} if the matrix data is continuous.
See also: \cvCppCross{Mat::convertTo}, \cvCppCross{MatND::convertTo}, \cvCppCross{SparseMat::convertTo}
\cvCppFunc{getOptimalDFTSize}
Returns optimal DFT size for a given vector size.
\cvdefCpp{int getOptimalDFTSize(int vecsize);}
\begin{description}
\cvarg{vecsize}{Vector size}
\end{description}
DFT performance is not a monotonic function of a vector size, therefore, when you compute convolution of two arrays or do a spectral analysis of array, it usually makes sense to pad the input data with zeros to get a bit larger array that can be transformed much faster than the original one.
Arrays, which size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process, though, the arrays, which size is a product of 2's, 3's and 5's (e.g. 300 = 5*5*3*2*2), are also processed quite efficiently.
The function \texttt{getOptimalDFTSize} returns the minimum number \texttt{N} that is greater than or equal to \texttt{vecsize}, such that the DFT
of a vector of size \texttt{N} can be computed efficiently. In the current implementation $N=2^p \times3^q \times5^r$, for some $p$, $q$, $r$.
The function returns a negative number if \texttt{vecsize} is too large (very close to \texttt{INT\_MAX}).
While the function cannot be used directly to estimate the optimal vector size for DCT transform (since the current DCT implementation supports only even-size vectors), it can be easily computed as \texttt{getOptimalDFTSize((vecsize+1)/2)*2}.
See also: \cvCppCross{dft}, \cvCppCross{dct}, \cvCppCross{idft}, \cvCppCross{idct}, \cvCppCross{mulSpectrums}
\cvCppFunc{idct}
Computes inverse Discrete Cosine Transform of a 1D or 2D array
\cvdefCpp{void idct(const Mat\& src, Mat\& dst, int flags=0);}
\cvarg{dst}{The destination matrix; will have $N \times M$ size and the same type as \texttt{src}}
\cvarg{flags}{The inversion method :
\begin{description}
\cvarg{DECOMP\_LU}{Gaussian elimination with optimal pivot element chosen}
\cvarg{DECOMP\_SVD}{Singular value decomposition (SVD) method}
\cvarg{DECOMP\_CHOLESKY}{Cholesky decomposion. The matrix must be symmetrical and positively defined}
\end{description}}
\end{description}
The function \texttt{invert} inverts matrix \texttt{src} and stores the result in \texttt{dst}.
When the matrix \texttt{src} is singular or non-square, the function computes the pseudo-inverse matrix, i.e. the matrix \texttt{dst}, such that $\|\texttt{src}\cdot\texttt{dst}- I\|$ is minimal.
In the case of \texttt{DECOMP\_LU} method, the function returns the \texttt{src} determinant (\texttt{src} must be square). If it is 0, the matrix is not inverted and \texttt{dst} is filled with zeros.
In the case of \texttt{DECOMP\_SVD} method, the function returns the inversed condition number of \texttt{src} (the ratio of the smallest singular value to the largest singular value) and 0 if \texttt{src} is singular. The SVD method calculates a pseudo-inverse matrix if \texttt{src} is singular.
Similarly to \texttt{DECOMP\_LU}, the method \texttt{DECOMP\_CHOLESKY} works only with non-singular square matrices. In this case the function stores the inverted matrix in \texttt{dst} and returns non-zero, otherwise it returns 0.
See also: \cvCppCross{solve}, \cvCppCross{SVD}
\cvCppFunc{log}
Calculates the natural logarithm of every array element.
Where \texttt{C} is a large negative number (about -700 in the current implementation).
The maximum relative error is about $7\times10^{-6}$ for single-precision input and less than $10^{-10}$ for double-precision input. Special values (NaN, $\pm\infty$) are not handled.
See also: \cvCppCross{exp}, \cvCppCross{cartToPolar}, \cvCppCross{polarToCart}, \cvCppCross{phase}, \cvCppCross{pow}, \cvCppCross{sqrt}, \cvCppCross{magnitude}
\cvarg{lut}{Look-up table of 256 elements. In the case of multi-channel source array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the source array}
\cvarg{dst}{Destination array; will have the same size and the same number of channels as \texttt{src}, and the same depth as \texttt{lut}}
\end{description}
The function \texttt{LUT} fills the destination array with values from the look-up table. Indices of the entries are taken from the source array. That is, the function processes each element of \texttt{src} as follows:
The covariance matrix may be calculated using the \cvCppCross{calcCovarMatrix} function and then inverted using the \cvCppCross{invert} function (preferably using DECOMP\_SVD method, as the most accurate).
\cvCppFunc{max}
Calculates per-element maximum of two arrays or array and a scalar
In the second variant, when the source array is multi-channel, each channel is compared with \texttt{value} independently.
The first 3 variants of the function listed above are actually a part of \cross{Matrix Expressions}, they return the expression object that can be further transformed, or assigned to a matrix, or passed to a function etc.
See also: \cvCppCross{min}, \cvCppCross{compare}, \cvCppCross{inRange}, \cvCppCross{minMaxLoc}, \cross{Matrix Expressions}
\cvarg{mtx}{The source array; it should have 1 to 4 channels (so that the results can be stored in \cvCppCross{Scalar}'s)}
\cvarg{mean}{The output parameter: computed mean value}
\cvarg{stddev}{The output parameter: computed standard deviation}
\cvarg{mask}{The optional operation mask}
\end{description}
The functions \texttt{meanStdDev} compute the mean and the standard deviation \texttt{M} of array elements, independently for each channel, and return it via the output parameters:
When all the mask elements are 0's, the functions return \texttt{mean=stddev=Scalar::all(0)}.
Note that the computed standard deviation is only the diagonal of the complete normalized covariance matrix. If the full matrix is needed, you can reshape the multi-channel array $M \times N$ to the single-channel array $M*N \times\texttt{mtx.channels}()$ (only possible when the matrix is continuous) and then pass the matrix to \cvCppCross{calcCovarMatrix}.
See also: \cvCppCross{countNonZero}, \cvCppCross{mean}, \cvCppCross{norm}, \cvCppCross{minMaxLoc}, \cvCppCross{calcCovarMatrix}
\cvCppFunc{merge}
Composes a multi-channel array from several single-channel arrays.
\cvarg{mv}{The source array or vector of the single-channel matrices to be merged. All the matrices in \texttt{mv} must have the same size and the same type}
\cvarg{count}{The number of source matrices when \texttt{mv} is a plain C array; must be greater than zero}
\cvarg{dst}{The destination array; will have the same size and the same depth as \texttt{mv[0]}, the number of channels will match the number of source matrices}
\end{description}
The functions \texttt{merge} merge several single-channel arrays (or rather interleave their elements) to make a single multi-channel array.
\[\texttt{dst}(I)_c =\texttt{mv}[c](I)\]
The function \cvCppCross{split} does the reverse operation and if you need to merge several multi-channel images or shuffle channels in some other advanced way, use \cvCppCross{mixChannels}
See also: \cvCppCross{mixChannels}, \cvCppCross{split}, \cvCppCross{reshape}
\cvCppFunc{min}
Calculates per-element minimum of two arrays or array and a scalar
In the second variant, when the source array is multi-channel, each channel is compared with \texttt{value} independently.
The first 3 variants of the function listed above are actually a part of \cross{Matrix Expressions}, they return the expression object that can be further transformed, or assigned to a matrix, or passed to a function etc.
See also: \cvCppCross{max}, \cvCppCross{compare}, \cvCppCross{inRange}, \cvCppCross{minMaxLoc}, \cross{Matrix Expressions}
\cvCppFunc{minMaxLoc}
Finds global minimum and maximum in a whole array or sub-array
\cvarg{minVal}{Pointer to returned minimum value; \texttt{NULL} if not required}
\cvarg{maxVal}{Pointer to returned maximum value; \texttt{NULL} if not required}
\cvarg{minLoc}{Pointer to returned minimum location (in 2D case); \texttt{NULL} if not required}
\cvarg{maxLoc}{Pointer to returned maximum location (in 2D case); \texttt{NULL} if not required}
\cvarg{minIdx}{Pointer to returned minimum location (in nD case);
\texttt{NULL} if not required, otherwise must point to an array of \texttt{src.dims} elements and the coordinates of minimum element in each dimensions will be stored sequentially there.}
\cvarg{maxIdx}{Pointer to returned maximum location (in nD case); \texttt{NULL} if not required}
\cvarg{mask}{The optional mask used to select a sub-array}
\end{description}
The functions \texttt{ninMaxLoc} find minimum and maximum element values
and their positions. The extremums are searched across the whole array, or,
if \texttt{mask} is not an empty array, in the specified array region.
The functions do not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use \cvCppCross{reshape} first to reinterpret the array as single-channel. Or you may extract the particular channel using \cvCppCross{extractImageCOI} or \cvCppCross{mixChannels} or \cvCppCross{split}.
in the case of a sparse matrix the minimum is found among non-zero elements only.
See also: \cvCppCross{max}, \cvCppCross{min}, \cvCppCross{compare}, \cvCppCross{inRange}, \cvCppCross{extractImageCOI}, \cvCppCross{mixChannels}, \cvCppCross{split}, \cvCppCross{reshape}.
\cvCppFunc{mixChannels}
Copies specified channels from input arrays to the specified channels of output arrays
\cvdefCpp{void mixChannels(const Mat* srcv, int nsrc, Mat* dstv, int ndst,\par
const int* fromTo, size\_t npairs);\newline
void mixChannels(const MatND* srcv, int nsrc, MatND* dstv, int ndst,\par
\cvarg{srcv}{The input array or vector of matrices.
All the matrices must have the same size and the same depth}
\cvarg{nsrc}{The number of elements in \texttt{srcv}}
\cvarg{dstv}{The output array or vector of matrices.
All the matrices \emph{must be allocated}, their size and depth must be the same as in \texttt{srcv[0]}}
\cvarg{ndst}{The number of elements in \texttt{dstv}}
\cvarg{fromTo}{The array of index pairs, specifying which channels are copied and where.
\texttt{fromTo[k*2]} is the 0-based index of the input channel in \texttt{srcv} and
\texttt{fromTo[k*2+1]} is the index of the output channel in \texttt{dstv}. Here the continuous channel numbering is used, that is,
the first input image channels are indexed from \texttt{0} to \texttt{srcv[0].channels()-1},
the second input image channels are indexed from \texttt{srcv[0].channels()} to
\texttt{srcv[0].channels() + srcv[1].channels()-1} etc., and the same scheme is used for the output image channels.
As a special case, when \texttt{fromTo[k*2]} is negative, the corresponding output channel is filled with zero.
}
\texttt{npairs}{The number of pairs. In the latter case the parameter is not passed explicitly, but computed as \texttt{srcv.size()} (=\texttt{dstv.size()})}
\end{description}
The functions \texttt{mixChannels} provide an advanced mechanism for shuffling image channels. \cvCppCross{split} and \cvCppCross{merge} and some forms of \cvCppCross{cvtColor} are partial cases of \texttt{mixChannels}.
As an example, this code splits a 4-channel RGBA image into a 3-channel
BGR (i.e. with R and B channels swapped) and separate alpha channel image:
\begin{lstlisting}
Mat rgba( 100, 100, CV_8UC4, Scalar(1,2,3,4) );
Mat bgr( rgba.rows, rgba.cols, CV_8UC3 );
Mat alpha( rgba.rows, rgba.cols, CV_8UC1 );
// forming array of matrices is quite efficient operations,
// because the matrix data is not copied, only the headers
Mat out[] = { bgr, alpha };
// rgba[0] -> bgr[2], rgba[1] -> bgr[1],
// rgba[2] -> bgr[0], rgba[3] -> alpha[0]
int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
mixChannels( &rgba, 1, out, 2, from_to, 4 );
\end{lstlisting}
Note that, unlike many other new-style C++ functions in OpenCV (see the introduction section and \cvCppCross{Mat::create}),
\texttt{mixChannels} requires the destination arrays be pre-allocated before calling the function.
See also: \cvCppCross{split}, \cvCppCross{merge}, \cvCppCross{cvtColor}
\cvCppFunc{mulSpectrums}
Performs per-element multiplication of two Fourier spectrums.
\cvarg{src2}{The second source array; must have the same size and the same type as \texttt{src1}}
\cvarg{dst}{The destination array; will have the same size and the same type as \texttt{src1}}
\cvarg{flags}{The same flags as passed to \cvCppCross{dft}; only the flag \texttt{DFT\_ROWS} is checked for}
\cvarg{conj}{The optional flag that conjugate the second source array before the multiplication (true) or not (false)}
\end{description}
The function \texttt{mulSpectrums} performs per-element multiplication of the two CCS-packed or complex matrices that are results of a real or complex Fourier transform.
The function, together with \cvCppCross{dft} and \cvCppCross{idft}, may be used to calculate convolution (pass \texttt{conj=false}) or correlation (pass \texttt{conj=false}) of two arrays rapidly. When the arrays are complex, they are simply multiplied (per-element) with optional conjugation of the second array elements. When the arrays are real, they assumed to be CCS-packed (see \cvCppCross{dft} for details).
\cvCppFunc{multiply}
Calculates the per-element scaled product of two arrays
\cvarg{aTa}{Specifies the multiplication ordering; see the description below}
\cvarg{delta}{The optional delta matrix, subtracted from \texttt{src} before the multiplication. When the matrix is empty (\texttt{delta=Mat()}), it's assumed to be zero, i.e. nothing is subtracted, otherwise if it has the same size as \texttt{src}, then it's simply subtracted, otherwise it is "repeated" (see \cvCppCross{repeat}) to cover the full \texttt{src} and then subtracted. Type of the delta matrix, when it's not empty, must be the same as the type of created destination matrix, see the \texttt{rtype} description}
\cvarg{scale}{The optional scale factor for the matrix product}
\cvarg{rtype}{When it's negative, the destination matrix will have the same type as \texttt{src}. Otherwise, it will have \texttt{type=CV\_MAT\_DEPTH(rtype)}, which should be either \texttt{CV\_32F} or \texttt{CV\_64F}}
\end{description}
The function \texttt{mulTransposed} calculates the product of \texttt{src} and its transposition:
otherwise. The function is used to compute covariance matrix and with zero delta can be used as a faster substitute for general matrix product $A*B$ when $B=A^T$.
See also: \cvCppCross{calcCovarMatrix}, \cvCppCross{gemm}, \cvCppCross{repeat}, \cvCppCross{reduce}
The functions \texttt{norm} return the calculated norm.
When there is \texttt{mask} parameter, and it is not empty (then it should have type \texttt{CV\_8U} and the same size as \texttt{src1}), the norm is computed only over the specified by the mask region.
A multiple-channel source arrays are treated as a single-channel, that is, the results for all channels are combined.
\cvarg{dst}{The destination array; will have the same size as \texttt{src}}
\cvarg{alpha}{The norm value to normalize to or the lower range boundary in the case of range normalization}
\cvarg{beta}{The upper range boundary in the case of range normalization; not used for norm normalization}
\cvarg{normType}{The normalization type, see the discussion}
\cvarg{rtype}{When the parameter is negative, the destination array will have the same type as \texttt{src}, otherwise it will have the same number of channels as \texttt{src} and the depth\texttt{=CV\_MAT\_DEPTH(rtype)}}
\cvarg{mask}{The optional operation mask}
\end{description}
The functions \texttt{normalize} scale and shift the source array elements, so that
\[\|\texttt{dst}\|_{L_p}=\texttt{alpha}\]
(where $p=\infty$, 1 or 2) when \texttt{normType=NORM\_INF}, \texttt{NORM\_L1} or \texttt{NORM\_L2},
when \texttt{normType=NORM\_MINMAX} (for dense arrays only).
The optional mask specifies the sub-array to be normalize, that is, the norm or min-n-max are computed over the sub-array and then this sub-array is modified to be normalized. If you want to only use the mask to compute the norm or min-max, but modify the whole array, you can use \cvCppCross{norm} and \cvCppCross{Mat::convertScale}/\cvCppCross{MatND::convertScale}/cross{SparseMat::convertScale} separately.
in the case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this, the range transformation for sparse matrices is not allowed, since it can shift the zero level.
See also: \cvCppCross{norm}, \cvCppCross{Mat::convertScale}, \cvCppCross{MatND::convertScale}, \cvCppCross{SparseMat::convertScale}
\cvclass{PCA}
Class for Principal Component Analysis
\begin{lstlisting}
class PCA
{
public:
// default constructor
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);
// 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);
// projects vector into the principal components space
// eigenvectors of the PC space, stored as the matrix rows
Mat eigenvectors;
// the corresponding eigenvalues; not used for PCA compression/decompression
Mat eigenvalues;
// mean vector, subtracted from the projected vector
// or added to the reconstructed vector
Mat mean;
};
\end{lstlisting}
The class \texttt{PCA} is used to compute the special basis for a set of vectors. The basis will consist of eigenvectors of the covariance matrix computed from the input set of vectors. And also the class \texttt{PCA} can transform vectors to/from the new coordinate space, defined by the basis. Usually, in this new coordinate system each vector from the original set (and any linear combination of such vectors) can be quite accurately approximated by taking just the first few its components, corresponding to the eigenvectors of the largest eigenvalues of the covariance matrix. Geometrically it means that we compute projection of the vector to a subspace formed by a few eigenvectors corresponding to the dominant eigenvalues of the covariation matrix. And usually such a projection is very close to the original vector. That is, we can represent the original vector from a high-dimensional space with a much shorter vector consisting of the projected vector's coordinates in the subspace. Such a transformation is also known as Karhunen-Loeve Transform, or KLT. See \url{http://en.wikipedia.org/wiki/Principal\_component\_analysis}
The following sample is the function that takes two matrices. The first one stores the set of vectors (a row per vector) that is used to compute PCA, the second one stores another "test" set of vectors (a row per vector) that are first compressed with PCA, then reconstructed back and then the reconstruction error norm is computed and printed for each vector.
\begin{lstlisting}
PCA compressPCA(const Mat& pcaset, int maxComponents,
const Mat& testset, Mat& compressed)
{
PCA pca(pcaset, // pass the data
Mat(), // we do not have a pre-computed mean vector,
// so let the PCA engine to compute it
CV_PCA_DATA_AS_ROW, // indicate that the vectors
// are stored as matrix rows
// (use CV_PCA_DATA_AS_COL if the vectors are
// the matrix columns)
maxComponents // specify, how many principal components to retain
);
// if there is no test data, just return the computed basis, ready-to-use
Mat vec = testset.row(i), coeffs = compressed.row(i);
// compress the vector, the result will be stored
// in the i-th row of the output matrix
pca.project(vec, coeffs);
// and then reconstruct it
pca.backProject(coeffs, reconstructed);
// and measure the error
printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
}
return pca;
}
\end{lstlisting}
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
\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
\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.
\cvarg{src}{The source two-channel or three-channel floating-point array;
each element is 2D/3D vector to be transformed}
\cvarg{dst}{The destination array; it will have the same size and same type as \texttt{src}}
\cvarg{mtx}{$3\times3$ or $4\times4$ transformation matrix}
\end{description}
The function \texttt{perspectiveTransform} transforms every element of \texttt{src},
by treating it as 2D or 3D vector, in the following way (here 3D vector transformation is shown; in the case of 2D vector transformation the $z$ component is omitted):
\[(x, y, z)\rightarrow(x'/w, y'/w, z'/w)\]
where
\[
(x', y', z', w') = \texttt{mat}\cdot
\begin{bmatrix} x & y & z & 1 \end{bmatrix}
\]
and
\[ w =\fork{w'}{if $w' \ne0$}{\infty}{otherwise}\]
Note that the function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use \cvCppCross{warpPerspective}. If you have an inverse task, i.e. want to compute the most probable perspective transformation out of several pairs of corresponding points, you can use \cvCppCross{getPerspectiveTransform} or \cvCppCross{findHomography}.
See also: \cvCppCross{transform}, \cvCppCross{warpPerspective}, \cvCppCross{getPerspectiveTransform}, \cvCppCross{findHomography}
\cvCppFunc{phase}
Calculates the rotation angle of 2d vectors
\cvdefCpp{void phase(const Mat\& x, const Mat\& y, Mat\& angle,\par
bool angleInDegrees=false);}
\begin{description}
\cvarg{x}{The source floating-point array of x-coordinates of 2D vectors}
\cvarg{y}{The source array of y-coordinates of 2D vectors; must have the same size and the same type as \texttt{x}}
\cvarg{angle}{The destination array of vector angles; it will have the same size and same type as \texttt{x}}
\cvarg{angleInDegrees}{When it is true, the function will compute angle in degrees, otherwise they will be measured in radians}
\end{description}
The function \texttt{phase} computes the rotation angle of each 2D vector that is formed from the corresponding elements of \texttt{x} and \texttt{y}:
\cvarg{magnitude}{The source floating-point array of magnitudes of 2D vectors. It can be an empty matrix (\texttt{=Mat()}) - in this case the function assumes that all the magnitudes are =1. If it's not empty, it must have the same size and same type as \texttt{angle}}
\cvarg{angle}{The source floating-point array of angles of the 2D vectors}
\cvarg{x}{The destination array of x-coordinates of 2D vectors; will have the same size and the same type as \texttt{angle}}
\cvarg{y}{The destination array of y-coordinates of 2D vectors; will have the same size and the same type as \texttt{angle}}
\cvarg{angleInDegrees}{When it is true, the input angles are measured in degrees, otherwise they are measured in radians}
\end{description}
The function \texttt{polarToCart} computes the cartesian coordinates of each 2D vector represented by the corresponding elements of \texttt{magnitude} and \texttt{angle}:
\cvarg{dst}{The destination array; will have the same size and the same type as \texttt{src}}
\end{description}
The function \texttt{pow} raises every element of the input array to \texttt{p}:
\[
\texttt{dst}(I) = \fork
{\texttt{src}(I)^p}{if \texttt{p} is integer}
{|\texttt{src}(I)|^p}{otherwise}
\]
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 5th root of array \texttt{src}, shows:
\begin{lstlisting}
Mat mask = src < 0;
pow(src, 1./5, dst);
subtract(Scalar::all(0), dst, dst, mask);
\end{lstlisting}
For some values of \texttt{p}, such as integer values, 0.5, and -0.5, specialized faster algorithms are used.
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
\cvarg{mtx}{The output array of random numbers. The array must be pre-allocated and have 1 to 4 channels}
\cvarg{low}{The inclusive lower boundary of the generated random numbers}
\cvarg{high}{The exclusive upper boundary of the generated random numbers}
\end{description}
The template functions \texttt{randu} generate and return the next uniformly-distributed random value of the specified type. \texttt{randu<int>()} is equivalent to \texttt{(int)theRNG();} etc. See \cvCppCross{RNG} description.
The second non-template variant of the function fills the matrix \texttt{mtx} with uniformly-distributed random numbers from the specified range:
\cvarg{mtx}{The output array of random numbers. The array must be pre-allocated and have 1 to 4 channels}
\cvarg{mean}{The mean value (expectation) of the generated random numbers}
\cvarg{stddev}{The standard deviation of the generated random numbers}
\end{description}
The function \texttt{randn} fills the matrix \texttt{mtx} with normally distributed random numbers with the specified mean and standard deviation. \hyperref[cppfunc.saturatecast]{saturate\_cast} is applied to the generated numbers (i.e. the values are clipped)
\cvarg{iterFactor}{The scale factor that determines the number of random swap operations. See the discussion}
\cvarg{rng}{The optional random number generator used for shuffling. If it is zero, \cvCppCross{theRNG}() is used instead}
\end{description}
The function \texttt{randShuffle} shuffles the specified 1D array by randomly choosing pairs of elements and swapping them. The number of such swap operations will be \texttt{mtx.rows*mtx.cols*iterFactor}
See also: \cvCppCross{RNG}, \cvCppCross{sort}
\cvCppFunc{reduce}
Reduces a matrix to a vector
\cvdefCpp{void reduce(const Mat\& mtx, Mat\& vec, \par int dim, int reduceOp, int dtype=-1);}
\begin{description}
\cvarg{mtx}{The source 2D matrix}
\cvarg{vec}{The destination vector. Its size and type is defined by \texttt{dim} and \texttt{dtype} parameters}
\cvarg{dim}{The dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row and 1 means that the matrix is reduced to a single column}
\cvarg{reduceOp}{The reduction operation, one of:
\begin{description}
\cvarg{CV\_REDUCE\_SUM}{The output is the sum of all of the matrix's rows/columns.}
\cvarg{CV\_REDUCE\_AVG}{The output is the mean vector of all of the matrix's rows/columns.}
\cvarg{CV\_REDUCE\_MAX}{The output is the maximum (column/row-wise) of all of the matrix's rows/columns.}
\cvarg{CV\_REDUCE\_MIN}{The output is the minimum (column/row-wise) of all of the matrix's rows/columns.}
\end{description}}
\cvarg{dtype}{When it is negative, the destination vector will have the same type as the source matrix, otherwise, its type will be \texttt{CV\_MAKE\_TYPE(CV\_MAT\_DEPTH(dtype), mtx.channels())}}
\end{description}
The function \texttt{reduce} reduces matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of an raster image. In the case of \texttt{CV\_REDUCE\_SUM} and \texttt{CV\_REDUCE\_AVG} the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
See also: \cvCppCross{repeat}
\cvCppFunc{repeat}
Fill the destination array with repeated copies of the source array.
\cvdefCpp{void repeat(const Mat\& src, int ny, int nx, Mat\& dst);\newline
Mat repeat(const Mat\& src, int ny, int nx);}
\begin{description}
\cvarg{src}{The source array to replicate}
\cvarg{dst}{The destination array; will have the same type as \texttt{src}}
\cvarg{ny}{How many times the \texttt{src} is repeated along the vertical axis}
\cvarg{nx}{How many times the \texttt{src} is repeated along the horizontal axis}
\end{description}
The functions \cvCppCross{repeat} duplicate the source array one or more times along each of the two axes:
The functions \texttt{saturate\_cast} resembles the standard C++ cast operations, such as \texttt{static\_cast<T>()} etc. They perform an efficient and accurate conversion from one primitive type to another, see the introduction. "saturate" in the name means that when the input value \texttt{v} is out of range of the target type, the result will not be formed just by taking low bits of the input, but instead the value will be clipped. For example:
\begin{lstlisting}
uchar a = saturate_cast<uchar>(-100); // a = 0 (UCHAR_MIN)
short b = saturate_cast<short>(33333.33333); // b = 32767 (SHRT_MAX)
\end{lstlisting}
Such clipping is done when the target type is \texttt{unsigned char, signed char, unsigned short or signed short} - for 32-bit integers no clipping is done.
When the parameter is floating-point value and the target type is an integer (8-, 16- or 32-bit), the floating-point value is first rounded to the nearest integer and then clipped if needed (when the target type is 8- or 16-bit).
This operation is used in most simple or complex image processing functions in OpenCV.
See also: \cvCppCross{add}, \cvCppCross{subtract}, \cvCppCross{multiply}, \cvCppCross{divide}, \cvCppCross{Mat::convertTo}
\cvCppFunc{scaleAdd}
Calculates the sum of a scaled array and another array.
\cvarg{src2}{The second source array; must have the same size and the same type as \texttt{src1}}
\cvarg{dst}{The destination array; will have the same size and the same type as \texttt{src1}}
\end{description}
The function \texttt{cvScaleAdd} is one of the classical primitive linear algebra operations, known as \texttt{DAXPY} or \texttt{SAXPY} in \href{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}{BLAS}. It calculates the sum of a scaled array and another array:
\cvarg{DECOMP\_LU}{Gaussian elimination with optimal pivot element chosen}
\cvarg{DECOMP\_CHOLESKY}{Cholesky $LL^T$ factorization; the matrix \texttt{src1} must be symmetrical and positively defined}
\cvarg{DECOMP\_EIG}{Eigenvalue decomposition; the matrix \texttt{src1} must be symmetrical}
\cvarg{DECOMP\_SVD}{Singular value decomposition (SVD) method; the system can be over-defined and/or the matrix \texttt{src1} can be singular}
\cvarg{DECOMP\_QR}{QR factorization; the system can be over-defined and/or the matrix \texttt{src1} can be singular}
\cvarg{DECOMP\_NORMAL}{While all the previous flags are mutually exclusive, this flag can be used together with any of the previous. It means that the normal equations $\texttt{src1}^T\cdot\texttt{src1}\cdot\texttt{dst}=\texttt{src1}^T\texttt{src2}$ are solved instead of the original system $\texttt{src1}\cdot\texttt{dst}=\texttt{src2}$}
\end{description}}
\end{description}
The function \texttt{solve} solves a linear system or least-squares problem (the latter is possible with SVD or QR methods, or by specifying the flag \texttt{DECOMP\_NORMAL}):
If \texttt{DECOMP\_LU} or \texttt{DECOMP\_CHOLESKY} method is used, the function returns 1 if \texttt{src1} (or $\texttt{src1}^T\texttt{src1}$) is non-singular and 0 otherwise; in the latter case \texttt{dst} is not valid. Other methods find some pseudo-solution in the case of singular left-hand side part.
Note that if you want to find unity-norm solution of an under-defined singular system $\texttt{src1}\cdot\texttt{dst}=0$, the function \texttt{solve} will not do the work. Use \cvCppCross{SVD::solveZ} instead.
See also: \cvCppCross{invert}, \cvCppCross{SVD}, \cvCppCross{eigen}
\cvdefCpp{void sort(const Mat\& src, Mat\& dst, int flags);}
\begin{description}
\cvarg{src}{The source single-channel array}
\cvarg{dst}{The destination array of the same size and the same type as \texttt{src}}
\cvarg{flags}{The operation flags, a combination of the following values:
\begin{description}
\cvarg{CV\_SORT\_EVERY\_ROW}{Each matrix row is sorted independently}
\cvarg{CV\_SORT\_EVERY\_COLUMN}{Each matrix column is sorted independently. This flag and the previous one are mutually exclusive}
\cvarg{CV\_SORT\_ASCENDING}{Each matrix row is sorted in the ascending order}
\cvarg{CV\_SORT\_DESCENDING}{Each matrix row is sorted in the descending order. This flag and the previous one are also mutually exclusive}
\end{description}}
\end{description}
The function \texttt{sort} sorts each matrix row or each matrix column in ascending or descending order. If you want to sort matrix rows or columns lexicographically, you can use STL \texttt{std::sort} generic function with the proper comparison predicate.
See also: \cvCppCross{sortIdx}, \cvCppCross{randShuffle}
\cvCppFunc{sortIdx}
Sorts each row or each column of a matrix
\cvdefCpp{void sortIdx(const Mat\& src, Mat\& dst, int flags);}
\begin{description}
\cvarg{src}{The source single-channel array}
\cvarg{dst}{The destination integer array of the same size as \texttt{src}}
\cvarg{flags}{The operation flags, a combination of the following values:
\begin{description}
\cvarg{CV\_SORT\_EVERY\_ROW}{Each matrix row is sorted independently}
\cvarg{CV\_SORT\_EVERY\_COLUMN}{Each matrix column is sorted independently. This flag and the previous one are mutually exclusive}
\cvarg{CV\_SORT\_ASCENDING}{Each matrix row is sorted in the ascending order}
\cvarg{CV\_SORT\_DESCENDING}{Each matrix row is sorted in the descending order. This flag and the previous one are also mutually exclusive}
\end{description}}
\end{description}
The function \texttt{sortIdx} sorts each matrix row or each matrix column in ascending or descending order. Instead of reordering the elements themselves, it stores the indices of sorted elements in the destination array. For example:
\cvarg{mv}{The destination array or vector of arrays; The number of arrays must match \texttt{mtx.channels()}. The arrays themselves will be reallocated if needed}
\end{description}
The functions \texttt{split} split multi-channel array into separate single-channel arrays:
\[\texttt{mv}[c](I)=\texttt{mtx}(I)_c \]
If you need to extract a single-channel or do some other sophisticated channel permutation, use \cvCppCross{mixChannels}
See also: \cvCppCross{merge}, \cvCppCross{mixChannels}, \cvCppCross{cvtColor}
\cvarg{dst}{The destination array; will have the same size and the same type as \texttt{src}}
\end{description}
The functions \texttt{sqrt} calculate square root of each source array element. in the case of multi-channel arrays each channel is processed independently. The function accuracy is approximately the same as of the built-in \texttt{std::sqrt}.
See also: \cvCppCross{pow}, \cvCppCross{magnitude}
\cvCppFunc{subtract}
Calculates per-element difference between two arrays or array and a scalar
// 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:
// x = vt.t()*inv(w)*u.t()*rhs ~ inv(A)*rhs
void backSubst( const Mat& rhs, Mat& x ) const;
Mat u; // the left orthogonal matrix
Mat w; // vector of singular values
Mat vt; // the right orthogonal matrix
};
\end{lstlisting}
The class \texttt{SVD} is used to compute Singular Value Decomposition of a floating-point matrix and then use it to solve least-square problems, under-determined linear systems, invert matrices, compute condition numbers etc.
For a bit faster operation you can pass \texttt{flags=SVD::MODIFY\_A|...} to modify the decomposed matrix when it is not necessarily to preserve it. If you want to compute condition number of a matrix or absolute value of its determinant - you do not need \texttt{u} and \texttt{vt}, so you can pass \texttt{flags=SVD::NO\_UV|...}. Another flag \texttt{FULL\_UV} indicates that full-size \texttt{u} and \texttt{vt} must be computed, which is not necessary most of the time.
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}{Indicates that only the vector of singular values \texttt{w} is to be computed, while \texttt{u} and \texttt{vt} will be set to empty matrices}
\cvarg{SVD::FULL\_UV}{When the matrix is not square, by default the algorithm produces \texttt{u} and \texttt{vt} matrices of sufficiently large size for the further \texttt{A} reconstruction. If, however, \texttt{FULL\_UV} flag is specified, \texttt{u} and \texttt{vt} 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{vt} matrices}
\cvarg{SVD::FULL\_UV}{When the matrix is not square, by default the algorithm produces \texttt{u} and \texttt{vt} matrices of sufficiently large size for the further \texttt{A} reconstruction. If, however, \texttt{FULL\_UV} flag is specified, \texttt{u} and \texttt{vt} will be full-size square orthogonal matrices.}
\end{description}
\end{description}
The operator performs singular value decomposition of the supplied matrix. The \texttt{u}, \texttt{vt} and the vector of singular values \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:
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
\cvdefCpp{Scalar sum(const Mat\& mtx);\newline
Scalar sum(const MatND\& mtx);}
\begin{description}
\cvarg{mtx}{The source array; must have 1 to 4 channels}
\end{description}
The functions \texttt{sum} calculate and return the sum of array elements, independently for each channel.
See also: \cvCppCross{countNonZero}, \cvCppCross{mean}, \cvCppCross{meanStdDev}, \cvCppCross{norm}, \cvCppCross{minMaxLoc}, \cvCppCross{reduce}
\cvCppFunc{theRNG}
Returns the default random number generator
\cvdefCpp{RNG\& theRNG();}
The function \texttt{theRNG} returns the default random number generator. For each thread there is separate random number generator, so you can use the function safely in multi-thread environments. If you just need to get a single random number using this generator or initialize an array, you can use \cvCppCross{randu} or \cvCppCross{randn} instead. But if you are going to generate many random numbers inside a loop, it will be much faster to use this function to retrieve the generator and then use \texttt{RNG::operator \_Tp()}.
See also: \cvCppCross{RNG}, \cvCppCross{randu}, \cvCppCross{randn}
\cvCppFunc{trace}
Returns the trace of a matrix
\cvdefCpp{Scalar trace(const Mat\& mtx);}
\begin{description}
\cvarg{mtx}{The source matrix}
\end{description}
The function \texttt{trace} returns the sum of the diagonal elements of the matrix \texttt{mtx}.
That is, every element of an \texttt{N}-channel array \texttt{src} is
considered as \texttt{N}-element vector, which is transformed using
a $\texttt{M}\times\texttt{N}$ or $\texttt{M}\times\texttt{N+1}$ matrix \texttt{mtx} into
an element of \texttt{M}-channel array \texttt{dst}.
The function may be used for geometrical transformation of $N$-dimensional
points, arbitrary linear color space transformation (such as various kinds of RGB$\rightarrow$YUV transforms), shuffling the image channels and so forth.
See also: \cvCppCross{perspectiveTransform}, \cvCppCross{getAffineTransform}, \cvCppCross{estimateRigidTransform}, \cvCppCross{warpAffine}, \cvCppCross{warpPerspective}
