API reference¶

Image to rotate.

Rotation in degrees, counter-clockwise (as for cv.getRotationMatrix2D).

Isotropic scale factor applied with the rotation.

Interpolation, as for cv.warpAffine.

How to fill the corners uncovered by the rotation, as for cv.warpAffine.

Fill color for cv.BORDER_CONSTANT.

The rotated image; its size is the bounding box of the rotated input.

If src is empty, angle is not finite, or scale is not a positive finite number.

Contour of shape (N, 1, 2) or (N, 2), as from cv.findContours.

If the contour has no points, is not finite, or has zero area (the centroid is undefined).

x coordinate(s).

y coordinate(s).

Return the angle in degrees instead of radians (same name as in OpenCV).

(theta, rho): the angle and the distance from the origin.

Angle(s), in radians unless angleInDegrees is true.

Distance(s) from the origin.

theta is in degrees (same name as in OpenCV).

Image size as (width, height), like cv.resize.

A scalar, or one value per channel (BGR, or BGRA for channels=4).

3 (BGR, default), 4 (BGRA) or 1 for a grayscale image of shape (height, width).

Pixel type.

If size is not positive, channels is not 1, 3 or 4, or color is not finite, does not match the channel count, or is outside the range of dtype.

Image whose shape (and dtype) to copy.

A scalar, or one value per channel of src.

Pixel type of the result; by default that of src.

If color is not finite, does not match the channels of src, or is outside the range of the result dtype.

Image size as (width, height), like cv.resize.

Start value. A scalar, or one value per channel (BGR).

End value. A scalar, or one value per channel (BGR).

"horizontal" (left to right), "vertical" (top to bottom), or "raster" (through every pixel in reading order, row by row).

3 for a BGR image (default) or 1 for a grayscale image of shape (height, width).

A uint8 image of shape (height, width, 3), or (height, width) for channels=1.

If size is not positive, channels is not 1 or 3, a value is outside [0, 255] or does not match the channel count, or direction is unknown.

Image to pad.

The width and height of the result are multiples of this.

Padding color: a scalar, or one value per channel.

If src is empty, multiple is not positive, or color is not finite or outside the range of the image dtype.

Image to pad.

Output size as (width, height); it must not be smaller than the image.

Padding color: a scalar, or one value per channel.

Center the image; otherwise it stays at the top-left.

If src is empty, size is smaller than the image, or color is not finite or outside the range of the image dtype.

Image to split.

Tile size as (width, height).

Pixels shared by neighboring tiles, to avoid artifacts at tile borders.

(tile, (x, y)) pairs in row-major order, where (x, y) is the tile's top-left corner in src.

Tiles are views of src; use :func:mergeTiles to put processed tiles back together.

If src is empty, tileSize is not positive, or overlap is not smaller than the tile.

(tile, (x, y)) pairs. Tiles may have any channel count, as long as all are the same.

Output size as (width, height), normally the size of the original image.

The assembled image, with the dtype of the tiles. Pixels covered by no tile are 0.

If tiles is empty or size is not positive.

Image to process.

Tile size as (width, height).

Called once per tile with the tile; returns the processed tile.

Pixels shared by neighboring tiles; the overlaps are averaged when merging, which hides tile seams.

Optional callback progress(done, total) called after each tile.

The processed image, the size of src, with the channels and dtype func returned.

If src is empty, tileSize or overlap is invalid (see :func:splitTiles), or func returns a tile of a different size.

Image to crop.

The box as (x, y, width, height), e.g. from cv.boundingRect or a detector.

Grow the box by this many pixels on every side (negative values shrink it).

None (default) clips the box to the image, so the result may be smaller than rect. Otherwise the result has exactly the box size, and the parts outside the image are filled with this color.

A new array (not a view of src).

If src is empty, rect is not finite, the box (after margin) has no area, or the box lies entirely outside the image.

Image to crop.

(width, height), or one number for a square.

None (default) clips the box to the image when it is larger than the image, so the result may be smaller than size. Otherwise the result has exactly size and the outside is filled with this color.

A new array.

If size is not positive or src is empty.

Image to trim.

Border color. By default the color of the top-left pixel.

Pixels whose every channel differs from background by at most this much count as border, which absorbs JPEG noise.

Keep this many pixels of border around the content (limited by the image size).

A new array with the content. If the whole image is border, a copy of src is returned unchanged.

If src is empty, tolerance or margin is negative, or background is not finite.

3-channel HSV image.

Lower bound (h, s, v).

Upper bound (h, s, v).

Single-channel mask (0 or 255).

If src does not have 3 channels or is empty, the bounds do not have 3 values, or a bound is not finite.

One box (x, y, width, height) or an array of shape (N, 4).

One box or an array of shape (M, 4).

A float64 array of shape (N, M) with values from 0 (no overlap) to 1 (identical boxes);

float(boxIoU(a, b)[0, 0]) for two single boxes.

If the boxes do not have 4 values.

Boxes (x, y, width, height), shape (N, 4).

One score per box.

Boxes overlapping a kept box by more than this IoU are dropped.

Boxes scoring below this are dropped first.

Keep at most this many boxes.

An int64 array of indices into boxes, in descending score order (empty if none survive).

If boxes and scores disagree in length, iouThreshold is outside [0, 1], scoreThreshold is not finite, or maxCount is negative.

If the last dimension of boxes does not have 4 values.

If the last dimension of boxes does not have 4 values.

A float64 array of shape (N, 4), or (4,) for a single input box.

If size is smaller than 1x1, or the boxes do not have 4 finite values each.

Boxes (x, y, width, height).

One factor, or (sx, sy).

(dx, dy) added after scaling (the padding of a letterbox).

Undo the transform instead: (x - offset) / scale.

A float64 array of shape (N, 4), or (4,) for a single input box.

If a factor is not positive and finite.

Boxes (x, y, width, height).

Fraction of the width and height to add on each side (0.1 adds 10% left and right, 10% top and bottom). Negative values shrink.

Fixed number of pixels to add on each side, after ratio (as margin in :func:cropRect).

(width, height) of the image; when given, the result is clipped to it.

A float64 array of shape (N, 4), or (4,) for a single input box. Widths and heights never go

below 0.

If ratio or margin is not finite, or the boxes do not have 4 finite values each.

Images with the same dtype.

Color of the padding and the gaps: a scalar, or one value per channel (BGR, or BGRA).

Space in pixels between the images.

If images is empty, the dtypes differ, an image has an unsupported channel count, or color does not match the channel count.

If images is empty, the dtypes differ, an image has an unsupported channel count, or color does not match the channel count.

Images with the same dtype; sizes and channel counts may differ (see :func:hconcatEx).

Number of columns. By default the grid is as square as possible.

Space in pixels between the cells.

Color of the gaps and padding.

If given, every image is fitted into (width, height) with :func:letterbox first, so all cells have the same size.

If images is empty or cols is not positive (and see :func:hconcatEx).

8-bit grayscale, BGR or BGRA image. It is not modified.

8-bit grayscale, BGR or BGRA image. Its alpha channel (if any) controls the blending per pixel.

Position of the overlay's top-left corner in src, as (x, y).

Overall opacity from 0 (invisible) to 1, multiplied with the overlay's alpha channel (the same name as in :func:overlayMask and cv.addWeighted).

A new image with the same shape as src.

If an image is not 8-bit, is empty or has an unsupported channel count, or alpha is outside [0, 1].

8-bit image with any number of channels.

Gamma value; 1 leaves the image unchanged.

If src is not 8-bit or is empty, or gamma is not a positive finite number.

8-bit image with 1 or 3 channels. Color images are processed per channel.

An 8-bit image with the shape of src.

If src is not 8-bit or is empty.

8-bit grayscale or BGR image.

Number of colors to find.

Number of pixels used to fit the colors (see :func:kmeansColors).

Seed, for reproducible results.

A list of (color, ratio) pairs sorted by ratio, where color is a BGR tuple (or a 1-tuple for

grayscale) and ratio is the share of pixels, summing to 1. Colors that no pixel ends up with are omitted.

As for :func:kmeansColors.

As for :func:kmeansColors.

8-bit BGR image.

Histogram cells per Lab axis. More bins separate similar colors; fewer bins merge them.

Histogram smoothing, in cells. Larger values give fewer, broader colors.

Peaks with less than this fraction of the pixels are merged into the nearest stronger color.

If positive, connected regions smaller than this many pixels take the label of the surrounding region. This removes speckles and gives cleaner segments, but also removes small details such as thin text.

class:Clusters (maps, centers) as for :func:kmeansColors: maps holds labels 0 .. n-1,

ordered from the most to the least common color, and centers the mean BGR color of each cluster.

If src is not an 8-bit BGR image or is empty, or a parameter is out of range.

8-bit grayscale or BGR image.

Number of colors.

Number of pixels used to fit the centers.

Seed for the initial centers and the sampling.

Maximum number of k-means iterations.

class:Clusters (maps, centers): maps has shape src.shape[:2] with labels 0 .. k-1;

centers has shape (k, channels) and holds the colors (BGR, or gray) as uint8.

If src is not an 8-bit grayscale or BGR image or is empty, k is not between 1 and the pixel count, sampleSize is below k, or maxIter is below 1.

8-bit BGR image.

Kernel size in Lab units; larger values merge more colors. By default it is estimated from the image with sklearn.cluster.estimate_bandwidth.

Used to estimate bandwidth when it is not given; larger values give fewer colors.

Number of pixels used to fit the centers.

Seed for the sampling.

class:Clusters (maps, centers) as for :func:kmeansColors; len(centers) is the number of

colors found.

If scikit-learn is not installed.

If src is not an 8-bit BGR image or is empty, bandwidth is not positive, or quantile is outside (0, 1].

8-bit BGR image.

Maximum Lab color distance between two pixels in the same neighborhood.

Minimum number of pixels in a neighborhood for a core point.

class:Clusters (maps, centers) as for :func:kmeansColors: maps holds the labels

0 .. len(centers) - 1 and -1 for noise pixels; centers holds the mean BGR color of every

cluster. Paint the result with :func:drawClusters.

If scikit-learn is not installed.

If src is not an 8-bit BGR image or is empty, eps is not positive, or minSamples is below 1.

8-bit grayscale or BGR image, the one that was clustered.

Label image of shape src.shape[:2], as returned in :class:Clusters.

A new image with the shape and dtype of src; src is not modified.

If src is not an 8-bit grayscale or BGR image or is empty, or maps has another shape.

Points as an array of shape (N, 2) (or (N, d)), or an OpenCV contour of shape (N, 1, 2).

Maximum distance between two points of the same group.

Minimum number of points that forms a group; 1 puts every point in some group.

Labels of shape (N,) (int32): 0, 1, ... for the groups and -1 for noise (points in no

group), as in :func:dbscanColors and scikit-learn.

If scikit-learn is not installed.

If points is empty or not finite, eps is not positive, or minSamples is below 1.

One point, (N, 2) or (N, 1, 2).

Rotation in degrees.

Center of rotation (x, y); the origin by default.

Isotropic scale applied with the rotation.

The rotated points as float64, in the shape of points.

If a value is not finite or scale is not positive.

One point, (N, 2) or (N, 1, 2).

One factor, or (sx, sy) for different factors per axis (new_w / old_w, new_h / old_h).

Fixed point (x, y); the origin by default.

The scaled points as float64, in the shape of points.

If a value is not finite.

The shifted points as float64, in the shape of points.

If a value is not finite.

One point, (N, 2) or (N, 1, 2).

Image size as (width, height).

As for cv.flip: 0 vertical, positive horizontal, negative both.

The flipped points as float64, in the shape of points.

If size is not positive.

One point, (N, 2) or (N, 1, 2) in pixels.

Image size as (width, height).

The normalized points as float64, in the shape of points. Points outside the image fall outside [0, 1].

If size is not positive.

One point, (N, 2) or (N, 1, 2) in [0, 1].

Image size as (width, height).

The pixel coordinates as float64, in the shape of points.

If size is not positive.

One point, (N, 2) or (N, 1, 2).

Image size as (width, height).

The clipped points as float64, in the shape of points.

If size is not positive.

If points is empty or not finite.

One point, (N, 2) or (N, 1, 2).

One point, (M, 2) or (M, 1, 2).

A float64 array of shape (N, M); float(distancePoints(p, q)[0, 0]) for two single points.

One point, (N, 2) or (N, 1, 2).

(M, 2) or (M, 1, 2), with at least one point.

(indices, distances): an int64 array and a float64 array, both of length N.

If b is empty.

4 points as (4, 2) or a contour of shape (4, 1, 2).

A float64 array of shape (4, 2).

If there are not exactly 4 points.

If points is empty or not finite.

Start point (x, y).

End point (x, y).

Return degrees ((-180, 180]) instead of radians.

If a point is not one finite (x, y) pair.

The point (x, y), or None if the lines are parallel (including coincident).

If a line is not two finite points, or its two points coincide.

The point (x, y).

Two points ((x1, y1), (x2, y2)) on the line.

Measure to the segment: beyond its ends, the distance to the nearer end point.

If the point or line is not finite, or the line's two points coincide.

Binary mask; nonzero (or True) pixels are foreground (color masks count any nonzero channel).

Simplification tolerance as a fraction of each polygon's perimeter (0.01 = 1%); 0 keeps every contour point.

Drop polygons whose cv.contourArea is smaller than this.

A list of int32 arrays of shape (N, 2), largest area first. The inverse is :func:polygonsToMask.

If mask is not a 2-D array or an image, is empty, or epsilon/minArea is negative.

One polygon (N, 2) or a sequence of polygons (an empty sequence gives an all-zero mask).

(width, height) of the mask.

Value of the polygon pixels, 1 to 255.

uint8 mask with values 0 and value.

If size is not positive, value is outside [1, 255] or a polygon is empty / not 2-D.

A list with one float64 (4, 2) array per box.

If the boxes do not have 4 finite values.

One polygon (N, 2) or a sequence of polygons.

A float64 array of shape (N, 4) ((0, 4) for no polygons).

If a polygon is empty, not 2-D or not finite.

(N, 2) points (or a point list); the polygon is closed implicitly.

The absolute area (0 for fewer than 3 points).

If polygon is empty, not 2-D or not finite.

(N, 2) points.

(M, 2) points.

Raster size of the longer side of the common bounding box, in pixels.

A value from 0 (disjoint) to 1 (identical); 0 when either polygon has no area.

If a polygon is empty, not 2-D or not finite, or resolution is less than 1.

Binary mask; nonzero (or True) pixels are foreground.

Binary mask of the same height and width.

A value from 0 to 1; 0 when both masks are empty.

If a mask is not a 2-D array or an image, is empty, or the shapes differ.

Binary mask; nonzero (or True) pixels are foreground.

A dict with "counts" (a list of int) and "size" ([height, width]).

If mask is not a 2-D array or an image, or is empty.

{"counts": [...], "size": [height, width]} with integer counts (compressed string counts are not supported; decode those with pycocotools.mask.decode).

If size is not positive, counts is not a list of non-negative integers, or the counts do not add up to height * width.

Boxes of shape (N, 4) (or one box).

(width, height) of the image.

One class id per box; when given, the rows are class cx cy w h as in a YOLO label file.

A float64 array of shape (N, 4), or (N, 5) with classIds. Values are not clipped to [0, 1].

If size is not positive, the boxes are invalid, or classIds has the wrong length.

Array of shape (N, 5) (class first) or (N, 4); extra columns (confidence) are ignored.

(width, height) of the image.

(boxes, classIds): float64 boxes of shape (N, 4) and int64 ids of shape (N,), or None

for classIds when the rows have no class column.

If size is not positive or the rows do not have 4 or more values.

Path of the .txt label file.

(width, height) of the matching image.

(boxes, classIds): float64 boxes of shape (N, 4) and int64 ids of shape (N,).

If size is not positive, or a line does not have at least 5 numbers.

Path of the .txt file (any path, including non-ASCII); an empty box list writes an empty file.

Boxes of shape (N, 4).

One integer class id per box.

(width, height) of the matching image.

Create missing parent directories.

If size is not positive, the boxes are invalid, or classIds has the wrong length.

If the file cannot be written.

2-D integer array of class ids (bool counts as 0/1).

One BGR color per class id, indexed by id ((K, 3)); None uses distinctColors(labels.max() + 1), so the same ids always get the same colors.

The id drawn black (set to -1 to color every id from the palette).

uint8 BGR image with the shape of labels.

If labels is not a 2-D integer array, is empty, has negative ids, or an id has no palette entry.

8-bit BGR (or BGRA) image whose colors come from palette.

One BGR color per class id, indexed by id ((K, 3)).

The id for pixels whose color is not in the palette.

int32 array of class ids with the shape image.shape[:2].

If image is not an 8-bit color image or is empty, or palette is not (K, 3).

Binary masks of the same shape; nonzero (or True) pixels are foreground.

int32 array of ids (0 = background) with the shape of the masks.

If masks is empty, or a mask is not 2-D, is empty or has a different shape.

2-D integer array of ids.

The id that gets no mask.

A list of uint8 masks (0/255), one for each id from 1 to labels.max() except background, so

masks[i] is id i + 1 when background is 0 (unused ids give all-zero masks).

If labels is not a 2-D integer array, is empty or has negative ids.

8-bit image to draw on.

One polygon (N, 2) or a sequence of polygons (floats are rounded).

One color for all polygons, one color per polygon, or None for :func:distinctColors.

Outline thickness (ignored with fill).

Fill the polygons instead of outlining them.

Opacity of the drawing, from 0 to 1.

One text per polygon, drawn at its top-most point.

Hershey font size for the labels.

As for cv.polylines.

src.

If src is not 8-bit or is empty, alpha is outside [0, 1], thickness is not positive, or labels/color has a different length than polygons.

8-bit grayscale, BGR or BGRA image (converted to BGR). It is not modified.

2-D integer label map with the shape src.shape[:2]. A bool array, or an array whose nonzero values are all 255, is treated as a binary mask (one class, id 1).

Opacity of the colors, from 0 to 1.

One BGR color per class id, as for :func:labelMapToColor.