Array Operations

Per-element operations, matrix arithmetic, and array manipulation functions

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.

src1 · InputArray

First input array or scalar

src2 · InputArray

Second input array or scalar

dst · OutputArray

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

mask · InputArray

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

dtype · 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.

src1 · InputArray

First input array or scalar

src2 · InputArray

Second input array or scalar

dst · OutputArray

Output array

mask · InputArray

Optional operation mask

dtype · 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.

src1 · InputArray

First input array

src2 · InputArray

Second input array of the same size and type as src1

dst · OutputArray

Output array

scale · double

Optional scale factor

dtype · 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.

src1 · InputArray

First input array (numerator)

src2 · InputArray

Second input array (denominator)

scale · double

Scalar factor

dst · 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).

src1 · InputArray

First input array

alpha · double

Scale factor for the first array

src2 · InputArray

Second input array (same size and type as src1)

dst · 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.

src1 · InputArray

First input array

alpha · double

Weight of the first array elements

src2 · InputArray

Second input array

beta · double

Weight of the second array elements

gamma · double

Scalar added to each sum

dst · 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.

src1 · InputArray

First input array or scalar

src2 · InputArray

Second input array or scalar

dst · OutputArray

Output array

mask · 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.

src · InputArray

Input array

dst · 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.

src1 · InputArray

First input array or scalar

src2 · InputArray

Second input array or scalar

dst · OutputArray

Output array of type CV_8U (0 or 255 values)

cmpop · 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.

src · InputArray

Input array

lowerb · InputArray

Inclusive lower boundary array or scalar

upperb · InputArray

Inclusive upper boundary array or scalar

dst · 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.

src · InputArray

Input array

power · double

Exponent of power

dst · 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.

x · InputArray

Floating-point array of x-coordinates

y · InputArray

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

magnitude · 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.

x · InputArray

Array of x-coordinates (floating-point)

y · InputArray

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

angle · OutputArray

Output array of angles

angleInDegrees · 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.

magnitude · InputArray

Array of vector magnitudes

angle · InputArray

Array of vector angles

x · OutputArray

Output array of x-coordinates

y · 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).

src1 · InputArray

First input matrix

src2 · InputArray

Second input matrix

alpha · double

Weight for src1 * src2

src3 · InputArray

Third input matrix (added to product)

beta · double

Weight for src3

dst · OutputArray

Output matrix

flags · 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.

src · InputArray

Input array (must be continuous)

dst · OutputArray

Output array

m · 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.

src · InputArray

Input matrix

dst · OutputArray

Output square matrix

aTa · bool

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

delta · InputArray

Optional delta matrix subtracted from src before multiplication

scale · 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.

src · InputArray

Input array

dst · OutputArray

Output array

flipCode · 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.

rotateCode · 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.

ny · int

Number of times to repeat along the vertical axis

nx · 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.

src · InputArray

Input multi-channel array

mv · 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.

fromTo · 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.