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

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