PDL::OpenCV - PDL interface to OpenCV
use PDL::OpenCV::Videoio; # ucfirsted name of the OpenCV "module" my $vfile='t/frames.avi'; my $vc = PDL::OpenCV::VideoCapture->new; # name of the OpenCV class die "Failed to open $vfile" if !$vc->open($vfile); my ($frame, $res) = $vc->read; die "Failed to read" if !$res; my $writer = PDL::OpenCV::VideoWriter->new; # note 4th arg is an OpenCV "Size" - PDL upgrades array-ref to ndarray $writer->open($outfile, PDL::OpenCV::VideoWriter::fourcc('M','P','4','V'), 20, [map $frame->dim($_), 1,2], 1); while ($res) { $writer->write($frame); # and/or display it, or feed it to a Tracker, or... ($frame, $res) = $vc->read; }
Use PDL::OpenCV to call OpenCV functions on your data using Perl/PDL.
As can be seen above, this distribution is structured to very closely match the structure of OpenCV v4 itself. That means the submodules match the "classes" and/or "modules" in OpenCV, with the obvious exception of the Mat class which needs special handling to thinly wrap ndarrays going into and coming back from OpenCV.
Mat
This includes method/function names which are exactly the same as in OpenCV, without being modified for the common Perl idiom of snake_casing. This is intended to make the OpenCV documentation trivially easy to use for the PDL binding (where a binding exists), including available tutorials.
The API is generated from the Python bindings that are part of OpenCV. In imitation of that, you are not currently able, as with "normal" PDL functions, to pass in output ndarrays.
Where things do not work as you would expect from a PDL and/or OpenCV point of view, and it is not documented as doing so, this is a bug - please report it as shown at "BUGS" below.
In PDL, images are often byte,3,x,y or occasionally (e.g. in PDL::Graphics::Simple) byte,x,y,3. The 3 is always R,G,B. Sometimes 4 is supported, in which case the 4th column will be an alpha (transparency) channel, or 1, which means the image is grayscale.
byte,3,x,y
byte,x,y,3
OpenCV has the concepts of "depth" and "channels".
"Depth" is bit-depth (and data type) per pixel and per channel: the bit-depth will be a multiple of 8, and the data type will be integer (signed or unsigned) or floating-point.
"Channels" resembles the above 1/3/4 point, with the important caveat that the default for OpenCV image-reading is to format data not as R,G,B, but B,G,R. This is for historical reasons, being the format returned by the cameras first used at the start of OpenCV. Use "cvtColor" in PDL::OpenCV::Imgproc if your application requires otherwise.
PDL data for use with OpenCV must be dimensioned (channels,x,y) where channels might be 1 if grayscale. This module will not use heuristics to guess what you meant if you only supply 2-dimensional data. This can lead to surprising results: e.g. with "EMD" in PDL::OpenCV::ImgProc, the two histogram inputs must be 3D, with a channels of 1. From the relevant test:
(channels,x,y)
channels
my $a = pdl float, q[[1 1] [1 2] [0 3] [0 4] [1 5]]; my $b = pdl float, q[[0 1] [1 2] [0 3] [1 4]]; my ($flow,$res) = EMD($a->dummy(0),$b->dummy(0),DIST_L2);
If you get an exception Unrecognized or unsupported array type, that is the cause.
Unrecognized or unsupported array type
Be careful when scaling byte-valued inputs to maximise dynamic range:
$frame = ($frame * (255/$max))->byte; # works $frame = ($frame * 255/$max)->byte; # multiply happens first and overflows
In OpenCV, as well as the most important type (Mat), there are various helper types including Rect, Size, and Scalar (often used for specifying colours). This distribution wraps these as ndarrays of appropriate types and dimensions.
Rect
Size
Scalar
While in C++ there are often default values for the constructors and/or polymorphic ways to call them with fewer than the full number of arguments, this is currently not possible in PDL. Therefore, e.g. with a Scalar, you have to supply all four values (just give zeroes for the ones that don't matter, e.g. the alpha value for a colour on a non-alpha image).
This distro reproduces the structure of OpenCV's various modules, so that e.g. the tracking module is made available as PDL::OpenCV::Tracking. Loading that makes available the PDL::OpenCV::Tracker package which has various methods like new.
tracking
PDL::OpenCV::Tracker
new
OpenCV defines various constants in its different modules. This distro will remove cv:: from the beginning of these, then put them in their loading module. E.g. in imgproc, COLOR_GRAY2RGB will be PDL::OpenCV::Imgproc::COLOR_GRAY2RGB (and exported by default).
cv::
imgproc
COLOR_GRAY2RGB
PDL::OpenCV::Imgproc::COLOR_GRAY2RGB
However, further-namespaced constants, like cv::Subdiv2D::PTLOC_VERTEX, will not be exported, and will be available as e.g. PDL::OpenCV::Imgproc::Subdiv2D::PTLOC_VERTEX.
cv::Subdiv2D::PTLOC_VERTEX
PDL::OpenCV::Imgproc::Subdiv2D::PTLOC_VERTEX
Computes the cube root of an argument.
$res = cubeRoot($val);
The function cubeRoot computes \sqrt[3]{\texttt{val}}. Negative arguments are handled correctly. NaN and Inf are not handled. The accuracy approaches the maximum possible accuracy for single-precision data.
\sqrt[3]{\texttt{val}}
Parameters:
A function argument.
Calculates the angle of a 2D vector in degrees.
$res = fastAtan2($y,$x);
The function fastAtan2 calculates the full-range angle of an input 2D vector. The angle is measured in degrees and varies from 0 to 360 degrees. The accuracy is about 0.3 degrees.
x-coordinate of the vector.
y-coordinate of the vector.
Computes the source location of an extrapolated pixel.
$res = borderInterpolate($p,$len,$borderType);
The function computes and returns the coordinate of a donor pixel corresponding to the specified extrapolated pixel when using the specified extrapolation border mode. For example, if you use cv::BORDER_WRAP mode in the horizontal direction, cv::BORDER_REFLECT_101 in the vertical direction and want to compute value of the "virtual" pixel Point(-5, 100) in a floating-point image img , it looks like:
{.cpp} float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101), borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
Normally, the function is not called directly. It is used inside filtering functions and also in copyMakeBorder. \<0 or \>= len
0-based coordinate of the extrapolated pixel along one of the axes, likely
Length of the array along the corresponding axis.
Border type, one of the #BorderTypes, except for #BORDER_TRANSPARENT and #BORDER_ISOLATED . When borderType==#BORDER_CONSTANT , the function always returns -1, regardless of p and len.
See also: copyMakeBorder
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] top(); int [phys] bottom(); int [phys] left(); int [phys] right(); int [phys] borderType(); double [phys] value(n8))
Forms a border around an image. NO BROADCASTING.
$dst = copyMakeBorder($src,$top,$bottom,$left,$right,$borderType); # with defaults $dst = copyMakeBorder($src,$top,$bottom,$left,$right,$borderType,$value);
The function copies the source image into the middle of the destination image. The areas to the left, to the right, above and below the copied source image will be filled with extrapolated pixels. This is not what filtering functions based on it do (they extrapolate pixels on-fly), but what other more complex functions, including your own, may do to simplify image boundary handling. The function supports the mode when src is already in the middle of dst . In this case, the function does not copy src itself but simply constructs the border, for example:
{.cpp} // let border be the same in all directions int border=2; // constructs a larger image to fit both the image and the border Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth()); // select the middle part of it w/o copying data Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows)); // convert image from RGB to grayscale cvtColor(rgb, gray, COLOR_RGB2GRAY); // form a border in-place copyMakeBorder(gray, gray_buf, border, border, border, border, BORDER_REPLICATE); // now do some custom filtering ... ...
@note When the source image is a part (ROI) of a bigger image, the function will try to use the pixels outside of the ROI to form a border. To disable this feature and always do extrapolation, as if src was not a ROI, use borderType | #BORDER_ISOLATED.
Source image.
Destination image of the same type as src and the size Size(src.cols+left+right, src.rows+top+bottom) .
the top pixels
the bottom pixels
the left pixels
Parameter specifying how many pixels in each direction from the source image rectangle to extrapolate. For example, top=1, bottom=1, left=1, right=1 mean that 1 pixel-wide border needs to be built.
Border type. See borderInterpolate for details.
Border value if borderType==BORDER_CONSTANT .
See also: borderInterpolate
copyMakeBorder ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3); [phys] mask(l4,c4,r4); int [phys] dtype())
Calculates the per-element sum of two arrays or an array and a scalar. NO BROADCASTING.
$dst = add($src1,$src2); # with defaults $dst = add($src1,$src2,$mask,$dtype);
The function add calculates: =over =back The first function in the list above can be replaced with matrix expressions:
{.cpp} dst = src1 + src2; dst += src1; // equivalent to add(dst, src1, dst);
The input arrays and the output array can all have the same or different depths. For example, you can add a 16-bit unsigned array to a 8-bit signed array and store the sum as a 32-bit floating-point array. Depth of the output array is determined by the dtype parameter. In the second and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this case, the output array will have the same depth as the input array, be it src1, src2 or both. @note Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.
first input array or a scalar.
second input array or a scalar.
output array that has the same size and number of channels as the input array(s); the depth is defined by dtype or src1/src2.
optional operation mask - 8-bit single channel array, that specifies elements of the output array to be changed.
optional depth of the output array (see the discussion below).
See also: subtract, addWeighted, scaleAdd, Mat::convertTo
add ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the per-element difference between two arrays or array and a scalar. NO BROADCASTING.
$dst = subtract($src1,$src2); # with defaults $dst = subtract($src1,$src2,$mask,$dtype);
The function subtract calculates: =over =back The first function in the list above can be replaced with matrix expressions:
{.cpp} dst = src1 - src2; dst -= src1; // equivalent to subtract(dst, src1, dst);
The input arrays and the output array can all have the same or different depths. For example, you can subtract to 8-bit unsigned arrays and store the difference in a 16-bit signed array. Depth of the output array is determined by dtype parameter. In the second and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this case the output array will have the same depth as the input array, be it src1, src2 or both. @note Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.
output array of the same size and the same number of channels as the input array.
optional operation mask; this is an 8-bit single channel array that specifies elements of the output array to be changed.
optional depth of the output array
See also: add, addWeighted, scaleAdd, Mat::convertTo
subtract ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3); double [phys] scale(); int [phys] dtype())
Calculates the per-element scaled product of two arrays. NO BROADCASTING.
$dst = multiply($src1,$src2); # with defaults $dst = multiply($src1,$src2,$scale,$dtype);
The function multiply calculates the per-element product of two arrays: \f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))\f] There is also a @ref MatrixExpressions -friendly variant of the first function. See Mat::mul . For a not-per-element matrix product, see gemm . @note Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.
first input array.
second input array of the same size and the same type as src1.
output array of the same size and type as src1.
optional scale factor.
See also: add, subtract, divide, scaleAdd, addWeighted, accumulate, accumulateProduct, accumulateSquare, Mat::convertTo
multiply ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Performs per-element division of two arrays or a scalar by an array. NO BROADCASTING.
$dst = divide($src1,$src2); # with defaults $dst = divide($src1,$src2,$scale,$dtype);
The function cv::divide divides one array by another: \f[\texttt{dst(I) = saturate(src1(I)*scale/src2(I))}\f] or a scalar by an array when there is no src1 : \f[\texttt{dst(I) = saturate(scale/src2(I))}\f] Different channels of multi-channel arrays are processed independently. For integer types when src2(I) is zero, dst(I) will also be zero. @note In case of floating point data there is no special defined behavior for zero src2(I) values. Regular floating-point division is used. Expect correct IEEE-754 behaviour for floating-point data (with NaN, Inf result values). @note Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.
second input array of the same size and type as src1.
scalar factor.
output array of the same size and type as src2.
optional depth of the output array; if -1, dst will have depth src2.depth(), but in case of an array-by-array division, you can only pass -1 when src1.depth()==src2.depth().
See also: multiply, add, subtract
divide ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [phys] scale(); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3); int [phys] dtype())
NO BROADCASTING.
$dst = divide2($scale,$src2); # with defaults $dst = divide2($scale,$src2,$dtype);
@overload
divide2 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); double [phys] alpha(); [phys] src2(l3,c3,r3); [o,phys] dst(l4,c4,r4))
Calculates the sum of a scaled array and another array. NO BROADCASTING.
$dst = scaleAdd($src1,$alpha,$src2);
The function scaleAdd is one of the classical primitive linear algebra operations, known as DAXPY or SAXPY in [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms). It calculates the sum of a scaled array and another array: \f[\texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I)\f] The function can also be emulated with a matrix expression, for example:
{.cpp} Mat A(3, 3, CV_64F); ... A.row(0) = A.row(1)*2 + A.row(2);
scale factor for the first array.
See also: add, addWeighted, subtract, Mat::dot, Mat::convertTo
scaleAdd ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); double [phys] alpha(); [phys] src2(l3,c3,r3); double [phys] beta(); double [phys] gamma(); [o,phys] dst(l6,c6,r6); int [phys] dtype())
Calculates the weighted sum of two arrays. NO BROADCASTING.
$dst = addWeighted($src1,$alpha,$src2,$beta,$gamma); # with defaults $dst = addWeighted($src1,$alpha,$src2,$beta,$gamma,$dtype);
The function addWeighted calculates the weighted sum of two arrays as follows: \f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )\f] where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently. The function can be replaced with a matrix expression:
{.cpp} dst = src1*alpha + src2*beta + gamma;
@note Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.
weight of the first array elements.
second input array of the same size and channel number as src1.
weight of the second array elements.
scalar added to each sum.
output array that has the same size and number of channels as the input arrays.
optional depth of the output array; when both input arrays have the same depth, dtype can be set to -1, which will be equivalent to src1.depth().
See also: add, subtract, scaleAdd, Mat::convertTo
addWeighted ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); double [phys] alpha(); double [phys] beta())
Scales, calculates absolute values, and converts the result to 8-bit. NO BROADCASTING.
$dst = convertScaleAbs($src); # with defaults $dst = convertScaleAbs($src,$alpha,$beta);
On each element of the input array, the function convertScaleAbs performs three operations sequentially: scaling, taking an absolute value, conversion to an unsigned 8-bit type: \f[\texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |)\f] 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 the Mat::convertTo method (or by using matrix expressions) and then by calculating an absolute value of the result. For example:
{.cpp} Mat_<float> A(30,30); randu(A, Scalar(-100), Scalar(100)); Mat_<float> B = A*5 + 3; B = abs(B); // Mat_<float> B = abs(A*5+3) will also do the job, // but it will allocate a temporary matrix
input array.
output array.
optional delta added to the scaled values.
See also: Mat::convertTo, cv::abs(const Mat&)
convertScaleAbs ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2))
Converts an array to half precision floating number. NO BROADCASTING.
$dst = convertFp16($src);
This function converts FP32 (single precision floating point) from/to FP16 (half precision floating point). CV_16S format is used to represent FP16 data. There are two use modes (src -> dst): CV_32F -> CV_16S and CV_16S -> CV_32F. The input array has to have type of CV_32F or CV_16S to represent the bit depth. If the input array is neither of them, the function will raise an error. The format of half precision floating point is defined in IEEE 754-2008.
convertFp16 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [phys] lut(l2,c2,r2); [o,phys] dst(l3,c3,r3))
Performs a look-up table transform of an array. NO BROADCASTING.
$dst = LUT($src,$lut);
The function LUT fills the output array with values from the look-up table. Indices of the entries are taken from the input array. That is, the function processes each element of src as follows: \f[\texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)}\f] where \f[d = \fork{0}{if \(\texttt{src}\) has depth \(\texttt{CV_8U}\)}{128}{if \(\texttt{src}\) has depth \(\texttt{CV_8S}\)}\f]
input array of 8-bit elements.
look-up table of 256 elements; in case of multi-channel input array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the input array.
output array of the same size and number of channels as src, and the same depth as lut.
See also: convertScaleAbs, Mat::convertTo
LUT ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); double [o,phys] res(n2=4))
Calculates the sum of array elements.
$res = sumElems($src);
The function cv::sum calculates and returns the sum of array elements, independently for each channel.
input array that must have from 1 to 4 channels.
See also: countNonZero, mean, meanStdDev, norm, minMaxLoc, reduce
sumElems ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); int [o,phys] res())
Counts non-zero array elements.
$res = countNonZero($src);
The function returns the number of non-zero elements in src : \f[\sum _{I: \; \texttt{src} (I) \ne0 } 1\f]
single-channel array.
See also: mean, meanStdDev, norm, minMaxLoc, calcCovarMatrix
countNonZero ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] idx(l2,c2,r2))
Returns the list of locations of non-zero pixels NO BROADCASTING.
$idx = findNonZero($src);
Given a binary matrix (likely returned from an operation such as threshold(), compare(), >, ==, etc, return all of the non-zero indices as a cv::Mat or std::vector<cv::Point> (x,y) For example:
{.cpp} cv::Mat binaryImage; // input, binary image cv::Mat locations; // output, locations of non-zero pixels cv::findNonZero(binaryImage, locations); // access pixel coordinates Point pnt = locations.at<Point>(i);
or
{.cpp} cv::Mat binaryImage; // input, binary image vector<Point> locations; // output, locations of non-zero pixels cv::findNonZero(binaryImage, locations); // access pixel coordinates Point pnt = locations[i];
single-channel array
the output array, type of cv::Mat or std::vector<Point>, corresponding to non-zero indices in the input
findNonZero ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [phys] mask(l2,c2,r2); double [o,phys] res(n3=4))
Calculates an average (mean) of array elements.
$res = mean($src); # with defaults $res = mean($src,$mask);
The function cv::mean calculates the mean value M of array elements, independently for each channel, and return it: \f[\begin{array}{l} 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}\f] When all the mask elements are 0's, the function returns Scalar::all(0)
input array that should have from 1 to 4 channels so that the result can be stored in Scalar_ .
optional operation mask.
See also: countNonZero, meanStdDev, norm, minMaxLoc
mean ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] mean(l2,c2,r2); [o,phys] stddev(l3,c3,r3); [phys] mask(l4,c4,r4))
($mean,$stddev) = meanStdDev($src); # with defaults ($mean,$stddev) = meanStdDev($src,$mask);
Calculates a mean and standard deviation of array elements. The function cv::meanStdDev calculates the mean and the standard deviation M of array elements independently for each channel and returns it via the output parameters: \f[\begin{array}{l} N = \sum _{I, \texttt{mask} (I) \ne 0} 1 \\ \texttt{mean} _c = \frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \texttt{src} (I)_c}{N} \\ \texttt{stddev} _c = \sqrt{\frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \left ( \texttt{src} (I)_c - \texttt{mean} _c \right )^2}{N}} \end{array}\f] When all the mask elements are 0's, the function returns mean=stddev=Scalar::all(0). @note The calculated standard deviation is only the diagonal of the complete normalized covariance matrix. If the full matrix is needed, you can reshape the multi-channel array M x N to the single-channel array M*N x mtx.channels() (only possible when the matrix is continuous) and then pass the matrix to calcCovarMatrix .
input array that should have from 1 to 4 channels so that the results can be stored in Scalar_ 's.
output parameter: calculated mean value.
output parameter: calculated standard deviation.
See also: countNonZero, mean, norm, minMaxLoc, calcCovarMatrix
meanStdDev ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); int [phys] normType(); [phys] mask(l3,c3,r3); double [o,phys] res())
Calculates the absolute norm of an array.
$res = norm($src1); # with defaults $res = norm($src1,$normType,$mask);
This version of #norm calculates the absolute norm of src1. The type of norm to calculate is specified using #NormTypes. As example for one array consider the function r(x)= \begin{pmatrix} x \\ 1-x \end{pmatrix}, x \in [-1;1]. The L_{1}, L_{2}and L_{\infty}norm for the sample value r(-1) = \begin{pmatrix} -1 \\ 2 \end{pmatrix}is calculated as follows \f{align*} \| r(-1) \|_{L_1} &= |-1| + |2| = 3 \\ \| r(-1) \|_{L_2} &= \sqrt{(-1)^{2} + (2)^{2}} = \sqrt{5} \\ \| r(-1) \|_{L_\infty} &= \max(|-1|,|2|) = 2 \f} and for r(0.5) = \begin{pmatrix} 0.5 \\ 0.5 \end{pmatrix}the calculation is \f{align*} \| r(0.5) \|_{L_1} &= |0.5| + |0.5| = 1 \\ \| r(0.5) \|_{L_2} &= \sqrt{(0.5)^{2} + (0.5)^{2}} = \sqrt{0.5} \\ \| r(0.5) \|_{L_\infty} &= \max(|0.5|,|0.5|) = 0.5. \f} The following graphic shows all values for the three norm functions \| r(x) \|_{L_1}, \| r(x) \|_{L_2}and \| r(x) \|_{L_\infty}. It is notable that the L_{1}norm forms the upper and the L_{\infty}norm forms the lower border for the example function r(x).  When the mask parameter is specified and it is not empty, the norm is If normType is not specified, #NORM_L2 is used. calculated only over the region specified by the mask. Multi-channel input arrays are treated as single-channel arrays, that is, the results for all channels are combined. Hamming norms can only be calculated with CV_8U depth arrays.
r(x)= \begin{pmatrix} x \\ 1-x \end{pmatrix}, x \in [-1;1]
L_{1}, L_{2}
L_{\infty}
r(-1) = \begin{pmatrix} -1 \\ 2 \end{pmatrix}
r(0.5) = \begin{pmatrix} 0.5 \\ 0.5 \end{pmatrix}
\| r(x) \|_{L_1}, \| r(x) \|_{L_2}
\| r(x) \|_{L_\infty}
L_{1}
r(x)
type of the norm (see #NormTypes).
optional operation mask; it must have the same size as src1 and CV_8UC1 type.
norm ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); int [phys] normType(); [phys] mask(l4,c4,r4); double [o,phys] res())
Calculates an absolute difference norm or a relative difference norm.
$res = norm2($src1,$src2); # with defaults $res = norm2($src1,$src2,$normType,$mask);
This version of cv::norm calculates the absolute difference norm or the relative difference norm of arrays src1 and src2. The type of norm to calculate is specified using #NormTypes.
norm2 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); double [phys] R(); double [o,phys] res())
Computes the Peak Signal-to-Noise Ratio (PSNR) image quality metric.
$res = PSNR($src1,$src2); # with defaults $res = PSNR($src1,$src2,$R);
This function calculates the Peak Signal-to-Noise Ratio (PSNR) image quality metric in decibels (dB), between two input arrays src1 and src2. The arrays must have the same type. The PSNR is calculated as follows: \f[ \texttt{PSNR} = 10 \cdot \log_{10}{\left( \frac{R^2}{MSE} \right) } \f] where R is the maximum integer value of depth (e.g. 255 in the case of CV_8U data) and MSE is the mean squared error between the two arrays.
second input array of the same size as src1.
the maximum pixel value (255 by default)
PSNR ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dist(l3,c3,r3); int [phys] dtype(); [o,phys] nidx(l5,c5,r5); int [phys] normType(); int [phys] K(); [phys] mask(l8,c8,r8); int [phys] update(); byte [phys] crosscheck())
naive nearest neighbor finder NO BROADCASTING.
($dist,$nidx) = batchDistance($src1,$src2,$dtype); # with defaults ($dist,$nidx) = batchDistance($src1,$src2,$dtype,$normType,$K,$mask,$update,$crosscheck);
see http://en.wikipedia.org/wiki/Nearest_neighbor_search @todo document
batchDistance ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [io,phys] dst(l2,c2,r2); double [phys] alpha(); double [phys] beta(); int [phys] norm_type(); int [phys] dtype(); [phys] mask(l7,c7,r7))
Normalizes the norm or value range of an array.
normalize($src,$dst); # with defaults normalize($src,$dst,$alpha,$beta,$norm_type,$dtype,$mask);
The function cv::normalize normalizes scale and shift the input array elements so that \f[\| \texttt{dst} \| _{L_p}= \texttt{alpha}\f] (where p=Inf, 1 or 2) when normType=NORM_INF, NORM_L1, or NORM_L2, respectively; or so that \f[\min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}\f] when normType=NORM_MINMAX (for dense arrays only). The optional mask specifies a sub-array to be normalized. This means that the norm or min-n-max are calculated over the sub-array, and then this sub-array is modified to be normalized. If you want to only use the mask to calculate the norm or min-max but modify the whole array, you can use norm and Mat::convertTo. 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. Possible usage with some positive example data:
{.cpp} vector<double> positiveData = { 2.0, 8.0, 10.0 }; vector<double> normalizedData_l1, normalizedData_l2, normalizedData_inf, normalizedData_minmax; // Norm to probability (total count) // sum(numbers) = 20.0 // 2.0 0.1 (2.0/20.0) // 8.0 0.4 (8.0/20.0) // 10.0 0.5 (10.0/20.0) normalize(positiveData, normalizedData_l1, 1.0, 0.0, NORM_L1); // Norm to unit vector: ||positiveData|| = 1.0 // 2.0 0.15 // 8.0 0.62 // 10.0 0.77 normalize(positiveData, normalizedData_l2, 1.0, 0.0, NORM_L2); // Norm to max element // 2.0 0.2 (2.0/10.0) // 8.0 0.8 (8.0/10.0) // 10.0 1.0 (10.0/10.0) normalize(positiveData, normalizedData_inf, 1.0, 0.0, NORM_INF); // Norm to range [0.0;1.0] // 2.0 0.0 (shift to left border) // 8.0 0.75 (6.0/8.0) // 10.0 1.0 (shift to right border) normalize(positiveData, normalizedData_minmax, 1.0, 0.0, NORM_MINMAX);
output array of the same size as src .
norm value to normalize to or the lower range boundary in case of the range normalization.
upper range boundary in case of the range normalization; it is not used for the norm normalization.
normalization type (see cv::NormTypes).
when negative, the output array has the same type as src; otherwise, it has the same number of channels as src and the depth =CV_MAT_DEPTH(dtype).
See also: norm, Mat::convertTo, SparseMat::convertTo
normalize ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); double [o,phys] minVal(); double [o,phys] maxVal(); indx [o,phys] minLoc(n4=2); indx [o,phys] maxLoc(n5=2); [phys] mask(l6,c6,r6))
Finds the global minimum and maximum in an array.
($minVal,$maxVal,$minLoc,$maxLoc) = minMaxLoc($src); # with defaults ($minVal,$maxVal,$minLoc,$maxLoc) = minMaxLoc($src,$mask);
The function cv::minMaxLoc finds the minimum and maximum element values and their positions. The extremums are searched across the whole array or, if mask is not an empty array, in the specified array region. The function do not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use Mat::reshape first to reinterpret the array as single-channel. Or you may extract the particular channel using either extractImageCOI , or mixChannels , or split .
input single-channel array.
pointer to the returned minimum value; NULL is used if not required.
pointer to the returned maximum value; NULL is used if not required.
pointer to the returned minimum location (in 2D case); NULL is used if not required.
pointer to the returned maximum location (in 2D case); NULL is used if not required.
optional mask used to select a sub-array.
See also: max, min, compare, inRange, extractImageCOI, mixChannels, split, Mat::reshape
minMaxLoc ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] dim(); int [phys] rtype(); int [phys] dtype())
Reduces a matrix to a vector. NO BROADCASTING.
$dst = reduce($src,$dim,$rtype); # with defaults $dst = reduce($src,$dim,$rtype,$dtype);
The function #reduce reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of #REDUCE_MAX and #REDUCE_MIN , the output image should have the same type as the source one. In case of #REDUCE_SUM and #REDUCE_AVG , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes. The following code demonstrates its usage for a single channel matrix. @snippet snippets/core_reduce.cpp example And the following code demonstrates its usage for a two-channel matrix. @snippet snippets/core_reduce.cpp example2
input 2D matrix.
output vector. Its size and type is defined by dim and dtype parameters.
dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row. 1 means that the matrix is reduced to a single column.
reduction operation that could be one of #ReduceTypes
when negative, the output vector will have the same type as the input matrix, otherwise, its type will be CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), src.channels()).
See also: repeat
reduce ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([o,phys] dst(l2,c2,r2); vector_MatWrapper * mv)
$dst = merge($mv);
input vector of matrices to be merged; all the matrices in mv must have the same size and the same depth.
output array of the same size and the same depth as mv[0]; The number of channels will be the total number of channels in the matrix array.
merge ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] m(l1,c1,r1); [o] vector_MatWrapper * mv)
$mv = split($m);
input multi-channel array.
output vector of arrays; the arrays themselves are reallocated, if needed.
split ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [phys] fromTo(n3d0); vector_MatWrapper * src; [o] vector_MatWrapper * dst)
mixChannels($src,$dst,$fromTo);
@overload *2] is a 0-based index of the input channel in src, fromTo[k*2+1] is an index of the output channel in dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to src[0].channels()-1, the second input image channels are indexed from src[0].channels() to src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image channels; as a special case, when fromTo[k*2] is negative, the corresponding output channel is filled with zero .
input array or vector of matrices; all of the matrices must have the same size and the same depth.
output array or vector of matrices; all the matrices **must be allocated**; their size and depth must be the same as in src[0].
array of index pairs specifying which channels are copied and where; fromTo[k
mixChannels ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] coi())
Extracts a single channel from src (coi is 0-based index) NO BROADCASTING.
$dst = extractChannel($src,$coi);
input array
output array
index of channel to extract
See also: mixChannels, split
extractChannel ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [io,phys] dst(l2,c2,r2); int [phys] coi())
Inserts a single channel to dst (coi is 0-based index)
insertChannel($src,$dst,$coi);
index of channel for insertion
See also: mixChannels, merge
insertChannel ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] flipCode())
Flips a 2D array around vertical, horizontal, or both axes. NO BROADCASTING.
$dst = flip($src,$flipCode);
The function cv::flip flips the array in one of three different ways (row and column indices are 0-based): \f[\texttt{dst} _{ij} = \left\{ \begin{array}{l l} \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 \\ \end{array} \right.\f] The example scenarios of using the function are the following: * Vertical flipping of the image (flipCode == 0) to switch between top-left and bottom-left image origin. This is a typical operation in video processing on Microsoft Windows* OS. * Horizontal flipping of the image with the subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (flipCode \> 0). * Simultaneous horizontal and vertical flipping of the image with the subsequent shift and absolute difference calculation to check for a central symmetry (flipCode \< 0). * Reversing the order of point arrays (flipCode \> 0 or flipCode == 0).
output array of the same size and type as src.
a flag to specify how to flip the array; 0 means flipping around the x-axis and positive value (for example, 1) means flipping around y-axis. Negative value (for example, -1) means flipping around both axes.
See also: transpose , repeat , completeSymm
flip ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] rotateCode())
Rotates a 2D array in multiples of 90 degrees. The function cv::rotate rotates the array in one of three different ways: * Rotate by 90 degrees clockwise (rotateCode = ROTATE_90_CLOCKWISE). * Rotate by 180 degrees clockwise (rotateCode = ROTATE_180). * Rotate by 270 degrees clockwise (rotateCode = ROTATE_90_COUNTERCLOCKWISE). NO BROADCASTING.
$dst = rotate($src,$rotateCode);
output array of the same type as src. The size is the same with ROTATE_180, and the rows and cols are switched for ROTATE_90_CLOCKWISE and ROTATE_90_COUNTERCLOCKWISE.
an enum to specify how to rotate the array; see the enum #RotateFlags
See also: transpose , repeat , completeSymm, flip, RotateFlags
rotate ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); int [phys] ny(); int [phys] nx(); [o,phys] dst(l4,c4,r4))
Fills the output array with repeated copies of the input array. NO BROADCASTING.
$dst = repeat($src,$ny,$nx);
The function cv::repeat duplicates the input array one or more times along each of the two axes: \f[\texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols }\f] The second variant of the function is more convenient to use with @ref MatrixExpressions.
input array to replicate.
Flag to specify how many times the `src` is repeated along the vertical axis.
Flag to specify how many times the `src` is repeated along the horizontal axis.
output array of the same type as `src`.
See also: cv::reduce
repeat ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([o,phys] dst(l2,c2,r2); vector_MatWrapper * src)
$dst = hconcat($src);
{.cpp} std::vector<cv::Mat> matrices = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)), cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)), cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),}; cv::Mat out; cv::hconcat( matrices, out ); //out: //[1, 2, 3; // 1, 2, 3; // 1, 2, 3; // 1, 2, 3]
input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
output array. It has the same number of rows and depth as the src, and the sum of cols of the src. same depth.
hconcat ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
$dst = vconcat($src);
{.cpp} std::vector<cv::Mat> matrices = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)), cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)), cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),}; cv::Mat out; cv::vconcat( matrices, out ); //out: //[1, 1, 1, 1; // 2, 2, 2, 2; // 3, 3, 3, 3]
input array or vector of matrices. all of the matrices must have the same number of cols and the same depth
output array. It has the same number of cols and depth as the src, and the sum of rows of the src. same depth.
vconcat ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3); [phys] mask(l4,c4,r4))
computes bitwise conjunction of the two arrays (dst = src1 & src2) Calculates the per-element bit-wise conjunction of two arrays or an array and a scalar. NO BROADCASTING.
$dst = bitwise_and($src1,$src2); # with defaults $dst = bitwise_and($src1,$src2,$mask);
The function cv::bitwise_and calculates the per-element bit-wise logical conjunction for: * Two arrays when src1 and src2 have the same size: \f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f] * An array and a scalar when src2 is constructed from Scalar or has the same number of elements as `src1.channels()`: \f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0\f] * A scalar and an array when src1 is constructed from Scalar or has the same number of elements as `src2.channels()`: \f[\texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f] In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the second and third cases above, the scalar is first converted to the array type.
output array that has the same size and type as the input arrays.
optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
bitwise_and ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the per-element bit-wise disjunction of two arrays or an array and a scalar. NO BROADCASTING.
$dst = bitwise_or($src1,$src2); # with defaults $dst = bitwise_or($src1,$src2,$mask);
The function cv::bitwise_or calculates the per-element bit-wise logical disjunction for: * Two arrays when src1 and src2 have the same size: \f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f] * An array and a scalar when src2 is constructed from Scalar or has the same number of elements as `src1.channels()`: \f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0\f] * A scalar and an array when src1 is constructed from Scalar or has the same number of elements as `src2.channels()`: \f[\texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f] In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the second and third cases above, the scalar is first converted to the array type.
bitwise_or ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the per-element bit-wise "exclusive or" operation on two arrays or an array and a scalar. NO BROADCASTING.
$dst = bitwise_xor($src1,$src2); # with defaults $dst = bitwise_xor($src1,$src2,$mask);
The function cv::bitwise_xor calculates the per-element bit-wise logical "exclusive-or" operation for: * Two arrays when src1 and src2 have the same size: \f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f] * An array and a scalar when src2 is constructed from Scalar or has the same number of elements as `src1.channels()`: \f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0\f] * A scalar and an array when src1 is constructed from Scalar or has the same number of elements as `src2.channels()`: \f[\texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f] In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the 2nd and 3rd cases above, the scalar is first converted to the array type.
bitwise_xor ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); [phys] mask(l3,c3,r3))
Inverts every bit of an array. NO BROADCASTING.
$dst = bitwise_not($src); # with defaults $dst = bitwise_not($src,$mask);
The function cv::bitwise_not calculates per-element bit-wise inversion of the input array: \f[\texttt{dst} (I) = \neg \texttt{src} (I)\f] In case of a floating-point input array, its machine-specific bit representation (usually IEEE754-compliant) is used for the operation. In case of multi-channel arrays, each channel is processed independently.
output array that has the same size and type as the input array.
bitwise_not ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3))
Calculates the per-element absolute difference between two arrays or between an array and a scalar. NO BROADCASTING.
$dst = absdiff($src1,$src2);
The function cv::absdiff calculates: * Absolute difference between two arrays when they have the same size and type: \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)\f] * Absolute difference between an array and a scalar when the second array is constructed from Scalar or has as many elements as the number of channels in `src1`: \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)\f] * Absolute difference between a scalar and an array when the first array is constructed from Scalar or has as many elements as the number of channels in `src2`: \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)\f] where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently. @note Saturation is not applied when the arrays have the depth CV_32S. You may even get a negative value in the case of overflow.
output array that has the same size and type as input arrays.
See also: cv::abs(const Mat&)
absdiff ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
This is an overloaded member function, provided for convenience (python) Copies the matrix to another one. When the operation mask is specified, if the Mat::create call shown above reallocates the matrix, the newly allocated matrix is initialized with all zeros before copying the data. NO BROADCASTING.
$dst = copyTo($src,$mask);
*this. Its non-zero elements indicate which matrix elements need to be copied. The mask has to be of type CV_8U and can have 1 or multiple channels.
source matrix.
Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.
Operation mask of the same size as
copyTo ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [phys] lowerb(l2,c2,r2); [phys] upperb(l3,c3,r3); [o,phys] dst(l4,c4,r4))
Checks if array elements lie between the elements of two other arrays. NO BROADCASTING.
$dst = inRange($src,$lowerb,$upperb);
The function checks the range as follows: =over =item * and so forth. =back That is, dst (I) is set to 255 (all 1 -bits) if src (I) is within the specified 1D, 2D, 3D, ... box and 0 otherwise. When the lower and/or upper boundary parameters are scalars, the indexes (I) at lowerb and upperb in the above formulas should be omitted.
inclusive lower boundary array or a scalar.
inclusive upper boundary array or a scalar.
output array of the same size as src and CV_8U type.
inRange ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3); int [phys] cmpop())
Performs the per-element comparison of two arrays or an array and scalar value. NO BROADCASTING.
$dst = compare($src1,$src2,$cmpop);
The function compares: * Elements of two arrays when src1 and src2 have the same size: \f[\texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I)\f] * Elements of src1 with a scalar src2 when src2 is constructed from Scalar or has a single element: \f[\texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2}\f] * src1 with elements of src2 when src1 is constructed from Scalar or has a single element: \f[\texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I)\f] When the comparison result is true, the corresponding element of output array is set to 255. The comparison operations can be replaced with the equivalent matrix expressions:
{.cpp} Mat dst1 = src1 >= src2; Mat dst2 = src1 < 8; ...
first input array or a scalar; when it is an array, it must have a single channel.
second input array or a scalar; when it is an array, it must have a single channel.
output array of type ref CV_8U that has the same size and the same number of channels as the input arrays.
a flag, that specifies correspondence between the arrays (cv::CmpTypes)
See also: checkRange, min, max, threshold
compare ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates per-element minimum of two arrays or an array and a scalar. NO BROADCASTING.
$dst = min($src1,$src2);
The function cv::min calculates the per-element minimum of two arrays: \f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I))\f] or array and a scalar: \f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )\f]
See also: max, compare, inRange, minMaxLoc
min ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates per-element maximum of two arrays or an array and a scalar. NO BROADCASTING.
$dst = max($src1,$src2);
The function cv::max calculates the per-element maximum of two arrays: \f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I))\f] or array and a scalar: \f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )\f] @ref MatrixExpressions
second input array of the same size and type as src1 .
See also: min, compare, inRange, minMaxLoc,
max ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates a square root of array elements. NO BROADCASTING.
$dst = sqrt($src);
The function cv::sqrt calculates a square root of each input array element. In case of multi-channel arrays, each channel is processed independently. The accuracy is approximately the same as of the built-in std::sqrt .
input floating-point array.
sqrt ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); double [phys] power(); [o,phys] dst(l3,c3,r3))
Raises every array element to a power. NO BROADCASTING.
$dst = pow($src,$power);
The function cv::pow raises every element of the input array to power : \f[\texttt{dst} (I) = \fork{\texttt{src}(I)^{power}}{if \(\texttt{power}\) is integer}{|\texttt{src}(I)|^{power}}{otherwise}\f] So, for a non-integer power exponent, the absolute values of input array elements are used. However, it is possible to get true values for negative values using some extra operations. In the example below, computing the 5th root of array src shows:
{.cpp} Mat mask = src < 0; pow(src, 1./5, dst); subtract(Scalar::all(0), dst, dst, mask);
For some values of power, such as integer values, 0.5 and -0.5, specialized faster algorithms are used. Special values (NaN, Inf) are not handled.
exponent of power.
See also: sqrt, exp, log, cartToPolar, polarToCart
pow ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the exponent of every array element. NO BROADCASTING.
$dst = exp($src);
The function cv::exp calculates the exponent of every element of the input array: \f[\texttt{dst} [I] = e^{ src(I) }\f] The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for double-precision input. Currently, the function converts denormalized values to zeros on output. Special values (NaN, Inf) are not handled.
See also: log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
exp ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the natural logarithm of every array element. NO BROADCASTING.
$dst = log($src);
The function cv::log calculates the natural logarithm of every element of the input array: \f[\texttt{dst} (I) = \log (\texttt{src}(I)) \f] Output on zero, negative and special (NaN, Inf) values is undefined.
output array of the same size and type as src .
See also: exp, cartToPolar, polarToCart, phase, pow, sqrt, magnitude
log ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] magnitude(l1,c1,r1); [phys] angle(l2,c2,r2); [o,phys] x(l3,c3,r3); [o,phys] y(l4,c4,r4); byte [phys] angleInDegrees())
Calculates x and y coordinates of 2D vectors from their magnitude and angle. NO BROADCASTING.
($x,$y) = polarToCart($magnitude,$angle); # with defaults ($x,$y) = polarToCart($magnitude,$angle,$angleInDegrees);
The function cv::polarToCart calculates the Cartesian coordinates of each 2D vector represented by the corresponding elements of magnitude and angle: \f[\begin{array}{l} \texttt{x} (I) = \texttt{magnitude} (I) \cos ( \texttt{angle} (I)) \\ \texttt{y} (I) = \texttt{magnitude} (I) \sin ( \texttt{angle} (I)) \\ \end{array}\f] The relative accuracy of the estimated coordinates is about 1e-6.
input floating-point array of magnitudes of 2D vectors; it can be an empty matrix (=Mat()), in this case, the function assumes that all the magnitudes are =1; if it is not empty, it must have the same size and type as angle.
input floating-point array of angles of 2D vectors.
output array of x-coordinates of 2D vectors; it has the same size and type as angle.
output array of y-coordinates of 2D vectors; it has the same size and type as angle.
when true, the input angles are measured in degrees, otherwise, they are measured in radians.
See also: cartToPolar, magnitude, phase, exp, log, pow, sqrt
polarToCart ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] x(l1,c1,r1); [phys] y(l2,c2,r2); [o,phys] magnitude(l3,c3,r3); [o,phys] angle(l4,c4,r4); byte [phys] angleInDegrees())
Calculates the magnitude and angle of 2D vectors. NO BROADCASTING.
($magnitude,$angle) = cartToPolar($x,$y); # with defaults ($magnitude,$angle) = cartToPolar($x,$y,$angleInDegrees);
The function cv::cartToPolar calculates either the magnitude, angle, or both for every 2D vector (x(I),y(I)): \f[\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}\f] The angles are calculated with accuracy about 0.3 degrees. For the point (0,0), the angle is set to 0. *Pi) or in degrees (0 to 360 degrees).
array of x-coordinates; this must be a single-precision or double-precision floating-point array.
array of y-coordinates, that must have the same size and same type as x.
output array of magnitudes of the same size and type as x.
output array of angles that has the same size and type as x; the angles are measured in radians (from 0 to 2
a flag, indicating whether the angles are measured in radians (which is by default), or in degrees.
See also: Sobel, Scharr
cartToPolar ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] x(l1,c1,r1); [phys] y(l2,c2,r2); [o,phys] angle(l3,c3,r3); byte [phys] angleInDegrees())
Calculates the rotation angle of 2D vectors. NO BROADCASTING.
$angle = phase($x,$y); # with defaults $angle = phase($x,$y,$angleInDegrees);
The function cv::phase calculates the rotation angle of each 2D vector that is formed from the corresponding elements of x and y : \f[\texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))\f] The angle estimation accuracy is about 0.3 degrees. When x(I)=y(I)=0 , the corresponding angle(I) is set to 0.
input floating-point array of x-coordinates of 2D vectors.
input array of y-coordinates of 2D vectors; it must have the same size and the same type as x.
output array of vector angles; it has the same size and same type as x .
when true, the function calculates the angle in degrees, otherwise, they are measured in radians.
phase ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] x(l1,c1,r1); [phys] y(l2,c2,r2); [o,phys] magnitude(l3,c3,r3))
Calculates the magnitude of 2D vectors. NO BROADCASTING.
$magnitude = magnitude($x,$y);
The function cv::magnitude calculates the magnitude of 2D vectors formed from the corresponding elements of x and y arrays: \f[\texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}\f]
floating-point array of x-coordinates of the vectors.
floating-point array of y-coordinates of the vectors; it must have the same size as x.
output array of the same size and type as x.
See also: cartToPolar, polarToCart, phase, sqrt
magnitude ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] a(l1,c1,r1); byte [phys] quiet(); indx [o,phys] pos(n3=2); double [phys] minVal(); double [phys] maxVal(); byte [o,phys] res())
Checks every element of an input array for invalid values.
($pos,$res) = checkRange($a); # with defaults ($pos,$res) = checkRange($a,$quiet,$minVal,$maxVal);
The function cv::checkRange checks that every array element is neither NaN nor infinite. When minVal \> -DBL_MAX and maxVal \< DBL_MAX, the function also checks that each value is between minVal and 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 pos (when pos != NULL). Then, the function either returns false (when quiet=true) or throws an exception.
a flag, indicating whether the functions quietly return false when the array elements are out of range or they throw an exception.
optional output parameter, when not NULL, must be a pointer to array of src.dims elements.
inclusive lower boundary of valid values range.
exclusive upper boundary of valid values range.
checkRange ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([io,phys] a(l1,c1,r1); double [phys] val())
converts NaNs to the given number
patchNaNs($a); # with defaults patchNaNs($a,$val);
input/output matrix (CV_32F type).
value to convert the NaNs
patchNaNs ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); double [phys] alpha(); [phys] src3(l4,c4,r4); double [phys] beta(); [o,phys] dst(l6,c6,r6); int [phys] flags())
Performs generalized matrix multiplication. NO BROADCASTING.
$dst = gemm($src1,$src2,$alpha,$src3,$beta); # with defaults $dst = gemm($src1,$src2,$alpha,$src3,$beta,$flags);
The function cv::gemm performs generalized matrix multiplication similar to the gemm functions in BLAS level 3. For example, `gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)` corresponds to \f[\texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T\f] In case of complex (two-channel) data, performed a complex matrix multiplication. The function can be replaced with a matrix expression. For example, the above call can be replaced with:
{.cpp} dst = alpha*src1.t()*src2 + beta*src3.t();
first multiplied input matrix that could be real(CV_32FC1, CV_64FC1) or complex(CV_32FC2, CV_64FC2).
second multiplied input matrix of the same type as src1.
weight of the matrix product.
third optional delta matrix added to the matrix product; it should have the same type as src1 and src2.
weight of src3.
output matrix; it has the proper size and the same type as input matrices.
operation flags (cv::GemmFlags)
See also: mulTransposed , transform
gemm ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); byte [phys] aTa(); [phys] delta(l4,c4,r4); double [phys] scale(); int [phys] dtype())
Calculates the product of a matrix and its transposition. NO BROADCASTING.
$dst = mulTransposed($src,$aTa); # with defaults $dst = mulTransposed($src,$aTa,$delta,$scale,$dtype);
The function cv::mulTransposed calculates the product of src and its transposition: \f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} )\f] if aTa=true , and \f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T\f] otherwise. The function is used to calculate the covariance matrix. With zero delta, it can be used as a faster substitute for general matrix product A*B when B=A'
input single-channel matrix. Note that unlike gemm, the function can multiply not only floating-point matrices.
output square matrix.
Flag specifying the multiplication ordering. See the description below.
Optional delta matrix subtracted from src before the multiplication. When the matrix is empty ( delta=noArray() ), it is assumed to be zero, that is, nothing is subtracted. If it has the same size as src , it is simply subtracted. Otherwise, it is "repeated" (see repeat ) to cover the full src and then subtracted. Type of the delta matrix, when it is not empty, must be the same as the type of created output matrix. See the dtype parameter description below.
Optional scale factor for the matrix product.
Optional type of the output matrix. When it is negative, the output matrix will have the same type as src . Otherwise, it will be type=CV_MAT_DEPTH(dtype) that should be either CV_32F or CV_64F .
See also: calcCovarMatrix, gemm, repeat, reduce
mulTransposed ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Transposes a matrix. NO BROADCASTING.
$dst = transpose($src);
The function cv::transpose transposes the matrix src : \f[\texttt{dst} (i,j) = \texttt{src} (j,i)\f] @note No complex conjugation is done in case of a complex matrix. It should be done separately if needed.
output array of the same type as src.
transpose ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); [phys] m(l3,c3,r3))
Performs the matrix transformation of every array element. NO BROADCASTING.
$dst = transform($src,$m);
The function cv::transform performs the matrix transformation of every element of the array src and stores the results in dst : \f[\texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I)\f] (when m.cols=src.channels() ), or \f[\texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1]\f] (when m.cols=src.channels()+1 ) Every element of the N -channel array src is interpreted as N -element vector that is transformed using the M x N or M x (N+1) matrix m to M-element vector - the corresponding element of the output array dst . The function may be used for geometrical transformation of N -dimensional points, arbitrary linear color space transformation (such as various kinds of RGB to YUV transforms), shuffling the image channels, and so forth.
input array that must have as many channels (1 to 4) as m.cols or m.cols-1.
output array of the same size and depth as src; it has as many channels as m.rows.
transformation 2x2 or 2x3 floating-point matrix.
See also: perspectiveTransform, getAffineTransform, estimateAffine2D, warpAffine, warpPerspective
transform ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Performs the perspective matrix transformation of vectors. NO BROADCASTING.
$dst = perspectiveTransform($src,$m);
The function cv::perspectiveTransform transforms every element of src by treating it as a 2D or 3D vector, in the following way: \f[(x, y, z) \rightarrow (x'/w, y'/w, z'/w)\f] where \f[(x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix}\f] and \f[w = \fork{w'}{if \(w' \ne 0\)}{\infty}{otherwise}\f] Here a 3D vector transformation is shown. In case of a 2D vector transformation, the z component is omitted. @note The function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use warpPerspective . If you have an inverse problem, that is, you want to compute the most probable perspective transformation out of several pairs of corresponding points, you can use getPerspectiveTransform or findHomography .
input two-channel or three-channel floating-point array; each element is a 2D/3D vector to be transformed.
3x3 or 4x4 floating-point transformation matrix.
See also: transform, warpPerspective, getPerspectiveTransform, findHomography
perspectiveTransform ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([io,phys] m(l1,c1,r1); byte [phys] lowerToUpper())
Copies the lower or the upper half of a square matrix to its another half.
completeSymm($m); # with defaults completeSymm($m,$lowerToUpper);
The function cv::completeSymm copies the lower or the upper half of a square matrix to its another half. The matrix diagonal remains unchanged: - \texttt{m}_{ij}=\texttt{m}_{ji}for i > jif lowerToUpper=false - \texttt{m}_{ij}=\texttt{m}_{ji}for i < jif lowerToUpper=true
\texttt{m}_{ij}=\texttt{m}_{ji}
i > j
i < j
input-output floating-point square matrix.
operation flag; if true, the lower half is copied to the upper half. Otherwise, the upper half is copied to the lower half.
See also: flip, transpose
completeSymm ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([io,phys] mtx(l1,c1,r1); double [phys] s(n2=4))
Initializes a scaled identity matrix.
setIdentity($mtx); # with defaults setIdentity($mtx,$s);
The function cv::setIdentity initializes a scaled identity matrix: \f[\texttt{mtx} (i,j)= \fork{\texttt{value}}{ if \(i=j\)}{0}{otherwise}\f] The function can also be emulated using the matrix initializers and the matrix expressions:
Mat A = Mat::eye(4, 3, CV_32F)*5; // A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
matrix to initialize (not necessarily square).
value to assign to diagonal elements.
See also: Mat::zeros, Mat::ones, Mat::setTo, Mat::operator=
setIdentity ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] mtx(l1,c1,r1); double [o,phys] res())
Returns the determinant of a square floating-point matrix.
$res = determinant($mtx);
The function cv::determinant calculates and returns the determinant of the specified matrix. For small matrices ( mtx.cols=mtx.rows\<=3 ), the direct method is used. For larger matrices, the function uses LU factorization with partial pivoting. For symmetric positively-determined matrices, it is also possible to use eigen decomposition to calculate the determinant. @ref MatrixExpressions
input matrix that must have CV_32FC1 or CV_64FC1 type and square size.
See also: trace, invert, solve, eigen,
determinant ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] mtx(l1,c1,r1); double [o,phys] res(n2=4))
Returns the trace of a matrix.
$res = trace($mtx);
The function cv::trace returns the sum of the diagonal elements of the matrix mtx . \f[\mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)\f]
input matrix.
trace ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] flags(); double [o,phys] res())
Finds the inverse or pseudo-inverse of a matrix. NO BROADCASTING.
($dst,$res) = invert($src); # with defaults ($dst,$res) = invert($src,$flags);
The function cv::invert inverts the matrix src and stores the result in dst . When the matrix src is singular or non-square, the function calculates the pseudo-inverse matrix (the dst matrix) so that norm(src*dst - I) is minimal, where I is an identity matrix. In case of the #DECOMP_LU method, the function returns non-zero value if the inverse has been successfully calculated and 0 if src is singular. In case of the #DECOMP_SVD method, the function returns the inverse condition number of src (the ratio of the smallest singular value to the largest singular value) and 0 if src is singular. The SVD method calculates a pseudo-inverse matrix if src is singular. Similarly to #DECOMP_LU, the method #DECOMP_CHOLESKY works only with non-singular square matrices that should also be symmetrical and positively defined. In this case, the function stores the inverted matrix in dst and returns non-zero. Otherwise, it returns 0.
input floating-point M x N matrix.
output matrix of N x M size and the same type as src.
inversion method (cv::DecompTypes)
See also: solve, SVD
invert ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src1(l1,c1,r1); [phys] src2(l2,c2,r2); [o,phys] dst(l3,c3,r3); int [phys] flags(); byte [o,phys] res())
Solves one or more linear systems or least-squares problems. NO BROADCASTING.
($dst,$res) = solve($src1,$src2); # with defaults ($dst,$res) = solve($src1,$src2,$flags);
The function cv::solve solves a linear system or least-squares problem (the latter is possible with SVD or QR methods, or by specifying the flag #DECOMP_NORMAL ): \f[\texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|\f] If #DECOMP_LU or #DECOMP_CHOLESKY method is used, the function returns 1 if src1 (or \texttt{src1}^T\texttt{src1}) is non-singular. Otherwise, it returns 0. In the latter case, dst is not valid. Other methods find a pseudo-solution in case of a singular left-hand side part. @note If you want to find a unity-norm solution of an under-defined singular system \texttt{src1}\cdot\texttt{dst}=0, the function solve will not do the work. Use SVD::solveZ instead.
\texttt{src1}^T\texttt{src1}
\texttt{src1}\cdot\texttt{dst}=0
input matrix on the left-hand side of the system.
input matrix on the right-hand side of the system.
output solution.
solution (matrix inversion) method (#DecompTypes)
See also: invert, SVD, eigen
solve ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] flags())
Sorts each row or each column of a matrix. NO BROADCASTING.
$dst = sort($src,$flags);
The function cv::sort sorts each matrix row or each matrix column in ascending or descending order. So you should pass two operation flags to get desired behaviour. If you want to sort matrix rows or columns lexicographically, you can use STL std::sort generic function with the proper comparison predicate.
operation flags, a combination of #SortFlags
See also: sortIdx, randShuffle
sort ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
$dst = sortIdx($src,$flags);
The function cv::sortIdx sorts each matrix row or each matrix column in the ascending or descending order. So you should pass two operation flags to get desired behaviour. Instead of reordering the elements themselves, it stores the indices of sorted elements in the output array. For example:
Mat A = Mat::eye(3,3,CV_32F), B; sortIdx(A, B, SORT_EVERY_ROW + SORT_ASCENDING); // B will probably contain // (because of equal elements in A some permutations are possible): // [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
output integer array of the same size as src.
operation flags that could be a combination of cv::SortFlags
See also: sort, randShuffle
sortIdx ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] coeffs(l1,c1,r1); [o,phys] roots(l2,c2,r2); int [o,phys] res())
Finds the real roots of a cubic equation. NO BROADCASTING.
($roots,$res) = solveCubic($coeffs);
The function solveCubic finds the real roots of a cubic equation: =over =back The roots are stored in the roots array.
equation coefficients, an array of 3 or 4 elements.
output array of real roots that has 1 or 3 elements.
Returns: number of real roots. It can be 0, 1 or 2.
solveCubic ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] coeffs(l1,c1,r1); [o,phys] roots(l2,c2,r2); int [phys] maxIters(); double [o,phys] res())
Finds the real or complex roots of a polynomial equation. NO BROADCASTING.
($roots,$res) = solvePoly($coeffs); # with defaults ($roots,$res) = solvePoly($coeffs,$maxIters);
The function cv::solvePoly finds real and complex roots of a polynomial equation: \f[\texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0\f]
array of polynomial coefficients.
output (complex) array of roots.
maximum number of iterations the algorithm does.
solvePoly ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] eigenvalues(l2,c2,r2); [o,phys] eigenvectors(l3,c3,r3); byte [o,phys] res())
Calculates eigenvalues and eigenvectors of a symmetric matrix. NO BROADCASTING.
($eigenvalues,$eigenvectors,$res) = eigen($src);
The function cv::eigen calculates just eigenvalues, or eigenvalues and eigenvectors of the symmetric matrix src:
src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
@note Use cv::eigenNonSymmetric for calculation of real eigenvalues and eigenvectors of non-symmetric matrix.
input matrix that must have CV_32FC1 or CV_64FC1 type, square size and be symmetrical (src ^T^ == src).
output vector of eigenvalues of the same type as src; the eigenvalues are stored in the descending order.
output matrix of eigenvectors; it has the same size and type as src; the eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues.
See also: eigenNonSymmetric, completeSymm , PCA
eigen ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] eigenvalues(l2,c2,r2); [o,phys] eigenvectors(l3,c3,r3))
Calculates eigenvalues and eigenvectors of a non-symmetric matrix (real eigenvalues only). NO BROADCASTING.
($eigenvalues,$eigenvectors) = eigenNonSymmetric($src);
@note Assumes real eigenvalues. The function calculates eigenvalues and eigenvectors (optional) of the square matrix src:
input matrix (CV_32FC1 or CV_64FC1 type).
output vector of eigenvalues (type is the same type as src).
output matrix of eigenvectors (type is the same type as src). The eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues.
See also: eigen
eigenNonSymmetric ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] samples(l1,c1,r1); [o,phys] covar(l2,c2,r2); [io,phys] mean(l3,c3,r3); int [phys] flags(); int [phys] ctype())
$covar = calcCovarMatrix($samples,$mean,$flags); # with defaults $covar = calcCovarMatrix($samples,$mean,$flags,$ctype);
@overload @note use #COVAR_ROWS or #COVAR_COLS flag
samples stored as rows/columns of a single matrix.
output covariance matrix of the type ctype and square size.
input or output (depending on the flags) array as the average value of the input vectors.
operation flags as a combination of #CovarFlags
type of the matrixl; it equals 'CV_64F' by default.
calcCovarMatrix ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] data(l1,c1,r1); [io,phys] mean(l2,c2,r2); [o,phys] eigenvectors(l3,c3,r3); int [phys] maxComponents())
$eigenvectors = PCACompute($data,$mean); # with defaults $eigenvectors = PCACompute($data,$mean,$maxComponents);
wrap PCA::operator()
PCACompute ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] data(l1,c1,r1); [io,phys] mean(l2,c2,r2); [o,phys] eigenvectors(l3,c3,r3); [o,phys] eigenvalues(l4,c4,r4); int [phys] maxComponents())
($eigenvectors,$eigenvalues) = PCACompute2($data,$mean); # with defaults ($eigenvectors,$eigenvalues) = PCACompute2($data,$mean,$maxComponents);
wrap PCA::operator() and add eigenvalues output parameter
PCACompute2 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] data(l1,c1,r1); [io,phys] mean(l2,c2,r2); [o,phys] eigenvectors(l3,c3,r3); double [phys] retainedVariance())
$eigenvectors = PCACompute3($data,$mean,$retainedVariance);
PCACompute3 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] data(l1,c1,r1); [io,phys] mean(l2,c2,r2); [o,phys] eigenvectors(l3,c3,r3); [o,phys] eigenvalues(l4,c4,r4); double [phys] retainedVariance())
($eigenvectors,$eigenvalues) = PCACompute4($data,$mean,$retainedVariance);
PCACompute4 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] data(l1,c1,r1); [phys] mean(l2,c2,r2); [phys] eigenvectors(l3,c3,r3); [o,phys] result(l4,c4,r4))
$result = PCAProject($data,$mean,$eigenvectors);
wrap PCA::project
PCAProject ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
$result = PCABackProject($data,$mean,$eigenvectors);
wrap PCA::backProject
PCABackProject ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] w(l2,c2,r2); [o,phys] u(l3,c3,r3); [o,phys] vt(l4,c4,r4); int [phys] flags())
($w,$u,$vt) = SVDecomp($src); # with defaults ($w,$u,$vt) = SVDecomp($src,$flags);
wrap SVD::compute
SVDecomp ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] w(l1,c1,r1); [phys] u(l2,c2,r2); [phys] vt(l3,c3,r3); [phys] rhs(l4,c4,r4); [o,phys] dst(l5,c5,r5))
$dst = SVBackSubst($w,$u,$vt,$rhs);
wrap SVD::backSubst
SVBackSubst ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] v1(l1,c1,r1); [phys] v2(l2,c2,r2); [phys] icovar(l3,c3,r3); double [o,phys] res())
Calculates the Mahalanobis distance between two vectors.
$res = Mahalanobis($v1,$v2,$icovar);
The function cv::Mahalanobis calculates and returns the weighted distance between two vectors: \f[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)})} }\f] The covariance matrix may be calculated using the #calcCovarMatrix function and then inverted using the invert function (preferably using the #DECOMP_SVD method, as the most accurate).
first 1D input vector.
second 1D input vector.
inverse covariance matrix.
Mahalanobis ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] src(l1,c1,r1); [o,phys] dst(l2,c2,r2); int [phys] flags(); int [phys] nonzeroRows())
Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array. NO BROADCASTING.
$dst = dft($src); # with defaults $dst = dft($src,$flags,$nonzeroRows);
The function cv::dft performs one of the following: =over =back F^{(N)}_{jk}=\exp(-2\pi i j k/N)and i=\sqrt{-1}- Inverse the Fourier transform of a 1D vector of N elements: \f[\begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array}\f] where F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T- Forward the 2D Fourier transform of a M x N matrix: \f[Y = F^{(M)} \cdot X \cdot F^{(N)}\f] - Inverse the 2D Fourier transform of a M x N matrix: \f[\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}\f] In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input spectrum of the inverse Fourier transform can be represented in a packed format called *CCS* (complex-conjugate-symmetrical). It was borrowed from IPL (Intel* Image Processing Library). Here is how 2D *CCS* spectrum looks: \f[\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}\f] In case of 1D transform of a real vector, the output looks like the first row of the matrix above. So, the function chooses an operation mode depending on the flags and size of the input array: =over =back If #DFT_SCALE is set, the scaling is done after the transformation. Unlike dct , the function supports arrays of arbitrary size. But only those arrays are processed efficiently, whose 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 calculated using the getOptimalDFTSize method. The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays:
F^{(N)}_{jk}=\exp(-2\pi i j k/N)
i=\sqrt{-1}
F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T
void convolveDFT(InputArray A, InputArray B, OutputArray C) { // reallocate the output array if needed C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type()); Size dftSize; // calculate the size of DFT transform dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1); dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1); // allocate temporary buffers and initialize them with 0's Mat tempA(dftSize, A.type(), Scalar::all(0)); Mat tempB(dftSize, B.type(), Scalar::all(0)); // copy A and B to the top-left corners of tempA and tempB, respectively Mat roiA(tempA, Rect(0,0,A.cols,A.rows)); A.copyTo(roiA); Mat roiB(tempB, Rect(0,0,B.cols,B.rows)); B.copyTo(roiB); // now transform the padded A & B in-place; // use "nonzeroRows" hint for faster processing dft(tempA, tempA, 0, A.rows); dft(tempB, tempB, 0, B.rows); // multiply the spectrums; // the function handles packed spectrum representations well mulSpectrums(tempA, tempB, tempA); // transform the product back from the frequency domain. // Even though all the result rows will be non-zero, // you need only the first C.rows of them, and thus you // pass nonzeroRows == C.rows dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows); // now copy the result back to C. tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C); // all the temporary buffers will be deallocated automatically }
To optimize this sample, consider the following approaches: =over =back All of the above improvements have been implemented in #matchTemplate and #filter2D . Therefore, by using them, you can get the performance even better than with the above theoretically optimal implementation. Though, those two functions actually calculate cross-correlation, not convolution, so you need to "flip" the second convolution operand B vertically and horizontally using flip . @note - An example using the discrete fourier transform can be found at opencv_source_code/samples/cpp/dft.cpp - (Python) An example using the dft functionality to perform Wiener deconvolution can be found at opencv_source/samples/python/deconvolution.py - (Python) An example rearranging the quadrants of a Fourier image can be found at opencv_source/samples/python/dft.py
input array that could be real or complex.
output array whose size and type depends on the flags .
transformation flags, representing a combination of the #DftFlags
when the parameter is not zero, the function assumes that only the first nonzeroRows rows of the input array (#DFT_INVERSE is not set) or only the first nonzeroRows of the output array (#DFT_INVERSE is set) contain non-zeros, thus, the function can handle the rest of the rows more efficiently and save some time; this technique is very useful for calculating array cross-correlation or convolution using DFT.
See also: dct , getOptimalDFTSize , mulSpectrums, filter2D , matchTemplate , flip , cartToPolar , magnitude , phase
dft ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the inverse Discrete Fourier Transform of a 1D or 2D array. NO BROADCASTING.
$dst = idft($src); # with defaults $dst = idft($src,$flags,$nonzeroRows);
idft(src, dst, flags) is equivalent to dft(src, dst, flags | #DFT_INVERSE) . @note None of dft and idft scales the result by default. So, you should pass #DFT_SCALE to one of dft or idft explicitly to make these transforms mutually inverse.
input floating-point real or complex array.
output array whose size and type depend on the flags.
operation flags (see dft and #DftFlags).
number of dst rows to process; the rest of the rows have undefined content (see the convolution sample in dft description.
See also: dft, dct, idct, mulSpectrums, getOptimalDFTSize
idft ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Performs a forward or inverse discrete Cosine transform of 1D or 2D array. NO BROADCASTING.
$dst = dct($src); # with defaults $dst = dct($src,$flags);
The function cv::dct performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D floating-point array: =over =back \alpha_0=1, \alpha_j=2for *j \> 0*. - Inverse Cosine transform of a 1D vector of N elements: \f[X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y\f] (since C^{(N)}is an orthogonal matrix, C^{(N)} \cdot \left(C^{(N)}\right)^T = I) - Forward 2D Cosine transform of M x N matrix: \f[Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T\f] - Inverse 2D Cosine transform of M x N matrix: \f[X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}\f] The function chooses the mode of operation by looking at the flags and size of the input array: =over =item * If (flags & #DCT_ROWS) != 0 , the function performs a 1D transform of each row. =item * If the array is a single column or a single row, the function performs a 1D transform. =item * If none of the above is true, the function performs a 2D transform. =back @note Currently dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you can pad the array when necessary. Also, the function performance depends very much, and not monotonically, on the array size (see getOptimalDFTSize ). In the current implementation DCT of a vector of size N is calculated via DFT of a vector of size N/2 . Thus, the optimal DCT size N1 \>= N can be calculated as:
\alpha_0=1
\alpha_j=2
C^{(N)}
C^{(N)} \cdot \left(C^{(N)}\right)^T = I
size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); } N1 = getOptimalDCTSize(N);
transformation flags as a combination of cv::DftFlags (DCT_*)
See also: dft , getOptimalDFTSize , idct
dct ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Calculates the inverse Discrete Cosine Transform of a 1D or 2D array. NO BROADCASTING.
$dst = idct($src); # with defaults $dst = idct($src,$flags);
idct(src, dst, flags) is equivalent to dct(src, dst, flags | DCT_INVERSE).
input floating-point single-channel array.
operation flags.
See also: dct, dft, idft, getOptimalDFTSize
idct ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] a(l1,c1,r1); [phys] b(l2,c2,r2); [o,phys] c(l3,c3,r3); int [phys] flags(); byte [phys] conjB())
Performs the per-element multiplication of two Fourier spectrums. NO BROADCASTING.
$c = mulSpectrums($a,$b,$flags); # with defaults $c = mulSpectrums($a,$b,$flags,$conjB);
The function cv::mulSpectrums performs the per-element multiplication of the two CCS-packed or complex matrices that are results of a real or complex Fourier transform. The function, together with dft and idft , may be used to calculate convolution (pass conjB=false ) or correlation (pass conjB=true ) of two arrays rapidly. When the arrays are complex, they are simply multiplied (per element) with an optional conjugation of the second-array elements. When the arrays are real, they are assumed to be CCS-packed (see dft for details).
output array of the same size and type as src1 .
operation flags; currently, the only supported flag is cv::DFT_ROWS, which indicates that each row of src1 and src2 is an independent 1D Fourier spectrum. If you do not want to use this flag, then simply add a `0` as value.
optional flag that conjugates the second input array before the multiplication (true) or not (false).
mulSpectrums ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Returns the optimal DFT size for a given vector size.
$res = getOptimalDFTSize($vecsize);
DFT performance is not a monotonic function of a vector size. Therefore, when you calculate convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to pad the input data with zeros to get a bit larger array that can be transformed much faster than the original one. Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process. Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5*5*3*2*2) are also processed quite efficiently. The function cv::getOptimalDFTSize returns the minimum number N that is greater than or equal to vecsize so that the DFT of a vector of size N can be processed efficiently. In the current implementation N = 2 ^p^ * 3 ^q^ * 5 ^r^ for some integer p, q, r. The function returns a negative number if vecsize is too large (very close to INT_MAX ). While the function cannot be used directly to estimate the optimal vector size for DCT transform (since the current DCT implementation supports only even-size vectors), it can be easily processed as getOptimalDFTSize((vecsize+1)/2)*2.
vector size.
See also: dft , dct , idft , idct , mulSpectrums
Sets state of default random number generator.
setRNGSeed($seed);
The function cv::setRNGSeed sets state of default random number generator to custom value.
new state for default random number generator
See also: RNG, randu, randn
Signature: ([io,phys] dst(l1,c1,r1); [phys] low(l2,c2,r2); [phys] high(l3,c3,r3))
Generates a single uniformly-distributed random number or an array of random numbers.
randu($dst,$low,$high);
Non-template variant of the function fills the matrix dst with uniformly-distributed random numbers from the specified range: \f[\texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c\f]
output array of random numbers; the array must be pre-allocated.
inclusive lower boundary of the generated random numbers.
exclusive upper boundary of the generated random numbers.
See also: RNG, randn, theRNG
randu ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([io,phys] dst(l1,c1,r1); [phys] mean(l2,c2,r2); [phys] stddev(l3,c3,r3))
Fills the array with normally distributed random numbers.
randn($dst,$mean,$stddev);
The function cv::randn fills the matrix dst with normally distributed random numbers with the specified mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the value range of the output array data type.
output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
mean value (expectation) of the generated random numbers.
standard deviation of the generated random numbers; it can be either a vector (in which case a diagonal standard deviation matrix is assumed) or a square matrix.
See also: RNG, randu
randn ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([io,phys] dst(l1,c1,r1); double [phys] iterFactor(); RNGWrapper * rng)
Shuffles the array elements randomly.
randShuffle($dst); # with defaults randShuffle($dst,$iterFactor,$rng);
The function cv::randShuffle shuffles the specified 1D array by randomly choosing pairs of elements and swapping them. The number of such swap operations will be dst.rows*dst.cols*iterFactor .
input/output numerical 1D array.
scale factor that determines the number of random swap operations (see the details below).
optional random number generator used for shuffling; if it is zero, theRNG () is used instead.
See also: RNG, sort
randShuffle ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: ([phys] data(l1,c1,r1); int [phys] K(); [io,phys] bestLabels(l3,c3,r3); int [phys] attempts(); int [phys] flags(); [o,phys] centers(l7,c7,r7); double [o,phys] res(); TermCriteriaWrapper * criteria)
Finds centers of clusters and groups input samples around the clusters. NO BROADCASTING.
($centers,$res) = kmeans($data,$K,$bestLabels,$criteria,$attempts,$flags);
The function kmeans implements a k-means algorithm that finds the centers of cluster_count clusters and groups the input samples around the clusters. As an output, \texttt{bestLabels}_icontains a 0-based cluster index for the sample stored in the i^{th}row of the samples matrix. @note - (Python) An example on K-means clustering can be found at opencv_source_code/samples/python/kmeans.py \<cv::Point2f\> points(sampleCount); \f[\sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2\f] after every attempt. The best (minimum) value is chosen and the corresponding labels and the compactness value are returned by the function. Basically, you can use only the core of the function, set the number of attempts to 1, initialize labels each time using a custom algorithm, pass them with the ( flags = #KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best (most-compact) clustering.
\texttt{bestLabels}_i
i^{th}
Data for clustering. An array of N-Dimensional points with float coordinates is needed. Examples of this array can be: - Mat points(count, 2, CV_32F); - Mat points(count, 1, CV_32FC2); - Mat points(1, count, CV_32FC2); - std::vector
Number of clusters to split the set by.
Input/output integer array that stores the cluster indices for every sample.
The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster centers moves by less than criteria.epsilon on some iteration, the algorithm stops.
Flag to specify the number of times the algorithm is executed using different initial labellings. The algorithm returns the labels that yield the best compactness (see the last function parameter).
Flag that can take values of cv::KmeansFlags
Output matrix of the cluster centers, one row per each cluster center.
Returns: The function returns the compactness measure that is computed as
kmeans ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
This is a base class for all more or less complex algorithms in OpenCV
especially for classes of algorithms, for which there can be multiple implementations. The examples are stereo correspondence (for which there are algorithms like block matching, semi-global block matching, graph-cut etc.), background subtraction (which can be done using mixture-of-gaussians models, codebook-based algorithm etc.), optical flow (block matching, Lucas-Kanade, Horn-Schunck etc.). Here is example of SimpleBlobDetector use in your application via Algorithm interface: @snippet snippets/core_various.cpp Algorithm
Clears the algorithm state
$obj->clear;
simplified API for language bindings *
$obj->write($fs); # with defaults $obj->write($fs,$name);
Reads algorithm parameters from a file storage
$obj->read($fn);
Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read
$res = $obj->empty;
$obj->save($filename);
Saves the algorithm to a file. In order to make this method work, the derived class must implement Algorithm::write(FileStorage& fs).
$res = $obj->getDefaultName;
Returns the algorithm string identifier. This string is used as top level xml/yml node tag when the object is saved to a file or string.
Class for matching keypoint descriptors
query descriptor index, train descriptor index, train image index, and distance between descriptors.
$obj = PDL::OpenCV::DMatch->new;
$obj = PDL::OpenCV::DMatch->new2($_queryIdx,$_trainIdx,$_distance);
$obj = PDL::OpenCV::DMatch->new3($_queryIdx,$_trainIdx,$_imgIdx,$_distance);
File Storage Node class.
The node is used to store each and every element of the file storage opened for reading. When XML/YAML file is read, it is first parsed and stored in the memory as a hierarchical collection of nodes. Each node can be a "leaf" that is contain a single number or a string, or be a collection of other nodes. There can be named collections (mappings) where each element has a name and it is accessed by a name, and ordered collections (sequences) where elements do not have names but rather accessed by index. Type of the file node can be determined using FileNode::type method. Note that file nodes are only used for navigating file storages opened for reading. When a file storage is opened for writing, no data is stored in memory after it is written.
The constructors.
$obj = PDL::OpenCV::FileNode->new;
These constructors are used to create a default file node, construct it from obsolete structures or from the another file node.
$res = $obj->getNode($nodename);
Name of an element in the mapping node.
$res = $obj->at($i);
Index of an element in the sequence node.
Signature: (P(); C(); FileNodeWrapper * self; [o] vector_StringWrapper * res)
Returns keys of a mapping node.
$res = $obj->keys;
Returns: Keys of a mapping node.
FileNode_keys ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Returns type of the node.
$res = $obj->type;
Returns: Type of the node. See FileNode::Type
$res = $obj->isNone;
$res = $obj->isSeq;
$res = $obj->isMap;
$res = $obj->isInt;
$res = $obj->isReal;
$res = $obj->isString;
$res = $obj->isNamed;
$res = $obj->name;
$res = $obj->size;
$res = $obj->rawSize;
$res = $obj->real;
Internal method used when reading FileStorage. Sets the type (int, real or string) and value of the previously created node.
$res = $obj->string;
Signature: ([o,phys] res(l2,c2,r2); FileNodeWrapper * self)
$res = $obj->mat;
FileNode_mat ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
XML/YAML/JSON file storage class that encapsulates all the information necessary for writing or reading data to/from a file.
$obj = PDL::OpenCV::FileStorage->new;
The full constructor opens the file. Alternatively you can use the default constructor and then call FileStorage::open.
$obj = PDL::OpenCV::FileStorage->new2($filename,$flags); # with defaults $obj = PDL::OpenCV::FileStorage->new2($filename,$flags,$encoding);
@overload @copydoc open()
Opens a file.
$res = $obj->open($filename,$flags); # with defaults $res = $obj->open($filename,$flags,$encoding);
See description of parameters in FileStorage::FileStorage. The method calls FileStorage::release before opening the file.
Name of the file to open or the text string to read the data from. Extension of the file (.xml, .yml/.yaml or .json) determines its format (XML, YAML or JSON respectively). Also you can append .gz to work with compressed files, for example myHugeMatrix.xml.gz. If both FileStorage::WRITE and FileStorage::MEMORY flags are specified, source is used just to specify the output file format (e.g. mydata.xml, .yml etc.). A file name can also contain parameters. You can use this format, "*?base64" (e.g. "file.json?base64" (case sensitive)), as an alternative to FileStorage::BASE64 flag.
Mode of operation. One of FileStorage::Mode
Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
Checks whether the file is opened.
$res = $obj->isOpened;
Returns: true if the object is associated with the current file and false otherwise. It is a good practice to call this method after you tried to open a file.
Closes the file and releases all the memory buffers.
$obj->release;
Call this method after all I/O operations with the storage are finished.
$res = $obj->releaseAndGetString;
Call this method after all I/O operations with the storage are finished. If the storage was opened for writing data and FileStorage::WRITE was specified
Returns the first element of the top-level mapping.
$res = $obj->getFirstTopLevelNode;
Returns: The first element of the top-level mapping.
Returns the top-level mapping
$res = $obj->root; # with defaults $res = $obj->root($streamidx);
Zero-based index of the stream. In most cases there is only one stream in the file. However, YAML supports multiple streams and so there can be several.
Returns: The top-level mapping.
Simplified writing API to use with bindings. *
$obj->write($name,$val);
*
Name of the written object. When writing to sequences (a.k.a. "arrays"), pass an empty string. *
Value of the written object.
$obj->write2($name,$val);
$obj->write3($name,$val);
Signature: ([phys] val(l3,c3,r3); FileStorageWrapper * self; StringWrapper* name)
$obj->write4($name,$val);
FileStorage_write4 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (P(); C(); FileStorageWrapper * self; StringWrapper* name; vector_StringWrapper * val)
$obj->write5($name,$val);
FileStorage_write5 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Writes a comment.
$obj->writeComment($comment); # with defaults $obj->writeComment($comment,$append);
The function writes a comment into file storage. The comments are skipped when the storage is read.
The written comment, single-line or multi-line
If true, the function tries to put the comment at the end of current line. Else if the comment is multi-line, or if it does not fit at the end of the current line, the comment starts a new line.
Starts to write a nested structure (sequence or a mapping).
$obj->startWriteStruct($name,$flags); # with defaults $obj->startWriteStruct($name,$flags,$typeName);
name of the structure. When writing to sequences (a.k.a. "arrays"), pass an empty string.
type of the structure (FileNode::MAP or FileNode::SEQ (both with optional FileNode::FLOW)).
optional name of the type you store. The effect of setting this depends on the storage format. I.e. if the format has a specification for storing type information, this parameter is used.
Finishes writing nested structure (should pair startWriteStruct())
$obj->endWriteStruct;
Returns the current format. *
$res = $obj->getFormat;
Returns: The current format, see FileStorage::Mode
Data structure for salient point detectors.
The class instance stores a keypoint, i.e. a point feature found by one of many available keypoint detectors, such as Harris corner detector, #FAST, %StarDetector, %SURF, %SIFT etc. The keypoint is characterized by the 2D position, scale (proportional to the diameter of the neighborhood that needs to be taken into account), orientation and some other parameters. The keypoint neighborhood is then analyzed by another algorithm that builds a descriptor (usually represented as a feature vector). The keypoints representing the same object in different images can then be matched using %KDTree or another method.
$obj = PDL::OpenCV::KeyPoint->new;
$obj = PDL::OpenCV::KeyPoint->new2($x,$y,$size); # with defaults $obj = PDL::OpenCV::KeyPoint->new2($x,$y,$size,$angle,$response,$octave,$class_id);
x-coordinate of the keypoint
y-coordinate of the keypoint
keypoint diameter
keypoint orientation
keypoint detector response on the keypoint (that is, strength of the keypoint)
pyramid octave in which the keypoint has been detected
object id
Signature: (float [o,phys] points2f(n2=2,n2d0); int [phys] keypointIndexes(n3d0); vector_KeyPointWrapper * keypoints)
$points2f = PDL::OpenCV::KeyPoint::convert($keypoints); # with defaults $points2f = PDL::OpenCV::KeyPoint::convert($keypoints,$keypointIndexes);
This method converts vector of keypoints to vector of points or the reverse, where each keypoint is assigned the same size and the same orientation.
Keypoints obtained from any feature detection algorithm like SIFT/SURF/ORB
Array of (x,y) coordinates of each keypoint
Array of indexes of keypoints to be converted to points. (Acts like a mask to convert only specified keypoints)
KeyPoint_convert ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (float [phys] points2f(n1=2,n1d0); float [phys] size(); float [phys] response(); int [phys] octave(); int [phys] class_id(); [o] vector_KeyPointWrapper * keypoints)
$keypoints = PDL::OpenCV::KeyPoint::convert2($points2f); # with defaults $keypoints = PDL::OpenCV::KeyPoint::convert2($points2f,$size,$response,$octave,$class_id);
KeyPoint_convert2 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
$res = PDL::OpenCV::KeyPoint::overlap($kp1,$kp2);
This method computes overlap for pair of keypoints. Overlap is the ratio between area of keypoint regions' intersection and area of keypoint regions' union (considering keypoint region as circle). If they don't overlap, we get zero. If they coincide at same location with same size, we get 1.
First keypoint
Second keypoint
struct returned by cv::moments
The spatial moments \texttt{Moments::m}_{ji}are computed as: \f[\texttt{m} _{ji}= \sum _{x,y} \left ( \texttt{array} (x,y) \cdot x^j \cdot y^i \right )\f] The central moments \texttt{Moments::mu}_{ji}are computed as: \f[\texttt{mu} _{ji}= \sum _{x,y} \left ( \texttt{array} (x,y) \cdot (x - \bar{x} )^j \cdot (y - \bar{y} )^i \right )\f] where (\bar{x}, \bar{y})is the mass center: \f[\bar{x} = \frac{\texttt{m}_{10}}{\texttt{m}_{00}} , \; \bar{y} = \frac{\texttt{m}_{01}}{\texttt{m}_{00}}\f] The normalized central moments \texttt{Moments::nu}_{ij}are computed as: \f[\texttt{nu} _{ji}= \frac{\texttt{mu}_{ji}}{\texttt{m}_{00}^{(i+j)/2+1}} .\f] @note \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. The moments of a contour are defined in the same way but computed using the Green's formula (see <http://en.wikipedia.org/wiki/Green_theorem>). So, due to a limited raster resolution, the moments computed for a contour are slightly different from the moments computed for the same rasterized contour. @note Since the contour moments are computed using Green formula, you may get seemingly odd results for contours with self-intersections, e.g. a zero area (m00) for butterfly-shaped contours.
\texttt{Moments::m}_{ji}
\texttt{Moments::mu}_{ji}
(\bar{x}, \bar{y})
\texttt{Moments::nu}_{ij}
\texttt{mu}_{00}=\texttt{m}_{00}
\texttt{nu}_{00}=1
\texttt{nu}_{10}=\texttt{mu}_{10}=\texttt{mu}_{01}=\texttt{mu}_{10}=0
Random Number Generator
Random number generator. It encapsulates the state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia ( <http://en.wikipedia.org/wiki/Multiply-with-carry> ). Gaussian-distribution random numbers are generated using the Ziggurat algorithm ( <http://en.wikipedia.org/wiki/Ziggurat_algorithm> ), introduced by G. Marsaglia and W. W. Tsang.
constructor
$obj = PDL::OpenCV::RNG->new;
These are the RNG constructors. The first form sets the state to some pre-defined value, equal to 2**32-1 in the current implementation. The second form sets the state to the specified value. If you passed state=0 , the constructor uses the above default value instead to avoid the singular random number sequence, consisting of all zeros.
$obj = PDL::OpenCV::RNG->new2($state);
64-bit value used to initialize the RNG.
Signature: ([io,phys] mat(l2,c2,r2); int [phys] distType(); [phys] a(l4,c4,r4); [phys] b(l5,c5,r5); byte [phys] saturateRange(); RNGWrapper * self)
Fills arrays with random numbers.
$obj->fill($mat,$distType,$a,$b); # with defaults $obj->fill($mat,$distType,$a,$b,$saturateRange);
Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In case of multiple-channel images, every channel is filled independently, which means that RNG cannot generate samples from the multi-dimensional Gaussian distribution with non-diagonal covariance matrix directly. To do that, the method generates samples from multi-dimensional standard Gaussian distribution with zero mean and identity covariation matrix, and then transforms them using transform to get samples from the specified Gaussian distribution.
2D or N-dimensional matrix; currently matrices with more than 4 channels are not supported by the methods, use Mat::reshape as a possible workaround.
distribution type, RNG::UNIFORM or RNG::NORMAL.
first distribution parameter; in case of the uniform distribution, this is an inclusive lower boundary, in case of the normal distribution, this is a mean value.
second distribution parameter; in case of the uniform distribution, this is a non-inclusive upper boundary, in case of the normal distribution, this is a standard deviation (diagonal of the standard deviation matrix or the full standard deviation matrix).
pre-saturation flag; for uniform distribution only; if true, the method will first convert a and b to the acceptable value range (according to the mat datatype) and then will generate uniformly distributed random numbers within the range [saturate(a), saturate(b)), if saturateRange=false, the method will generate uniformly distributed random numbers in the original range [a, b) and then will saturate them, it means, for example, that <tt>theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX)</tt> will likely produce array mostly filled with 0's and 255's, since the range (0, 255) is significantly smaller than [-DBL_MAX, DBL_MAX).
RNG_fill ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Mersenne Twister random number generator
Inspired by http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/mt19937ar.c @todo document
The class represents rotated (i.e. not up-right) rectangles on a plane.
Each rectangle is specified by the center point (mass center), length of each side (represented by #Size2f structure) and the rotation angle in degrees. The sample below demonstrates how to use RotatedRect: @snippet snippets/core_various.cpp RotatedRect_demo  See also: CamShift, fitEllipse, minAreaRect, CvBox2D
$obj = PDL::OpenCV::RotatedRect->new;
Signature: (float [phys] center(n2=2); float [phys] size(n3=2); float [phys] angle(); char * klass; [o] RotatedRectWrapper * res)
$obj = PDL::OpenCV::RotatedRect->new2($center,$size,$angle);
full constructor
The rectangle mass center.
Width and height of the rectangle.
The rotation angle in a clockwise direction. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
RotatedRect_new2 ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (indx [o,phys] res(n2=4); RotatedRectWrapper * self)
$res = $obj->boundingRect;
returns 4 vertices of the rectangle
The points array for storing rectangle vertices. The order is bottomLeft, topLeft, topRight, bottomRight.
RotatedRect_boundingRect ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
The class defining termination criteria for iterative algorithms.
You can initialize it by default constructor and then override any parameters, or the structure may be fully initialized using the advanced variant of the constructor.
$obj = PDL::OpenCV::TermCriteria->new;
$obj = PDL::OpenCV::TermCriteria->new2($type,$maxCount,$epsilon);
The type of termination criteria, one of TermCriteria::Type
The maximum number of iterations or elements to compute.
The desired accuracy or change in parameters at which the iterative algorithm stops.
Please report bugs at https://github.com/PDLPorters/PDL-OpenCV/issues, or on the mailing list(s) at https://pdl.perl.org/?page=mailing-lists.
Ingo Schmid and the PDL Porters. Same terms as PDL itself.
To install PDL::OpenCV, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL::OpenCV
CPAN shell
perl -MCPAN -e shell install PDL::OpenCV
For more information on module installation, please visit the detailed CPAN module installation guide.