> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencv/opencv/llms.txt
> Use this file to discover all available pages before exploring further.

# Array Operations

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

## Arithmetic Operations

### add

```cpp theme={null}
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.

<ParamField path="src1" type="InputArray">
  First input array or scalar
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array or scalar
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array with the same size and number of channels as input arrays
</ParamField>

<ParamField path="mask" type="InputArray">
  Optional 8-bit single channel mask that specifies elements to be changed
</ParamField>

<ParamField path="dtype" type="int">
  Optional depth of the output array. Default is -1 (same as input)
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
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;
```

<Note>
  Saturation is not applied when the output array has depth CV\_32S. You may get incorrect sign in case of overflow.
</Note>

### subtract

```cpp theme={null}
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.

<ParamField path="src1" type="InputArray">
  First input array or scalar
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array or scalar
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

<ParamField path="mask" type="InputArray">
  Optional operation mask
</ParamField>

<ParamField path="dtype" type="int">
  Optional depth of the output array
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
Mat result;
subtract(imageA, imageB, result);
// Equivalent: result = imageA - imageB;
```

### multiply

```cpp theme={null}
void multiply(InputArray src1, InputArray src2, OutputArray dst,
              double scale = 1, int dtype = -1)
```

Calculates the per-element scaled product of two arrays.

<ParamField path="src1" type="InputArray">
  First input array
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array of the same size and type as src1
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

<ParamField path="scale" type="double">
  Optional scale factor
</ParamField>

<ParamField path="dtype" type="int">
  Optional depth of the output array
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
Mat A, B, C;
multiply(A, B, C, 2.5); // Element-wise multiplication with scaling
```

<Note>
  For matrix multiplication (not element-wise), use gemm() function.
</Note>

### divide

```cpp theme={null}
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.

<ParamField path="src1" type="InputArray">
  First input array (numerator)
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array (denominator)
</ParamField>

<ParamField path="scale" type="double">
  Scalar factor
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
Mat A, B, C;
divide(A, B, C); // Element-wise division
divide(255.0, B, C); // Scalar divided by array
```

<Warning>
  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).
</Warning>

### scaleAdd

```cpp theme={null}
void scaleAdd(InputArray src1, double alpha, InputArray src2, OutputArray dst)
```

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

<ParamField path="src1" type="InputArray">
  First input array
</ParamField>

<ParamField path="alpha" type="double">
  Scale factor for the first array
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array (same size and type as src1)
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
Mat A, B, C;
scaleAdd(A, 2.0, B, C); // C = 2*A + B
```

### addWeighted

```cpp theme={null}
void addWeighted(InputArray src1, double alpha, InputArray src2,
                 double beta, double gamma, OutputArray dst, int dtype = -1)
```

Calculates the weighted sum of two arrays.

<ParamField path="src1" type="InputArray">
  First input array
</ParamField>

<ParamField path="alpha" type="double">
  Weight of the first array elements
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array
</ParamField>

<ParamField path="beta" type="double">
  Weight of the second array elements
</ParamField>

<ParamField path="gamma" type="double">
  Scalar added to each sum
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
// Image blending
Mat img1, img2, blended;
addWeighted(img1, 0.7, img2, 0.3, 0.0, blended);
```

## Bitwise Operations

### bitwise\_and

```cpp theme={null}
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.

<ParamField path="src1" type="InputArray">
  First input array or scalar
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array or scalar
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

<ParamField path="mask" type="InputArray">
  Optional operation mask
</ParamField>

**Formula:**

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

### bitwise\_or

```cpp theme={null}
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

```cpp theme={null}
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

```cpp theme={null}
void bitwise_not(InputArray src, OutputArray dst, InputArray mask = noArray())
```

Inverts every bit of an array.

<ParamField path="src" type="InputArray">
  Input array
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
Mat mask, inverted_mask;
bitwise_not(mask, inverted_mask);
```

## Comparison Operations

### compare

```cpp theme={null}
void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop)
```

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

<ParamField path="src1" type="InputArray">
  First input array or scalar
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input array or scalar
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array of type CV\_8U (0 or 255 values)
</ParamField>

<ParamField path="cmpop" type="int">
  Comparison operation: CMP\_EQ, CMP\_GT, CMP\_GE, CMP\_LT, CMP\_LE, CMP\_NE
</ParamField>

**Example:**

```cpp theme={null}
Mat A, B, mask;
compare(A, B, mask, CMP_GT); // mask = (A > B)
```

### min

```cpp theme={null}
void min(InputArray src1, InputArray src2, OutputArray dst)
```

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

**Example:**

```cpp theme={null}
Mat A, B, C;
min(A, B, C); // C = min(A, B) element-wise
```

### max

```cpp theme={null}
void max(InputArray src1, InputArray src2, OutputArray dst)
```

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

**Example:**

```cpp theme={null}
Mat A, B, C;
max(A, B, C); // C = max(A, B) element-wise
```

### inRange

```cpp theme={null}
void inRange(InputArray src, InputArray lowerb, InputArray upperb, OutputArray dst)
```

Checks if array elements lie between two bounds.

<ParamField path="src" type="InputArray">
  Input array
</ParamField>

<ParamField path="lowerb" type="InputArray">
  Inclusive lower boundary array or scalar
</ParamField>

<ParamField path="upperb" type="InputArray">
  Inclusive upper boundary array or scalar
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array of type CV\_8U (0 or 255)
</ParamField>

**Formula:**

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

**Example:**

```cpp theme={null}
// Color segmentation
Mat hsv, mask;
cvtColor(image, hsv, COLOR_BGR2HSV);
inRange(hsv, Scalar(100, 50, 50), Scalar(130, 255, 255), mask);
```

## Mathematical Operations

### sqrt

```cpp theme={null}
void sqrt(InputArray src, OutputArray dst)
```

Calculates square root of array elements.

**Formula:**

```
dst(I) = √src(I)
```

### pow

```cpp theme={null}
void pow(InputArray src, double power, OutputArray dst)
```

Raises every array element to a power.

<ParamField path="src" type="InputArray">
  Input array
</ParamField>

<ParamField path="power" type="double">
  Exponent of power
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

**Formula:**

```
dst(I) = src(I)^power
```

**Example:**

```cpp theme={null}
Mat A, B;
pow(A, 2.0, B); // Square each element
```

### exp

```cpp theme={null}
void exp(InputArray src, OutputArray dst)
```

Calculates the exponent of every array element.

**Formula:**

```
dst(I) = e^src(I)
```

### log

```cpp theme={null}
void log(InputArray src, OutputArray dst)
```

Calculates the natural logarithm of every array element.

**Formula:**

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

**Example:**

```cpp theme={null}
Mat A, logA;
log(A, logA);
```

### absdiff

```cpp theme={null}
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:**

```cpp theme={null}
// Frame difference for motion detection
Mat frame1, frame2, diff;
absdiff(frame1, frame2, diff);
```

### magnitude

```cpp theme={null}
void magnitude(InputArray x, InputArray y, OutputArray magnitude)
```

Calculates magnitude of 2D vectors.

<ParamField path="x" type="InputArray">
  Floating-point array of x-coordinates
</ParamField>

<ParamField path="y" type="InputArray">
  Floating-point array of y-coordinates (same size as x)
</ParamField>

<ParamField path="magnitude" type="OutputArray">
  Output array of magnitudes
</ParamField>

**Formula:**

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

### phase

```cpp theme={null}
void phase(InputArray x, InputArray y, OutputArray angle, bool angleInDegrees = false)
```

Calculates the rotation angle of 2D vectors.

<ParamField path="x" type="InputArray">
  Array of x-coordinates (floating-point)
</ParamField>

<ParamField path="y" type="InputArray">
  Array of y-coordinates (same size and type as x)
</ParamField>

<ParamField path="angle" type="OutputArray">
  Output array of angles
</ParamField>

<ParamField path="angleInDegrees" type="bool">
  When true, angles are in degrees (0-360), otherwise radians (0-2π)
</ParamField>

**Formula:**

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

### cartToPolar

```cpp theme={null}
void cartToPolar(InputArray x, InputArray y, OutputArray magnitude,
                 OutputArray angle, bool angleInDegrees = false)
```

Calculates the magnitude and angle of 2D vectors.

**Example:**

```cpp theme={null}
Mat dx, dy, magnitude, angle;
// ... compute gradients dx, dy ...
cartToPolar(dx, dy, magnitude, angle, true);
```

### polarToCart

```cpp theme={null}
void polarToCart(InputArray magnitude, InputArray angle, OutputArray x,
                 OutputArray y, bool angleInDegrees = false)
```

Converts polar coordinates to Cartesian.

<ParamField path="magnitude" type="InputArray">
  Array of vector magnitudes
</ParamField>

<ParamField path="angle" type="InputArray">
  Array of vector angles
</ParamField>

<ParamField path="x" type="OutputArray">
  Output array of x-coordinates
</ParamField>

<ParamField path="y" type="OutputArray">
  Output array of y-coordinates
</ParamField>

## Matrix Operations

### gemm

```cpp theme={null}
void gemm(InputArray src1, InputArray src2, double alpha,
          InputArray src3, double beta, OutputArray dst, int flags = 0)
```

Performs generalized matrix multiplication (GEMM).

<ParamField path="src1" type="InputArray">
  First input matrix
</ParamField>

<ParamField path="src2" type="InputArray">
  Second input matrix
</ParamField>

<ParamField path="alpha" type="double">
  Weight for src1 \* src2
</ParamField>

<ParamField path="src3" type="InputArray">
  Third input matrix (added to product)
</ParamField>

<ParamField path="beta" type="double">
  Weight for src3
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output matrix
</ParamField>

<ParamField path="flags" type="int">
  Operation flags: GEMM\_1\_T (transpose src1), GEMM\_2\_T (transpose src2), GEMM\_3\_T (transpose src3)
</ParamField>

**Formula:**

```
dst = alpha · src1 · src2 + beta · src3
```

**Example:**

```cpp theme={null}
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

```cpp theme={null}
void transpose(InputArray src, OutputArray dst)
```

Transposes a matrix.

**Formula:**

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

**Example:**

```cpp theme={null}
Mat A, AT;
transpose(A, AT);
```

### transform

```cpp theme={null}
void transform(InputArray src, OutputArray dst, InputArray m)
```

Performs matrix transformation of every array element.

<ParamField path="src" type="InputArray">
  Input array (must be continuous)
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

<ParamField path="m" type="InputArray">
  Transformation matrix (2x2, 2x3, 3x3, or 3x4 for 2D, 3x3 or 3x4 for 3D)
</ParamField>

**Example:**

```cpp theme={null}
// 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

```cpp theme={null}
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.

<ParamField path="src" type="InputArray">
  Input matrix
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output square matrix
</ParamField>

<ParamField path="aTa" type="bool">
  If true, computes src^T \* src; if false, computes src \* src^T
</ParamField>

<ParamField path="delta" type="InputArray">
  Optional delta matrix subtracted from src before multiplication
</ParamField>

<ParamField path="scale" type="double">
  Optional scale factor for the matrix product
</ParamField>

**Formula:**

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

## Array Manipulation

### flip

```cpp theme={null}
void flip(InputArray src, OutputArray dst, int flipCode)
```

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

<ParamField path="src" type="InputArray">
  Input array
</ParamField>

<ParamField path="dst" type="OutputArray">
  Output array
</ParamField>

<ParamField path="flipCode" type="int">
  Flip type: 0 (vertical flip), positive (horizontal flip), negative (both axes)
</ParamField>

**Example:**

```cpp theme={null}
Mat img, flipped;
flip(img, flipped, 1); // Horizontal flip
flip(img, flipped, 0); // Vertical flip
flip(img, flipped, -1); // Both axes
```

### rotate

```cpp theme={null}
void rotate(InputArray src, OutputArray dst, int rotateCode)
```

Rotates a 2D array in multiples of 90 degrees.

<ParamField path="rotateCode" type="int">
  Rotation type: ROTATE\_90\_CLOCKWISE, ROTATE\_180, ROTATE\_90\_COUNTERCLOCKWISE
</ParamField>

**Example:**

```cpp theme={null}
Mat img, rotated;
rotate(img, rotated, ROTATE_90_CLOCKWISE);
```

### repeat

```cpp theme={null}
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.

<ParamField path="ny" type="int">
  Number of times to repeat along the vertical axis
</ParamField>

<ParamField path="nx" type="int">
  Number of times to repeat along the horizontal axis
</ParamField>

**Example:**

```cpp theme={null}
Mat pattern(2, 2, CV_8U, Scalar(255));
Mat tiled = repeat(pattern, 5, 5); // Create 10x10 tiled pattern
```

### hconcat

```cpp theme={null}
void hconcat(InputArray src1, InputArray src2, OutputArray dst)
void hconcat(InputArrayOfArrays src, OutputArray dst)
```

Concatenates arrays horizontally (along columns).

**Example:**

```cpp theme={null}
Mat A, B, C;
hconcat(A, B, C); // Concatenate side by side
```

### vconcat

```cpp theme={null}
void vconcat(InputArray src1, InputArray src2, OutputArray dst)
void vconcat(InputArrayOfArrays src, OutputArray dst)
```

Concatenates arrays vertically (along rows).

**Example:**

```cpp theme={null}
Mat A, B, C;
vconcat(A, B, C); // Stack vertically
```

## Channel Operations

### split

```cpp theme={null}
void split(InputArray src, OutputArrayOfArrays mv)
```

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

<ParamField path="src" type="InputArray">
  Input multi-channel array
</ParamField>

<ParamField path="mv" type="OutputArrayOfArrays">
  Output vector of arrays
</ParamField>

**Example:**

```cpp theme={null}
Mat bgr, channels[3];
split(bgr, channels);
// channels[0] = blue, channels[1] = green, channels[2] = red
```

### merge

```cpp theme={null}
void merge(InputArrayOfArrays mv, OutputArray dst)
```

Merges several arrays to make a multi-channel array.

**Example:**

```cpp theme={null}
std::vector<Mat> channels;
Mat bgr;
merge(channels, bgr);
```

### mixChannels

```cpp theme={null}
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.

<ParamField path="fromTo" type="const int*">
  Array of index pairs: fromTo\[k*2] is source channel, fromTo\[k*2+1] is destination channel
</ParamField>

**Example:**

```cpp theme={null}
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);
```

<Note>
  Channel indexing starts from 0. Use -1 to set a channel to zero.
</Note>