Differences

This shows you the differences between two versions of the page.

Link to this comparison view

opencv:mat_class [2013/05/19 01:03]
jongbor [Accessing matrix elements]
opencv:mat_class [2014/04/19 15:41] (current)
Line 1: Line 1:
 +====== OpenCV'​s Mat class ======
  
 +These are my own notes based on [[http://​docs.opencv.org/​modules/​core/​doc/​basic_structures.html|OpenCV'​s documentation]]. The main difference is that I categorize functions in a way that helps me remember them better. So this is more of a cheat sheet. As long as it beats alphabetical listing... ​
 +
 +===== Matrix operations =====
 +
 +Let's start with the fun part, the one about doing actual work with matrices: sums, multiplications,​ transposes, inverses, decompositions... Note that many interesting matrix operations in OpenCV are not instance methods of Mat, but functions in the cv namespace. Many of these functions take a reference to a Mat in which the output of the operation is written. Sometimes, functions return objects of class MatExpr, which can be assigned to a Mat object or further as part of more complex operations.
 +
 +==== Basic matrix expressions ====
 +
 +  * **Addition, substraction**:​ A+B, A-B
 +  * **Scaling**:​ -A, A*s
 +  * **Matrix multiplication**:​ A*B
 +
 +==== Element-wise arithmetic operations ====
 +
 +Symbolic:
 +
 +  * **Addition**:​ A+s, A-s, s+A, s-A
 +  * **Multiplication and division**: A/B, s/A
 +  * **Comparison**:​ A cmp B, A cmp s, s cmp A where cmp is one of >, >=, ==, !=, <=, <. The result is 255 if true, 0 if false.
 +
 +Functions or methods:
 +
 +  * **add**(A,​B,​out,​mask)
 +  * **subtract**(A,​B,​out,​mask)
 +  * **divide**(A,​B,​out,​scale)
 +  * **multiply**(A,​B,​out,​scale),​ **Mat::​mul**(A)
 +  * **absdiff**(A,​B,​out)
 +
 +==== Bitwise operations ====
 +
 +  * **Bitwise operations**:​ A op B, A op s, s op A, ~A where op is one of &, |, ^.
 +  * **bitwise_and**(A,​B,​out)
 +  * **bitwise_or**(A,​B,​out)
 +  * **bitwise_xor**(A,​B,​out)
 +  * **bitwise_not**(A,​out)
 + 
 +==== Elementary functions ====
 +
 +  * **abs**(A)
 +  * **exp**(A,​out)
 +  * **log**(A,​out)
 +  * **pow**(A,​exponent,​out)
 +  * **sqrt**(A,​out)
 +
 +==== Algebraic combinations ====
 +
 +  * **scaleAdd**(A,​alpha,​B,​out):​ alpha*A + B.
 +  * **addWeighted**(A,​alpha,​B,​beta,​gamma,​out):​ alpha*A + beta*B + gamma.
 +  * **convertScaleAbs**(A,​out,​alpha,​beta):​ alpha*A + beta and casting to uchar.
 +  * **gemm**(A,​B,​alpha,​C,​gamma,​out,​transpose):​ alpha*A*B + beta*C with additive flags GEMM_1_T, GEMM_2_T, GEMM_3_T to transpose A, B or C respectively.
 +  * **mulTransposed**(A,​out,​aTa,​delta,​scale):​ scale * (A-delta)'​ * (A-delta) if aTa is true, else scale * (A-delta) * (A-delta)'​.
 +
 +==== Unary matrix operations ====
 +
 +  * **transpose**(A,​out),​ **Mat::​t**()
 +  * **invert**(A,​out,​flags),​ **Mat::​inv**()
 +  * **determinant**(A)
 +  * **trace**(A)
 +  * **norm**(A,​normType)
 +  * **norm**(A,​B,​normType):​ norm of A-B (not unary but fits here).
 +  * **normalize**(A,​out,​alpha,​beta,​norm_type):​ transform A so that norm(A) = alpha.
 +
 +==== Aggregate operation ====
 +
 +  * **min**(A,​B),​ **min**(A,​B,​out):​ element-wise minimum.
 +  * **min**(A,​s),​ **min**(s,​A),​ **min**(A,​s,​out):​ minimum between array and scalar.
 +  * **max**(A,​B),​ **max**(A,​B,​out):​ element-wise maximum.
 +  * **max**(A,​s),​ **max**(s,​A),​ **max**(A,​s,​out):​ maximum between array and scalar.
 +  * **minMaxLoc**(A,​minVal,​maxVal,​minLoc,​maxLoc,​mask) ​   ​
 +  * **minMaxIdx**(A,​minVal,​maxVal,​minIdx,​maxIdx,​mask)
 +  * **reduce**(A,​out,​dim,​rtype):​ reduces matrix to a sum/​min/​max/​avg along rows/cols.
 +  * **sum**(A): returns one scalar per channel. Not the same as add!
 +  * **countNonZero**(A)
 +  ​
 +==== Comparisons and ranges ====
 +
 +  * **checkRange**(A,​quiet,​position,​min,​max):​ check that values are in range, optionally throwing exception and optionally storing position of outlier.
 +  * **inRange**(A,​Lower,​Upper,​out):​ sets 0 when element not in range, 255 if element in range.  ​
 +  * **compare**(A,​B,​out,​op):​ element-wise comparison.
 +
 +==== Polar coordinates ====
 +
 +  * **cartToPolar**(X,​Y,​magnitude,​angle)
 +  * **polarToCart**(magnitude,​angle,​X,​Y)
 +  * **magnitude**(X,​Y,​out):​ sqrt(X^2 + Y^2) element-wise
 +  * **phase**(X,​Y,​out):​ atan2(Y,X) element-wise
 +
 +==== Vector operations ====
 +
 +  * **Mat::​cross**(v):​ cross products (only with vectors of size 3).
 +  * **Mat::​dot**(v):​ dot product.
 +  * **Mahalanobis**(v1,​v2,​covar):​ Mahalanobis distance between two vectors using a covariance matrix covar.
 +
 +==== Misc ====
 +
 +  * **flip**(A,​out,​how)
 +  * **LUT**(A,​lut,​out):​ transform A according to look up table.
 +  * **perspectiveTransform**(A,​out,​M):​ A must be a 2-channel or 3-channel array; each is a 2D or 3D vector. M is a 3x3 or 4x4 matrix (homogeneous coordinates...).
 +
 +  * **completeSymm**(A,​lowerToUpper=false):​ copies lower or upper half of matrix.
 +  * **getConvertElem**(fromType,​toType):​ get pointer to function that converts pixels.
 +
 +==== Solving equations ====
 +
 +  * **solve**(A,​b,​out,​flags):​ solve linear systems.
 +  * **solveCubic**(coeffs,​roots):​ find real roots of cubic equation.
 +  * **solvePoly**(coeffs,​roots,​maxIters):​ find real or complex roots of polynomial equation.
 +
 +==== Randomness ====
 +
 +  * **RNG**
 +  * RNG::RNG
 +  * RNG::next
 +  * RNG::​operator T
 +  * RNG::​operator ()
 +  * RNG::​uniform
 +  * RNG::​gaussian
 +  * RNG::fill
 +  * **theRNG**
 +  * **randu**(A,​low,​high):​ fill A with uniformly distributed values.
 +  * **randn**(A,​mean,​stddev):​ fill A with normally distributed values.
 +  * **randShuffle**(A):​ shuffle A.
 +  * **sort**(A,​out,​flags):​ sort each row or each column.
 +  * **sortIdx**(A,​out,​flags):​ sort each row or each column, but store sorted indices instead of elements themselves.
 +
 +==== Channel manipulation ====
 +
 +  * **split**(A,​Mats):​ divide multi-channel array.
 +  * **merge**(Mats,​A):​ create multi-channel array out of single-channel ones.
 +  * **transform**(A,​out,​M):​ transform each multi-channel element of A by multiplying it by M. Useful for color transforms, shuffling channels, etc.
 +  * **extractImageCOI**(CvArr*,​out):​ extract image channel from old-style array.
 +  * **insertImageCOI**(in,​CvArr*):​ copy image channel to old-style array.
 +  * **mixChannels**:​ advanced channel shuffling.
 +
 +==== Statistics ====
 +
 +  * **mean**(A):​ mean of each channel.
 +  * **meanStdDev**(A,​mean,​stddev,​mask):​ per-channel mean and standard deviation.
 +  * **calcCovarMatrix**(samples,​outCovar,​outMean,​flags):​ calculate covariance matrix and, optionally, mean vector.
 +
 +==== Fourier and Fourier related transforms ====
 +
 +  * **dct**
 +  * **dft**
 +  * **idct**
 +  * **idft**
 +  * **mulSpectrums**
 +  * **getOptimalDFTSize**
 +  ​
 +==== Matrix decompositions ====
 +
 +  * **eigen**(A,​eigenvalues,​eigenvectors)
 +  * **PCA**
 +  * PCA::PCA
 +  * PCA::​operator ()
 +  * PCA::​project
 +  * PCA::​backProject
 +  * **SVD**
 +  * SVD::SVD
 +  * SVD::​operator ()
 +  * SVD::​compute
 +  * SVD::solveZ
 +  * SVD::​backSubst
 +
 +
 +===== Getting matrix information =====
 +
 +  * **Mat::​type**():​ returns CV_[depth_and_type]C[number_of_channels],​ for example CV_8UC3, a 8-bit unsigned 3-channel array.
 +  * **Mat::​depth**():​ returns CV_[depth_and_type],​ for example CV_8U (8-bit unsigned), CV_64F (64-bit floating point).
 +  * **Mat::​channels**():​ returns number of channels.
 +  * **Mat::​size**():​ returns Size(cols,​rows) object.
 +  * **Mat::​empty**():​ true if matrix has no elements.
 +  * **Mat::​total**():​ returns total number of array elements.
 +
 +  * **Mat::​elemSize**
 +  * **Mat::​elemSize1**
 +  * **Mat::​step1**
 +
 +===== Matrix creation =====
 +
 +  * **Mat::​create**(rows,​cols,​type),​ **Mat::​create**(size,​type),​ **Mat::​create**(ndims,​sz):​ if create **if needed**. This saves work.
 +  * **Mat::​clone**()
 +  * **Mat::​copyTo**(out[,​mask])
 +  * **Mat::​convertTo**(out,​rtype,​alpha,​beta):​ convert matrix to desired depth with optional scaling (alpha * this + beta).
 +  * **Mat::​assignTo**(out,​type):​ not sure about the difference with convertTo.
 +
 +  * **Mat::​zeros**(rows,​cols,​type),​ **Mat::​zeros**(size,​type),​ **Mat::​zeros**(ndims,​sz)
 +  * **Mat::​ones**(rows,​cols,​type),​ **Mat::​ones**(size,​type),​ **Mat::​ones**(ndims,​sz)
 +  * **Mat::​eye**(rows,​cols,​type),​ **Mat::​eye**(size,​type):​ identity matrix.
 +
 +  * **Mat::​addref**():​ increment reference counter.
 +  * **Mat::​release**():​ decrement reference counter and deallocate if needed.
 +  * **Mat::​reserve**(nrows):​ reserve space for nrows rows.
 +  * **Mat::​isContinuous**():​ true if elements are stored continuously without gaps.
 +
 +  * **Mat::​diag**(vector):​ create matrix (header) from vector. The vector is placed in the diagonal.
 +
 +  * **cvarrToMat**(CvArr* arr): convert CvMat, IplImage or CvMatND to Mat.
 +  * **Mat::​operator CvMat**(): create CvMat header.
 +  * **Mat::​operator IplImage**():​ create IplImage header.
 +
 +===== Accessing matrix elements =====
 +
 +  * **Mat::​at**(...):​ element access.
 +
 +  * **Mat::​row**(y):​ create matrix header for row.
 +  * **Mat::​col**(x):​ create matrix header for column.
 +  * **Mat::​rowRange**(startrow,​endrow),​ **Mat::​rowRange**(range):​ create matrix header for row range.
 +  * **Mat::​colRange**(startcol,​endcol),​ **Mat::​colRange**(range):​ create matrix header for column range.
 +  * **Mat::​diag**(diagnum):​ create header for matrix diagonal (represented as a column vector). diagnum=0 is the main diagonal, diagnum>​0 is for the upper half and diagnum<​0 is for the lower half.
 +  * **Mat::​reshape**(channels,​rows=0):​ create matrix header for the same data (no data is copied) but with a different number of channels and a different number of rows.
 +
 +  * **Mat::​begin**():​ iterator for matrix elements set to first element.
 +  * **Mat::​end**():​ iterator for matrix elements set to after-last matrix element.
 +
 +  * **Mat::​ptr**(row):​ returns uchar* pointer to row.
 +
 +===== Using regions of interest (ROI) =====
 +
 +Regions of interest are Mat's that reference data from a bigger matrix but are matrices in their own right.
 +
 +  * **Mat::​operator()**(rowRange,​colRange),​ **Mat::​operator()**(rect),​ **Mat::​operator()**(ranges):​ extract a ROI.
 +  * **Mat::​locateROI**(outSize,​outOffset):​ get size of parent matrix and offset of ROI within parent matrix.
 +  * **Mat::​adjustROI**(dtop,​dbottom,​dleft,​dright):​ adjust size of ROI.
 +
 +===== Modifying a matrix =====
 +
 +  * **Mat::​push_back**(elem):​ add elements to the bottom of matrix.
 +  * **Mat::​pop_back**(nelems=1):​ remove rows from the bottom of matrix.
 +  * **Mat::​setTo**(value,​mask):​ sets matrix to a scalar value. For example, to set a color: m.setTo(CV_RGB(120,​240,​0)).
 +  * **Mat::​resize**(size,​scalar):​ change number of rows, fill with optional scalar.
 +
 +  * **setIdentity**(A,​s):​ initialize an identity matrix scaled by s.
 +  * **repeat**(A,​ny,​nx,​out),​ Mat = repeat(A,​ny,​nx):​ repeat matrix A the specified number of times.