Array Operations

Arithmetic Operations

add

void add(InputArray src1, InputArray src2, OutputArray dst,
         InputArray mask = noArray(), int dtype = -1)

Calculates the per-element sum of two arrays or an array and a scalar.

InputArray

First input array or scalar

InputArray

Second input array or scalar

OutputArray

Output array with the same size and number of channels as input arrays

InputArray

Optional 8-bit single channel mask that specifies elements to be changed

int

Optional depth of the output array. Default is -1 (same as input)

Formula:

dst(I) = saturate(src1(I) + src2(I)) if mask(I) ≠ 0

Example:

Mat A(100, 100, CV_8UC1, Scalar(50));
Mat B(100, 100, CV_8UC1, Scalar(100));
Mat C;
add(A, B, C); // C = A + B

// Equivalent matrix expression
C = A + B;

Saturation is not applied when the output array has depth CV_32S. You may get incorrect sign in case of overflow.

subtract

void subtract(InputArray src1, InputArray src2, OutputArray dst,
              InputArray mask = noArray(), int dtype = -1)

Calculates the per-element difference between two arrays or array and a scalar.

InputArray

First input array or scalar

InputArray

Second input array or scalar

OutputArray

Output array

InputArray

Optional operation mask

int

Optional depth of the output array

Formula:

dst(I) = saturate(src1(I) - src2(I)) if mask(I) ≠ 0

Example:

Mat result;
subtract(imageA, imageB, result);
// Equivalent: result = imageA - imageB;

multiply

void multiply(InputArray src1, InputArray src2, OutputArray dst,
              double scale = 1, int dtype = -1)

Calculates the per-element scaled product of two arrays.

InputArray

First input array

InputArray

Second input array of the same size and type as src1

OutputArray

Output array

double

Optional scale factor

int

Optional depth of the output array

Formula:

dst(I) = saturate(scale · src1(I) · src2(I))

Example:

Mat A, B, C;
multiply(A, B, C, 2.5); // Element-wise multiplication with scaling

For matrix multiplication (not element-wise), use gemm() function.

divide

void divide(InputArray src1, InputArray src2, OutputArray dst,
            double scale = 1, int dtype = -1)
void divide(double scale, InputArray src2, OutputArray dst, int dtype = -1)

Performs per-element division of two arrays or a scalar by an array.

InputArray

First input array (numerator)

InputArray

Second input array (denominator)

double

Scalar factor

OutputArray

Output array

Formula:

dst(I) = saturate(src1(I) * scale / src2(I))
dst(I) = saturate(scale / src2(I))  // Second overload

Example:

Mat A, B, C;
divide(A, B, C); // Element-wise division
divide(255.0, B, C); // Scalar divided by array

For integer types, when src2(I) is zero, dst(I) will also be zero. For floating-point data, expect IEEE-754 behavior (NaN, Inf values).

scaleAdd

void scaleAdd(InputArray src1, double alpha, InputArray src2, OutputArray dst)

Calculates the sum of a scaled array and another array (SAXPY/DAXPY operation).

InputArray

First input array

double

Scale factor for the first array

InputArray

Second input array (same size and type as src1)

OutputArray

Output array

Formula:

dst(I) = scale · src1(I) + src2(I)

Example:

Mat A, B, C;
scaleAdd(A, 2.0, B, C); // C = 2*A + B

addWeighted

void addWeighted(InputArray src1, double alpha, InputArray src2,
                 double beta, double gamma, OutputArray dst, int dtype = -1)

Calculates the weighted sum of two arrays.

InputArray

First input array

double

Weight of the first array elements

InputArray

Second input array

double

Weight of the second array elements

double

Scalar added to each sum

OutputArray

Output array

Formula:

dst(I) = saturate(src1(I) · alpha + src2(I) · beta + gamma)

Example:

// Image blending
Mat img1, img2, blended;
addWeighted(img1, 0.7, img2, 0.3, 0.0, blended);

Bitwise Operations

bitwise_and

void bitwise_and(InputArray src1, InputArray src2, OutputArray dst,
                 InputArray mask = noArray())

Calculates per-element bit-wise conjunction of two arrays or array and a scalar.

InputArray

First input array or scalar

InputArray

Second input array or scalar

OutputArray

Output array

InputArray

Optional operation mask

Formula:

dst(I) = src1(I) & src2(I) if mask(I) ≠ 0

bitwise_or

void bitwise_or(InputArray src1, InputArray src2, OutputArray dst,
                InputArray mask = noArray())

Calculates per-element bit-wise disjunction of two arrays or array and a scalar. Formula:

dst(I) = src1(I) | src2(I) if mask(I) ≠ 0

bitwise_xor

void bitwise_xor(InputArray src1, InputArray src2, OutputArray dst,
                 InputArray mask = noArray())

Calculates per-element bit-wise exclusive OR of two arrays or array and a scalar. Formula:

dst(I) = src1(I) ^ src2(I) if mask(I) ≠ 0

bitwise_not

void bitwise_not(InputArray src, OutputArray dst, InputArray mask = noArray())

Inverts every bit of an array.

InputArray

Input array

OutputArray

Output array

Formula:

dst(I) = ~src(I) if mask(I) ≠ 0

Example:

Mat mask, inverted_mask;
bitwise_not(mask, inverted_mask);

Comparison Operations

compare

void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop)

Performs per-element comparison of two arrays or array and scalar.

InputArray

First input array or scalar

InputArray

Second input array or scalar

OutputArray

Output array of type CV_8U (0 or 255 values)

int

Comparison operation: CMP_EQ, CMP_GT, CMP_GE, CMP_LT, CMP_LE, CMP_NE

Example:

Mat A, B, mask;
compare(A, B, mask, CMP_GT); // mask = (A > B)

min

void min(InputArray src1, InputArray src2, OutputArray dst)

Calculates per-element minimum of two arrays or array and scalar. Example:

Mat A, B, C;
min(A, B, C); // C = min(A, B) element-wise

max

void max(InputArray src1, InputArray src2, OutputArray dst)

Calculates per-element maximum of two arrays or array and scalar. Example:

Mat A, B, C;
max(A, B, C); // C = max(A, B) element-wise

inRange

void inRange(InputArray src, InputArray lowerb, InputArray upperb, OutputArray dst)

Checks if array elements lie between two bounds.

InputArray

Input array

InputArray

Inclusive lower boundary array or scalar

InputArray

Inclusive upper boundary array or scalar

OutputArray

Output array of type CV_8U (0 or 255)

Formula:

dst(I) = 255 if lowerb(I) ≤ src(I) ≤ upperb(I), else 0

Example:

// Color segmentation
Mat hsv, mask;
cvtColor(image, hsv, COLOR_BGR2HSV);
inRange(hsv, Scalar(100, 50, 50), Scalar(130, 255, 255), mask);

Mathematical Operations

sqrt

void sqrt(InputArray src, OutputArray dst)

Calculates square root of array elements. Formula:

dst(I) = √src(I)

pow

void pow(InputArray src, double power, OutputArray dst)

Raises every array element to a power.

InputArray

Input array

double

Exponent of power

OutputArray

Output array

Formula:

dst(I) = src(I)^power

Example:

Mat A, B;
pow(A, 2.0, B); // Square each element

exp

void exp(InputArray src, OutputArray dst)

Calculates the exponent of every array element. Formula:

dst(I) = e^src(I)

log

void log(InputArray src, OutputArray dst)

Calculates the natural logarithm of every array element. Formula:

dst(I) = log(|src(I)|)

Example:

Mat A, logA;
log(A, logA);

absdiff

void absdiff(InputArray src1, InputArray src2, OutputArray dst)

Calculates per-element absolute difference between two arrays or array and scalar. Formula:

dst(I) = |src1(I) - src2(I)|

Example:

// Frame difference for motion detection
Mat frame1, frame2, diff;
absdiff(frame1, frame2, diff);

magnitude

void magnitude(InputArray x, InputArray y, OutputArray magnitude)

Calculates magnitude of 2D vectors.

InputArray

Floating-point array of x-coordinates

InputArray

Floating-point array of y-coordinates (same size as x)

OutputArray

Output array of magnitudes

Formula:

magnitude(I) = √(x(I)² + y(I)²)

phase

void phase(InputArray x, InputArray y, OutputArray angle, bool angleInDegrees = false)

Calculates the rotation angle of 2D vectors.

InputArray

Array of x-coordinates (floating-point)

InputArray

Array of y-coordinates (same size and type as x)

OutputArray

Output array of angles

bool

When true, angles are in degrees (0-360), otherwise radians (0-2π)

Formula:

angle(I) = atan2(y(I), x(I))

cartToPolar

void cartToPolar(InputArray x, InputArray y, OutputArray magnitude,
                 OutputArray angle, bool angleInDegrees = false)

Calculates the magnitude and angle of 2D vectors. Example:

Mat dx, dy, magnitude, angle;
// ... compute gradients dx, dy ...
cartToPolar(dx, dy, magnitude, angle, true);

polarToCart

void polarToCart(InputArray magnitude, InputArray angle, OutputArray x,
                 OutputArray y, bool angleInDegrees = false)

Converts polar coordinates to Cartesian.

InputArray

Array of vector magnitudes

InputArray

Array of vector angles

OutputArray

Output array of x-coordinates

OutputArray

Output array of y-coordinates

Matrix Operations

gemm

void gemm(InputArray src1, InputArray src2, double alpha,
          InputArray src3, double beta, OutputArray dst, int flags = 0)

Performs generalized matrix multiplication (GEMM).

InputArray

First input matrix

InputArray

Second input matrix

double

Weight for src1 * src2

InputArray

Third input matrix (added to product)

double

Weight for src3

OutputArray

Output matrix

int

Operation flags: GEMM_1_T (transpose src1), GEMM_2_T (transpose src2), GEMM_3_T (transpose src3)

Formula:

dst = alpha · src1 · src2 + beta · src3

Example:

Mat A, B, C, D;
gemm(A, B, 1.0, C, 1.0, D); // D = A*B + C
gemm(A, B, 2.0, C, 0.5, D, GEMM_1_T); // D = 2*A^T*B + 0.5*C

transpose

void transpose(InputArray src, OutputArray dst)

Transposes a matrix. Formula:

dst(i,j) = src(j,i)

Example:

Mat A, AT;
transpose(A, AT);

transform

void transform(InputArray src, OutputArray dst, InputArray m)

Performs matrix transformation of every array element.

InputArray

Input array (must be continuous)

OutputArray

Output array

InputArray

Transformation matrix (2x2, 2x3, 3x3, or 3x4 for 2D, 3x3 or 3x4 for 3D)

Example:

// Rotate all 2D points by 45 degrees
std::vector<Point2f> points, rotated;
Mat R = getRotationMatrix2D(Point2f(0,0), 45, 1.0);
transform(points, rotated, R);

mulTransposed

void mulTransposed(InputArray src, OutputArray dst, bool aTa,
                   InputArray delta = noArray(), double scale = 1, int dtype = -1)

Calculates the product of a matrix and its transposition.

InputArray

Input matrix

OutputArray

Output square matrix

bool

If true, computes src^T * src; if false, computes src * src^T

InputArray

Optional delta matrix subtracted from src before multiplication

double

Optional scale factor for the matrix product

Formula:

dst = scale · (src - delta)^T · (src - delta)  // if aTa=true
dst = scale · (src - delta) · (src - delta)^T  // if aTa=false

Array Manipulation

flip

void flip(InputArray src, OutputArray dst, int flipCode)

Flips a 2D array around vertical, horizontal, or both axes.

InputArray

Input array

OutputArray

Output array

int

Flip type: 0 (vertical flip), positive (horizontal flip), negative (both axes)

Example:

Mat img, flipped;
flip(img, flipped, 1); // Horizontal flip
flip(img, flipped, 0); // Vertical flip
flip(img, flipped, -1); // Both axes

rotate

void rotate(InputArray src, OutputArray dst, int rotateCode)

Rotates a 2D array in multiples of 90 degrees.

int

Rotation type: ROTATE_90_CLOCKWISE, ROTATE_180, ROTATE_90_COUNTERCLOCKWISE

Example:

Mat img, rotated;
rotate(img, rotated, ROTATE_90_CLOCKWISE);

repeat

void repeat(InputArray src, int ny, int nx, OutputArray dst)
Mat repeat(const Mat& src, int ny, int nx)

Fills the output array with repeated copies of the input array.

int

Number of times to repeat along the vertical axis

int

Number of times to repeat along the horizontal axis

Example:

Mat pattern(2, 2, CV_8U, Scalar(255));
Mat tiled = repeat(pattern, 5, 5); // Create 10x10 tiled pattern

hconcat

void hconcat(InputArray src1, InputArray src2, OutputArray dst)
void hconcat(InputArrayOfArrays src, OutputArray dst)

Concatenates arrays horizontally (along columns). Example:

Mat A, B, C;
hconcat(A, B, C); // Concatenate side by side

vconcat

void vconcat(InputArray src1, InputArray src2, OutputArray dst)
void vconcat(InputArrayOfArrays src, OutputArray dst)

Concatenates arrays vertically (along rows). Example:

Mat A, B, C;
vconcat(A, B, C); // Stack vertically

Channel Operations

split

void split(InputArray src, OutputArrayOfArrays mv)

Divides a multi-channel array into several single-channel arrays.

InputArray

Input multi-channel array

OutputArrayOfArrays

Output vector of arrays

Example:

Mat bgr, channels[3];
split(bgr, channels);
// channels[0] = blue, channels[1] = green, channels[2] = red

merge

void merge(InputArrayOfArrays mv, OutputArray dst)

Merges several arrays to make a multi-channel array. Example:

std::vector<Mat> channels;
Mat bgr;
merge(channels, bgr);

mixChannels

void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
                 const int* fromTo, size_t npairs)
void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
                 const std::vector<int>& fromTo)

Copies specified channels from input arrays to specified channels of output arrays.

const int*

Array of index pairs: fromTo[k2] is source channel, fromTo[k2+1] is destination channel

Example:

Mat bgr, bgra;
// Copy BGR to BGRA and set alpha to 255
int from_to[] = {0,0, 1,1, 2,2, -1,3};
mixChannels(&bgr, 1, &bgra, 1, from_to, 4);

Channel indexing starts from 0. Use -1 to set a channel to zero.

​Arithmetic Operations

​add

​subtract

​multiply

​divide

​scaleAdd

​addWeighted

​Bitwise Operations

​bitwise_and

​bitwise_or

​bitwise_xor

​bitwise_not

​Comparison Operations

​compare

​min

​max

​inRange

​Mathematical Operations

​sqrt

​pow

​exp

​log

​absdiff

​magnitude

​phase

​cartToPolar

​polarToCart

​Matrix Operations

​gemm

​transpose

​transform

​mulTransposed

​Array Manipulation

​flip

​rotate

​repeat

​hconcat

​vconcat

​Channel Operations

​split

​merge

​mixChannels

Arithmetic Operations

add

subtract

multiply

divide

scaleAdd

addWeighted

Bitwise Operations

bitwise_and

bitwise_or

bitwise_xor

bitwise_not

Comparison Operations

compare

min

max

inRange

Mathematical Operations

sqrt

pow

exp

log

absdiff

magnitude

phase

cartToPolar

polarToCart

Matrix Operations

gemm

transpose

transform

mulTransposed

Array Manipulation

flip

rotate

repeat

hconcat

vconcat

Channel Operations

split

merge

mixChannels