\section{CV. Image Processing and Computer Vision}
-\subsection{Image Filtering}
+\subsection{Image Filtering}\label{CV.Filtering}
+
+Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images (represented as \cross{Mat}'s), that is, for each pixel location $(x,y)$ in the source image some its (normally rectangular) neighborhood is considered and used to compute the response. In case of a linear filter it is a weighted sum of pixel values, in case of morphological operations it is the minimum or maximum etc. The computed response is stored to the destination image at the same location $(x,y)$. It means, that the output image will be of the same size as the input image. Normally, the functions supports multi-channel arrays, in which case every channel is processed independently, therefore the output image will also have the same number of channels as the input one.
+
+Another common feature of the functions and classes described in this section is that, unlike simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For example, if we want to smooth an image using a Gaussian $3 \times 3$ filter, then during the processing of the left-most pixels in each row we need pixels to the left of them, i.e. outside of the image. We can let those pixels be the same as the left-most image pixels (i.e. use "replicated border" extrapolation mthod), or assume that all the non-existing pixels are zeros ("contant border" extrapolation method) etc. OpenCV let the user to specify the extrapolation method; see the function \cross{borderInterpolate} and discussion of \texttt{borderType} parameter in various functions below.
\cvfunc{BaseColumnFilter}\label{BaseColumnFilter}
Base class for filters with single-column kernels
{
public:
virtual ~BaseColumnFilter();
+
+ // To be overriden by the user.
+ //
// runs filtering operation on the set of rows,
// "dstcount + ksize - 1" rows on input,
// "dstcount" rows on output,
The class \texttt{BaseColumnFilter} is the base class for filtering data using single-column kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
-\[\texttt{dst}(x,y) = F(\texttt{src}[y](x), \texttt{src}[y+1](x), ..., \texttt{src}[y+\texttt{ksize}-1](x)\]
+\[\texttt{dst}(x,y) = F(\texttt{src}[y](x),\;\texttt{src}[y+1](x),\;...,\;\texttt{src}[y+\texttt{ksize}-1](x)\]
where $F$ is the filtering function, but, as it is represented as a class, it can produce any side effects, memorize previously processed data etc. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to \cross{FilterEngine} constructor. While the filtering operation interface uses \texttt{uchar} type, a particular implementation is not limited to 8-bit data.
{
public:
virtual ~BaseFilter();
+
+ // To be overriden by the user.
+ //
// runs filtering operation on the set of rows,
// "dstcount + ksize.height - 1" rows on input,
// "dstcount" rows on output,
\[
\begin{array}{l}
- \texttt{dst}(x,y) = F( \\
- \texttt{src}[y](x), \texttt{src}[y](x+1), ..., \texttt{src}[y](x+\texttt{ksize.width}-1), \\
- \texttt{src}[y+1](x), \texttt{src}[y+1](x+1), ..., \texttt{src}[y+1](x+\texttt{ksize.width}-1), \\
+ \texttt{dst}(x,y) = F( \texttt{src}[y](x),\;\texttt{src}[y](x+1),\;...,\;\texttt{src}[y](x+\texttt{ksize.width}-1), \\
+ \texttt{src}[y+1](x),\;\texttt{src}[y+1](x+1),\;...,\;\texttt{src}[y+1](x+\texttt{ksize.width}-1), \\
......................................................................................... \\
- \texttt{src}[y+\texttt{ksize.height-1}](x), \texttt{src}[y+\texttt{ksize.height-1}](x+1), ..., \texttt{src}[y+\texttt{ksize.height-1}](x+\texttt{ksize.width}-1))
+ \texttt{src}[y+\texttt{ksize.height-1}](x),\\
+ \texttt{src}[y+\texttt{ksize.height-1}](x+1),\\
+ ...
+ \texttt{src}[y+\texttt{ksize.height-1}](x+\texttt{ksize.width}-1))
\end{array}
\]
public:
virtual ~BaseRowFilter();
+ // To be overriden by the user.
+ //
+ // runs filtering operation on the single input row
+ // of "width" element, each element is has "cn" channels.
+ // the filtered row is written into "dst" buffer.
virtual void operator()(const uchar* src, uchar* dst,
int width, int cn) = 0;
int ksize, anchor;
The class \texttt{BaseRowFilter} is the base class for filtering data using single-row kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
-\[\texttt{dst}(x,y) = F(\texttt{src}[y](x), \texttt{src}[y](x+1), ..., \texttt{src}[y](x+\texttt{ksize.width}-1))\]
+\[\texttt{dst}(x,y) = F(\texttt{src}[y](x),\;\texttt{src}[y](x+1),\;...,\;\texttt{src}[y](x+\texttt{ksize.width}-1))\]
where $F$ is the filtering function. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to \cross{FilterEngine} constructor. While the filtering operation interface uses \texttt{uchar} type, a particular implementation is not limited to 8-bit data.
\[ \texttt{K} = \frac{1}{\texttt{ksize.width*ksize.height}}
\begin{bmatrix}
-1 1 1 ... 1 1 \\
-1 1 1 ... 1 1 \\
-............... \\
-1 1 1 ... 1 1
+1 & 1 & 1 & \cdots & 1 & 1 \\
+1 & 1 & 1 & \cdots & 1 & 1 \\
+\hdotsfor{6} \\
+1 & 1 & 1 & \cdots & 1 & 1 \\
\end{bmatrix}
\]
\[ \texttt{K} = \alpha
\begin{bmatrix}
-1 & 1 & 1 & ... & 1 & 1 \\
-1 & 1 & 1 & ... & 1 & 1 \\
+1 & 1 & 1 & \cdots & 1 & 1 \\
+1 & 1 & 1 & \cdots & 1 & 1 \\
\hdotsfor{6} \\
-1 & 1 & 1 & ... & 1 & 1
+1 & 1 & 1 & \cdots & 1 & 1
\end{bmatrix}
\]
{\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}
{1}{otherwise} \]
-Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariation matrices of image derivatives (used in dense optical flow algorithms, \href{conerHarris}{Harris corner detector} etc.). If you need to compute pixel sums over variable-size windows, use \cross{integral}.
+Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariation matrices of image derivatives (used in dense optical flow algorithms, \hyperref[conerHarris]{Harris corner detector} etc.). If you need to compute pixel sums over variable-size windows, use \cross{integral}.
See also: \cross{boxFilter}, \cross{bilateralFilter}, \cross{GaussianBlur}, \cross{medianBlur}, \cross{integral}.
See also: \cross{createSeparableLinearFilter}, \cross{getDerivKernels}, \cross{Scharr}, \cross{Sobel}.
\cvfunc{createGaussianFilter}\label{createGaussianFilter}
-Returns engine for smoothing images with Gaussian filter
+Returns engine for smoothing images with a Gaussian filter
\begin{lstlisting}
Ptr<FilterEngine> createGaussianFilter( int type, Size ksize,
Creates engine for non-separable morphological operations
\begin{lstlisting}
-Ptr<FilterEngine> createMorphologyFilter(int op, int type, const Mat& element,
- Point anchor=Point(-1,-1), int rowBorderType=BORDER_CONSTANT,
- int columnBorderType=-1,
- const Scalar& borderValue=morphologyDefaultBorderValue());
+Ptr<FilterEngine> createMorphologyFilter(int op, int type,
+ const Mat& element, Point anchor=Point(-1,-1),
+ int rowBorderType=BORDER_CONSTANT,
+ int columnBorderType=-1,
+ const Scalar& borderValue=morphologyDefaultBorderValue());
Ptr<BaseFilter> getMorphologyFilter(int op, int type, const Mat& element,
- Point anchor=Point(-1,-1));
+ Point anchor=Point(-1,-1));
Ptr<BaseRowFilter> getMorphologyRowFilter(int op, int type,
int esize, int anchor=-1);
Ptr<BaseColumnFilter> getMorphologyColumnFilter(int op, int type,
int esize, int anchor=-1);
-static inline Scalar morphologyDefaultBorderValue() { return Scalar::all(DBL_MAX); }
+static inline Scalar morphologyDefaultBorderValue()
+{ return Scalar::all(DBL_MAX); }
\end{lstlisting}
\begin{description}
\cvarg{op}{The morphology operation id, \texttt{MORPH\_ERODE} or \texttt{MORPH\_DILATE}}
\cvarg{esize}{The horizontal or vertical structuring element size for separable morphological operations}
\cvarg{anchor}{The anchor position within the structuring element; negative values mean that the anchor is at the center}
\cvarg{rowBorderType, columnBorderType}{The pixel extrapolation methods in the horizontal and the vertical directions; see \cross{borderInterpolate}}
-\cvarg{borderValue}{The border value in case of a constant border. The default value, \texttt{morphologyDefaultBorderValue}, has the special meaning. It is transformed $+\inf$ for the erosion and to $-\inf$ for the dilation, which means that the minimum (maximum) is effectively computed only over the pixels that are inside the image.}
+\cvarg{borderValue}{The border value in case of a constant border. The default value,\\ \texttt{morphologyDefaultBorderValue}, has the special meaning. It is transformed $+\inf$ for the erosion and to $-\inf$ for the dilation, which means that the minimum (maximum) is effectively computed only over the pixels that are inside the image.}
\end{description}
The functions construct primitive morphological filtering operations or a filter engine based on them. Normally it's enough to use \cross{createMorphologyFilter} or even higher-level \cross{erode}, \cross{dilate} or \cross{morphologyEx}, Note, that \cross{createMorphologyFilter} analyses the structuring element shape and builds a separable morphological filter engine when the structuring element is square.
\texttt{dst}(x,y) = \max_{(x',y'): \, \texttt{element}(x',y')\ne0}\texttt{src}(x+x',y+y')
\]
-The function supports the in-place mode. Dilation can be applied several (\texttt{iterations}) times. For color images, each channel is processed independently.
+The function supports the in-place mode. Dilation can be applied several (\texttt{iterations}) times. In the case of multi-channel images each channel is processed independently.
See also: \cross{erode}, \cross{morphologyEx}, \cross{createMorphologyFilter}
The function \texttt{erode} erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:
\[
-\texttt{dst}(x,y) = \min_{(x',y'): \, \texttt{kernel}(x',y')\ne0}\texttt{src}(x+x',y+y')
+\texttt{dst}(x,y) = \min_{(x',y'): \, \texttt{element}(x',y')\ne0}\texttt{src}(x+x',y+y')
\]
-The function supports the in-place mode. Erosion can be applied several (\texttt{iterations}) times. For color images, each channel is processed independently.
+The function supports the in-place mode. Erosion can be applied several (\texttt{iterations}) times. In the case of multi-channel images each channel is processed independently.
See also: \cross{dilate}, \cross{morphologyEx}, \cross{createMorphologyFilter}
The function does actually computes correlation, not the convolution:
\[
-\texttt{dst}(x,y) = \sum_{0\leq x' < \texttt{kernel.cols},\,0\leq y' < \texttt{kernel.rows}} \texttt{kernel}(x',y')*\texttt{src}(x+x'-\texttt{anchor.x},y+y'-\texttt{anchor.y})
+\texttt{dst}(x,y) = \sum_{\stackrel{0\leq x' < \texttt{kernel.cols},}{0\leq y' < \texttt{kernel.rows}}} \texttt{kernel}(x',y')*\texttt{src}(x+x'-\texttt{anchor.x},y+y'-\texttt{anchor.y})
\]
That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using \cross{flip} and set the new anchor to \texttt{(kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1)}.
-The function uses \href{dft}{DFT}-based algorithm in case of sufficiently large kernels (~$11\times11$) and the direct algorithm (that uses the engine retrieved by \cross{createLinearFilter}) for small kernels.
+The function uses \hyperref[dft]{DFT}-based algorithm in case of sufficiently large kernels (~$11\times11$) and the direct algorithm (that uses the engine retrieved by \cross{createLinearFilter}) for small kernels.
See also: \cross{sepFilter2D}, \cross{createLinearFilter}, \cross{dft}, \cross{matchTemplate}
\cvarg{dx}{The derivative order in respect with x}
\cvarg{dy}{The derivative order in respect with y}
\cvarg{ksize}{The aperture size. It can be \texttt{CV\_SCHARR}, 1, 3, 5 or 7}
-\cvarg{normalize}{Indicates, whether to normalize (scale down) the filter coefficients or not. In theory the coefficients have the denominator $=2^{ksize*2-dx-dy-2}$. If you are going to filter floating-point images, you will likely want to use the normalized kernels. But if you compute derivatives of a 8-bit image, store the results in 16-bit image and want to preserve all the fractional bits, you may leave \texttt{normalize=false}.}
+\cvarg{normalize}{Indicates, whether to normalize (scale down) the filter coefficients or not. In theory the coefficients should have the denominator $=2^{ksize*2-dx-dy-2}$. If you are going to filter floating-point images, you will likely want to use the normalized kernels. But if you compute derivatives of a 8-bit image, store the results in 16-bit image and wish to preserve all the fractional bits, you may want to set \texttt{normalize=false}.}
\cvarg{ktype}{The type of filter coefficients. It can be \texttt{CV\_32f} or \texttt{CV\_64F}}
\end{description}
\end{lstlisting}
\begin{description}
\cvarg{ksize}{The aperture size. It should be odd ($\texttt{ksize} \mod 2 = 1$) and positive.}
-\cvarg{sigma}{The Gaussian standard deviation. If it is non-positive, it is computed from \texttt{ksize} as
+\cvarg{sigma}{The Gaussian standard deviation. If it is non-positive, it is computed from \texttt{ksize} as \\
\texttt{sigma = 0.3*(ksize/2 - 1) + 0.8}}
\cvarg{ktype}{The type of filter coefficients. It can be \texttt{CV\_32f} or \texttt{CV\_64F}}
\end{description}
where $i=0..\texttt{ksize}-1$ and $\alpha$ is the scale factor chosen so that $\sum_i G_i=1$
-Two of such generated kernels can be passed to \cross{sepFilter2D} or to \cross{createSeparableLinearFilter} that will automatically detect that these are smoothing kernels are process the image accordingly. Also you may use the higher-level \cross{GaussianBlur}.
+Two of such generated kernels can be passed to \cross{sepFilter2D} or to \cross{createSeparableLinearFilter} that will automatically detect that these are smoothing kernels and handle them accordingly. Also you may use the higher-level \cross{GaussianBlur}.
See also: \cross{sepFilter2D}, \cross{createSeparableLinearFilter}, \cross{getDerivKernels}, \cross{getStructuringElement}, \cross{GaussianBlur}.
\end{itemize}}
\cvarg{esize}{Size of the structuring element}
-\cvarg{anchor}{The anchor position within the element. The default value $(-1, -1)$ means that the anchor is at the center. Note that only the cross-shaped element's shape depends on the anchor position; in other cases the anchor just regulates by how much the morphological operation result is shifted}
+\cvarg{anchor}{The anchor position within the element. The default value $(-1, -1)$ means that the anchor is at the center. Note that only the cross-shaped element's shape depends on the anchor position; in other cases the anchor just regulates by how much the result of the morphological operation is shifted}
\end{description}
The function constructs and returns the structuring element that can be then passed to \cross{createMorphologyFilter}, \cross{erode}, \cross{dilate} or \cross{morphologyEx}. But also you can construct an arbitrary binary mask yourself and use it as the structuring element.
Opening:
\[
-dst=open(src,element)=dilate(erode(src,element),element)
+\texttt{dst}=\mathrm{open}(\texttt{src},\texttt{element})=\mathrm{dilate}(\mathrm{erode}(\texttt{src},\texttt{element}))
\]
Closing:
\[
-dst=close(src,element)=erode(dilate(src,element),element)
+\texttt{dst}=\mathrm{close}(\texttt{src},\texttt{element})=\mathrm{erode}(\mathrm{dilate}(\texttt{src},\texttt{element}))
\]
Morphological gradient:
\[
-dst=morph\_grad(src,element)=dilate(src,element)-erode(src,element)
+\texttt{dst}=\mathrm{morph\_grad}(\texttt{src},\texttt{element})=\mathrm{dilate}(\texttt{src},\texttt{element})-\mathrm{erode}(\texttt{src},\texttt{element})
\]
"Top hat":
\[
-dst=tophat(src,element)=src-open(src,element)
+\texttt{dst}=\mathrm{tophat}(\texttt{src},\texttt{element})=\texttt{src}-\mathrm{open}(\texttt{src},\texttt{element})
\]
"Black hat":
\[
-dst=blackhat(src,element)=close(src,element)-src
+\texttt{dst}=\mathrm{blackhat}(\texttt{src},\texttt{element})=\mathrm{close}(\texttt{src},\texttt{element})-\texttt{src}
\]
Any of the operations can be done in-place.
The function \texttt{pyrUp} performs the upsampling step of the Gaussian pyramid construction (it can actually be used to construct the Laplacian pyramid). First it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in \cross{pyrDown}, multiplied by 4.
-\cross{sepFilter2D}
+\cvfunc{sepFilter2D}\label{sepFilter2D}
Applies separable linear filter to an image
\begin{lstlisting}
In all cases except 1, an $\texttt{ksize} \times
\texttt{ksize}$ separable kernel will be used to calculate the
-derivative. For $\texttt{ksize} = 1$ $ 3 \times 1$ or $ 1 \times 3$
-a kernel will be used (no Gaussian smoothing is not done). \texttt{ksize=1} can only be used for the first or the second x- or y- derivatives.
+derivative. When $\texttt{ksize = 1}$, a $ 3 \times 1$ or $ 1 \times 3$
+kernel will be used (i.e. no Gaussian smoothing is done). \texttt{ksize = 1} can only be used for the first or the second x- or y- derivatives.
-There is also the special value \texttt{CV\_SCHARR} (-1) that corresponds to a $3\times3$ Scharr
-filter that may give more accurate results than a $3\times3$ Sobel. Scharr
+There is also the special value \texttt{ksize = CV\_SCHARR} (-1) that corresponds to a $3\times3$ Scharr
+filter that may give more accurate results than a $3\times3$ Sobel. The Scharr
aperture is
\[ \vecthreethree
\texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}
\]
-The Sobel operators combine Gaussian smoothing and differentiation
+The Sobel operators combine Gaussian smoothing and differentiation,
so the result is more or less resistant to the noise. Most often,
the function is called with (\texttt{xorder} = 1, \texttt{yorder} = 0,
\texttt{ksize} = 3) or (\texttt{xorder} = 0, \texttt{yorder} = 1,
\cvarg{borderType}{The pixel extrapolation method, see \cross{borderInterpolate}}
\end{description}
-The function computes the first x- or y- spatial image derivative using Scharr operator. The call \texttt{Scharr(src, dst, ddepth, xorder, yorder, scale, delta, borderType)} is equivalent to \cross{Sobel}\texttt{(src, dst, ddepth, xorder, yorder, CV\_SCHARR, scale, delta, borderType)}.
+The function computes the first x- or y- spatial image derivative using Scharr operator. The call
+\[\texttt{Scharr(src, dst, ddepth, xorder, yorder, scale, delta, borderType)}\]
+is equivalent to
+\[\texttt{Sobel(src, dst, ddepth, xorder, yorder, CV\_SCHARR, scale, delta, borderType)}.\]
+
+\subsection{Geometric Image Transformations}\label{CV.Geometric}
+
+The functions in this subsection perform various geometrical transformations of 2D images. That is, they do not change the image content, but deform the pixel grid, and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the inverse mapping is done in the reverse order, from destination to the source. That is, for each pixel $(x, y)$ of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value, that is:
-\subsection{Geometric Image Transformations}
+\[\texttt{dst}(x,y)=\texttt{src}(f_x(x,y), f_y(x,y))\]
+
+In the case when the user specifies the forward mapping: $\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}$, the OpenCV functions first compute the corresponding inverse mapping: $\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}$ and then use the above formula.
+
+The actual implementations of the geometrical transformations, from the most generic \cross{remap} and to the simplest and the fastest \cross{resize}, need to solve the 2 main problems with the above formula:
+\begin{enumerate}
+ \item extrapolation of non-existing pixels. Similarly to \hyperref[CV.Filtering]{the filtering functions}, for some $(x,y)$ one of $f_x(x,y)$ or $f_y(x,y)$, or they both, may fall outside of the image, in which case some extrapolation method needs to be used. OpenCV provides the same selection of the extrapolation methods as in the filtering functions, but also an additional method \texttt{BORDER\_TRANSPARENT}, which means that the corresponding pixels in the destination image will not be modified at all.
+ \item interpolation of pixel values. Usually $f_x(x,y)$ and $f_y(x,y)$ are floating-point numbers (i.e. $\left<f_x, f_y\right>$ can be an affine or perspective transformation, or radial lens distortion correction etc.), so a pixel values at fractional coordinates needs to be retrieved. In the simplest case the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel used, which is called nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated \href{http://en.wikipedia.org/wiki/Multivariate_interpolation}{interpolation methods}, where a polynomial function is fit into some neighborhood of the computed pixel $(f_x(x,y), f_y(x,y))$ and then the value of the polynomial at $(f_x(x,y), f_y(x,y))$ is taken as the interpolated pixel value. In OpenCV you can choose between several interpolation methods, see \cross{resize}.
+\end{enumerate}
\cvfunc{convertMaps}\label{convertMaps}
Converts image transformation maps from one representation to another
The function \texttt{getRectSubPix} extracts pixels from \texttt{src}:
\[
-dst(x, y) = src(x + \texttt{center.x} - (width(\texttt{dst})-1)*0.5, y + \texttt{center.y} - (height(\texttt{dst} )-1)*0.5)
+dst(x, y) = src(x + \texttt{center.x} - (\texttt{dst.cols}-1)*0.5, y + \texttt{center.y} - (\texttt{dst.rows}-1)*0.5)
\]
where the values of the pixels at non-integer coordinates are retrieved
where
\[
-\alpha = \texttt{scale} \cdot \cos \texttt{angle},\,\beta = \texttt{scale} \cdot \sin \texttt{angle}
+\begin{array}{l}
+\alpha = \texttt{scale} \cdot \cos \texttt{angle},\\
+\beta = \texttt{scale} \cdot \sin \texttt{angle}
+\end{array}
\]
The transformation maps the rotation center to itself. If this is not the purpose, the shift should be adjusted.
Size size, int m1type, Mat& map1, Mat& map2 );
\end{lstlisting}
\begin{description}
-\cvarg{cameraMatrix}{The camera matrix $A=[f_x 0 c_x; 0 f_y c_y; 0 0 1]$}
+\cvarg{cameraMatrix}{The camera matrix $A=\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}$}
\cvarg{distCoeffs}{The vector of distortion coefficients, \cross{4x1, 1x4, 5x1 or 1x5}}
\cvarg{R}{The rectification transformation in object space (3x3 matrix). \texttt{R1} or \texttt{R2}, computed by \cross{stereoRectify} can be passed here. If the matrix is empty, the identity transformation is assumed}
-\cvarg{newCameraMatrix}{The new camera matrix $A'=[{f'}_x 0 {c'}_x; 0 {f'}_y {c'}_y; 0 0 1]$}
+\cvarg{newCameraMatrix}{The new camera matrix $A'=\vecthreethree{f_x'}{0}{c_x'}{0}{f_y'}{c_y'}{0}{0}{1}$}
\cvarg{size}{The image size}
\cvarg{m1type}{The type of the first output map, can be \texttt{CV\_32FC1} or \texttt{CV\_16SC2}. See \cross{convertMaps}}
\cvarg{map1}{The first output map}
\cvarg{map2}{The second output map}
\end{description}
-The function computes the joint undistortion+rectification transformation and represent the result in forms of maps for \cross{remap}. The undistorted image will look like the same scene as in the original image, but captured with a camera with camera matrix \texttt{=newCameraMatrix} and zero distortion. Also, this new camera will be oriented slightly different in the space, according to \texttt{R}. That, for example, helps to align a stereo pair so that the epipolar lines on both images become horizontal and have the same y- coordinate (in case of horizontally aligned stereo camera).
+The function computes the joint undistortion+rectification transformation and represents the result in the form of maps for \cross{remap}. The undistorted image will look like the original, as if it was captured with a camera with camera matrix \texttt{=newCameraMatrix} and zero distortion. Also, this new camera will be oriented differently in the coordinate space, according to \texttt{R}. That, for example, helps to align a stereo pair so that the epipolar lines on both images become horizontal and have the same y- coordinate (in case of horizontally aligned stereo camera).
The function actually builds the maps for the inverse mapping algorithm that is used by \cross{remap}. That is, for each pixel $(u, v)$ in the destination (corrected and rectified) image the function computes the corresponding coordinates in the source image (i.e. the original image from camera). The process is the following:
map_y(u,v) \leftarrow y" f_y + c_y
\end{array}
\]
-where $(k_1, k_2, p_1, p_2[, k_3])$ are the distortion coefficients.
+where $(k_1, k_2, p_1, p_2[, k_3])$\label{4x1, 1x4, 5x1 or 1x5} are the distortion coefficients.
-Normally, this function is called [twice, once for each head of stereo camera] after \cross{stereoRectify}. But it is also possible to compute the rectification transformations directly from the fundamental matrix, e.g. by using \cross{stereoRectifyUncalibrated}. Such functions work with pixels and produce homographies \texttt{H} as rectification transformations, not rotation matrices \texttt{R} in 3D space. In this case, the \texttt{R} can be computed from the homography matrix \texttt{H} as
+In the case of a stereo camera this function is called twice, once for each camera head, after \cross{stereoRectify}. But it is also possible to compute the rectification transformations directly from the fundamental matrix, e.g. by using \cross{stereoRectifyUncalibrated}. Such functions work with pixels and produce homographies \texttt{H} as rectification transformations, not rotation matrices \texttt{R} in 3D space. In this case, the \texttt{R} can be computed from the homography matrix \texttt{H} as
-\[ \texttt{R} = \texttt{cameraMatrix}^{-1} \texttt{H} \texttt{cameraMatrix} \]
+\[ \texttt{R} = \texttt{cameraMatrix}^{-1} \cdot \texttt{H} \cdot \texttt{cameraMatrix} \]
\cvfunc{invertAffineTransform}\label{invertAffineTransform}
Inverts an affine transformation
The function computes inverse affine transformation represented by $2 \times 3$ matrix \texttt{M}:
\[\begin{bmatrix}
-a_11 & a_12 & b_1 \\
-a_21 & a_22 & b_2
+a_{11} & a_{12} & b_1 \\
+a_{21} & a_{22} & b_2
\end{bmatrix}
\]
\cvarg{map1}{The first map of type \texttt{CV\_16SC2}, \texttt{CV\_32FC1} or \texttt{CV\_32FC2}. See \cross{convertMaps}}
\cvarg{map2}{The second map of type \texttt{CV\_16UC1}, \texttt{CV\_32FC1} or none (empty map), respectively}
\cvarg{interpolation}{The interpolation method, see \cross{resize}. The method \texttt{INTER\_AREA} is not supported by this function}
-\cvarg{borderMode}{The pixel extrapolation method, see \cross{borderInterpolate}. When the \texttt{borderMode=BORDER\_TRANSPARENT}, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function}
-\cvarg{borderValue}{A value used in case of a constant border. By default it is 0}
+\cvarg{borderMode}{The pixel extrapolation method, see \cross{borderInterpolate}. When the\\ \texttt{borderMode=BORDER\_TRANSPARENT}, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function}
+\cvarg{borderValue}{A value used in the case of a constant border. By default it is 0}
\end{description}
The function \texttt{remap} transforms the source image using the specified map:
\cvarg{src}{Source image}
\cvarg{dst}{Destination image}
\cvarg{dsize}{The destination image size. If it is zero, then it is computed as:
-\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}}
+\[\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}\]}
\cvarg{fx}{The scale factor along the horizontal axis. When 0, it is computed as
-\texttt{(double)dsize.width/src.cols}}
-\cvarg{fx}{The scale factor along the vertical axis. When 0, it is computed as
-\texttt{(double)dsize.height/src.rows}}
+\[\texttt{(double)dsize.width/src.cols}\]}
+\cvarg{fy}{The scale factor along the vertical axis. When 0, it is computed as
+\[\texttt{(double)dsize.height/src.rows}\]}
\cvarg{interpolation}{The interpolation method:
\begin{description}
\cvarg{INTER\_NEAREST}{nearest-neighbor interpolation}
The function \texttt{undistort} transforms the image to compensate
radial and tangential lens distortion. The function is simply a combination of \cross{initUndistortRectifyMap} (with unity \texttt{R}) and \cross{remap} (with bilinear interpolation) put into one loop.
-The camera matrix and distortion parameters can be determined using
-\cross{calibrateCamera}. If the resolution of images is different from what
-was used at the calibration stage, $f_x, f_y, c_x$ and $c_y$
-need to be adjusted appropriately, while the distortion coefficients
-remain the same.
+The camera matrix and the distortion parameters can be determined using
+\cross{calibrateCamera}. If the resolution of images is different from the used at the calibration stage, $f_x, f_y, c_x$ and $c_y$
+need to be scaled accordingly, while the distortion coefficients remain the same.
\cvfunc{warpAffine}\label{warpAffine}
Applies an affine transformation to an image.
\cvarg{M}{$2\times 3$ transformation matrix}
\cvarg{dsize}{Size of the destination image}
\cvarg{flags}{A combination of interpolation methods, see \cross{resize}, and the optional flag \texttt{WARP\_INVERSE\_MAP} that means that \texttt{M} is the inverse transformation (\texttt{dst}$\rightarrow$\texttt{src})}
-\cvarg{borderMode}{The pixel extrapolation method, see \cross{borderInterpolate}. When the \texttt{borderMode=BORDER\_TRANSPARENT}, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function}
+\cvarg{borderMode}{The pixel extrapolation method, see \cross{borderInterpolate}. When the \\ \texttt{borderMode=BORDER\_TRANSPARENT}, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function}
\cvarg{borderValue}{A value used in case of a constant border. By default it is 0}
\end{description}
The function \texttt{warpAffine} transforms the source image using the specified matrix:
\[
-dst(x,y) = src(M_{11} x + M_{12} y + M_{13}, M_{21} x + M_{22} y + M_{23})
+\texttt{dst}(x,y) = \texttt{src}(\texttt{M}_{11} x + \texttt{M}_{12} y + \texttt{M}_{13}, \texttt{M}_{21} x + \texttt{M}_{22} y + \texttt{M}_{23})
\]
when the flag \texttt{WARP\_INVERSE\_MAP} is set. Otherwise, the transformation is first inverted with \cross{invertAffineTransform} and then put in the formula above instead of \texttt{M}.
See also: \cross{warpPerspective}, \cross{resize}, \cross{remap}, \cross{getRectSubPix}, \cross{transform}
\cvfunc{warpPerspective}\label{warpPerspective}
-Applies an affine transformation to an image.
+Applies a perspective transformation to an image.
\begin{lstlisting}
void warpPerspective( const Mat& src, Mat& dst,
\cvarg{M}{$3\times 3$ transformation matrix}
\cvarg{dsize}{Size of the destination image}
\cvarg{flags}{A combination of interpolation methods, see \cross{resize}, and the optional flag \texttt{WARP\_INVERSE\_MAP} that means that \texttt{M} is the inverse transformation (\texttt{dst}$\rightarrow$\texttt{src})}
-\cvarg{borderMode}{The pixel extrapolation method, see \cross{borderInterpolate}. When the \texttt{borderMode=BORDER\_TRANSPARENT}, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function}
+\cvarg{borderMode}{The pixel extrapolation method, see \cross{borderInterpolate}. When the \\ \texttt{borderMode=BORDER\_TRANSPARENT}, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function}
\cvarg{borderValue}{A value used in case of a constant border. By default it is 0}
\end{description}
The function \texttt{warpPerspective} transforms the source image using the specified matrix:
\[
-dst(x,y) = src\left(\frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}},
+\texttt{dst}(x,y) = \texttt{src}\left(\frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}},
\frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}}\right)
\]
when the flag \texttt{WARP\_INVERSE\_MAP} is set. Otherwise, the transformation is first inverted with \cross{invert} and then put in the formula above instead of \texttt{M}.
where $T(x,y)$ is a threshold calculated individually for each pixel.
-For the method \texttt{ADAPTIVE\_THRESH\_MEAN\_C} it is the mean of a $\texttt{blockSize} \times \texttt{blockSize}$ pixel neighborhood, minus \texttt{C}.
-
-For the method \texttt{ADAPTIVE\_THRESH\_GAUSSIAN\_C} it is the weighted sum (i.e. cross-correlation with a Gaussian window) of a $\texttt{blockSize} \times \texttt{blockSize}$ pixel neighborhood, minus \texttt{C}. The default sigma (standard deviation) is used for the specified \texttt{blockSize}, see \cross{getGaussianKernel}.
+\begin{enumerate}
+ \item
+For the method \texttt{ADAPTIVE\_THRESH\_MEAN\_C} the threshold value $T(x,y)$ is the mean of a $\texttt{blockSize} \times \texttt{blockSize}$ neighborhood of $(x, y)$, minus \texttt{C}.
+ \item
+For the method \texttt{ADAPTIVE\_THRESH\_GAUSSIAN\_C} the threshold value $T(x, y)$ is the weighted sum (i.e. cross-correlation with a Gaussian window) of a $\texttt{blockSize} \times \texttt{blockSize}$ neighborhood of $(x, y)$, minus \texttt{C}. The default sigma (standard deviation) is used for the specified \texttt{blockSize}, see \cross{getGaussianKernel}.
+\end{enumerate}
The function can process the image in-place.
\cvarg{threshold1}{The first threshold for the hysteresis procedure}
\cvarg{threshold2}{The second threshold for the hysteresis procedure}
\cvarg{apertureSize}{Aperture size for the \cross{Sobel} operator}
-\cvarg{L2gradient}{Indicates, whether the more accurate $L_2$ norm $\sqrt{(dI/dx)^2 + (dI/dy)^2}$ should be used to compute the image gradient magnitude (\texttt{L2gradient=true}), or a faster default $L_1$ norm $|dI/dx|+|dI/dy|$ is enough (\texttt{L2gradient=false})}
+\cvarg{L2gradient}{Indicates, whether the more accurate $L_2$ norm $=\sqrt{(dI/dx)^2 + (dI/dy)^2}$ should be used to compute the image gradient magnitude (\texttt{L2gradient=true}), or a faster default $L_1$ norm $=|dI/dx|+|dI/dy|$ is enough (\texttt{L2gradient=false})}
\end{description}
The function \texttt{Canny} finds edges in the input image \texttt{image} and marks them in the output map \texttt{edges} using the Canny algorithm. The smallest value between \texttt{threshold1} and \texttt{threshold2} is used for edge linking, the largest value is used to find the initial segments of strong edges, see
void cvtColor( const Mat& src, Mat& dst, int code, int dstCn=0 );
\end{lstlisting}
\begin{description}
-\cvarg{The source image, 8-bit unsigned, 16-bit unsigned (\texttt{CV\_16UC...}) or single-precision floating-point}
-\cvarg{The destination image; will have the same size and the same depth as \texttt{src}}
+\cvarg{src}{The source image, 8-bit unsigned, 16-bit unsigned (\texttt{CV\_16UC...}) or single-precision floating-point}
+\cvarg{dst}{The destination image; will have the same size and the same depth as \texttt{src}}
\cvarg{code}{The color space conversion code; see the discussion}
\cvarg{dstCn}{The number of channels in the destination image; if the parameter is 0, the number of the channels will be derived automatically from \texttt{src} and the \texttt{code}}
\end{description}
The function \texttt{cvtColor} converts the input image from one color
-space to another. The case of transformation to-from RGB color space the ordering of the channels should be specified explicitly (RGB or BGR).
+space to another. In the case of transformation to-from RGB color space the ordering of the channels should be specified explicitly (RGB or BGR).
-The conventional ranges for R,G,B channel values are:
+The conventional ranges for R, G and B channel values are:
\begin{itemize}
- \item 0 to 255 for 8-bit images
- \item 0 to 65535 for 16-bit images and
- \item 0 to 1 for floating-point images.
+ \item 0 to 255 for \texttt{CV\_8U} images
+ \item 0 to 65535 for \texttt{CV\_16U} images and
+ \item 0 to 1 for \texttt{CV\_32F} images.
\end{itemize}
Of course, in the case of linear transformations the range does not matter,
-but in order to get correct results in the case of non-linear
-transformations, the input image should be scaled if a different value range is used (this note is mostly about 32-bit floating-point images that, if directly converted from 8-bit images, for example, can have 0..255 value range instead of the standard 0..1).
+but in the non-linear cases the input RGB image should be normalized to the proper value range in order to get the correct results, e.g. for RGB$\rightarrow$L*u*v* transformation. For example, if you have a 32-bit floating-point image directly converted from 8-bit image without any scaling, then it will have 0..255 value range, instead of the assumed by the function 0..1. So, before calling \texttt{cvtColor}, you need first to scale the image down:
+\begin{lstlisting}
+img *= 1./255;
+cvtColor(img, img, CV_BGR2Luv);
+\end{lstlisting}
The function can do the following transformations:
\begin{itemize}
\item Transformations within RGB space like adding/removing the alpha channel, reversing the channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5), as well as conversion to/from grayscale using:
\[
- \text{RGB[A] to Gray:} Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
+ \text{RGB[A] to Gray:}\quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
\]
and
\[
- \text{Gray to RGB[A]:} R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
+ \text{Gray to RGB[A]:}\quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
\]
The conversion from a RGB image to gray is done with:
\begin{lstlisting}
-cvtColor(src ,bwsrc, CV_RGB2GRAY)
+cvtColor(src, bwsrc, CV_RGB2GRAY);
\end{lstlisting}
Some more advanced channel reordering can also be done with \cross{mixChannels}.
The values are then converted to the destination data type:
\begin{description}
\item[8-bit images]
-\[ V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)} \]
+\[ V \leftarrow 255\cdot V, S \leftarrow 255\cdot S, H \leftarrow H/2\; \text{(to fit to 0 to 255)} \]
\item[16-bit images (currently not supported)]
-\[ V <- 65535 V, S <- 65535 S, H <- H \]
+\[ V <- 65535\cdot V, S <- 65535\cdot S, H <- H \]
\item[32-bit images]
H, S, V are left as is
\end{description}
The values are then converted to the destination data type:
\begin{description}
\item[8-bit images]
-\[L \leftarrow L*255/100, a \leftarrow a + 128, b \leftarrow b + 128\]
+\[L \leftarrow L*255/100,\; a \leftarrow a + 128,\; b \leftarrow b + 128\]
\item[16-bit images] currently not supported
\item[32-bit images]
L, a, b are left as is
The values are then converted to the destination data type:
\begin{description}
\item[8-bit images]
-\[L \leftarrow 255/100 L, u \leftarrow 255/354 (u + 134), v \leftarrow 255/256 (v + 140) \]
+\[L \leftarrow 255/100 L,\; u \leftarrow 255/354 (u + 134),\; v \leftarrow 255/256 (v + 140) \]
\item[16-bit images] currently not supported
\item[32-bit images] L, u, v are left as is
\end{description}
When \texttt{maskSize == CV\_DIST\_MASK\_PRECISE} and \texttt{distanceType == CV\_DIST\_L2}, the function runs the algorithm described in \cite{Felzenszwalb04}.
-In other cases the \cite{Borgefors86} algorithm is used, that is,
+In other cases the algorithm \cite{Borgefors86} is used, that is,
for pixel the function finds the shortest path to the nearest zero pixel
consisting of basic shifts: horizontal,
vertical, diagonal or knight's move (the latest is available for a
\texttt{CV\_DIST\_L1} types the distance is calculated precisely,
whereas for \texttt{CV\_DIST\_L2} (Euclidian distance) the distance
can be calculated only with some relative error (a $5\times 5$ mask
-gives more accurate results). For \texttt{a, b, c}
+gives more accurate results). For \texttt{a}, \texttt{b} and \texttt{c}
OpenCV uses the values suggested in the original paper:
+
\begin{tabular}{| c | c | c |}
\hline
\texttt{CV\_DIST\_C} & $(3\times 3)$ & a = 1, b = 1\\ \hline
\texttt{CV\_DIST\_L2} & $(5\times 5)$ & a=1, b=1.4, c=2.1969\\ \hline
\end{tabular}
+
Typically, for a fast, coarse distance estimation \texttt{CV\_DIST\_L2},
a $3\times 3$ mask is used, and for a more accurate distance estimation
\texttt{CV\_DIST\_L2}, a $5\times 5$ mask or the precise algorithm is used.
\texttt{src}(x',y')-\texttt{loDiff} \leq \texttt{src}(x,y) \leq \texttt{src}(x',y')+\texttt{upDiff} \]
\item[grayscale image, fixed range] \[
-\texttt{src}(seed.x,seed.y)-\texttt{loDiff}\leq \texttt{src}(x,y) \leq \texttt{src}(seed.x,seed.y)+\texttt{upDiff} \]
+\texttt{src}(\texttt{seed}.x,\texttt{seed}.y)-\texttt{loDiff}\leq \texttt{src}(x,y) \leq \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)+\texttt{upDiff} \]
\item[color image, floating range]
\[ \texttt{src}(x',y')_r-\texttt{loDiff}_r\leq \texttt{src}(x,y)_r\leq \texttt{src}(x',y')_r+\texttt{upDiff}_r \]
\[ \texttt{src}(x',y')_b-\texttt{loDiff}_b\leq \texttt{src}(x,y)_b\leq \texttt{src}(x',y')_b+\texttt{upDiff}_b \]
\item[color image, fixed range]
-\[ \texttt{src}(seed.x,seed.y)_r-\texttt{loDiff}_r\leq \texttt{src}(x,y)_r\leq \texttt{src}(seed.x,seed.y)_r+\texttt{upDiff}_r \]
-\[ \texttt{src}(seed.x,seed.y)_g-\texttt{loDiff}_g\leq \texttt{src}(x,y)_g\leq \texttt{src}(seed.x,seed.y)_g+\texttt{upDiff}_g \]
-\[ \texttt{src}(seed.x,seed.y)_b-\texttt{loDiff}_b\leq \texttt{src}(x,y)_b\leq \texttt{src}(seed.x,seed.y)_b+\texttt{upDiff}_b \]
+\[ \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)_r-\texttt{loDiff}_r\leq \texttt{src}(x,y)_r\leq \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)_r+\texttt{upDiff}_r \]
+\[ \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)_g-\texttt{loDiff}_g\leq \texttt{src}(x,y)_g\leq \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)_g+\texttt{upDiff}_g \]
+\[ \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)_b-\texttt{loDiff}_b\leq \texttt{src}(x,y)_b\leq \texttt{src}(\texttt{seed}.x,\texttt{seed}.y)_b+\texttt{upDiff}_b \]
\end{description}
where $src(x',y')$ is the value of one of pixel neighbors that is already known to belong to the component. That is, to be added to the connected component, a pixel's color/brightness should be close enough to the:
Using these integral images, one may calculate sum, mean and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
\[
-\sum_{x_1\leq x < x_2, \, y_1 \leq y < y_2} = \texttt{sum}(x_2,y_2)-\texttt{sum}(x_1,y_2)-\texttt{sum}(x_2,y_1)+\texttt{sum}(x_1,x_1)
+\sum_{x_1\leq x < x_2, \, y_1 \leq y < y_2} \texttt{image}(x,y) = \texttt{sum}(x_2,y_2)-\texttt{sum}(x_1,y_2)-\texttt{sum}(x_2,y_1)+\texttt{sum}(x_1,x_1)
\]
It makes possible to do a fast blurring or fast block correlation with variable window size, for example. In the case of multi-channel images, sums for each channel are accumulated independently.
Applies a fixed-level threshold to each array element
\begin{lstlisting}
-double threshold( const Mat& src, Mat& dst, double thresh, double maxVal, int thresholdType );
+double threshold( const Mat& src, Mat& dst, double thresh,
+ double maxVal, int thresholdType );
-enum { THRESH_BINARY=0, THRESH_BINARY_INV=1, THRESH_TRUNC=2, THRESH_TOZERO=3,
- THRESH_TOZERO_INV=4, THRESH_MASK=7, THRESH_OTSU=8 };
+enum { THRESH_BINARY=0, THRESH_BINARY_INV=1,
+ THRESH_TRUNC=2, THRESH_TOZERO=3,
+ THRESH_TOZERO_INV=4, THRESH_MASK=7,
+ THRESH_OTSU=8 };
\end{lstlisting}
\begin{description}
\cvarg{src}{Source array (single-channel, 8-bit of 32-bit floating point)}
\texttt{thresholdType}:
\begin{description}
-\cvarg{THRESH\_BINARY}{\[ \texttt{dst}(x,y) = \fork{\texttt{maxVal}}{if $\texttt{src}(x,y) > \texttt{thres}$}{0}{otherwise} \]}
+\cvarg{THRESH\_BINARY}{\[ \texttt{dst}(x,y) = \fork{\texttt{maxVal}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise} \]}
\cvarg{THRESH\_BINARY\_INV}{\[ \texttt{dst}(x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxVal}}{otherwise} \]}
\cvarg{THRESH\_TRUNC}{\[ \texttt{dst}(x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise} \]}
\cvarg{THRESH\_TOZERO}{\[ \texttt{dst}(x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise} \]}
See also: \cross{calcHist}
-\cross{compareHist}
+\cvfunc{compareHist}\label{compareHist}
Compares two histograms
\begin{lstlisting}
and $N$ is the total number of histogram bins.
\item[Chi-Square (method=CV\_COMP\_CHISQR)]
-\[ d(H_1,H_2) = \sum_I \frac{H_1(I)-H_2(I)}{H_1(I)+H_2(I)} \]
+\[ d(H_1,H_2) = \sum_I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)} \]
\item[Intersection (method=CV\_COMP\_INTERSECT)]
\[ d(H_1,H_2) = \sum_I \min (H_1(I), H_2(I)) \]
\item[Bhattacharyya distance (method=CV\_COMP\_BHATTACHARYYA)]
-\[ d(H_1,H_2) = \sqrt{1 - \frac{1}{\bar{H_1} \bar{H_2} N^2} \sum_I \sqrt{H_1(I) \cdot H_2(I)}} \]
+\[ d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}} \]
\end{description}
\item normalize the histogram so that the sum of histogram bins is 255.
\item compute the integral of the histogram:
\[
-H'_i = \sum_{0 \le j \le i} H(j)
+H'_i = \sum_{0 \le j < i} H(j)
\]
\item transform the image using $H'$ as a look-up table: $\texttt{dst}(x,y) = H'(\texttt{src}(x,y))$
\end{enumerate}
The function \texttt{cornerHarris} runs the Harris edge detector on the image. Similarly to \cross{cornerMinEigenVal} and \cross{cornerEigenValsAndVecs}, for each pixel $(x, y)$ it calculates a $2\times2$ gradient covariation matrix $M^{(x,y)}$ over a $\texttt{blockSize} \times \texttt{blockSize}$ neighborhood. Then, it computes the following characteristic:
\[
-\texttt{dst}(x,y) = det(M^{(x,y)}) - k \, trace(M^{(x,y)})^2
+\texttt{dst}(x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left(\mathrm{tr} M^{(x,y)}\right)^2
\]
Corners in the image can be found as the local maxima of this response map.
\cvarg{boderType}{Pixel extrapolation method; see \cross{borderInterpolate}}
\end{description}
-The function \texttt{cornerMinEigenVal} is similar to \cross{cornerEigenValsAndVecs} but it calculates and stores only the minimal eigenvalue of the covariation matrix of derivatives, i.e. $min(\lambda_1, \lambda_2)$ in terms of the formulae in \cross{cornerEigenValsAndVecs} description.
+The function \texttt{cornerMinEigenVal} is similar to \cross{cornerEigenValsAndVecs} but it calculates and stores only the minimal eigenvalue of the covariation matrix of derivatives, i.e. $\min(\lambda_1, \lambda_2)$ in terms of the formulae in \cross{cornerEigenValsAndVecs} description.
\cvfunc{cornerSubPix}\label{cornerSubPix}
Refines the corner locations.
\cvarg{minDistance}{The minimum possible Euclidean distance between the returned corners}
\cvarg{mask}{The optional region of interest. If the image is not empty (then it needs to have the type \texttt{CV\_8UC1} and the same size as \texttt{image}), it will specify the region in which the corners are detected}
\cvarg{blockSize}{Size of the averaging block for computing derivative covariation matrix over each pixel neighborhood, see \cross{cornerEigenValsAndVecs}}
-\cvarg{useHarrisDetector}{Indicates, whether to use \href{cornerHarris}{Harris} operator or \cross{cornerMinEigenVal}}
+\cvarg{useHarrisDetector}{Indicates, whether to use \hyperref[cornerHarris]{Harris} operator or \cross{cornerMinEigenVal}}
\cvarg{k}{Free parameter of Harris detector}
\end{description}
\begin{description}
\cvarg{image}{The 8-bit, single-channel, grayscale input image}
\cvarg{circles}{The output vector of found circles. Each vector is encoded as 3-element floating-point vector $(x, y, radius)$}
-\cvarg{method}{Currently, the only implemented method is \texttt{CV\_HOUGH\_GRADIENT}, which is basically \emph{21HT}, described in \cite{Yuen03}.}
+\cvarg{method}{Currently, the only implemented method is \texttt{CV\_HOUGH\_GRADIENT}, which is basically \emph{21HT}, described in \cite{Yuen90}.}
\cvarg{dp}{The inverse ratio of the accumulator resolution to the image resolution. For example, if \texttt{dp=1}, the accumulator will have the same resolution as the input image, if \texttt{dp=2} - accumulator will have half as big width and height, etc}
\cvarg{minDist}{Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed}
\cvarg{param1}{The first method-specific parameter. in the case of \texttt{CV\_HOUGH\_GRADIENT} it is the higher threshold of the two passed to \cross{Canny} edge detector (the lower one will be twice smaller)}
\cvarg{lines}{The output vector of lines. Each line is represented by a two-element vector $(\rho, \theta)$. $\rho$ is the distance from the coordinate origin $(0,0)$ (top-left corner of the image) and $\theta$ is the line rotation angle in radians (0 $\sim$ vertical line, $\pi/2 \sim$ horizontal line)}
\cvarg{rho}{Distance resolution of the accumulator in pixels}
\cvarg{theta}{Angle resolution of the accumulator in radians}
-\cvarg{threshold}{The accumulator threshold parameter. Only those lines are returned that get enough votes (>\texttt{threshold})}
+\cvarg{threshold}{The accumulator threshold parameter. Only those lines are returned that get enough votes ($>\texttt{threshold}$)}
\cvarg{srn}{For the multi-scale Hough transform it is the divisor for the distance resolution \texttt{rho}. The coarse accumulator distance resolution will be \texttt{rho} and the accurate accumulator resolution will be \texttt{rho/srn}. If both \texttt{srn=0} and \texttt{stn=0} then the classical Hough transform is used, otherwise both these parameters should be positive.}
\cvarg{stn}{For the multi-scale Hough transform it is the divisor for the distance resolution \texttt{theta}}
\end{description}
\cvarg{lines}{The output vector of lines. Each line is represented by a 4-element vector $(x_1, y_1, x_2, y_2)$, where $(x_1,y_1)$ and $(x_2, y_2)$ are the ending points of each line segment detected.}
\cvarg{rho}{Distance resolution of the accumulator in pixels}
\cvarg{theta}{Angle resolution of the accumulator in radians}
-\cvarg{threshold}{The accumulator threshold parameter. Only those lines are returned that get enough votes (>\texttt{threshold})}
+\cvarg{threshold}{The accumulator threshold parameter. Only those lines are returned that get enough votes ($>\texttt{threshold}$)}
\cvarg{minLineLength}{The minimum line length. Line segments shorter than that will be rejected}
\cvarg{maxLineGap}{The maximum allowed gap between points on the same line to link them.}
\end{description}
-The function \texttt{HoughLinesP} implements probabilistic Hough transform algorithm for line detection, described in \cite[Matas98]. Below is line detection example:
+The function \texttt{HoughLinesP} implements probabilistic Hough transform algorithm for line detection, described in \cite{Matas00}. Below is line detection example:
\begin{lstlisting}
/* This is a standalone program. Pass an image name as a first parameter
\texttt{dst} = (D_x \texttt{src})^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src})^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src}
\]
-where $D_x$, $D_y$ are the first image derivatives, $D_xx$, $D_yy$ are the second image derivatives and $D_xy$ is the mixed derivative.
+where $D_x$, $D_y$ are the first image derivatives, $D_{xx}$, $D_{yy}$ are the second image derivatives and $D_{xy}$ is the mixed derivative.
The corners can be found as local maximums of the functions, as shown below:
\cvfunc{KeyPoint}\label{KeyPoint}
-Data structure for interest point detectors
+Data structure for salient point detectors
\begin{lstlisting}
class KeyPoint
};
\end{lstlisting}
-The class \texttt{SURF} implements Speeded Up Robust Features descriptor described \cite{Bay06}.
+The class \texttt{SURF} implements Speeded Up Robust Features descriptor \cite{Bay06}.
There is fast multi-scale Hessian keypoint detector that can be used to find the keypoints
(which is the default option), but the descriptors can be also computed for the user-specified keypoints.
The function can be used for object tracking and localization, image stitching etc. See the
\end{lstlisting}
\begin{description}
\cvarg{array}{A raster image (single-channel, 8-bit or floating-point 2D array) or an array
- ($1 \times N$ or $N \times 1$) of 2D points (\href{Point\_}{Point} or \href{Point\_}{Point2f})}
+ ($1 \times N$ or $N \times 1$) of 2D points (\texttt{Point} or \texttt{Point2f})}
\cvarg{binaryImage}{(For images only) If it is true, then all the non-zero image pixels are treated as 1's}
\end{description}
The function \texttt{moments} computes moments, up to the 3rd order, of a vector shape or a rasterized shape.
-In case of a raster image, the spatial moments $\texttt{Moments::m}_ji$ are computed as:
+In case of a raster image, the spatial moments $\texttt{Moments::m}_{ji}$ are computed as:
-\[\texttt{m}_{ji}=\sum_{x,y} (\texttt{array}(x,y) \cdot x^j \cdot y^i),\]
+\[\texttt{m}_{ji}=\sum_{x,y} \left(\texttt{array}(x,y) \cdot x^j \cdot y^i\right),\]
-the central moments $\texttt{Moments::mu}_ji$ are computed as:
-\[\texttt{mu}_{ji}=\sum_{x,y} (\texttt{array}(x,y) \cdot (x - \bar{x})^j \cdot (y - \bar{y})^i)\]
+the central moments $\texttt{Moments::mu}_{ji}$ are computed as:
+\[\texttt{mu}_{ji}=\sum_{x,y} \left(\texttt{array}(x,y) \cdot (x - \bar{x})^j \cdot (y - \bar{y})^i\right)\]
where $(\bar{x}, \bar{y})$ is the mass center:
\[
-\bar{x}=\frac{\texttt{m}_{10}}{\texttt{m}_{00}}, \bar{y}=\frac{\texttt{m}_{01}}{\texttt{m}_{00}}
+\bar{x}=\frac{\texttt{m}_{10}}{\texttt{m}_{00}},\; \bar{y}=\frac{\texttt{m}_{01}}{\texttt{m}_{00}}
\]
-and the normalized central moments $\texttt{Moments::nu}_ij$ are computed as:
+and the normalized central moments $\texttt{Moments::nu}_{ij}$ are computed as:
\[\texttt{nu}_{ji}=\frac{\texttt{mu}_{ji}}{\texttt{m}_{00}^{(i+j)/2+1}}.\]
Note that $\texttt{mu}_{00}=\texttt{m}_{00}$, $\texttt{nu}_{00}=1$ $\texttt{nu}_{10}=\texttt{mu}_{10}=\texttt{mu}_{01}=\texttt{mu}_{10}=0$, hence the values are not stored.
\[ [A^*|b^*] = arg \min_{[A|b]} \sum_i \|\texttt{dstpt}_i - A {\texttt{srcpt}_i}^T - b \|^2 \]
-where $[A|b]$ can be either arbitrary (when \texttt{fullAffine=true}) or have form \texttt{[a11 a12 b1; -a12 a11 b2]} when \texttt{fullAffine=false}.
+where $[A|b]$ can be either arbitrary (when \texttt{fullAffine=true}) or have form
+$\begin{bmatrix}a_{11} & a_{12} & b_1 \\ -a_{12} & a_{11} & b_2 \end{bmatrix}$ when \texttt{fullAffine=false}.
See also: \cross{getAffineTransform}, \cross{getPerspectiveTransform}, \cross{findHomography}
\begin{lstlisting}
int estimateAffine3D(const Mat& srcpt, const Mat& dstpt, Mat& out,
vector<uchar>& outliers,
- double ransacThreshold = 3.0, double confidence = 0.99);
+ double ransacThreshold = 3.0,
+ double confidence = 0.99);
\end{lstlisting}
\begin{description}
\cvarg{srcpt}{The first input 3D point set}
Finds the convex hull of a point set.
\begin{lstlisting}
-void convexHull( const Mat& points, vector<int>& hull, bool clockwise=false );
-void convexHull( const Mat& points, vector<Point>& hull, bool clockwise=false );
-void convexHull( const Mat& points, vector<Point2f>& hull, bool clockwise=false );
+void convexHull( const Mat& points, vector<int>& hull,
+ bool clockwise=false );
+void convexHull( const Mat& points, vector<Point>& hull,
+ bool clockwise=false );
+void convexHull( const Mat& points, vector<Point2f>& hull,
+ bool clockwise=false );
\end{lstlisting}
\begin{description}
\cvarg{points}{The input 2D point set, represented by \texttt{CV\_32SC2} or \texttt{CV\_32FC2} matrix or by
\cvarg{RANSAC}{RANSAC-based robust method}
\cvarg{LMEDS}{Least-Median robust method}
\end{description}}
-\cvarg{ransacReprojThreshold}{The maximum allowed reprojection error to treat a point pair as an inlier (used in the RANSAC method only). That is, if $\|\texttt{dstPoints}_i - \texttt{convertPointHomogeneous}(\texttt{H} \texttt{srcPoints}_i)\| > \texttt{ransacReprojThreshold}$ then the point $i$ is considered an outlier. If \texttt{srcPoints} and \texttt{dstPoints} are measured in pixels, it usually makes sense to set this parameter somewhere in the range 1 to 10. }
+\cvarg{ransacReprojThreshold}{The maximum allowed reprojection error to treat a point pair as an inlier (used in the RANSAC method only). That is, if
+\[\|\texttt{dstPoints}_i - \texttt{convertPointHomogeneous}(\texttt{H} \texttt{srcPoints}_i)\| > \texttt{ransacReprojThreshold}\]
+then the point $i$ is considered an outlier. If \texttt{srcPoints} and \texttt{dstPoints} are measured in pixels, it usually makes sense to set this parameter somewhere in the range 1 to 10. }
\cvarg{mask}{The optional output mask 8-bit single-channel matrix or a vector; will have as many elements as \texttt{srcPoints}. \texttt{mask[i]} is set to 0 if the point $i$ is outlier and 0 otherwise}
\end{description}
s_i \vecthree{x'_i}{y'_i}{1} \sim H \vecthree{x_i}{y_i}{1}
\]
-So that the back-projection error is minimized:
+So that the back-projection error
\[
\sum_i
\left( y'_i-\frac{h_{21} x_i + h_{22} y_i + h_{23}}{h_{31} x_i + h_{32} y_i + h_{33}} \right)^2
\]
-If the parameter method is set to the default value 0, the function
+is minimized. If the parameter method is set to the default value 0, the function
uses all the point pairs and estimates the best suitable homography
matrix. However, if not all of the point pairs ($src\_points_i$,
$dst\_points_i$) fit the rigid perspective transformation (i.e. there
\cvarg{object1}{The first contour or grayscale image}
\cvarg{object2}{The second contour or grayscale image}
\cvarg{method}{Comparison method:
- \texttt{CV\_CONTOUR\_MATCH\_I1},
- \texttt{CV\_CONTOURS\_MATCH\_I2}
+ \texttt{CV\_CONTOUR\_MATCH\_I1},\\
+ \texttt{CV\_CONTOURS\_MATCH\_I2}\\
or
\texttt{CV\_CONTOURS\_MATCH\_I3} (see the discussion below)}
\cvarg{parameter}{Method-specific parameter (is not used now)}
\[
\begin{array}{l}
-m^A_i = sign(h^A_i) \cdot \log{h^A_i}
-m^B_i = sign(h^B_i) \cdot \log{h^B_i}
+m^A_i = \mathrm{sign}(h^A_i) \cdot \log{h^A_i} \\
+m^B_i = \mathrm{sign}(h^B_i) \cdot \log{h^B_i}
\end{array}
\]
bool read(const FileNode& node);
// detects objects of different sizes in the input image.
// the detected objects are returned as a list of rectangles.
- // scaleFactor specifies how much the image size is reduced at each image scale.
+ // scaleFactor specifies how much the image size
+ // is reduced at each image scale.
// minNeighbors speficifes how many neighbors should
// each candiate rectangle have to retain it.
// flags - ignored
- // minSize - the minimum possible object size. Objects smaller than that are ignored.
+ // minSize - the minimum possible object size.
+ // Objects smaller than that are ignored.
void detectMultiScale( const Mat& image,
vector<Rect>& objects,
double scaleFactor=1.1,
int minNeighbors=3, int flags=0,
Size minSize=Size());
- // sets the image for detection (called by detectMultiScale at each image level)
+ // sets the image for detection
+ // (called by detectMultiScale at each image level)
bool setImage( Ptr<FeatureEvaluator>& feval, const Mat& image );
// runs the detector at the specified point
// (the image that the detector is working with should be set
Groups the object candidate rectangles
\begin{lstlisting}
-void groupRectangles(vector<Rect>& rectList, int groupThreshold, double eps=0.2);
+void groupRectangles(vector<Rect>& rectList,
+ int groupThreshold, double eps=0.2);
\end{lstlisting}
\begin{description}
\cvarg{rectList}{The input/output vector of rectangles. On output there will be retained and grouped rectangles}
Compares a template against overlapped image regions.
\begin{lstlisting}
-void matchTemplate( const Mat& image, const Mat& templ, Mat& result, int method );
+void matchTemplate( const Mat& image, const Mat& templ,
+ Mat& result, int method );
enum { TM_SQDIFF=CV_TM_SQDIFF, TM_SQDIFF_NORMED=CV_TM_SQDIFF_NORMED,
TM_CCORR=CV_TM_CCORR, TM_CCORR_NORMED=CV_TM_CCORR_NORMED,
using a perspective transformation.
\[
-s \quad m' = A [R|t] M'
+s \; m' = A [R|t] M'
\]
or
\vecthree{x}{y}{z} = R \vecthree{X}{Y}{Z} + t\\
x' = x/z\\
y' = y/z\\
-u = fx*x' + cx\\
-v = fy*y' + cy
+u = f_x*x' + c_x\\
+v = f_y*y' + c_y
\end{array}
\]
x'' = x' (1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + 2 p_1 x' y' + p_2(r^2 + 2 x'^2) \\
y'' = y' (1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + p_1 (r^2 + 2 y'^2) + 2 p_2 x' y' \\
\text{where} \quad r^2 = x'^2 + y'^2 \\
-u = fx*x'' + cx\\
-v = fy*y'' + cy
+u = f_x*x'' + c_x\\
+v = f_y*y'' + c_y
\end{array}
\]
$k_1$, $k_2$, $k_3$ are radial distortion coefficients, $p_1$, $p_2$ are tangential distortion coefficients.
Higher-order coefficients are not considered in OpenCV.
-The distortion coefficients also do not depend on the scene viewed, thus they are intrinsic camera parameters.
+The distortion coefficients do not depend on the scene viewed, thus they also belong to the intrinsic camera parameters.
\emph{And they remain the same regardless of the captured image resolution.}
That is, if, for example, a camera has been calibrated on images of $320
\times 240$ resolution, absolutely the same distortion coefficients can
-be used for images of $640 \times 480$ resolution from the same camera (while $fx$,
-$fy$, $cx$ and $cy$ need to be scaled appropriately).
+be used for images of $640 \times 480$ resolution from the same camera (while $f_x$,
+$f_y$, $c_x$ and $c_y$ need to be scaled appropriately).
The functions below use the above model to
Note: if you're using a non-square (=non-NxN) grid and
\cross{findChessboardCorners} for calibration, and \texttt{calibrateCamera} returns
bad values (i.e. zero distortion coefficients, an image center very far from
-(w/2-0.5,h/2-0.5), and / or large differences between $fx$ and $fy$ (ratios of
+$(w/2-0.5,h/2-0.5)$, and / or large differences between $f_x$ and $f_y$ (ratios of
10:1 or more)), then you've probaby used \texttt{patternSize=cvSize(rows,cols)},
but should use \texttt{patternSize=cvSize(cols,rows)} in \cross{findChessboardCorners}.
\cvarg{fovy}{The output field of view in degrees along the vertical sensor axis}
\cvarg{focalLength}{The focal length of the lens in mm}
\cvarg{prinicialPoint}{The principal point in pixels}
-\cvarg{aspectRatio}{\texttt{fy}/texttt{fx}}
+\cvarg{aspectRatio}{$f_y/f_x$}
\end{description}
The function computes various useful camera characteristics from the previously estimated camera matrix.
The functions compute:
\[ \begin{array}{l}
-\texttt{rvec3} = \texttt{Rodrigues}^{(M \rightarrow V)}
- (\texttt{Rodrigues}^{(V \rightarrow M)}{\texttt{rvec2}} \texttt{Rodrigues}^{(V \rightarrow M)}{\texttt{rvec1}}) \\
-\texttt{tvec3} = (\texttt{Rodrigues}^{(V \rightarrow M)}{\texttt{rvec2}} \texttt{tvec1} + \texttt{tvec2})
-\end{array} \]
+\texttt{rvec3} = \mathrm{rodrigues}^{-1}\left(\mathrm{rodrigues}(\texttt{rvec2}) \cdot
+\mathrm{rodrigues}(\texttt{rvec1})\right) \\
+\texttt{tvec3} = \mathrm{rodrigues}(\texttt{rvec2}) \cdot \texttt{tvec1} + \texttt{tvec2}
+\end{array}, \]
+
+where $\mathrm{rodrigues}$ denotes a rotation vector to rotation matrix transformation, and $\mathrm{rodrigues}^{-1}$ denotes the inverse transformation, see \cross{Rodrigues}.
-and, optionally, the derivatives of the output vectors w.r.t the input vectors (see \cross{matMulDeriv}).
+Also, the functions can compute the derivatives of the output vectors w.r.t the input vectors (see \cross{matMulDeriv}).
The functions are used inside \cross{stereoCalibrate} but can also be used in your own code where Levenberg-Marquardt or another gradient-based solver is used to optimize a function that contains matrix multiplication.
\end{array}
\]
-Inverse transformation can also be done easily as
+Inverse transformation can also be done easily, since
\[
\sin(\theta)
The function transforms 1-channel disparity map to 3-channel image representing a 3D surface. That is, for each pixel \texttt{(x,y)} and the corresponding disparity \texttt{d=disparity(x,y)} it computes:
\[\begin{array}{l}
-[X Y Z W]^T = \texttt{Q}*[x y \texttt{disparity}(x,y) 1]^T \\
-\texttt{\_3dImage}(x,y) = (X/W, Y/W, Z/W)
+[X\; Y\; Z\; W]^T = \texttt{Q}*[x\; y\; \texttt{disparity}(x,y)\; 1]^T \\
+\texttt{\_3dImage}(x,y) = (X/W,\; Y/W,\; Z/W)
\end{array}\]
The matrix \texttt{Q} can be arbitrary $4 \times 4$ matrix, e.g. the one computed by \cross{stereoRectify}. To reproject a sparse set of points {(x,y,d),...} to 3D space, use \cross{perspectiveTransform}.
where $T_i$ are components of the translation vector $T:\,T=[T_0, T_1, T_2]^T$,
and the fundamental matrix \texttt{F}:
-\[F = cameraMatrix2^{-T} E cameraMatrix1^{-1}\]
+\[F = cameraMatrix2^{-T} \cdot E \cdot cameraMatrix1^{-1}\]
Besides the stereo-related information, the function can also perform full calibration of each of the 2 cameras. However, because of the high dimensionality of the parameter space and noise in the input data the function can diverge from the correct solution. Thus, if the intrinsic parameters can be estimated with high accuracy for each of the cameras individually (e.g. using \cross{calibrateCamera}), it is recommended to do so and then pass \texttt{CALIB\_FIX\_INTRINSIC} flag to the function along with the computed intrinsic parameters. Otherwise, if all the parameters are needed to be estimated at once, it makes sense to restrict some parameters, e.g. pass \texttt{CALIB\_SAME\_FOCAL\_LENGTH} and \texttt{CALIB\_ZERO\_TANGENT\_DIST} flags, which are usually reasonable assumptions.
int flags=CALIB_ZERO_DISPARITY );
\end{lstlisting}
\begin{description}
-\cvarg{cameraMatrix1, cameraMatrix2}{The camera matrices [$f_x^{(j)}$ 0 $c_x^{(j)}$; 0 $f_y^{(j)}$ $c_y^{(j)}$; 0 0 1].}
-\cvarg{distCoeffs1, distCoeffs2}{The vectors of distortion coefficients for each camera, \href{\#Pinhole Camera Model, Distortion}{4x1, 1x4, 5x1 or 1x5.}}
+\cvarg{cameraMatrix1, cameraMatrix2}{The camera matrices $\vecthreethree{f_x^{(j)}}{0}{c_x^{(j)}}{0}{f_y^{(j)}}{c_y^{(j)}}{0}{0}{1}$}
+\cvarg{distCoeffs1, distCoeffs2}{The vectors of distortion coefficients for each camera, \cross{4x1, 1x4, 5x1 or 1x5}}
\cvarg{imageSize}{Size of the image used for stereo calibration.}
\cvarg{R}{The input rotation matrix between the 1st and the 2nd cameras' coordinate systems; can be computed with \cross{stereoCalibrate}.}
\cvarg{T}{The translation vector between the cameras' coordinate systems; can be computed with \cross{stereoCalibrate}.}
\cvarg{threshold}{Optional threshold used to filter out the outliers. If the parameter is greater than zero, then all the point pairs that do not comply the epipolar geometry well enough (that is, the points for which $|\texttt{points2[i]}^T*\texttt{F}*\texttt{points1[i]}|>\texttt{threshold}$) are rejected prior to computing the homographies.}
\end{description}
-The function \texttt{stereoRectifyUncalibrated} computes the rectification transformations without knowing intrinsic parameters of the cameras and their relative position in space, hence the suffix "Uncalibrated". Another related difference from \cross{stereoRectify} is that the function outputs not the rectification transformations in the object (3D) space, but the planar perspective transformations, encoded by the homography matrices \texttt{H1} and \texttt{H2}. The function implements the following algorithm \href{\#Hartly99}{[Hartley99]}.
+The function \texttt{stereoRectifyUncalibrated} computes the rectification transformations without knowing intrinsic parameters of the cameras and their relative position in space, hence the suffix "Uncalibrated". Another related difference from \cross{stereoRectify} is that the function outputs not the rectification transformations in the object (3D) space, but the planar perspective transformations, encoded by the homography matrices \texttt{H1} and \texttt{H2}. The function implements the algorithm \cite{Hartley99}.
Note that while the algorithm does not need to know the intrinsic parameters of the cameras, it heavily depends on the epipolar geometry. Therefore, if the camera lenses have significant distortion, it would better be corrected before computing the fundamental matrix and calling this function. For example, distortion coefficients can be estimated for each head of stereo camera separately by using \cross{calibrateCamera} and then the images can be corrected using \cross{undistort}, or just the point coordinates can be corrected with \cross{undistortPoints}.
\begin{description}
\cvarg{src}{The observed point coordinates, a matrix or vector of 2D points.}
\cvarg{dst}{The ideal point coordinates, after undistortion and reverse perspective transformation}
-\cvarg{cameraMatrix}{The camera matrix $[f_x 0 c_x; 0 f_y c_y; 0 0 1]$}
+\cvarg{cameraMatrix}{The camera matrix $\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}$}
\cvarg{distCoeffs}{he vector of distortion coefficients, \cross{4x1, 1x4, 5x1 or 1x5}}
\cvarg{R}{The rectification transformation in object space (3x3 matrix). \texttt{R1} or \texttt{R2}, computed by \cross{StereoRectify} can be passed here. If the matrix is empty, the identity transformation is used}
\cvarg{P}{The new camera matrix (3x3) or the new projection matrix (3x4). \texttt{P1} or \texttt{P2}, computed by \cross{StereoRectify} can be passed here. If the matrix is empty, the identity new camera matrix is used}
\subsection{Introduction}
Starting from OpenCV 2.0 the new modern C++ interface has been introduced.
-It is crisp (less typing is needed to code the same thing), type-safe (no more CvArr $\sim$ void*)
-and in general more convenient to use. Here is a short sample of what it looks like:
+It is crisp (less typing is needed to code the same thing), type-safe (no more \texttt{CvArr*} a.k.a. \texttt{void*})
+and, in general, more convenient to use. Here is a short example of what it looks like:
\begin{lstlisting}
//
planes[2] = Mat_<uchar>(planes[2]*color_scale + 128*(1-color_scale));
// Mat::mul replaces cvMul(). Again, no temporary arrays are
- // created in case of simple expressions.
+ // created in the case of simple expressions.
planes[0] = planes[0].mul(planes[0], 1./255);
// now merge the results back
namedWindow("image with grain", CV_WINDOW_AUTOSIZE);
#if DEMO_MIXED_API_USE
// this is to demonstrate that img and iplimg really share the data -
- // the result of the above processing is stored in img and thus in iplimg too.
+ // the result of the above processing is stored to img and thus in iplimg too.
cvShowImage("image with grain", iplimg);
#else
imshow("image with grain", img);
a /= std::log(2.);
\end{lstlisting}
-For most used C functions and structures from OpenCV 1.x you may find the direct counterparts in the new C++ interface. The name is usually formed by omitting \texttt{cv} or \texttt{Cv} prefix and turning the first letter to the low case (unless it's a own name, like Canny, Sobel etc). In case when there is no the new-style counterpart, it's possible to use the old functions with the new structures, as shown the first sample in the chapter.
+For the most of the C functions and structures from OpenCV 1.x you may find the direct counterparts in the new C++ interface. The name is usually formed by omitting \texttt{cv} or \texttt{Cv} prefix and turning the first letter to the low case (unless it's a own name, like Canny, Sobel etc). In case when there is no the new-style counterpart, it's possible to use the old functions with the new structures, as shown the first sample in the chapter.
\subsection{Memory Management}
-The new interface does most of memory deallocation or even memory allocation operations automatically when needed.
+When using the new interface, the most of memory deallocation and even memory allocation operations are done automatically when needed.
First of all, \cross{Mat}, \cross{SparseMat} and other classes have destructors
that deallocate memory buffers occupied by the structures when needed.
Secondly, this "when needed" means that the destructors do not always deallocate the buffers, they take into account possible data sharing.
That is, in a destructor the reference counter associated with the underlying data is decremented and the data is deallocated
-if and only if the reference counter reaches zero, that is, when no other structures use the same buffers. When such a structure
-containing a reference counter is copied, usually just the header is duplicated and the underlying data is not; instead, the reference counter is incremented to memorize that there is another owner of the same data.
-Also, some structures, such as \texttt{Mat}, can use pre-allocated data rather than data allocated by the structures' methods.
+if and only if the reference counter becomes zero, that is, when no other structures refer to the same buffer. When such a structure
+containing a reference counter is copied, usually just the header is duplicated, while the underlying data is not; instead, the reference counter is incremented to memorize that there is another owner of the same data.
+Also, some structures, such as \texttt{Mat}, can refer to the user-allocated data.
In this case the reference counter is \texttt{NULL} pointer and then no reference counting is done - the data is not deallocated by the destructors and should be deallocated manually by the user. We saw this scheme in the first example in the chapter:
\begin{lstlisting}
// allocates IplImages and wraps it into shared pointer class.
// of NULL pointer to the reference counter.
//
// Then Ptr<IplImage> destructor is called that decrements
-// the reference counter and if it reached 0, calls cvReleaseImage().
+// the reference counter and, as the counter becomes 0 in this case,
+// the destructor calls cvReleaseImage().
\end{lstlisting}
-The copying semantics was mentioned in the above paragraph, but deserves a dedicated explanation.
-By default, the new OpenCV structures implement cheap, so called O(1) (i.e. constant-time) assignment operations. It gives user possibility to pass quite big data structures to functions (though, \texttt{const Mat\&} is even faster), return them (e.g. see the example with \cross{findHomography} above) and store in OpenCV and STL containers, and do all of this very efficiently. On the other hand, most of the new data structures provide clone()
-method that creates a full copy of an object. Here is the sample:
+The copying semantics was mentioned in the above paragraph, but deserves a dedicated discussion.
+By default, the new OpenCV structures implement shallow, so called O(1) (i.e. constant-time) assignment operations. It gives user possibility to pass quite big data structures to functions (though, e.g. passing \texttt{const Mat\&} is still faster than passing \texttt{Mat}), return them (e.g. see the example with \cross{findHomography} above), store them in OpenCV and STL containers etc. - and do all of this very efficiently. On the other hand, most of the new data structures provide \texttt{clone()} method that creates a full copy of an object. Here is the sample:
\begin{lstlisting}
// create a big 8Mb matrix
Mat A(1000, 1000, CV_64F);
A = D;
// now make B an empty matrix (which references no memory buffers),
// but the modified version of A will still be referenced by C,
-// despite that C is just a single matrix row
+// despite that C is just a single row of the original A
B.release();
-// finally, make a full copy of C and deallocate the modified
-// big matrix, since it's not referenced by anyone
+// finally, make a full copy of C. In result, the big modified
+// matrix will be deallocated, since it's not referenced by anyone
C = C.clone();
\end{lstlisting}
Memory management of the new data structures is automatic and thus easy. If, however, your code uses \cross{IplImage},
\cross{CvMat} or other C data structures a lot, memory management can still be automated without immediate migration
to \cross{Mat} by using the already mentioned template class \cross{Ptr}, similar to \texttt{shared\_ptr} from Boost and C++ TR1.
-It warps a pointer to an arbitrary object, provides transparent access to all the object fields and associates a reference counter with it.
-Instance of the class can be passed to any function that expects the original pointer. For correct deallocation of the object, you should specialize \texttt{Ptr<T>::delete\_obj()} method, like it was done for classic OpenCV datatypes:
+It wraps a pointer to an arbitrary object, provides transparent access to all the object fields and associates a reference counter with it.
+Instance of the class can be passed to any function that expects the original pointer. For correct deallocation of the object, you should specialize \texttt{Ptr<T>::delete\_obj()} method. Such specialized methods already exist for the classical OpenCV structures, e.g.:
\begin{lstlisting}
// cxoperations.hpp:
...
See \cross{Ptr} description for more details and other usage scenarios.
-\subsection{Memory Management Part II. Automatic Data Allocation}\label{AutomaticMemoryManagement}
+\subsection{Memory Management Part II. Automatic Data Allocation}\label{AutomaticMemoryManagement2}
With the new interface not only explicit memory deallocation is not needed anymore,
but the memory allocation is often done automatically too. That was demonstrated in the example
If a new buffer is needed, the previously allocated buffer is released
(by engaging all the reference counting mechanism described in the previous section).
Now, since it is very quick to check whether the needed memory buffer is already allocated,
-most new OpenCV functions that have output arrays call the \texttt{create} method and
-this way the Automatic Data Allocation concept is implemented. Here is the example:
+most new OpenCV functions that have arrays as output parameters call the \texttt{create} method and
+this way the \emph{automatic data allocation} concept is implemented. Here is the example:
\begin{lstlisting}
#include "cv.h"
#include "highgui.h"
the same buffer will be reused for every next frame's edge map.
In many cases the output array type and size can be inferenced from the input arrays' respective characteristics, but not always.
-In these rare cases functions take separate input parameters that specify the data type and/or size of the output arrays,
+In these rare cases the corresponding functions take separate input parameters that specify the data type and/or size of the output arrays,
like \cross{resize}. Anyway, a vast majority of the new-style array processing functions call \texttt{create}
for each of the output array, with just a few exceptions like \texttt{mixChannels}, \texttt{RNG::fill} and some others.
\subsection{Algebraic Operations}
-Just like in v1.x, OpenCV 2.x provides basic functions operating on matrices, like \texttt{add},
-\texttt{subtract}, \texttt{gemm} etc. In addition, it introduces overloaded operators that give user convenient
-algebraic notation and nearly as fast as the functions. For example, here is how the least squares problem $Ax=b$
+Just like in v1.x, OpenCV 2.x provides some basic functions operating on matrices, like \texttt{add},
+\texttt{subtract}, \texttt{gemm} etc. In addition, it introduces overloaded operators that give the user a convenient
+algebraic notation, which is nearly as fast as using the functions directly. For example, here is how the least squares problem $Ax=b$
can be solved using normal equations:
\begin{lstlisting}
Mat x = (A.t()*A).inv()*(A.t()*b);
\subsection{Fast Element Access}
Historically, OpenCV provided many different ways to access image and matrix elements, and none of them was both fast and convenient.
-With the new data structures, OpenCV 2.x introduces a few more alternatives, hopefully more convenient than before. For detailed description of the operations, please, check \cross{Mat} and \href{#MatT}{Mat\_} description. Here is part of the retro-photo-styling example rewritten (in simplified form) using the element access operations:
+With the new data structures, OpenCV 2.x introduces a few more alternatives, hopefully more convenient than before. For detailed description of the operations, please, check \cross{Mat} and \hyperref[MatT]{Mat\_} description. Here is part of the retro-photo-styling example rewritten (in simplified form) using the element access operations:
\begin{lstlisting}
...
\subsection{Saturation Arithmetics}
-In the above sample you may have noticed \href{saturate}{saturate\_cast<>()} operator, and that's how all the pixel processing is done in OpenCV. When a result of image operation is 8-bit image with pixel values ranging from 0 to 255, each output pixel value is clipped to this available range:
+In the above sample you may have noticed \hyperref[saturatecast]{saturate\_cast} operator, and that's how all the pixel processing is done in OpenCV. When a result of image operation is 8-bit image with pixel values ranging from 0 to 255, each output pixel value is clipped to this available range:
\[
I(x,y)=\min(\max(value, 0), 255)
\]
-and the similar rules are applied to 8-bit signed and 16-bit signed and unsigned types. This "saturation" semantics (different from usual C language "wrapping" semantics, where lowest bits are taken) is implemented in every image processing function, from the simple \texttt{cv::add} and \texttt{cvAdd} to \texttt{cv::cvtColor}, \texttt{cv::resize}, \texttt{cv::filter2D} etc.
-It is not a new feature of OpenCV v2.x, it was there from very beginning. In the new version this special \href{saturate}{saturate\_cast<T>()} template operator is introduced to simplify implementation of this semantic in your own functions.
+and the similar rules are applied to 8-bit signed and 16-bit signed and unsigned types. This "saturation" semantics (different from usual C language "wrapping" semantics, where lowest bits are taken, is implemented in every image processing function, from the simple \texttt{cv::add} to \texttt{cv::cvtColor}, \texttt{cv::resize}, \texttt{cv::filter2D} etc.
+It is not a new feature of OpenCV v2.x, it was there from very beginning. In the new version this special \hyperref[saturatecast]{saturate\_cast} template operator is introduced to simplify implementation of this semantic in your own functions.
\subsection{Error handling}
\subsection{Threading and Reenterability}
-OpenCV uses OpenMP to do thread some time-consuming operations. Threading can be explicitly controlled by \cross{setNumThreads} function. Also, functions and "const" methods of the classes are generally re-enterable, that is, they can be called from different threads asynchronously.
+OpenCV uses OpenMP to run some time-consuming operations in parallel. Threading can be explicitly controlled by \cross{setNumThreads} function. Also, functions and "const" methods of the classes are generally re-enterable, that is, they can be called from different threads asynchronously.
\subsection{Basic Structures}
// it is int for uchar, signed char, unsigned short, signed short and int,
// float for float, double for double, ...
typedef <...> work_type;
- // in case of multi-channel data it is the data type of each channel
+ // in the case of multi-channel data it is the data type of each channel
typedef <...> channel_type;
enum
{
};
\end{lstlisting}
-The template class \texttt{DataType} is descriptive class for OpenCV primitive data types and other types that comply with the following definition. A primitive OpenCV data type is one of \texttt{unsigned char, bool ($\sim$unsigned char), signed char, unsigned short, signed short, int, float, double} or a tuple of values of one of these types, where all the values in the tuple have the same type. If you are familiar with OpenCV \cross{CvMat}'s type notation, CV\_8U ... CV\_32FC3, CV\_64FC2 etc., when a primitive type can be defined as a type for which you can give a unique identifier in a form \verb*"CV\_<bit-depth>{U|S|F}C<number_of_channels>". A universal type able to store a single instance of such primitive data type is \cross{Vec}. Multiple instances of such a type can be stored in a \texttt{std::vector}, \texttt{Mat}, \texttt{Mat\_}, \texttt{MatND}, \texttt{MatND\_}, \texttt{SparseMat}, \texttt{SparseMat\_} or any other container that is able to store \cross{Vec} instances.
+The template class \texttt{DataType} is descriptive class for OpenCV primitive data types and other types that comply with the following definition. A primitive OpenCV data type is one of \texttt{unsigned char, bool ($\sim$unsigned char), signed char, unsigned short, signed short, int, float, double} or a tuple of values of one of these types, where all the values in the tuple have the same type. If you are familiar with OpenCV \cross{CvMat}'s type notation, CV\_8U ... CV\_32FC3, CV\_64FC2 etc., then a primitive type can be defined as a type for which you can give a unique identifier in a form \verb*"CV\_<bit-depth>{U|S|F}C<number_of_channels>". A universal OpenCV structure able to store a single instance of such primitive data type is \cross{Vec}. Multiple instances of such a type can be stored to a \texttt{std::vector}, \texttt{Mat}, \texttt{Mat\_}, \texttt{MatND}, \texttt{MatND\_}, \texttt{SparseMat}, \texttt{SparseMat\_} or any other container that is able to store \cross{Vec} instances.
-The class \texttt{DataType} is basically used to provide some description of any data type without adding any fields or methods to the corresponding class (and it is actually impossible to add anything to primitive C/C++ data types). This technique is known in C++ as class traits. It's not \texttt{DataType} itself that is used, but its specialized versions, such as:
+The class \texttt{DataType} is basically used to provide some description of such primitive data types without adding any fields or methods to the corresponding classes (and it is actually impossible to add anything to primitive C/C++ data types). This technique is known in C++ as class traits. It's not \texttt{DataType} itself that is used, but its specialized versions, such as:
\begin{lstlisting}
template<> class DataType<uchar>
...
\end{lstlisting}
-The main purpose of the classes is to convert compile time type information to OpenCV-compatible data type identifier, for example:
+The main purpose of the classes is to convert compile-time type information to OpenCV-compatible data type identifier, for example:
\begin{lstlisting}
// allocates 30x40 floating-point matrix
cout << B.depth() << ", " << B.channels() << endl;
\end{lstlisting}
-that is, such traits are used to tell OpenCV which data type you are working with, even if such a type is not native. Also, this mechanism is useful for generic algorithm implementation (in particular, it is used this way internally in OpenCV).
+that is, such traits are used to tell OpenCV which data type you are working with, even if such a type is not native to OpenCV (the matrix \texttt{B} intialization above compiles because OpenCV defines the proper specialized template class \texttt{DataType<complex<\_Tp> >}). Also, this mechanism is useful (and used in OpenCV this way) for generic algorithms implementations.
\cvfunc{Point\_}
Template class for 2D points
\end{lstlisting}
The class represents a 2D point, specified by its coordinates $x$ and $y$.
-Instance of the class is interchangeable with С structures \texttt{CvPoint} and \texttt{CvPoint2D32f}. There is also cast operator to convert point coordinates to the specified type. The conversion from floating-point coordinates to integer coordinates is done by rounding; in general case the conversion uses \href{saturate}{saturate\_cast<>()} operation on each of the coordinates. Besides the class members listed in the declaration above, the following operations on points are implemented:
+Instance of the class is interchangeable with С structures \texttt{CvPoint} and \texttt{CvPoint2D32f}. There is also cast operator to convert point coordinates to the specified type. The conversion from floating-point coordinates to integer coordinates is done by rounding; in general case the conversion uses \hyperref[saturatecast]{saturate\_cast} operation on each of the coordinates. Besides the class members listed in the declaration above, the following operations on points are implemented:
\begin{itemize}
\item \texttt{pt1 = pt2 $\pm$ pt3}
};
\end{lstlisting}
-The rectangle is described by the coordinates of the top-left corner (which is the default interpretation of \texttt{Rect\_::x} and \texttt{Rect\_::y} in OpenCV; though, in your algorithms you may treat \texttt{x} and \texttt{y} as coordinates of the bottom-left corner), the rectangle width and height. Another assumption OpenCV usually makes is that the top and left boundary of the rectangle are inclusive, while the right and bottom boundaries are not, for example, the method \texttt{Rect\_::contains} returns true if
+The rectangle is described by the coordinates of the top-left corner (which is the default interpretation of \texttt{Rect\_::x} and \texttt{Rect\_::y} in OpenCV; though, in your algorithms you may count \texttt{x} and \texttt{y} from the bottom-left corner), the rectangle width and height.
+
+Another assumption OpenCV usually makes is that the top and left boundary of the rectangle are inclusive, while the right and bottom boundaries are not, for example, the method \texttt{Rect\_::contains} returns true if
\begin{eqnarray*}
x \leq pt.x < x+width,\\
y \leq pt.y < y+height
};
\end{lstlisting}
-The class is most universal representation of short numerical vectors or tuples. It is possible to convert \texttt{Vec<T,2>} to/from \texttt{Point\_}, \texttt{Vec<T,3>} to/from \texttt{Point3\_} and \texttt{Vec<T,4>} to \cross{CvScalar}. The elements of \texttt{Vec} are accessed using \texttt{operator[]} and expected vector operations are implemented too:
+The class is the most universal representation of short numerical vectors or tuples. It is possible to convert \texttt{Vec<T,2>} to/from \texttt{Point\_}, \texttt{Vec<T,3>} to/from \texttt{Point3\_}, and \texttt{Vec<T,4>} to \cross{CvScalar}~. The elements of \texttt{Vec} are accessed using \texttt{operator[]}. All the expected vector operations are implemented too:
\begin{itemize}
- \item \texttt{v1 = v2 $\pm$ v3, v1 = v2 * $\alpha$, v1 = $\alpha * v2$} (plus the corresponding augmenting operations; note that these operations apply \href{saturate}{saturate\_cast<\_Tp>()} to the each computed vector component)
+ \item \texttt{v1 = v2 $\pm$ v3, v1 = v2 * $\alpha$, v1 = $\alpha$ * v2} (plus the corresponding augmenting operations; note that these operations apply \hyperref[saturatecast]{saturate\_cast.3C.3E} to the each computed vector component)
\item \texttt{v1 == v2, v1 != v2}
\item \texttt{double n = norm(v1); // $L_2$-norm}
\end{itemize}
typedef Scalar_<double> Scalar;
\end{lstlisting}
-The template class \texttt{Scalar\_} and it's double-precision instantiation \texttt{Scalar} represent 4-element vector. They are absolutely similar to \texttt{Vec<\_Tp, 4>} expect that they can be constructed from \texttt{CvScalar}. \texttt{Scalar} is widely used in OpenCV for passing pixel values and it is a drop-in replacement for \cross{CvScalar} that was used for the same purpose in the earlier versions of OpenCV.
+The template class \texttt{Scalar\_} and it's double-precision instantiation \texttt{Scalar} represent 4-element vector. Being derived from \texttt{Vec<\_Tp, 4>}, they can be used as typical 4-element vectors, but in addition they can be converted to/from \texttt{CvScalar}. The type \texttt{Scalar} is widely used in OpenCV for passing pixel values and it is a drop-in replacement for \cross{CvScalar} that was used for the same purpose in the earlier versions of OpenCV.
\cvfunc{Range}\label{Range}
Specifies a continuous subsequence (a.k.a. slice) of a sequence.
The class is used to specify a row or column span in a matrix (\cross{Mat}), and for many other purposes. \texttt{Range(a,b)} is basically the same as \texttt{a:b} in Matlab or \texttt{a..b} in Python. As in Python, \texttt{start} is inclusive left boundary of the range, and \texttt{end} is exclusive right boundary of the range. Such a half-opened interval is usually denoted as $[start,end)$.
-The static method \texttt{Range::all()} returns some special variable that means "the whole sequence" or "the whole range", just like "\texttt{:}" in Matlab or "\texttt{...}" in Python. All the methods and functions in OpenCV that take \texttt{Range} support this special \texttt{Range::all()} value, but of course, in case of your own custom processing you will probably have to implement it manually:
+The static method \texttt{Range::all()} returns some special variable that means "the whole sequence" or "the whole range", just like "\texttt{:}" in Matlab or "\texttt{...}" in Python. All the methods and functions in OpenCV that take \texttt{Range} support this special \texttt{Range::all()} value, but of course, in the case of your own custom processing you will probably have to check and handle it explicitly:
\begin{lstlisting}
void my_function(..., const Range& r, ....)
{
}
\end{lstlisting}
+\cvfunc{Ptr}\label{Ptr}
+
+A template class for smart reference-counting pointers
+
+\begin{lstlisting}
+template<typename _Tp> class Ptr
+{
+public:
+ // default constructor
+ Ptr();
+ // constructor that wraps the object pointer
+ Ptr(_Tp* _obj);
+ // destructor: calls release()
+ ~Ptr();
+ // copy constructor; increments ptr's reference counter
+ Ptr(const Ptr& ptr);
+ // assignment operator; decrements own reference counter
+ // (with release()) and increments ptr's reference counter
+ Ptr& operator = (const Ptr& ptr);
+ // increments reference counter
+ void addref();
+ // decrements reference counter; when it becomes 0,
+ // delete_obj() is called
+ void release();
+ // user-specified custom object deletion operation.
+ // by default, "delete obj;" is called
+ void delete_obj();
+ // returns true if obj == 0;
+ bool empty() const;
+
+ // provide access to the object fields and methods
+ _Tp* operator -> ();
+ const _Tp* operator -> () const;
+
+ // return the underlying object pointer;
+ // thanks to the methods, the Ptr<_Tp> can be
+ // used instead of _Tp*
+ operator _Tp* ();
+ operator const _Tp*() const;
+protected:
+ // the incapsulated object pointer
+ _Tp* obj;
+ // the associated reference counter
+ int* refcount;
+};
+\end{lstlisting}
+
+The class \texttt{Ptr<\_Tp>} is a template class that wraps pointers of the corresponding type. It is similar to \texttt{shared\_ptr} that is a part of Boost library (\url{http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm}) and also a part of the
+\href{http://en.wikipedia.org/wiki/C%2B%2B0x}{C++0x} standard.
+
+By using this class you can get the following capabilities:
+
+\begin{itemize}
+ \item default constructor, copy constructor and assignment operator for an arbitrary C++ class or a C structure. For some objects, like files, windows, mutexes, sockets etc, copy constructor or assignment operator are difficult to define. For some other objects, like complex classifiers in OpenCV, copy constructors are absent and not easy to implement. Finally, some of complex OpenCV and your own data structures may have been written in C. However, copy constructors and default constructors can simplify programming a lot; besides, they are often required (e.g. by STL containers). By wrapping a pointer to such a complex object \texttt{TObj} to \texttt{Ptr<TObj>} you will automatically get all of the necessary constructors and the assignment operator.
+ \item all the above-mentioned operations running very fast, regardless of the data size, i.e. as "O(1)" operations. Indeed, while some structures, like \texttt{std::vector} provide a copy constructor and an assignment operator, the operations may take considerable time if the data structures are big. But if the structures are put into \texttt{Ptr<>}, the overhead becomes small and independent of the data size.
+ \item automatic destruction, even for C structures. See the example below with \texttt{FILE*}.
+ \item heterogeneous collections of objects. The standard STL and most other C++ and OpenCV containers can only store objects of the same type and the same size. The classical solution to store objects of different types in the same container is to store pointers to the base class \texttt{base\_class\_t*} instead, but when you loose the automatic memory management. Again, by using \texttt{Ptr<base\_class\_t>()} instead of the raw pointers, you can solve the problem.
+\end{itemize}
+
+The class \texttt{Ptr} treats the wrapped object as a black box, the reference counter is allocated and managed separately. The only thing the pointer class needs to know about the object is how to deallocate it. This knowledge is incapsulated in \texttt{Ptr::delete\_obj()} method, which is called when the reference counter becomes 0. If the object is a C++ class instance, no additional coding is needed, because the default implementation of this method calls \texttt{delete obj;}.
+However, if the object is deallocated in a different way, then the specialized method should be created. For example, if you want to wrap \texttt{FILE}, the \texttt{delete\_obj} may be implemented as following:
+
+\begin{lstlisting}
+template<> inline void Ptr<FILE>::delete_obj()
+{
+ fclose(obj); // no need to clear the pointer afterwards,
+ // it is done externally.
+}
+...
+
+// now use it:
+Ptr<FILE> f(fopen("myfile.txt", "r"));
+if(f.empty())
+ throw ...;
+fprintf(f, ....);
+...
+// the file will be closed automatically by the Ptr<FILE> destructor.
+\end{lstlisting}
+
+\textbf{Note}: The reference increment/decrement operations are implemented as atomic operations, and therefore it is normally safe to use the classes in multi-threaded applications. The same is true for \cross{Mat} and other C++ OpenCV classes that operate on the reference counters.
+
\cvfunc{Mat}\label{Mat}
OpenCV C++ matrix class.
There are many different ways to create \texttt{Mat} object. Here are the some popular ones:
\begin{itemize}
\item using \texttt{create(nrows, ncols, type)} method or
- similar \texttt{Mat(nrows, ncols, type[, fill\_value])} constructor.
- A new matrix of the specified size and specifed type is allocated.
+ the similar constructor \texttt{Mat(nrows, ncols, type[, fill\_value])} constructor.
+ A new matrix of the specified size and specifed type will be allocated.
\texttt{type} has the same meaning as in \cross{cvCreateMat} method,
e.g. \texttt{CV\_8UC1} means 8-bit single-channel matrix,
\texttt{CV\_32FC2} means 2-channel (i.e. complex) floating-point matrix etc:
As noted in the introduction of this chapter, \texttt{create()}
will only allocate a new matrix when the current matrix dimensionality
- or type is different from the specified.
+ or type are different from the specified.
\item by using a copy constructor or assignment operator, where on the right side it can
be a matrix or expression, see below. Again, as noted in the introduction,
matrix assignment is O(1) operation because it only copies the header
- and increases the reference counter. \texttt{Mat::clone()} method can be used to get full
+ and increases the reference counter. \texttt{Mat::clone()} method can be used to get a full
(a.k.a. deep) copy of the matrix when you need it.
\item by constructing a header for a part of another matrix. It can be a single row, single column,
several rows, several columns, rectangular region in the matrix (called a minor in algebra) or
- a diagonal. Such operation is also O(1) operation because the new header will reference the same data.
+ a diagonal. Such operations are also O(1), because the new header will reference the same data.
You can actually modify a part of the matrix using this feature, e.g.
\begin{lstlisting}
// add 5-th row, multiplied by 3 to the 3rd row
M.row(3) = M.row(3) + M.row(5)*3;
+// now copy 7-th column to the 1-st column
+// M.col(1) = M.col(7); // this will not work
+Mat M1 = M.col(1);
+M.col(7).copyTo(M1);
+
// create new 320x240 image
cv::Mat img(Size(320,240),CV_8UC3);
// select a roi
Mat C = B(Range(5, 9), Range::all());
Size size; Point ofs;
C.locateROI(size, ofs);
-// size will be (10,10) and ofs will be (/*x=*/1, /*y=*/5)
+// size will be (width=10,height=10) and the ofs will be (x=1, y=5)
\end{lstlisting}
- As in case of whole matrices, if you need a deep copy, use \texttt{clone()} method
+ As in the case of whole matrices, if you need a deep copy, use \texttt{clone()} method
of the extracted sub-matrices.
\item by making a header for user-allocated-data. It can be useful for
\begin{enumerate}
\item processing "foreign" data using OpenCV (e.g. when you implement
- DirectShow filter or gstreamer processing module), e.g.
+ a DirectShow filter or a processing module for gstreamer etc.), e.g.
\begin{lstlisting}
void process_video_frame(const unsigned char* pixels,
int width, int height, int step)
{
cv::Mat img(height, width, CV_8UC3, pixels, step);
- cv::GaussianBlur(img, img, Size(7,7), 1.5, 1.5);
+ cv::GaussianBlur(img, img, cv::Size(7,7), 1.5, 1.5);
}
\end{lstlisting}
\item for quick initialization of small matrices and/or super-fast element access
\begin{lstlisting}
double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
-cv::Mat M(3, 3, CV_64F, m);
-M = M.inv();
+cv::Mat M = cv::Mat(3, 3, CV_64F, m).inv();
\end{lstlisting}
\end{enumerate}
\texttt{Mat::operator CvMat() const} an \texttt{Mat::operator IplImage()}.
The operators do \emph{not} copy the data.
+\begin{lstlisting}
+IplImage* img = cvLoadImage("greatwave.jpg", 1);
+Mat mtx(img); // convert IplImage* -> cv::Mat
+CvMat oldmat = mtx; // convert cv::Mat -> CvMat
+CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
+ oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
+\end{lstlisting}
+
\item by using MATLAB-style matrix initializers, \texttt{zeros(), ones(), eye()}, e.g.:
\begin{lstlisting}
-// create 100x100 double-precision identity martix and add it to M.
-M += Mat::eye(100, 100, CV_64F);
+// create a double-precision identity martix and add it to M.
+M += Mat::eye(M.rows, M.cols, CV_64F);
\end{lstlisting}
\item by using comma-separated initializer:
Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
\end{lstlisting}
-here we first call constructor of \texttt{Mat\_} class (that we describe further) with the proper matrix, and then we just put << operator followed by comma-separated values that can be constants, variables, expressions etc. Also, note the extra parentheses that are needed to avoid compiler errors.
+here we first call constructor of \texttt{Mat\_} class (that we describe further) with the proper matrix, and then we just put \texttt{<<} operator followed by comma-separated values that can be constants, variables, expressions etc. Also, note the extra parentheses that are needed to avoid compiler errors.
\end{itemize}
-Once matrix is created, it will be automatically managed by using reference-counting mechanism (unless the matrix header is built on top of user-allocated data, in which case you should handle the data yourself).
-So the matrix data will be deallocated when no one points to it; if you want to release the data pointed by a matrix header before the matrix destructor is called, the \texttt{Mat::release()} method is the safe way to do it.
+Once matrix is created, it will be automatically managed by using reference-counting mechanism (unless the matrix header is built on top of user-allocated data, in which case you should handle the data by yourself).
+The matrix data will be deallocated when no one points to it; if you want to release the data pointed by a matrix header before the matrix destructor is called, use \texttt{Mat::release()}.
-The next important thing to learn about matrix is element access. Here is how the matrix is stored. The elements are stored in row-major order (row by row). The \texttt{data} member points to the first element of the first row, \texttt{rows} contains the number of matrix rows and \texttt{cols} -- the number of matrix columns. There is yet another member, called \texttt{step} that is used to actually compute address of a matrix element. The \texttt{step} is needed because the matrix can be a part of another matrix or because there can some padding space for proper alignment in the end of each row:
+The next important thing to learn about the matrix class is element access. Here is how the matrix is stored. The elements are stored in row-major order (row by row). The \texttt{Mat::data} member points to the first element of the first row, \texttt{Mat::rows} contains the number of matrix rows and \texttt{Mat::cols} -- the number of matrix columns. There is yet another member, called \texttt{Mat::step} that is used to actually compute address of a matrix element. The \texttt{Mat::step} is needed because the matrix can be a part of another matrix or because there can some padding space in the end of each row for a proper alignment.
%\includegraphics[width=1.0\textwidth]{pics/roi.png}
+
Given these parameters, address of the matrix element $M_{ij}$ is computed as following:
\texttt{addr($M_{ij}$)=M.data + M.step*i + j*M.elemSize()}
-if you know matrix element type, e.g. it is \texttt{float}, then you can use \texttt{at<>()} method:
+if you know the matrix element type, e.g. it is \texttt{float}, then you can use \texttt{at<>()} method:
\texttt{addr($M_{ij}$)=\&M.at<float>(i,j)}
(where \& is used to convert the reference returned by \texttt{at} to a pointer).
-if you need to process a whole row of matrix, much more efficient way is to get the pointer to the row first, and then just use plain C operator []:
+if you need to process a whole row of matrix, the most efficient way is to get the pointer to the row first, and then just use plain C operator \texttt{[]}:
\begin{lstlisting}
// compute sum of positive matrix elements
sum += std::max(Mi[j], 0.);
}
\end{lstlisting}
-In case of continuous matrix the loop body will be executed only once, so the overhead will be smaller, which will be especially noticeable in case of small matrices.
+in the case of continuous matrix the outer loop body will be executed just once, so the overhead will be smaller, which will be especially noticeable in the case of small matrices.
Finally, there are STL-style iterators that are smart enough to skip gaps between successive rows:
\begin{lstlisting}
sum += std::max(*it, 0.);
\end{lstlisting}
-The matrix iterators are random-access iterators, so they can be passed to arbitrary STL algorithm, including \texttt{std::sort()}.
+The matrix iterators are random-access iterators, so they can be passed to any STL algorithm, including \texttt{std::sort()}.
-\cvfunc{Matrix Expressions}
+\cvfunc{Matrix Expressions}\label{Matrix Expressions}
This is a list of implemented matrix operations that can be combined in arbitrary complex expressions
(here \emph{A}, \emph{B} stand for matrices (\texttt{Mat}), \emph{s} for a scalar (\texttt{Scalar}),
\emph{$\alpha$} for a real-valued scalar (\texttt{double})):
\begin{itemize}
- \item addition, subtraction, negation: \texttt{A$\pm$ B, A$\pm$ s, s$\pm$ A, -A}
+ \item addition, subtraction, negation: \texttt{A$\pm$B, A$\pm$s, s$\pm$A, -A}
\item scaling: \texttt{A*$\alpha$, A/$\alpha$}
\item per-element multiplication and division: \texttt{A.mul(B), A/B, $\alpha$/A}
\item matrix multiplication: \texttt{A*B}
\item transposition: \texttt{A.t() $\sim A^t$}
\item matrix inversion and pseudo-inversion, solving linear systems and least-squares problems:
\texttt{A.inv([method]) $\sim A^{-1}$}, \texttt{A.inv([method])*B $\sim X:\,AX=B$}
- \item comparison: \texttt{A$\gtreqqless$ B, A $\ne$ B, A$\gtreqqless \alpha$, A $\ne \alpha$}
- (the result of comparison is 8-bit single channel mask, which elements are set to 255
- (if the particular element or pair of elements satisfy the condition) and 0 otherwise)
+ \item comparison: \texttt{A$\gtreqqless$ B, A $\ne$ B, A$\gtreqqless \alpha$, A $\ne \alpha$}.
+ The result of comparison is 8-bit single channel mask, which elements are set to 255
+ (if the particular element or pair of elements satisfy the condition) and 0 otherwise.
\item bitwise logical operations: \verb"A & B, A & s, A | B, A | s, A ^ B, A ^ s, ~A"
\item element-wise minimum and maximum: \texttt{min(A, B), min(A, $\alpha$), max(A, B), max(A, $\alpha$)}
\item element-wise absolute value: \texttt{abs(A)}
\end{itemize}
Note, however, that comma-separated initializers and probably some other operations may require additional explicit \texttt{Mat()} or \verb"Mat_<T>()" constuctor calls to resolve possible ambiguity.
-\cvfunc{Mat\_}
+\cvfunc{Mat\_}\label{MatT}
Template matrix class derived from \cross{Mat}
\begin{lstlisting}
Mat M(100,100,CV_8U);
// this will compile fine. no any data conversion will be done.
Mat_<float>& M1 = (Mat_<float>&)M;
-// the program will likely at the statement below
+// the program will likely crash at the statement below
M1(99,99) = 1.f;
\end{lstlisting}
};
\end{lstlisting}
-The class \texttt{MatND} describes n-dimensional dense numerical single-channel or multi-channel array. This is a convenient representation for multi-dimensional histograms (when they are not very sparse, otherwise \texttt{SparseMat} will do better), voxel volumes, stacked motion fields etc. The data layout of matrix $M$ is defined by the array of \texttt{M.step[i]}, so that the address of element $(i_0,...,i_{M.dims-1})$, where $0\leq i_k<M.size[k]$ is computed as:
+The class \texttt{MatND} describes n-dimensional dense numerical single-channel or multi-channel array. This is a convenient representation for multi-dimensional histograms (when they are not very sparse, otherwise \texttt{SparseMat} will do better), voxel volumes, stacked motion fields etc. The data layout of matrix $M$ is defined by the array of \texttt{M.step[]}, so that the address of element $(i_0,...,i_{M.dims-1})$, where $0\leq i_k<M.size[k]$ is computed as:
\[
addr(M_{i_0,...,i_{M.dims-1}}) = M.data + M.step[0]*i_0 + M.step[1]*i_1 + ... + M.step[M.dims-1]*i_{M.dims-1}
\]
In other aspects \texttt{MatND} is also very similar to \texttt{Mat}, with the following limitations and differences:
\begin{itemize}
\item much less operations are implemented for \texttt{MatND}
- \item currently, algebraic expressions with \texttt{MatND} are not supported
+ \item currently, algebraic expressions with \texttt{MatND}'s are not supported
\item the \texttt{MatND} iterator is completely different from \texttt{Mat} and \texttt{Mat\_} iterators. The latter are per-element iterators, while the former is per-slice iterator, see below.
\end{itemize}
// and clear it
hist = Scalar(0);
- // the loop below assumes that we the image
+ // the loop below assumes that the image
// is 8-bit 3-channel, so let's check it.
CV_Assert(image.type() == CV_8UC3);
MatConstIterator_<Vec3b> it = image.begin<Vec3b>(),
{
const Vec3b& pix = *it;
- // we could have added 1.f/(image.rows*image.cols)
+ // we could have incremented the cells by 1.f/(image.rows*image.cols)
// instead of 1.f to make the histogram normalized.
hist.at<float>(pix[0]*N/256, pix[1]*N/256, pix[2]*N/256) += 1.f;
}
};
\end{lstlisting}
-The class \texttt{SparseMat} represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements of arbitrary type that \cross{Mat} and \cross{MatND} can store. "Sparse" means that only non-zero elements are stored (though, during some operations on sparse matrices some of the stored elements can actually become 0. It's up to the user to detect such elements and delete them using \texttt{SparseMat::erase}). The non-zero elements are stored in a hash table that grows when it's filled enough, so that the search time is O(1) in average (regardless of whether element is there or not). Elements can be accessed using the following methods:
+The class \texttt{SparseMat} represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements of any type that \cross{Mat} and \cross{MatND} can store. "Sparse" means that only non-zero elements are stored (though, as a result of operations on a sparse matrix, some of its stored elements can actually become 0. It's up to the user to detect such elements and delete them using \texttt{SparseMat::erase}). The non-zero elements are stored in a hash table that grows when it's filled enough, so that the search time is O(1) in average (regardless of whether element is there or not). Elements can be accessed using the following methods:
\begin{enumerate}
\item query operations (\texttt{SparseMat::ptr} and the higher-level \texttt{SparseMat::ref}, \texttt{SparseMat::value} and \texttt{SparseMat::find}), e.g.:
sparse_mat.ref<float>(idx) += 1.f;
}
\end{lstlisting}
- \item sparse matrix iterators. Like \cross{Mat} iterators and unlike \cross{MatND} iterators, the sparse matrix iterators are STL-style, that is the iteration loop is familiar to C++ users:
+ \item sparse matrix iterators. Like \cross{Mat} iterators and unlike \cross{MatND} iterators, the sparse matrix iterators are STL-style, that is, the iteration loop is familiar to C++ users:
\begin{lstlisting}
- // prints elements of a sparse floating-point matrix and the sum of elements.
- SparseMatConstIterator_<float> it = sparse_mat.begin<float>(), it_end = sparse_mat.end<float>();
+ // prints elements of a sparse floating-point matrix
+ // and the sum of elements.
+ SparseMatConstIterator_<float>
+ it = sparse_mat.begin<float>(),
+ it_end = sparse_mat.end<float>();
double s = 0;
int dims = sparse_mat.dims();
for(; it != it_end; ++it)
}
printf("Element sum is %g\n", s);
\end{lstlisting}
- If you run this loop, you will notice that elements are enumerated in no any logical order (lexicographical or any other), they come in the same order as they stored in the hash table. You may collect pointers to the nodes and sort them to get the proper ordering. Note, however, that pointers to the nodes may become invalid when you add more elements to the matrix; this is because possible buffer reallocation.
+ If you run this loop, you will notice that elements are enumerated in no any logical order (lexicographical etc.), they come in the same order as they stored in the hash table, i.e. semi-randomly. You may collect pointers to the nodes and sort them to get the proper ordering. Note, however, that pointers to the nodes may become invalid when you add more elements to the matrix; this is because of possible buffer reallocation.
\item a combination of the above 2 methods when you need to process 2 or more sparse matrices simultaneously, e.g. this is how you can compute unnormalized cross-correlation of the 2 floating-point sparse matrices:
\begin{lstlisting}
double cross_corr(const SparseMat& a, const SparseMat& b)
{
const SparseMat *_a = &a, *_b = &b;
- // if b contains less elements than a, it's faster to iterate through b
+ // if b contains less elements than a,
+ // it's faster to iterate through b
if(_a->nzcount() > _b->nzcount())
std::swap(_a, _b);
- SparseMatConstIterator_<float> it = _a->begin<float>(), it_end = _a->end<float>();
+ SparseMatConstIterator_<float> it = _a->begin<float>(),
+ it_end = _a->end<float>();
double ccorr = 0;
for(; it != it_end; ++it)
{
};
\end{lstlisting}
-\texttt{SparseMat\_} is thin wrapper on top of \cross{SparseMat}, made in the same way as \texttt{Mat\_} and \texttt{MatND\_}:
+\texttt{SparseMat\_} is a thin wrapper on top of \cross{SparseMat}, made in the same way as \texttt{Mat\_} and \texttt{MatND\_}.
+It simplifies notation of some operations, and that's it.
\begin{lstlisting}
int sz[] = {10, 20, 30};
SparseMat_<double> M(3, sz);
\cvarg{src}{matrix or matrix expression}
\end{description}
-\texttt{abs} is meta-function that is expanded to one of \cross{absdiff} forms:
+\texttt{abs} is a meta-function that is expanded to one of \cross{absdiff} forms:
\begin{itemize}
\item \texttt{C = abs(A-B)} is equivalent to \texttt{absdiff(A, B, C)} and
The output matrix will have the same size and the same type as the input one
(except for the last case, where \texttt{C} will be \texttt{depth=CV\_8U}).
-See also: \cross{Matrix Expressions}, \cross{absdiff}, \href{saturate}{saturate\_cast<T>}
+See also: \cross{Matrix Expressions}, \cross{absdiff}, \hyperref[saturatecast]{saturate\_cast}
\cvfunc{absdiff}\label{absdiff}
Computes per-element absolute difference between 2 arrays or between array and a scalar.
The functions \texttt{absdiff} compute:
\begin{itemize}
\item absolute difference between two arrays
- \texttt{dst(I) = saturate(abs(src1(I) - src2(I)))}
+ \[\texttt{dst}(I) = \texttt{saturate}(|\texttt{src1}(I) - \texttt{src2}(I)|)\]
\item or absolute difference between array and a scalar:
- \texttt{dst(I) = saturate(abs(src1(I) - sc))}
+ \[\texttt{dst}(I) = \texttt{saturate}(|\texttt{src1}(I) - \texttt{sc}|)\]
\end{itemize}
where \texttt{I} is multi-dimensional index of array elements.
+in the case of multi-channel arrays each channel is processed independently.
-See also: \cross{abs}, \href{saturate}{saturate\_cast<>}
+See also: \cross{abs}, \hyperref[saturatecast]{saturate\_cast}
\cvfunc{add}\label{add}
Computes the per-element sum of two arrays or an array and a scalar.
specifies elements of the destination array to be changed}
\end{description}
-The functions \texttt{add} compute
-
+The functions \texttt{add} compute:
\begin{itemize}
- \item the sum of two arrays
- \texttt{dst(I) = saturate(src1(I) + src2(I)) if mask(I)$\ne$0}
- \item the sum of array and a scalar:
- \texttt{dst(I) = saturate(src1(I) + sc) if mask(I) $\ne$ 0}
+ \item the sum of two arrays:
+ \[\texttt{dst}(I) = \texttt{saturate}(\texttt{src1}(I) + \texttt{src2}(I))\quad\texttt{if mask}(I)\ne0\]
+ \item or the sum of array and a scalar:
+ \[\texttt{dst}(I) = \texttt{saturate}(\texttt{src1}(I) + \texttt{sc})\quad\texttt{if mask}(I)\ne0\]
\end{itemize}
-
where \texttt{I} is multi-dimensional index of array elements.
The first function in the above list can be replaced with matrix expressions:
\begin{lstlisting}
- dst = src1 + src2;
- dst += src1; // ~ add(dst, src1, dst);
+dst = src1 + src2;
+dst += src1; // equivalent to add(dst, src1, dst);
\end{lstlisting}
+in the case of multi-channel arrays each channel is processed independently.
+
See also: \cross{subtract}, \cross{addWeighted}, \cross{scaleAdd}, \cross{convertScale},
-\cross{Matrix Expressions}, \href{saturate}{saturate\_cast<>}.
+\cross{Matrix Expressions}, \hyperref[saturatecast]{saturate\_cast}.
\cvfunc{addWeighted}\label{addWeighted}
Computes the weighted sum of two arrays.
\end{description}
The functions \texttt{addWeighted} calculate the weighted sum of two arrays as follows:
-
-\begin{lstlisting}
-dst(I)=saturate(src1(I)*alpha+src2(I)*beta+gamma)
-\end{lstlisting}
-
+\[\texttt{dst}(I)=\texttt{saturate}(\texttt{src1}(I)*\texttt{alpha} + \texttt{src2}(I)*\texttt{beta} + \texttt{gamma})\]
where \texttt{I} is multi-dimensional index of array elements.
+
The first function can be replaced with a matrix expression:
\begin{lstlisting}
dst = src1*alpha + src2*beta + gamma;
\end{lstlisting}
+In the case of multi-channel arrays each channel is processed independently.
+
See also: \cross{add}, \cross{subtract}, \cross{scaleAdd}, \cross{convertScale},
-\cross{Matrix Expressions}, \href{saturate}{saturate\_cast<>}.
+\cross{Matrix Expressions}, \hyperref[saturatecast]{saturate\_cast}.
\cvfunc{bitwise\_and}\label{bitwise and}
Calculates per-element bit-wise conjunction of two arrays and an array and a scalar.
specifies elements of the destination array to be changed}
\end{description}
-The functions \texttt{bitwise\_and} compute per-element bit-wise logical conjunction
-
+The functions \texttt{bitwise\_and} compute per-element bit-wise logical conjunction:
\begin{itemize}
\item of two arrays
- \texttt{dst(I) = src1(I) \& src2(I) if mask(I)$\ne$0}
+ \[\texttt{dst}(I) = \texttt{src1}(I) \wedge \texttt{src2}(I)\quad\texttt{if mask}(I)\ne0\]
\item or array and a scalar:
- \texttt{dst(I) = src1(I) \& sc if mask(I) $\ne$ 0}
+ \[\texttt{dst}(I) = \texttt{src1}(I) \wedge \texttt{sc}\quad\texttt{if mask}(I)\ne0\]
\end{itemize}
-In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation.
+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: \href{bitwise.and}{bitwise\_and}, \href{bitwise.not}{bitwise\_not}, \href{bitwise.xor}{bitwise\_xor}
+See also: \hyperref[bitwise.and]{bitwise\_and}, \hyperref[bitwise.not]{bitwise\_not}, \hyperref[bitwise.xor]{bitwise\_xor}
\cvfunc{bitwise\_not}
Inverts every bit of array
\end{description}
The functions \texttt{bitwise\_not} compute per-element bit-wise inversion of the source array:
+\[\texttt{dst}(I) = \neg\texttt{src}(I)\]
-\begin{lstlisting}
-dst(I) = ~src1(I)
-\end{lstlisting}
-
-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 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: \href{bitwise.and}{bitwise\_and}, \href{bitwise.or}{bitwise\_or}, \href{bitwise.xor}{bitwise\_xor}
+See also: \hyperref[bitwise.and]{bitwise\_and}, \hyperref[bitwise.or]{bitwise\_or}, \hyperref[bitwise.xor]{bitwise\_xor}
\cvfunc{bitwise\_or}
\end{description}
The functions \texttt{bitwise\_or} compute per-element bit-wise logical disjunction
-
\begin{itemize}
\item of two arrays
- \texttt{dst(I) = src1(I) | src2(I) if mask(I)$\ne$0}
+ \[\texttt{dst}(I) = \texttt{src1}(I) \vee \texttt{src2}(I)\quad\texttt{if mask}(I)\ne0\]
\item or array and a scalar:
- \texttt{dst(I) = src1(I) | sc if mask(I) $\ne$ 0}
+ \[\texttt{dst}(I) = \texttt{src1}(I) \vee \texttt{sc}\quad\texttt{if mask}(I)\ne0\]
\end{itemize}
-In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation.
+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: \href{bitwise.and}{bitwise\_and}, \href{bitwise.not}{bitwise\_not}, \href{bitwise.xor}{bitwise\_xor}
+See also: \hyperref[bitwise.and]{bitwise\_and}, \hyperref[bitwise.not]{bitwise\_not}, \hyperref[bitwise.or]{bitwise\_or}
\cvfunc{bitwise\_xor}
Calculates per-element bit-wise "exclusive or" operation on two arrays and an array and a scalar.
\begin{itemize}
\item on two arrays
- \texttt{dst(I) = src1(I) \^ src2(I) if mask(I)$\ne$0}
+ \[\texttt{dst}(I) = \texttt{src1}(I) \oplus \texttt{src2}(I)\quad\texttt{if mask}(I)\ne0\]
\item or array and a scalar:
- \texttt{dst(I) = src1(I) \^ sc if mask(I) $\ne$ 0}
+ \[\texttt{dst}(I) = \texttt{src1}(I) \oplus \texttt{sc}\quad\texttt{if mask}(I)\ne0\]
\end{itemize}
-In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation.
+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: \href{bitwise.and}{bitwise\_and}, \href{bitwise.not}{bitwise\_not}, \href{bitwise.or}{bitwise\_or}
+See also: \hyperref[bitwise.and]{bitwise\_and}, \hyperref[bitwise.not]{bitwise\_not}, \hyperref[bitwise.or]{bitwise\_or}
\cvfunc{calcCovarMatrix}\label{calcCovarMatrix}
Calculates covariation matrix of a set of vectors
\begin{description}
\cvarg{CV\_COVAR\_SCRAMBLED}{The output covariance matrix is calculated as:
\[
- \texttt{scale} * [ \texttt{vects} [0]- \texttt{avg} ,\texttt{vects} [1]- \texttt{avg} ,...]^T \cdot [\texttt{vects} [0]-\texttt{avg} ,\texttt{vects} [1]-\texttt{avg} ,...]
+ \texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} ,\texttt{vects} [1]- \texttt{mean} ,...]^T \cdot [\texttt{vects} [0]-\texttt{mean} ,\texttt{vects} [1]-\texttt{mean} ,...]
\],
that is, the covariance matrix will be $\texttt{nsamples} \times \texttt{nsamples}$.
Such an unusual covariance matrix is used for fast PCA
"scrambled" covariance matrix.}
\cvarg{CV\_COVAR\_NORMAL}{The output covariance matrix is calculated as:
\[
- \texttt{scale} * [ \texttt{vects} [0]- \texttt{avg} ,\texttt{vects} [1]- \texttt{avg} ,...] \cdot [\texttt{vects} [0]-\texttt{avg} ,\texttt{vects} [1]-\texttt{avg} ,...]^T
+ \texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} ,\texttt{vects} [1]- \texttt{mean} ,...] \cdot [\texttt{vects} [0]-\texttt{mean} ,\texttt{vects} [1]-\texttt{mean} ,...]^T
\],
-that is, \texttt{covar} will be a covariance matrix
-with the same linear size as the total number of elements in each
+that is, \texttt{covar} will be a square matrix
+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 '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 ('scale=1').}
+\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. 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. 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.}
+\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 function \texttt{cartToPolar} 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)=atan2(y(I), x(I))[*180/pi]
-\end{lstlisting}
+\[
+\begin{array}{l}
+\texttt{magnitude}(I)=\sqrt{\texttt{x}(I)^2+\texttt{y}(I)^2},\\
+\texttt{angle}(I)=\texttt{atan2}(\texttt{y}(I), \texttt{x}(I))[\cdot180/\pi]
+\end{array}
+\]
-The angles are calculated with $\sim$;0.3 degree accuracy. For the (0,0) point, the angle is set to 0.
+The angles are calculated with $\sim\,0.3^\circ$ accuracy. For the (0,0) point, the angle is set to 0.
\cvfunc{checkRange}\label{checkRange}
Checks every element of an input array for invalid values.
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 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 it is $\ne$0), and then the function either return false (when \texttt{quiet=true}) or throw an exception otherwise.
+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.
\cvfunc{compare}\label{compare}
\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}{src1(I) "equal to" src2(I) or src1(I) "equal to" value}
- \cvarg{CMP\_GT}{src1(I) "greater than" src2(I) or src1(I) "greater than" value}
- \cvarg{CMP\_GE}{src1(I) "greater or equal" src2(I) or src1(I) "greater or equal" value}
- \cvarg{CMP\_LT}{src1(I) "less than" src2(I) or src1(I) "less than" value}
- \cvarg{CMP\_LE}{src1(I) "less or equal" src2(I) or src1(I) "less or equal" value}
- \cvarg{CMP\_NE}{src1(I) "not equal" src2(I) or src1(I) "not equal" value}
+ \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:
-
\begin{itemize}
\item \texttt{dst(I) = src1(I) cmpop src2(I) ? 255 : 0}
\item \texttt{dst(I) = src1(I) cmpop value ? 255 : 0}
See also: \cross{checkRange}, \cross{min}, \cross{max}, \cross{threshold}, \cross{Matrix Expressions}
\cvfunc{completeSymm}\label{completeSymm}
-Copies lower or upper half of a square matrix to another half.
+Copies the lower or the upper half of a square matrix to another half.
\begin{lstlisting}
void completeSymm(Mat& mtx, bool lowerToUpper=false);
The function \texttt{completeSymm} copies the lower half of a square matrix to its another half; the matrix diagonal remains unchanged:
\begin{itemize}
- \item $\texttt{mtx}_ij=\texttt{mtx}_ji$ for $i > j$ if \texttt{lowerToUpper=false}
- \item $\texttt{mtx}_ij=\texttt{mtx}_ji$ for $i < j$ if \texttt{lowerToUpper=true}
+ \item $\texttt{mtx}_{ij}=\texttt{mtx}_{ji}$ for $i > j$ if \texttt{lowerToUpper=false}
+ \item $\texttt{mtx}_{ij}=\texttt{mtx}_{ji}$ for $i < j$ if \texttt{lowerToUpper=true}
\end{itemize}
See also: \cross{flip}, \cross{transpose}
\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:
+\[\texttt{dst}(I)=\texttt{saturate\_cast<uchar>}(|\texttt{src}(I)*\texttt{alpha} + \texttt{beta}|)\]
-\begin{lstlisting}
-dst(I)=saturate_cast<uchar>(abs(src(I)*alpha + beta))
-\end{lstlisting}
-
-In 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:
+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);
The function \texttt{cvCountNonZero} returns the number of non-zero elements in mtx:
-\[ \sum_{I,\,mtx(I)\ne0} 1 \]
+\[ \sum_{I:\;\texttt{mtx}(I)\ne0} 1 \]
See also: \cross{mean}, \cross{meanStdDev}, \cross{norm}, \cross{minMaxLoc}, \cross{calcCovarMatrix}
\cvarg{val}The function argument
\end{description}
-The function \texttt{cubeRoot} computes cube root of the floating-point argument.
-Negative arguments are handled correctly, \emph{NaN} and $\pm\inf$ are not handled.
+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.
\cvfunc{cvsrcToMat}\label{cvsrcToMat}
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 \cross{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 \cross{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 \cross{Mat} and \cross{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, or extract the COI using \cross{mixChannels} (for new-style arrays) or \cross{extractImageCOI} (for old-style arrays), process this individual channel and put it back to the if need (using \cross{mixChannel} or \cross{insertImageCOI}).
+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 \cross{Mat} and \cross{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 \cross{mixChannels} (for new-style arrays) or \cross{extractImageCOI} (for old-style arrays), process this individual channel and insert it back to the destination array if need (using \cross{mixChannel} or \cross{insertImageCOI}, respectively).
See also: \cross{cvGetImage}, \cross{cvGetMat}, \cross{cvGetMatND}, \cross{extractImageCOI}, \cross{insertImageCOI}, \cross{mixChannels}
Forward Cosine transform of 1D vector of $N$ elements:
\[Y = C^{(N)} \cdot X\]
where
-\[C^{(N)}_{jk}=\sqrt{\alpha_j/N\cos(\pi(2k+1)j/N)}\]
-and $\alpha_0=1$, $\alpha_j=2$ for $j > 1$.
+\[C^{(N)}_{jk}=\sqrt{\alpha_j/N}\cos\left(\frac{\pi(2k+1)j}{2N}\right)\]
+and $\alpha_0=1$, $\alpha_j=2$ for $j > 0$.
Inverse Cosine transform of 1D vector of N elements:
-\[X = (C^{(N)})^{-1} \cdot Y = (C^{(N)})^T \cdot Y\]
-(since $C^{(N)}$ is orthogonal matrix, $C^{(N)} \cdot (C^{(N)})^T = I$)
+\[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 (C^{(N)})^T\]
+\[Y = C^{(N)} \cdot X \cdot \left(C^{(N)}\right)^T\]
Inverse Cosine transform of 2D vector of $M \times N$ elements:
-\[X = (C^{(N)})^T \cdot X \cdot C^{(N)}\]
+\[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 otherwise it performs 2D transform.
\end{itemize}
-\emph{Important note: currently cv::dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation you can pad the array when necessary.}
+\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 \cross{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:
\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)\],
-where $i=\sqrt{-1}$
+\[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:
-\[X'= (F^{(N)})^{-1} \cdot Y = (F^{(N)})^* \cdot y
-X = (1/N) \cdot X\], where $F^*=(Re(F^{(N)})-Im(F^{(N)}))^T$
+\[
+\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:
-\[X'= (F^{(M)})^* \cdot Y \cdot (F^{(N)})^*
-X = (1/(M \cdot N)) \cdot X'\]
+\[
+\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{array}{l}
-Re Y_{0,0} \quad Re Y_{0,1} \quad Im Y_{0,1} \quad Re Y_{0,2} \quad Im Y_{0,2} \quad ... \quad Re Y_{0,N/2-1} \quad Im Y_{0,N/2-1} \quad Re Y_{0,N/2} \\
-
-Re Y_{1,0} \quad Re Y_{1,1} \quad Im Y_{1,1} \quad Re Y_{1,2} \quad Im Y_{1,2} \quad ... \quad Re Y_{1,N/2-1} \quad Im Y_{1,N/2-1} \quad Re Y_{1,N/2} \\
-
-Im Y_{1,0} \quad Re Y_{2,1} \quad Im Y_{2,1} \quad Re Y_{2,2} \quad Im Y_{2,2} \quad ... \quad Re Y_{2,N/2-1} \quad Im Y_{2,N/2-1} \quad Im Y_{2,N/2} \\
-............................................................................................................................................................ \\
-Re Y_{M/2-1,0} \quad Re Y_{M-3,1} \quad Im Y_{M-3,1} \quad Re Y_{M-3,2} \quad Im Y_{M-3,2} \quad... \quad Re Y_{M-3,N/2-1} \quad Im Y_{M-3,N/2-1}\quad Re Y_{M-3,N/2} \\
-Im Y_{M/2-1,0} \quad Re Y_{M-2,1} \quad Im Y_{M-2,1} \quad Re Y_{M-2,2} \quad Im Y_{M-2,2} \quad... \quad Re Y_{M-2,N/2-1} \quad Im Y_{M-2,N/2-1}\quad Im Y_{M-2,N/2} \\
-Re Y_{M/2,0} \quad Re Y_{M-1,1} \quad Im Y_{M-1,1} \quad Re Y_{M-1,2} \quad Im Y_{M-1,2} \quad ... \quad Re Y_{M-1,N/2-1} \quad Im Y_{M-1,N/2-1}\quad Im Y_{M-1,N/2}
-\end{array}
+\[\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 case of 1D transform of real vector, the output will look as the first row of the above matrix.
+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 input array is real and \texttt{(flags \& DFT\_INVERSE) == 0}, the function does forward 1D or 2D transform:
\begin{itemize}
\item when \texttt{(flags \& DFT\_COMPLEX\_OUTPUT) $\ne$ 0)} 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 case of 2D transform it will use the packed format as shown above; in case of single 1D transform it will look as the first row of the above matrix; in 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.
+ \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 \texttt{(flags \& DFT\_INVERSE) == 0} or \texttt{(flags \& DFT\_REAL\_OUTPUT) == 0} 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{(flags \& DFT\_INVERSE) $\ne$ 0}, the input array is real, or it is complex but \texttt{(flags \& DFT\_REAL\_OUTPUT) $\ne$ 0}, 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 if need (\texttt{(flags \& DFT\_SCALE) $\ne$ 0}) after the transformation.
+The scaling is done if needed (\texttt{(flags \& DFT\_SCALE) $\ne$ 0}) after the transformation.
Unlike \cross{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 \cross{getOptimalDFTSize} method.
\item since we passed \texttt{nonzeroRows $\ne$ 0} 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},
+ 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.
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 once the previous step is done, then, since different tiles in \texttt{C} can be computed in parallel, the loop can be threaded.
+ \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 the above improvements have been implemented in \cross{matchTemplate} and \cross{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 \cross{flip}).
+All of the above improvements have been implemented in \cross{matchTemplate} and \cross{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 \cross{flip}).
See also: \cross{dct}, \cross{getOptimalDFTSize}, \cross{mulSpectrums}, \cross{filter2D}, \cross{matchTemplate}, \cross{flip}, \cross{cartToPolar}, \cross{magnitude}, \cross{phase}
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 \cross{SVD}: $mtx=U \cdot W \cdot V^T$ and then calculate the determinant as a product of the diagonal elements of $W$.
+For symmetric positive-determined matrices, it is also possible to compute \cross{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: \cross{SVD}, \cross{trace}, \cross{invert}, \cross{solve}, \cross{Matrix Expressions}
int highindex);
\end{lstlisting}
\begin{description}
-\cvarg{src}{The input matrix; must have \texttt{CV\_32FC1} or \texttt{CV\_64FC1} type, square size and be symmetric: $src^T=src$}
+\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.
\end{lstlisting}
If either low- or highindex is supplied the other is required, too.
-Indexing is 1-based. Example: To calculate the largest eigenvector/-value set
-lowindex = highindex = 1.
+Indexing is 0-based. Example: To calculate the largest eigenvector/-value set
+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
The function \texttt{exp} calculates the exponent of every element of the input array:
\[
-\texttt{dst} [I] = e^{\texttt{src}(I)}
+\texttt{dst} [I] = e^{\texttt{src}}(I)
\]
-The maximum relative error is about $7 \times 10^{-6}$ for single-precision and <$10^{-10}$ for double-precision. Currently, the function converts denormalized values to zeros on output. Special values (NaN, $\pm \inf$) are not handled.
+The maximum relative error is about $7 \times 10^{-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: \cross{log}, \cross{cartToPolar}, \cross{polarToCart}, \cross{phase}, \cross{pow}, \cross{sqrt}, \cross{magnitude}
\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 degrees to 360 degrees. The accuracy is about 0.3 degrees.
+measured in degrees and varies from $0^\circ$ to $360^\circ$. The accuracy is about $0.3^\circ$.
\cvfunc{flip}\label{flip}
Flips a 2D array around vertical, horizontal or both axes.
The function \texttt{flip} flips the array in one of three different ways (row and column indices are 0-based):
\[
-dst(i,j) = \forkthree
-{\texttt{src}(rows(\texttt{src})-i-1,j)}{if $\texttt{flip\_mode} = 0$}
-{\texttt{src}(i,cols(\texttt{src})-j-1)}{if $\texttt{flip\_mode} > 0$}
-{\texttt{src}(rows(\texttt{src})-i-1,cols(\texttt{src})-j-1)}{if $\texttt{flip\_mode} < 0$}
+\texttt{dst}_{ij} = \forkthree
+{\texttt{src}_{\texttt{src.rows}-i-1,j}}{if \texttt{flipCode} = 0}
+{\texttt{src}_{i,\texttt{src.cols}-j-1}}{if \texttt{flipCode} > 0}
+{\texttt{src}_{\texttt{src.rows}-i-1,\texttt{src.cols}-j-1}}{if \texttt{flipCode} < 0}
\]
The example scenarios of function use are:
\begin{itemize}
- \item vertical flipping of the image (flip\_mode > 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 (flip\_mode $>$ 0)
- \item simultaneous horizontal and vertical flipping of the image with subsequent shift and absolute difference calculation to check for a central symmetry (flip\_mode $<$ 0)
- \item reversing the order of 1d point arrays (flip\_mode > 0)
+ \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: \cross{transpose}, \cross{repeat}, \cross{completeSymm}
\cvarg{dst}{The destination matrix; It will have the proper size and the same type as input matrices}
\cvarg{flags}{Operation flags:
\begin{description}
- \cvarg{GEMM\_1\_T}{transpose src1}
- \cvarg{GEMM\_2\_T}{transpose src2}
- \cvarg{GEMM\_3\_T}{transpose src3}
+ \cvarg{GEMM\_1\_T}{transpose \texttt{src1}}
+ \cvarg{GEMM\_2\_T}{transpose \texttt{src2}}
+ \cvarg{GEMM\_3\_T}{transpose \texttt{src3}}
\end{description}}
\end{description}
The function performs generalized matrix multiplication and similar to the corresponding functions \texttt{*gemm} in BLAS level 3.
-For example, \texttt{gemm(src1, src2, alpha, src3, beta, dst, GEMM\_1\_T + GEMM\_2\_T)} corresponds to
+For example, \texttt{gemm(src1, src2, alpha, src3, beta, dst, GEMM\_1\_T + GEMM\_3\_T)} corresponds to
\[
\texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T
\]
ConvertScaleData getConvertScaleElem(int fromType, int toType);
typedef void (*ConvertData)(const void* from, void* to, int cn);
-typedef void (*ConvertScaleData)(const void* from, void* to, int cn, double alpha, double beta);
+typedef void (*ConvertScaleData)(const void* from, void* to,
+ int cn, double alpha, double beta);
\end{lstlisting}
\begin{description}
\cvarg{fromType}{The source pixel type}
The function returns a negative number if \texttt{vecsize} is too large (very close to \texttt{INT\_MAX}).
-While the function can 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 be easily computed as \texttt{getOptimalDFTSize((vecsize+1)/2)*2}.
+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: \cross{dft}, \cross{dct}, \cross{idft}, \cross{idct}, \cross{mulSpectrums}
\texttt{dst}(I)=\texttt{lowerb}(I)_0 \leq \texttt{src}(I)_0 < \texttt{upperb}(I)_0
\]
-For single-channel arrays,
+for single-channel arrays,
\[
\texttt{dst}(I)=
\texttt{lowerb}(I)_1 \leq \texttt{src}(I)_1 < \texttt{upperb}(I)_1
\]
-For two-channel arrays and so forth,
-dst(I) is set to 255 (all \texttt{1}-bits) if src(I) is within the range and 0 otherwise.
+for two-channel arrays and so forth.
+\texttt{dst}(I) is set to 255 (all \texttt{1}-bits) if \texttt{src}(I) is within the specified range and 0 otherwise.
\cvfunc{invert}\label{invert}
\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 $\|src \cdot dst - I\|$
+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 calculate a pseudo-inverse matrix if \texttt{src} is singular.
+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 matrices. In this case the function stores the inverted matrix in \texttt{dst} and returns non-zero, otherwise it returns 0.
+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: \cross{solve}, \cross{SVD}
The function \texttt{log} calculates the natural logarithm of the absolute value of every element of the input array:
\[
-\texttt{dst}_I = \fork
-{\log |\texttt{src}_I|}{if $\texttt{src}_I \ne 0$ }
+\texttt{dst}(I) = \fork
+{\log |\texttt{src}(I)|}{if $\texttt{src}(I) \ne 0$ }
{\texttt{C}}{otherwise}
\]
Where \texttt{C} is a large negative number (about -700 in the current implementation).
-The maximum relative error is about $7 \times 10^{-6}$ for single-precision and <$10^{-10}$ for double-precision. Special values (NaN, $\pm \inf$) are not handled.
+The maximum relative error is about $7 \times 10^{-6}$ for single-precision input and less than $10^{-10}$ for double-precision input. Special values (NaN, $\pm \infty$) are not handled.
See also: \cross{exp}, \cross{cartToPolar}, \cross{polarToCart}, \cross{phase}, \cross{pow}, \cross{sqrt}, \cross{magnitude}
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:
\[
-\texttt{dst}_I \leftarrow \texttt{lut}_{\texttt{src}_I + d}
+\texttt{dst}(I) \leftarrow \texttt{lut(src(I) + d)}
\]
where
The function \texttt{magnitude} calculates magnitude of 2D vectors formed from the corresponding elements of \texttt{x} and \texttt{y} arrays:
\[
-\texttt{dst}_I = \sqrt{\texttt{x}_I^2 + \texttt{y}_I^2}
+\texttt{dst}(I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}
\]
See also: \cross{cartToPolar}, \cross{polarToCart}, \cross{phase}, \cross{sqrt}
The function \texttt{cvMahalonobis} calculates and returns the weighted distance between two vectors:
\[
-d(vec1,vec2)=\sqrt{\sum_{i,j}{icovar(i,j)\cdot(vec1(i)-vec2(i))\cdot(vec1(j)-vec2(j))}}
+d(\texttt{vec1},\texttt{vec2})=\sqrt{\sum_{i,j}{\texttt{icovar(i,j)}\cdot(\texttt{vec1}(I)-\texttt{vec2}(I))\cdot(\texttt{vec1(j)}-\texttt{vec2(j)})}}
\]
The covariance matrix may be calculated using the \cross{calcCovarMatrix} function and then inverted using the \cross{invert} function (preferably using DECOMP\_SVD method, as the most accurate).
\[
\begin{array}{l}
-N = \sum_{I, \texttt{mask}(I) \ne 0} 1\\
-M_c = \frac{\sum_{I, \texttt{mask}(I) \ne 0} \texttt{mtx}(I)_c}{N}
+N = \sum_{I:\;\texttt{mask}(I)\ne 0} 1\\
+M_c = \left(\sum_{I:\;\texttt{mask}(I)\ne 0}{\texttt{mtx}(I)_c}\right)/N
\end{array}
\]
\[
\begin{array}{l}
N = \sum_{I, \texttt{mask}(I) \ne 0} 1\\
-mean_c = \frac{\sum_{ I, \, \texttt{mask}(I) \ne 0} \texttt{src}(I)_c}{N}\\
-stddev_c = \sqrt{\sum_{ I, \, \texttt{mask}(I) \ne 0} (\texttt{src}(I)_c - mean_c)^2}
+\texttt{mean}_c = \frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \texttt{src}(I)_c}{N}\\
+\texttt{stddev}_c = \sqrt{\sum_{ I: \; \texttt{mask}(I) \ne 0} \left(\texttt{src}(I)_c - \texttt{mean}_c\right)^2}
\end{array}
\]
The functions do not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use \cross{reshape} first to reinterpret the array as single-channel. Or you may extract the particular channel using \cross{extractImageCOI} or \cross{mixChannels} or \cross{split}.
-In case of a sparse matrix the minimum is found among non-zero elements only.
+in the case of a sparse matrix the minimum is found among non-zero elements only.
See also: \cross{max}, \cross{min}, \cross{compare}, \cross{inRange}, \cross{extractImageCOI}, \cross{mixChannels}, \cross{split}, \cross{reshape}.
The function \texttt{mulTransposed} calculates the product of \texttt{src} and its transposition:
\[
-\texttt{dst}=\texttt{scale} (\texttt{src}-\texttt{delta}) (\texttt{src}-\texttt{delta})^T
+\texttt{dst}=\texttt{scale} (\texttt{src}-\texttt{delta})^T (\texttt{src}-\texttt{delta})
\]
-
-if $\texttt{aTa}=false$, and
+if \texttt{aTa=true}, and
\[
-\texttt{dst}=\texttt{scale} (\texttt{src}-\texttt{delta})^T (\texttt{src}-\texttt{delta})
+\texttt{dst}=\texttt{scale} (\texttt{src}-\texttt{delta}) (\texttt{src}-\texttt{delta})^T
\]
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$.
\cvarg{mask}{The optional operation mask}
\end{description}
-The functions \texttt{norm} calculate the absolute norm of \texttt{src1} if \texttt{src2} is NULL:
+The functions \texttt{norm} calculate the absolute norm of \texttt{src1} (when there is no \texttt{src2}):
\[
norm = \forkthree
-{\|\texttt{src1}\|_{L_{\inf}} = \max_I |\texttt{src1}(I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$}
+{\|\texttt{src1}\|_{L_{\infty}} = \max_I |\texttt{src1}(I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$}
{\|\texttt{src1}\|_{L_1} = \sum_I |\texttt{src1}(I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$}
{\|\texttt{src1}\|_{L_2} = \sqrt{\sum_I \texttt{src1}(I)^2}}{if $\texttt{normType} = \texttt{NORM\_L2}$}
\]
-And the function calculates absolute or relative difference norm if \texttt{src2} is not NULL:
+or an absolute or relative difference norm if \texttt{src2} is there:
\[
norm = \forkthree
-{\|\texttt{src1}-\texttt{src2}\|_{L_{\inf}} = \max_I |\texttt{src1}(I) - \texttt{src2}(I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$}
-{\|\texttt{src1}-\texttt{src2}\|_{L1} = \sum_I |\texttt{src1}(I) - \texttt{src2}(I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$}
-{\|\texttt{src1}-\texttt{src2}\|_{L2} = \sqrt{\sum_I (\texttt{src1}(I) - \texttt{src2}(I))^2}}{if $\texttt{normType} = \texttt{NORM\_L2}$}
+{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} = \max_I |\texttt{src1}(I) - \texttt{src2}(I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$}
+{\|\texttt{src1}-\texttt{src2}\|_{L_1} = \sum_I |\texttt{src1}(I) - \texttt{src2}(I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$}
+{\|\texttt{src1}-\texttt{src2}\|_{L_2} = \sqrt{\sum_I (\texttt{src1}(I) - \texttt{src2}(I))^2}}{if $\texttt{normType} = \texttt{NORM\_L2}$}
\]
or
\[
norm = \forkthree
-{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_{\inf}} }{\|\texttt{src2}\|_{L_{\inf}} }}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_INF}$}
-{\frac{\|\texttt{src1}-\texttt{src2}\|_{L1} }{\|\texttt{src2}\|_{L1}}}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L1}$}
-{\frac{\|\texttt{src1}-\texttt{src2}\|_{L2} }{\|\texttt{src2}\|_{L2}}}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L2}$}
+{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} }{\|\texttt{src2}\|_{L_{\infty}} }}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_INF}$}
+{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_1} }{\|\texttt{src2}\|_{L_1}}}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L1}$}
+{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_2} }{\|\texttt{src2}\|_{L_2}}}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L2}$}
\]
The functions \texttt{norm} return the calculated norm.
-When there is \texttt{mask} parameter, and the matrix 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.
+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.
\begin{description}
\cvarg{src}{The source array}
\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 case of range normalization}
-\cvarg{beta}{The upper range boundary in case of range normalization; not used for norm normalization}
+\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
-\[\|dst\|_{L_p}=\texttt{alpha}\]
-(where $p=\inf$, 1 or 2) when \texttt{normType=NORM\_INF}, \texttt{NORM\_L1} or \texttt{NORM\_L2},
+\[\|\texttt{dst}\|_{L_p}=\texttt{alpha}\]
+(where $p=\infty$, 1 or 2) when \texttt{normType=NORM\_INF}, \texttt{NORM\_L1} or \texttt{NORM\_L2},
or so that
\[\min_I \texttt{dst}(I)=\texttt{alpha},\,\,\max_I \texttt{dst}(I)=\texttt{beta}\]
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 \cross{norm} and \cross{Mat::convertScale}/\cross{MatND::convertScale}/cross{SparseMat::convertScale} separately.
-In 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.
+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: \cross{norm}, \cross{Mat::convertScale}, \cross{MatND::convertScale}, \cross{SparseMat::convertScale}
};
\end{lstlisting}
-The class PCA is used to compute the special basis for a set of vectors. The basis will consist of eigenvectors of the covariance matrix of the set of vectors and then 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 them) can be quite accurately approximated by taking just the first few its components, corresponding to the eigenvectors for the largest eigenvalues of the covariance matrix. That is, we can approximate the original vectors with much shorter ones. Such a transformation is also known as Karhunen-Loeve Transform, or KLT. See \url{http://en.wikipedia.org/wiki/Principal\_component\_analysis}
+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 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,
\cvarg{mtx}{$3\times 3$ or $4 \times 4$ 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:
+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) \]
and
\[ w = \fork{w'}{if $w' \ne 0$}{\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 \cross{warpPerspective}. If you have an inverse task - compute the most probably perspective transformation out of several pairs of corresponding points, you can use \cross{getPerspectiveTransform} or \cross{findHomography}.
+Note that the function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use \cross{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 \cross{getPerspectiveTransform} or \cross{findHomography}.
See also: \cross{transform}, \cross{warpPerspective}, \cross{getPerspectiveTransform}, \cross{findHomography}
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}:
-\[\texttt{angle}(I) = \texttt{atan2}(\texttt{y}(I)/\texttt{x}(I))\]
+\[\texttt{angle}(I) = \texttt{atan2}(\texttt{y}(I), \texttt{x}(I))\]
-The angle estimation accuracy is $\sim$ 0.3 degrees.
+The angle estimation accuracy is $\sim\,0.3^\circ$, when \texttt{x(I)=y(I)=0}, the corresponding \texttt{angle}(I) is set to $0$.
See also:
\[
\begin{array}{l}
-\texttt{x}(I) = \texttt{magnitude}(I)\cos(angle(I))\\
-\texttt{y}(I) = \texttt{magnitude}(I)\sin(angle(I))\\
+\texttt{x}(I) = \texttt{magnitude}(I)\cos(\texttt{angle}(I))\\
+\texttt{y}(I) = \texttt{magnitude}(I)\sin(\texttt{angle}(I))\\
\end{array}
\]
-The relative accuracy of the estimated coordinates is $\sim$;1e-6.
+The relative accuracy of the estimated coordinates is $\sim\,10^{-6}$.
See also: \cross{cartToPolar}, \cross{magnitude}, \cross{phase}, \cross{exp}, \cross{log}, \cross{pow}, \cross{sqrt}
The function \texttt{pow} raises every element of the input array to \texttt{p}:
\[
-\texttt{dst} [I] = \fork
+\texttt{dst}(I) = \fork
{\texttt{src}(I)^p}{if \texttt{p} is integer}
{|\texttt{src}(I)|^p}{otherwise}
\]
\[\texttt{low}_c \leq \texttt{mtx}(I)_c < \texttt{high}_c\]
-See also: \cross{RNG}, \cross{randn}
+See also: \cross{RNG}, \cross{randn}, \cross{theRNG}.
\cvfunc{randn}\label{randn}
Fills array with normally distributed 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. \href{saturate}{saturate\_cast<>} is applied to the generated numbers (i.e. the values are clipped)
+The function \texttt{randn} fills the matrix \texttt{mtx} with normally distributed random numbers with the specified mean and standard deviation. \hyperref[saturatecast]{saturate\_cast} is applied to the generated numbers (i.e. the values are clipped)
See also: \cross{RNG}, \cross{randu}
The functions \cross{repeat} duplicate the source array one or more times along each of the two axes:
-\[\texttt{dst}_ij=\texttt{src}_{i \mod \texttt{src.rows}, j \mod \texttt{src.cols}}\]
+\[\texttt{dst}_{ij}=\texttt{src}_{i\mod\texttt{src.rows},\;j\mod\texttt{src.cols}}\]
The second variant of the function is more convenient to use with \cross{Matrix Expressions}
See also: \cross{reduce}, \cross{Matrix Expressions}
-\cvfunc{saturate\_cast}\label{saturate cast}
+\cvfunc{saturate\_cast}\label{saturatecast}
Template function for accurate conversion from one primitive type to another
\begin{lstlisting}
\cvarg{v}{The function parameter}
\end{description}
-The functions \texttt{saturate\_cast} resembler standard C++ cast operations, such as \texttt{static\_cast<T>()} etc. They perform 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:
+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 = 32768 ~ SHRT_MAX
+uchar a = saturate_cast<uchar>(-100); // a = 0 (UCHAR_MIN)
+short b = saturate_cast<short>(33333.33333); // b = 32768 (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 (again, only when the result is 8- or 16-bit).
+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.
\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} and \texttt{saxpy} in BLAS. It calculates the sum of a scaled array and another array:
+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:
\[
\texttt{dst}(I)=\texttt{scale} \cdot \texttt{src1}(I) + \texttt{src2}(I)
bool solve(const Mat& src1, const Mat& src2, Mat& dst, int flags=DECOMP_LU);
\end{lstlisting}
\begin{description}
-\cvarg{src1}{The source matrix}
-\cvarg{src2}{The right-hand part of the linear system}
+\cvarg{src1}{The input matrix on the left-hand side of the system}
+\cvarg{src2}{The input matrix on the right-hand side of the system}
\cvarg{dst}{The output solution}
\cvarg{flags}{The solution (matrix inversion) method
\begin{description}
\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}
+ \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{sSolve} solves a linear system or least-squares problem (the latter is possible with SVD or QR methods):
+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}):
\[
-\texttt{dst} = \arg \min_X\|\texttt{src1} \, \texttt{X} - \texttt{src2}\|
+\texttt{dst} = \arg \min_X\|\texttt{src1}\cdot\texttt{X} - \texttt{src2}\|
\]
-If \texttt{CV\_LU} or \texttt{CV\_CHOLESKY} 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. Other methods find some pseudo-solution in the case of singular \texttt{src1}.
+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 \cross{SVD::solveZ} instead.
\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 case of multi-channel arrays each channel is processed independently. The function accuracy is approximately the same as in the built-in \texttt{std::sqrt}.
+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: \cross{pow}, \cross{magnitude}
\begin{itemize}
\item the difference between two arrays
- \texttt{dst(I) = saturate(src1(I) - src2(I)) if mask(I)$\ne$0}
+ \[\texttt{dst}(I) = \texttt{saturate}(\texttt{src1}(I) - \texttt{src2}(I))\quad\texttt{if mask}(I)\ne0\]
\item the difference between array and a scalar:
- \texttt{dst(I) = saturate(src1(I) - sc) if mask(I) $\ne$ 0}
+ \[\texttt{dst}(I) = \texttt{saturate}(\texttt{src1}(I) - \texttt{sc})\quad\texttt{if mask}(I)\ne0\]
\item the difference between scalar and an array:
- \texttt{dst(I) = saturate(sc - src2(I)) if mask(I) $\ne$ 0}
+ \[\texttt{dst}(I) = \texttt{saturate}(\texttt{sc} - \texttt{src2}(I))\quad\texttt{if mask}(I)\ne0\]
\end{itemize}
where \texttt{I} is multi-dimensional index of array elements.
The first function in the above list can be replaced with matrix expressions:
\begin{lstlisting}
- dst = src1 - src2;
- dst -= src2; // ~ subtract(dst, src2, dst);
+dst = src1 - src2;
+dst -= src2; // equivalent to subtract(dst, src2, dst);
\end{lstlisting}
See also: \cross{add}, \cross{addWeighted}, \cross{scaleAdd}, \cross{convertScale},
-\cross{Matrix Expressions}, \href{saturate}{saturate\_cast<>}.
+\cross{Matrix Expressions}, \hyperref[saturatecast]{saturate\_cast}.
\cvfunc{SVD}\label{SVD}
-Class for computing and using Singular Value Decomposition
+Class for computing Singular Value Decomposition
\begin{lstlisting}
class SVD
The function \texttt{trace} returns the sum of the diagonal elements of the matrix \texttt{mtx}.
-\[ tr(\texttt{mtx}) = \sum_i \texttt{mtx}(i,i) \]
+\[ \mathrm{tr}(\texttt{mtx}) = \sum_i \texttt{mtx}(i,i) \]
\cvfunc{transform}\label{transform}
baseline += thickness;
// center the text
-Point textOrg((img.cols - textSize.width)/2, (img.rows + textSize.height)/2);
+Point textOrg((img.cols - textSize.width)/2,
+ (img.rows + textSize.height)/2);
// draw the box
-rectangle(img, textOrg + Point(0, baseline), textOrg + Point(textSize.width, -textSize.height),
+rectangle(img, textOrg + Point(0, baseline),
+ textOrg + Point(textSize.width, -textSize.height),
Scalar(0,0,255));
// ... and the baseline first
-line(img, textOrg + Point(0, thickness), textOrg + Point(textSize.width, thickness),
+line(img, textOrg + Point(0, thickness),
+ textOrg + Point(textSize.width, thickness),
Scalar(0, 0, 255));
// then put the text itself
The number of pixels along the line is store in \texttt{LineIterator::count}.
\begin{lstlisting}
-\\ grabs pixels along the line (pt1, pt2) from 8-bit 3-channel image to the buffer
+\\ grabs pixels along the line (pt1, pt2)
+\\ from 8-bit 3-channel image to the buffer
LineIterator it(img, pt1, pt2, 8);
vector<Vec3b> buf(it.count);
Draws several polygonal curves
\begin{lstlisting}
-void polylines(Mat& img, const Point** pts, const int* npts, int ncontours, bool isClosed,
- const Scalar& color, int thickness=1, int lineType=8, int shift=0 );
+void polylines(Mat& img, const Point** pts, const int* npts,
+ int ncontours, bool isClosed, const Scalar& color,
+ int thickness=1, int lineType=8, int shift=0 );
\end{lstlisting}
\begin{description}
\cvarg{img}{The image}
class CV_EXPORTS FileNode
{
public:
- enum { NONE=0, INT=1, REAL=2, FLOAT=REAL, STR=3, STRING=STR, REF=4, SEQ=5, MAP=6, TYPE_MASK=7,
+ enum { NONE=0, INT=1, REAL=2, FLOAT=REAL, STR=3,
+ STRING=STR, REF=4, SEQ=5, MAP=6, TYPE_MASK=7,
FLOW=8, USER=16, EMPTY=32, NAMED=64 };
FileNode();
FileNode(const CvFileStorage* fs, const CvFileNode* node);
};
\end{lstlisting}
-\cvfunc{FileNode}\label{FileNode}
+\cvfunc{FileNodeIterator}\label{FileNodeIterator}
The XML/YAML file node iterator class
\begin{lstlisting}
{
public:
FileNodeIterator();
- FileNodeIterator(const CvFileStorage* fs, const CvFileNode* node, size_t ofs=0);
+ FileNodeIterator(const CvFileStorage* fs,
+ const CvFileNode* node, size_t ofs=0);
FileNodeIterator(const FileNodeIterator& it);
FileNode operator *() const;
FileNode operator ->() const;
double kmeans( const Mat& samples, int clusterCount, Mat& labels,
TermCriteria termcrit, int attempts,
int flags, Mat* centers );
-enum { KMEANS_RANDOM_CENTERS=0, KMEANS_PP_CENTERS=2, KMEANS_USE_INITIAL_LABELS=1 };
+enum { KMEANS_RANDOM_CENTERS=0,
+ KMEANS_PP_CENTERS=2,
+ KMEANS_USE_INITIAL_LABELS=1 };
\end{lstlisting}
\begin{description}
\cvarg{samples}{Floating-point matrix of input samples, one row per sample}
The function \texttt{kmeans} implements a k-means algorithm that finds the
centers of \texttt{clusterCount} clusters and groups the input samples
-around the clusters. On output, $\texttt{labels}_i$ contains a cluster index for
-the sample stored in the $i^th$ row of the \texttt{samples} matrix.
+around the clusters. On output, $\texttt{labels}_i$ contains a 0-based cluster index for
+the sample stored in the $i^{th}$ row of the \texttt{samples} matrix.
The function returns the compactness measure, which is computed as
\[
\cvarg{predicate}{The equivalence predicate (i.e. pointer to a boolean function of two arguments or an instance of the class that has the method \texttt{bool operator()(const \_Tp\& a, const \_Tp\& b)}. The predicate returns true when the elements are certainly if the same class, and false if they may or may not be in the same class}
\end{description}
-The generic function \texttt{partition} implements a quadratic algorithm for
-splitting a set into one or more equivalancy classes, described in \url{http://en.wikipedia.org/wiki/Disjoint-set_data_structure}. The function
+The generic function \texttt{partition} implements an $O(N^2)$ algorithm for
+splitting a set of $N$ elements into one or more equivalency classes, as described in \url{http://en.wikipedia.org/wiki/Disjoint-set_data_structure}. The function
returns the number of equivalency classes.
\subsection{Utility and System Functions and Macros}
\end{description}
The function returns the aligned pointer of the same type as the input pointer:
-\[(\_Tp*)(((size\_t)ptr + n-1) \& -n)\]
+\[\texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)}\]
\cvfunc{alignSize}\label{alignSize}
\end{description}
The function returns the minimum number that is greater or equal to \texttt{sz} and is divisble by \texttt{n}:
-\[(sz + n-1) \& -n\]
+\[\texttt{(sz + n-1) \& -n}\]
\cvfunc{allocate}\label{allocate}
\cvarg{size}{The allocated buffer size}
\end{description}
-The function \texttt{fastMalloc} allocates buffer of the specified size and returns it. When the buffer is 16 bytes or more, the returned buffer is aligned on 16 bytes.
+The function \texttt{fastMalloc} allocates buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned on 16 bytes.
\cvfunc{fastFree}\label{fastFree}
Deallocates memory buffer
projects / opencv.git / commitdiff