# Differences

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

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:
+
+  * **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.
+  * **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::​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.