# OpenCV's Mat class

These are my own notes based on 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

• 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

• 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 3×3 or 4×4 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.

### 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.
• 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::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. 