OpenCV API Manual#
The cv2 module provides MicroPython bindings for the OpenCV computer vision library, supporting classical computer vision functions such as image I/O, filtering, morphology, thresholding, color space conversion, geometric transformation, drawing, contour analysis, template matching, Hough transform, histogram, corner detection, and image segmentation.
Image data is represented using ulab.numpy’s ndarray, and can be converted to/from image.Image objects via the image.Image.to_numpy_ref() method.
import cv2
from ulab import numpy as np
Function List#
imgcodecs — Image Read/Write (4 functions)#
Function |
Description |
|---|---|
|
Read image from file |
|
Save image to file |
|
Decode image from memory buffer |
|
Encode image to memory buffer |
core — Core Operations (23 functions)#
Function |
Description |
|---|---|
|
Element-wise addition |
|
Element-wise subtraction |
|
Element-wise multiplication |
|
Element-wise division |
|
Weighted blending of two images: |
|
Element-wise absolute difference between two images |
|
Bitwise AND operation |
|
Bitwise OR operation |
|
Bitwise XOR operation |
|
Bitwise NOT operation |
|
Split multi-channel image into single-channel list |
|
Merge single-channel list into multi-channel image |
|
Calculate mean value of each channel |
|
Normalize image value range |
|
Element-wise comparison of two images, returns binary mask |
|
Color range filtering, returns binary mask |
|
Scale, take absolute value, then convert to 8-bit |
|
Find min/max values and their positions |
|
Lookup table mapping transformation |
|
Count non-zero pixels |
|
Image flip (vertical/horizontal/diagonal) |
|
Image rotation (90°/180°/270°) |
|
Matrix transpose |
imgproc — Image Processing (65 functions)#
Image Filtering
Function |
Description |
|---|---|
|
Canny edge detection |
|
Gaussian blur |
|
Mean blur (box filter) |
|
Median blur |
|
Bilateral filter (edge-preserving denoising) |
|
Box filter |
|
Custom kernel convolution filter |
|
Sobel edge detection (first-order derivative) |
|
Scharr edge detection (higher precision than Sobel) |
|
Laplacian edge detection (second-order derivative) |
Morphology
Function |
Description |
|---|---|
|
Erosion operation |
|
Dilation operation |
|
Advanced morphology (open/close/gradient/top hat/black hat) |
|
Get structuring element (rectangle/cross/ellipse) |
Thresholding
Function |
Description |
|---|---|
|
Global threshold segmentation (supports OTSU / Triangle) |
|
Adaptive threshold segmentation (mean/Gaussian) |
Color Conversion
Function |
Description |
|---|---|
|
Color space conversion (BGR↔GRAY/HSV/LAB/YUV and 22 others) |
Geometric Transformation
Function |
Description |
|---|---|
|
Image resizing |
|
Affine transformation |
|
Perspective transformation |
|
Get 2D rotation matrix |
|
Compute affine transformation matrix from three point pairs |
|
Compute perspective transformation matrix from four point pairs |
|
Pixel remapping |
Pyramid
Function |
Description |
|---|---|
|
Gaussian pyramid downsampling (size halved) |
|
Gaussian pyramid upsampling (size doubled) |
Drawing
Function |
Description |
|---|---|
|
Draw line |
|
Draw rectangle |
|
Draw circle |
|
Draw ellipse/arc |
|
Draw text (supports 8 Hershey fonts) |
|
Draw line with arrow |
|
Draw marker (cross/star/diamond and 4 others) |
|
Fill polygon |
|
Draw polygon outline |
|
Get text rendering size and baseline |
Contours
Function |
Description |
|---|---|
|
Find contours in binary image |
|
Draw contours |
|
Calculate contour area |
|
Calculate contour perimeter |
|
Calculate bounding upright rectangle |
|
Polygon approximation |
|
Calculate convex hull (supports returning point coordinates or indices) |
|
Minimum enclosing rotated rectangle |
|
Minimum enclosing circle |
|
Fit ellipse (requires ≥5 points) |
|
Fit line |
|
Test point and contour position relationship |
|
Calculate convex hull defects |
|
Shape matching (based on Hu moments) |
|
Check if contour is convex |
Template Matching & Moments
Function |
Description |
|---|---|
|
Template matching (6 matching methods) |
|
Calculate image moments (spatial/central/normalized moments) |
Hough Transform
Function |
Description |
|---|---|
|
Standard Hough line detection |
|
Probabilistic Hough line detection (returns line segment endpoints) |
|
Hough circle detection (gradient method) |
Histogram
Function |
Description |
|---|---|
|
Calculate image histogram |
|
Histogram back projection |
|
Histogram comparison (6 comparison methods) |
|
Histogram equalization |
Corner Detection
Function |
Description |
|---|---|
|
Harris corner detection |
|
Shi-Tomasi corner detection |
|
Sub-pixel corner precise localization |
Segmentation
Function |
Description |
|---|---|
|
Watershed segmentation |
|
Distance transform |
|
Flood fill |
|
GrabCut foreground segmentation |
|
Connected components labeling |
highgui — Interaction (2 functions)#
Function |
Description |
|---|---|
|
Wait for key press (supports timeout) |
|
Enhanced version of waitKey |
Total: 94 functions. ⚠ indicates platform limitations:
getAffineTransform/getPerspectiveTransform/grabCutmay overflow with the default 128KB thread stack;cornerSubPixhas an incompatibleInputOutputArraywrapper path in this OpenCV port.
imgcodecs — Image Read/Write#
imread#
Read an image from a file.
img = cv2.imread(filename, flags=cv2.IMREAD_COLOR)
Parameter |
Type |
Description |
|---|---|---|
|
|
Image file path, supports BMP, PNG, JPEG and other formats |
|
|
Read mode (see constants table), defaults to |
Return value: ndarray, returns None on failure.
Example:
img = cv2.imread("/sdcard/photo.jpg")
gray = cv2.imread("/sdcard/photo.jpg", cv2.IMREAD_GRAYSCALE)
imwrite#
Save an image to a file.
success = cv2.imwrite(filename, img)
Parameter |
Type |
Description |
|---|---|---|
|
|
Save path, format is determined by extension (e.g. |
|
|
Image array |
Return value: bool, returns True on success.
Example:
img = np.zeros((240, 320, 3), dtype=np.uint8)
cv2.imwrite("/sdcard/output.png", img)
imdecode#
Decode an image from a memory buffer.
img = cv2.imdecode(buf, flags=cv2.IMREAD_COLOR)
Parameter |
Type |
Description |
|---|---|---|
|
|
Byte buffer containing image data |
|
|
Decode mode, same as |
Return value: ndarray, returns None on failure.
imencode#
Encode an image into a memory buffer.
success, buf = cv2.imencode(ext, img, params=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
Image format extension, e.g. |
|
|
Image to be encoded |
|
|
Optional, encoding parameter list |
Return value: (bool, bytes) tuple. success indicates whether encoding succeeded, buf is the encoded byte data.
Example:
success, buf = cv2.imencode(".jpg", img, [1, 50]) # JPEG quality=50
decoded = cv2.imdecode(buf, cv2.IMREAD_COLOR)
Image Read/Write Constants#
Constant |
Value |
Description |
|---|---|---|
|
-1 |
Keep original format |
|
0 |
Convert to grayscale |
|
1 |
Convert to BGR color image |
|
2 |
Preserve original bit depth |
|
4 |
Preserve original number of channels |
|
128 |
Ignore EXIF orientation tag |
core — Core Operations#
Arithmetic Operations#
add#
Element-wise addition of two images or an image and a scalar.
dst = cv2.add(src1, src2, dst=None, mask=None, dtype=-1)
Parameter |
Type |
Description |
|---|---|---|
|
|
First input image |
|
|
Second input image (or scalar ndarray) |
|
|
Optional, output image |
|
|
Optional, 8-bit single-channel mask |
|
|
Optional, output depth (-1 means same as src1) |
Return value: ndarray.
subtract#
Element-wise subtraction.
dst = cv2.subtract(src1, src2, dst=None, mask=None, dtype=-1)
Parameters same as add.
multiply#
Element-wise multiplication.
dst = cv2.multiply(src1, src2, dst=None, scale=None, dtype=-1)
Parameter |
Type |
Description |
|---|---|---|
|
|
Optional, scale factor, default is 1.0 |
divide#
Element-wise division.
dst = cv2.divide(src1, src2, dst=None, scale=None, dtype=-1)
addWeighted#
Weighted blending of two images.
dst = cv2.addWeighted(src1, alpha, src2, beta, gamma, dst=None, dtype=-1)
Formula: dst = alpha * src1 + beta * src2 + gamma
Parameter |
Type |
Description |
|---|---|---|
|
|
First input |
|
|
Weight of the first input |
|
|
Second input |
|
|
Weight of the second input |
|
|
Scalar added to each sum |
result = cv2.addWeighted(img1, 0.7, img2, 0.3, 0)
absdiff#
Computes the element-wise absolute difference between two images.
dst = cv2.absdiff(src1, src2, dst=None)
Bitwise Operations#
bitwise_and#
dst = cv2.bitwise_and(src1, src2, dst=None, mask=None)
bitwise_or#
dst = cv2.bitwise_or(src1, src2, dst=None, mask=None)
bitwise_xor#
dst = cv2.bitwise_xor(src1, src2, dst=None, mask=None)
bitwise_not#
dst = cv2.bitwise_not(src, dst=None, mask=None)
Channel Operations#
split#
Splits a multi-channel image into a list of single channels.
channels = cv2.split(m)
Parameter |
Type |
Description |
|---|---|---|
|
|
Multi-channel input image |
Return value: list[ndarray], each element is one channel.
b, g, r = cv2.split(img) # Split into B, G, R three channels
merge#
Merges a list of single channels into a multi-channel image.
merged = cv2.merge(mv)
Parameter |
Type |
Description |
|---|---|---|
|
|
List of single-channel ndarrays |
Return value: ndarray, the merged multi-channel image.
merged = cv2.merge([b_channel, g_channel, r_channel])
Statistics and Normalization#
mean#
Compute the image mean.
mean_vals = cv2.mean(src, mask=None)
Return value: list[float], mean of each channel.
normalize#
Normalize the image value range.
dst = cv2.normalize(src, dst=None, alpha=None, beta=None, norm_type=cv2.NORM_L2, dtype=-1, mask=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
Minimum value for range normalization, or target value for norm normalization |
|
|
Maximum value for range normalization (effective when |
|
|
Normalization type (see constants table) |
normed = cv2.normalize(src, alpha=0, beta=255, norm_type=cv2.NORM_MINMAX)
compare#
Compare two images element-wise.
dst = cv2.compare(src1, src2, cmpop)
Parameter |
Type |
Description |
|---|---|---|
|
|
Comparison operation type (see constants table) |
Return value: ndarray (dtype=uint8), matching positions are 255, non-matching are 0.
mask = cv2.compare(img, threshold_val, cv2.CMP_GT)
Other core functions#
inRange#
Color range filter.
dst = cv2.inRange(src, lowerb, upperb, dst=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
Lower bound value (consistent with src channel count) |
|
|
Upper bound value |
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
lo = np.array([0, 50, 50], dtype=np.uint8)
hi = np.array([10, 255, 255], dtype=np.uint8)
mask = cv2.inRange(hsv, lo, hi)
convertScaleAbs#
Scale and take absolute value, then convert to 8-bit.
dst = cv2.convertScaleAbs(src, dst=None, alpha=None, beta=None)
dst = saturate_cast<uchar>(|alpha * src + beta|)
minMaxLoc#
Find the minimum value, maximum value, and their positions.
minVal, maxVal, minLoc, maxLoc = cv2.minMaxLoc(src, mask=None)
Return value: (float, float, (int,int), (int,int))
LUT#
Look-up table mapping transformation.
dst = cv2.LUT(src, lut, dst=None)
countNonZero#
Count the number of non-zero pixels.
count = cv2.countNonZero(src)
flip#
Image flipping.
dst = cv2.flip(src, flipCode, dst=None)
|
Effect |
|---|---|
0 |
Vertical flip |
1 |
Horizontal flip |
-1 |
Diagonal flip |
rotate#
Image rotation.
dst = cv2.rotate(src, rotateCode, dst=None)
See the rotation constants table for rotateCode values.
transpose#
Matrix transpose.
dst = cv2.transpose(src, dst=None)
core Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Rotate 90° clockwise |
|
1 |
Rotate 180° |
|
2 |
Rotate 90° counterclockwise |
|
0 |
Equal |
|
1 |
Greater than |
|
2 |
Greater than or equal |
|
3 |
Less than |
|
4 |
Less than or equal |
|
5 |
Not equal |
|
1 |
Infinity norm |
|
2 |
L1 norm |
|
4 |
L2 norm |
|
32 |
Min-max normalization |
imgproc — Image Processing#
Image Filtering#
Canny#
Canny edge detection.
edges = cv2.Canny(image, threshold1, threshold2, edges=None, apertureSize=3, L2gradient=False)
Parameter |
Type |
Description |
|---|---|---|
|
|
Input (single-channel grayscale image) |
|
|
Low threshold |
|
|
High threshold |
|
|
Sobel kernel size, default 3 |
|
|
Whether to use L2 norm |
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
edges = cv2.Canny(gray, 80, 200)
GaussianBlur#
Gaussian blur.
dst = cv2.GaussianBlur(src, ksize, sigmaX, dst=None, sigmaY=None, borderType=cv2.BORDER_DEFAULT)
Parameter |
Type |
Description |
|---|---|---|
|
|
Kernel size, e.g. |
|
|
Standard deviation in X direction |
blur#
Mean blur (box filter).
dst = cv2.blur(src, ksize, dst=None, anchor=None, borderType=cv2.BORDER_DEFAULT)
medianBlur#
Median blur.
dst = cv2.medianBlur(src, ksize, dst=None)
ksize must be odd, e.g. 5.
bilateralFilter#
Bilateral filter (edge-preserving denoising).
dst = cv2.bilateralFilter(src, d, sigmaColor, sigmaSpace, dst=None, borderType=cv2.BORDER_DEFAULT)
Parameter |
Type |
Description |
|---|---|---|
|
|
Diameter of pixel neighborhood |
|
|
Standard deviation in color space |
|
|
Standard deviation in coordinate space |
boxFilter#
Box filter.
dst = cv2.boxFilter(src, ddepth, ksize, dst=None, anchor=None, normalize=True, borderType=cv2.BORDER_DEFAULT)
filter2D#
Custom convolution kernel filter.
dst = cv2.filter2D(src, ddepth, kernel, dst=None, anchor=None, delta=None, borderType=cv2.BORDER_DEFAULT)
Parameter |
Type |
Description |
|---|---|---|
|
|
Output depth (-1 means same as input) |
|
|
Convolution kernel |
|
|
Optional offset added to each pixel |
kernel = np.ones((3, 3), dtype=np.float) / 9.0
result = cv2.filter2D(img, -1, kernel)
Sobel#
Sobel edge detection.
dst = cv2.Sobel(src, ddepth, dx, dy, dst=None, ksize=3, scale=None, delta=None, borderType=cv2.BORDER_DEFAULT)
Parameter |
Type |
Description |
|---|---|---|
|
|
Order of the derivative in X direction |
|
|
Order of the derivative in Y direction |
|
|
Kernel size (1/3/5/7) |
grad_x = cv2.Sobel(gray, cv2.CV_8U, 1, 0, ksize=3)
grad_y = cv2.Sobel(gray, cv2.CV_8U, 0, 1, ksize=3)
Scharr#
Scharr edge detection (higher accuracy than Sobel).
dst = cv2.Scharr(src, ddepth, dx, dy, dst=None, scale=None, delta=None, borderType=cv2.BORDER_DEFAULT)
Laplacian#
Laplacian edge detection.
dst = cv2.Laplacian(src, ddepth, dst=None, ksize=1, scale=None, delta=None, borderType=cv2.BORDER_DEFAULT)
Morphological Operations#
erode#
Erosion operation.
dst = cv2.erode(src, kernel, dst=None, anchor=None, iterations=1, borderType=cv2.BORDER_CONSTANT)
dilate#
Dilation operation.
dst = cv2.dilate(src, kernel, dst=None, anchor=None, iterations=1, borderType=cv2.BORDER_CONSTANT)
morphologyEx#
Advanced morphological operation.
dst = cv2.morphologyEx(src, op, kernel, dst=None, anchor=None, iterations=1, borderType=cv2.BORDER_CONSTANT)
See the morphological constants table for op values.
kernel = np.ones((3, 3), dtype=np.uint8)
opened = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
getStructuringElement#
Get structuring element.
kernel = cv2.getStructuringElement(shape, ksize, anchor=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
Shape ( |
|
|
Size, e.g. |
Threshold Processing#
threshold#
Global threshold segmentation.
retval, dst = cv2.threshold(src, thresh, maxval, type, dst=None)
Return value: (float, ndarray) — The actual threshold used and the output image.
ret, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
ret, otsu = cv2.threshold(gray, 0, 255, cv2.THRESH_OTSU)
adaptiveThreshold#
Adaptive threshold segmentation.
dst = cv2.adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C, dst=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
|
|
|
Neighborhood size (odd number) |
|
|
Constant subtracted from the mean/weighted mean |
result = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
cv2.THRESH_BINARY, 11, 2)
Color Space Conversion#
cvtColor#
Color space conversion.
dst = cv2.cvtColor(src, code, dst=None, dstCn=0)
Parameter |
Type |
Description |
|---|---|---|
|
|
Conversion code (see color conversion constants table) |
|
|
Target number of channels (0 means automatic) |
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
Geometric Transformations#
resize#
Image resizing.
dst = cv2.resize(src, dsize, dst=None, fx=None, fy=None, interpolation=cv2.INTER_LINEAR)
Parameter |
Type |
Description |
|---|---|---|
|
|
Target size |
|
|
Optional, X-direction scaling factor |
|
|
Optional, Y-direction scaling factor |
small = cv2.resize(img, (160, 120))
warpAffine#
Affine transformation.
dst = cv2.warpAffine(src, M, dsize, dst=None, flags=cv2.INTER_LINEAR,
borderMode=cv2.BORDER_CONSTANT, borderValue=None)
M is a 2x3 transformation matrix.
warpPerspective#
Perspective transformation.
dst = cv2.warpPerspective(src, M, dsize, dst=None, flags=cv2.INTER_LINEAR,
borderMode=cv2.BORDER_CONSTANT, borderValue=None)
M is a 3x3 transformation matrix.
Note:
getPerspectiveTransform/getAffineTransformconsume a significant amount of stack space during internal matrix solving, which may trigger stack overflow on the default 128KB thread stack. It is recommended to call them from the main REPL thread or increase the thread stack size.
getRotationMatrix2D#
Get a 2D rotation matrix.
M = cv2.getRotationMatrix2D(center, angle, scale)
Parameter |
Type |
Description |
|---|---|---|
|
|
Rotation center |
|
|
Rotation angle (in degrees, positive is counterclockwise) |
|
|
Scaling factor |
M = cv2.getRotationMatrix2D((160, 120), 45, 1.0)
rotated = cv2.warpAffine(img, M, (320, 240))
getAffineTransform ⚠#
Computes a 2x3 affine transformation matrix from three pairs of points.
M = cv2.getAffineTransform(src, dst)
src and dst are 3x2 point-set matrices.
getPerspectiveTransform ⚠#
Computes a 3x3 perspective transformation matrix from four pairs of points.
M = cv2.getPerspectiveTransform(src, dst, solveMethod=cv2.DECOMP_LU)
src and dst are 4x2 point-set matrices.
remap#
Pixel remapping.
dst = cv2.remap(src, map1, map2, interpolation, dst=None,
borderMode=cv2.BORDER_CONSTANT, borderValue=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
X coordinate mapping table |
|
|
Y coordinate mapping table |
|
|
Interpolation method (see interpolation constants table) |
Image Pyramid#
pyrDown#
Gaussian pyramid downsampling.
dst = cv2.pyrDown(src, dst=None, dstsize=None, borderType=cv2.BORDER_DEFAULT)
Image size is halved.
pyrUp#
Gaussian pyramid upsampling.
dst = cv2.pyrUp(src, dst=None, dstsize=None, borderType=cv2.BORDER_DEFAULT)
Image size is doubled.
Drawing Functions#
All drawing functions modify the input image in-place and return it, supporting chained calls.
line#
Draws a straight line.
img = cv2.line(img, pt1, pt2, color, thickness=1, lineType=cv2.LINE_8, shift=0)
Parameter |
Type |
Description |
|---|---|---|
|
|
Starting point |
|
|
Ending point |
|
|
Color, BGR tuple such as |
rectangle#
Draws a rectangle.
img = cv2.rectangle(img, pt1, pt2, color, thickness=1, lineType=cv2.LINE_8, shift=0)
When thickness=-1, the rectangle is filled.
cv2.rectangle(img, (10, 10), (80, 60), (0, 0, 255), -1) # Fill red rectangle
circle#
Draws a circle.
img = cv2.circle(img, center, radius, color, thickness=1, lineType=cv2.LINE_8, shift=0)
ellipse#
Draws an ellipse/arc.
img = cv2.ellipse(img, center, axes, angle, startAngle, endAngle, color,
thickness=1, lineType=cv2.LINE_8, shift=0)
Parameter |
Type |
Description |
|---|---|---|
|
|
Center of the ellipse |
|
|
Half-axis lengths |
|
|
Rotation angle |
|
|
Starting angle |
|
|
Ending angle |
putText#
Draws text.
img = cv2.putText(img, text, org, fontFace, fontScale, color,
thickness=1, lineType=cv2.LINE_8, bottomLeftOrigin=False)
Parameter |
Type |
Description |
|---|---|---|
|
|
Text content |
|
|
Position of the bottom-left corner of the text |
|
|
Font (see font constants table) |
|
|
Font scale factor |
arrowedLine#
Draws a line segment with an arrow.
img = cv2.arrowedLine(img, pt1, pt2, color, thickness=1, line_type=cv2.LINE_8, shift=0, tipLength=None)
drawMarker#
Draws a marker point.
img = cv2.drawMarker(img, position, color, markerType=cv2.MARKER_CROSS,
markerSize=20, thickness=1, line_type=cv2.LINE_8)
See marker constants table for markerType.
fillPoly#
Fills a polygon.
img = cv2.fillPoly(img, pts, color, lineType=cv2.LINE_8, shift=0, offset=None)
pts is a list of contour points, where each contour is an Nx2 ndarray.
tri = np.array([[20, 20], [80, 20], [50, 80]], dtype=np.float)
cv2.fillPoly(img, [tri], (0, 255, 0))
polylines#
Draws polygon outlines.
img = cv2.polylines(img, pts, isClosed, color, thickness=1, lineType=cv2.LINE_8, shift=0)
getTextSize#
Gets the rendered text size.
size, baseline = cv2.getTextSize(text, fontFace, fontScale, thickness)
Return value: ((width, height), baseline)
Contour Analysis#
findContours#
Find contours in a binary image.
contours, hierarchy = cv2.findContours(image, mode, method, contours=None, hierarchy=None, offset=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
Contour retrieval mode ( |
|
|
Contour approximation method ( |
Return value: (list[ndarray], ndarray) — list of contours and hierarchy.
drawContours#
Draw contours.
img = cv2.drawContours(image, contours, contourIdx, color, thickness=1,
lineType=cv2.LINE_8, hierarchy=None, maxLevel=INT_MAX, offset=None)
When contourIdx=-1, all contours are drawn.
contourArea#
Calculate the contour area.
area = cv2.contourArea(contour, oriented=False)
arcLength#
Calculate the contour perimeter.
perimeter = cv2.arcLength(curve, closed)
boundingRect#
Calculate the bounding upright rectangle.
x, y, w, h = cv2.boundingRect(array)
approxPolyDP#
Polygon approximation.
approx = cv2.approxPolyDP(curve, epsilon, closed)
epsilon is usually set to 0.02 * cv2.arcLength(curve, True).
convexHull#
Compute the convex hull.
hull = cv2.convexHull(points, hull=None, clockwise=False, returnPoints=True)
Parameter |
Type |
Description |
|---|---|---|
|
|
|
minAreaRect#
Minimum enclosing rotated rectangle.
center, size, angle = cv2.minAreaRect(points)
Return value: ((cx, cy), (w, h), angle) — center, size, rotation angle.
minEnclosingCircle#
Minimum enclosing circle.
center, radius = cv2.minEnclosingCircle(points)
fitEllipse#
Fit an ellipse.
center, size, angle = cv2.fitEllipse(points)
At least 5 points are required as input.
fitLine#
Fit a line.
line = cv2.fitLine(points, distType, param, reps, aeps)
Return value: (vx, vy, x0, y0) — unit direction vector + a point on the line.
pointPolygonTest#
Test the positional relationship between a point and a contour.
dist = cv2.pointPolygonTest(contour, pt, measureDist)
|
Behavior |
|---|---|
|
Returns signed shortest distance |
|
Returns +1 (inside), 0 (on edge), -1 (outside) |
convexityDefects#
Compute convexity defects.
defects = cv2.convexityDefects(contour, convexhull)
convexhull must be a 1D index array (i.e., the output of convexHull(..., returnPoints=False)).
matchShapes#
Shape matching (based on Hu moments).
score = cv2.matchShapes(contour1, contour2, method, parameter)
isContourConvex#
Determine whether a contour is convex.
result = cv2.isContourConvex(contour)
Returns bool.
Template Matching#
matchTemplate#
Template matching.
result = cv2.matchTemplate(image, templ, method, result=None, mask=None)
See the TM_* constants table for optional values of method.
result = cv2.matchTemplate(img, templ, cv2.TM_CCOEFF_NORMED)
_, max_val, _, max_loc = cv2.minMaxLoc(result)
Image Moments#
moments#
Computes image moments.
m = cv2.moments(array, binaryImage=False)
Returns a dict containing spatial moments (m00, m10, …), central moments (mu20, …), and normalized central moments (nu20, …).
m = cv2.moments(binary)
cx = m['m10'] / m['m00'] # Centroid X
cy = m['m01'] / m['m00'] # Centroid Y
Hough Transform#
HoughLines#
Standard Hough line detection.
lines = cv2.HoughLines(image, rho, theta, threshold, lines=None,
srn=None, stn=None, min_theta=None, max_theta=None)
Return value: Nx2 ndarray, each row is (rho, theta).
HoughLinesP#
Probabilistic Hough line detection (line segments).
lines = cv2.HoughLinesP(image, rho, theta, threshold, lines=None,
minLineLength=None, maxLineGap=None)
Return value: Nx4 ndarray, each row is (x1, y1, x2, y2).
lines = cv2.HoughLinesP(edges, 1, np.pi/180, 50, minLineLength=30)
for i in range(lines.shape[0]):
x1, y1, x2, y2 = lines[i, 0], lines[i, 1], lines[i, 2], lines[i, 3]
HoughCircles#
Hough circle detection.
circles = cv2.HoughCircles(image, method, dp, minDist, circles=None,
param1=None, param2=None, minRadius=0, maxRadius=0)
Parameter |
Type |
Description |
|---|---|---|
|
|
Detection method (3 = |
|
|
Inverse ratio of accumulator resolution to image resolution |
|
|
Minimum distance between circle centers |
|
|
Canny high threshold, default 100 |
|
|
Circle center accumulator threshold, default 100 |
|
|
Minimum radius |
|
|
Maximum radius |
Return value: Nx3 ndarray, each row is (cx, cy, r).
Histogram#
calcHist#
Computes the image histogram.
hist = cv2.calcHist(images, channels, mask, histSize, ranges)
Parameter |
Type |
Description |
|---|---|---|
|
|
Input image list |
|
|
List of channel indices to compute |
|
|
Optional 8-bit single-channel mask |
|
|
Number of bins for each dimension |
|
|
Value range for each dimension (flattened list) |
hist = cv2.calcHist([img], [0], None, [32], [0, 256])
calcBackProject#
Histogram back projection.
dst = cv2.calcBackProject(images, channels, hist, dst=None, ranges, scale=None)
Used to find regions in an image that match a histogram.
compareHist#
Histogram comparison.
score = cv2.compareHist(H1, H2, method)
See the HISTCMP_* constants table for method values.
equalizeHist#
Histogram equalization.
dst = cv2.equalizeHist(src, dst=None)
Corner Detection#
cornerHarris#
Harris corner detection.
dst = cv2.cornerHarris(src, blockSize, ksize, k, dst=None, borderType=cv2.BORDER_DEFAULT)
Parameter |
Type |
Description |
|---|---|---|
|
|
Neighborhood size for corner detection |
|
|
Sobel aperture size |
|
|
Harris detector free parameter (typically 0.04-0.06) |
goodFeaturesToTrack#
Shi-Tomasi corner detection.
corners = cv2.goodFeaturesToTrack(image, maxCorners, qualityLevel, minDistance,
mask=None, blockSize=3, useHarrisDetector=False, k=None)
Parameter |
Type |
Description |
|---|---|---|
|
|
Maximum number of corners |
|
|
Quality threshold (0.01-0.1) |
|
|
Minimum Euclidean distance between corners |
|
|
Window size for gradient computation |
Return value: Nx2 ndarray, each row is (x, y) (float coordinates).
cornerSubPix ⚠#
Sub-pixel accurate corner localization.
refined = cv2.cornerSubPix(image, corners, winSize, zeroZone, criteria)
Parameter |
Type |
Description |
|---|---|---|
|
|
Initial corner coordinates (e.g., output of |
|
|
Half-width of the search window |
|
|
Half-width of the dead zone |
|
|
Termination criteria |
Platform limitation: The
InputOutputArray(std::vector<Point2f>&)wrapping path of this ported OpenCV is inconsistent with the standard version, and calls will trigger acount >= 0assertion failure. For real-time detection scenarios, please usegoodFeaturesToTrackinstead.
Image Segmentation#
watershed#
Watershed segmentation.
markers = cv2.watershed(image, markers)
Parameter |
Type |
Description |
|---|---|---|
|
|
3-channel 8-bit input image |
|
|
int32 marker image (input/output parameter) |
distanceTransform#
Distance transform.
dst = cv2.distanceTransform(src, distanceType, maskSize, dst=None, dstType=cv2.CV_32F, labelType=cv2.DIST_LABEL_CCOMP)
Parameter |
Type |
Description |
|---|---|---|
|
|
Distance type ( |
|
|
Distance transform mask size (3 or 5) |
floodFill#
Flood fill.
filled, rect = cv2.floodFill(image, mask, seedPoint, newVal, loDiff=None, upDiff=None, flags=4)
Return value: (ndarray, (x, y, w, h)) — filled image and filled region bounding box.
filled, rect = cv2.floodFill(img, None, (50, 50), (0, 255, 0))
grabCut ⚠#
GrabCut foreground segmentation.
mask, bgd, fgd = cv2.grabCut(img, mask, rect, bgdModel, fgdModel, iterCount, mode=cv2.GC_INIT_WITH_RECT)
Note: The internal GMM iteration stack consumption is relatively large, and may overflow under the default 128KB thread stack. It is recommended to increase the stack or call it from the main REPL thread.
connectedComponents#
Connected components labeling.
nlabels, labels = cv2.connectedComponents(image, labels=None, connectivity=8, ltype=cv2.CV_32S)
Return value: (int, ndarray) — number of labels and marker image.
highgui — Interaction#
waitKey#
Wait for a key press.
key = cv2.waitKey(delay=0)
|
Behavior |
|---|---|
0 |
Wait indefinitely |
>0 |
Wait up to |
On the K230 MicroPython, input is read from the serial REPL.
waitKeyEx#
Enhanced version of waitKey, behaves the same as waitKey.
key = cv2.waitKeyEx(delay=0)
Constant Reference#
Morphology Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Erosion |
|
1 |
Dilation |
|
2 |
Opening |
|
3 |
Closing |
|
4 |
Morphological Gradient |
|
5 |
Top Hat |
|
6 |
Black Hat |
|
7 |
Hit-or-Miss |
|
0 |
Rectangular structuring element |
|
1 |
Cross-shaped structuring element |
|
2 |
Elliptical structuring element |
Threshold Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Binary |
|
1 |
Inverse Binary |
|
2 |
Truncate |
|
3 |
To Zero |
|
4 |
To Zero Inverted |
|
8 |
OTSU (can be combined with the above) |
|
16 |
Triangle method |
Adaptive Threshold Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Mean method |
|
1 |
Gaussian method |
Border Constants#
Constant |
Value |
|---|---|
|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
4 |
|
5 |
|
16 |
Interpolation Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Nearest neighbor |
|
1 |
Bilinear (default) |
|
2 |
Bicubic |
|
3 |
Area interpolation |
|
4 |
Lanczos |
|
5 |
Exact bilinear |
|
7 |
Interpolation mask |
|
8 |
Fill outliers |
|
16 |
Inverse mapping |
Color Conversion Constants#
Constant |
Value |
Description |
|---|---|---|
|
6 |
BGR → Grayscale |
|
7 |
RGB → Grayscale |
|
8 |
Grayscale → BGR |
|
8 |
Grayscale → RGB |
|
4 |
BGR ↔ RGB |
|
40 |
BGR → HSV |
|
54 |
HSV → BGR |
|
41 |
RGB → HSV |
|
55 |
HSV → RGB |
|
82 |
BGR → YUV |
|
84 |
YUV → BGR |
|
36 |
BGR → YCrCb |
|
38 |
YCrCb → BGR |
|
44 |
BGR → LAB |
|
56 |
LAB → BGR |
|
50 |
BGR → LUV |
|
58 |
LUV → BGR |
|
32 |
BGR → XYZ |
|
34 |
XYZ → BGR |
|
52 |
BGR → HLS |
|
60 |
HLS → BGR |
|
45 |
BGRA → BGR |
|
43 |
BGR → BGRA |
Font Constants#
Constant |
Value |
|---|---|
|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
16 (can be combined with the above) |
Line Constants#
Constant |
Value |
Description |
|---|---|---|
|
4 |
4-connected line |
|
8 |
8-connected line |
|
16 |
Anti-aliased line |
|
-1 |
Filled (used for thickness parameter) |
Contour Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Only detect the outermost contours |
|
1 |
Detect all contours |
|
2 |
Two-level hierarchy |
|
3 |
Full hierarchy tree |
|
4 |
Flood fill |
|
1 |
Save all contour points |
|
2 |
Compress and retain endpoints |
|
3 |
Teh-Chin chain L1 |
|
4 |
Teh-Chin chain kCos |
Shape Matching Constants#
Constant |
Value |
Description |
|---|---|---|
|
1 |
Method 1 |
|
2 |
Method 2 |
|
3 |
Method 3 |
Connected Components Constants#
Constant |
Value |
Description |
|---|---|---|
|
4 |
4-connected |
|
8 |
8-connected |
|
-1 |
Default algorithm |
|
0 |
Wu |
|
1 |
Grana |
|
2 |
Bolelli |
|
3 |
SAUF |
|
4 |
BBDT |
|
5 |
Spaghetti |
Distance Transform Constants#
Constant |
Value |
Description |
|---|---|---|
|
1 |
Manhattan distance |
|
2 |
Euclidean distance |
|
3 |
Chebyshev distance |
|
4 |
L1-L2 hybrid |
|
5 |
Fair |
|
6 |
Welsch |
|
7 |
Huber |
|
0 |
CComp labeling |
|
1 |
Pixel labeling |
Template Matching Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Squared difference |
|
1 |
Normalized squared difference |
|
2 |
Correlation |
|
3 |
Normalized correlation |
|
4 |
Correlation coefficient |
|
5 |
Normalized correlation coefficient |
Marker Type Constants#
Constant |
Value |
|---|---|
|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
Histogram Comparison Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Correlation |
|
1 |
Chi-square |
|
2 |
Intersection |
|
3 |
Bhattacharyya |
|
3 |
Hellinger (same as Bhattacharyya) |
|
4 |
Alternative Chi-square |
|
5 |
KL divergence |
GrabCut Constants#
Constant |
Value |
Description |
|---|---|---|
|
0 |
Definite background |
|
1 |
Definite foreground |
|
2 |
Probable background |
|
3 |
Probable foreground |
|
0 |
Rectangle initialization |
|
1 |
Mask initialization |
|
2 |
Evaluation mode |
|
3 |
Freeze model evaluation |
Termination Criteria Constants#
Constant |
Value |
Description |
|---|---|---|
|
1 |
Iteration count |
|
2 |
Precision |
|
1 |
Maximum iterations (same as COUNT) |
Usage Examples#
Complete Workflow: Read, Process, Save#
import cv2
from ulab import numpy as np
img = cv2.imread("/sdcard/input.jpg")
if img is None:
img = np.zeros((240, 320, 3), dtype=np.uint8)
cv2.circle(img, (160, 120), 80, (0, 255, 0), -1)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blurred, 50, 150)
contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
result = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
cv2.drawContours(result, contours, -1, (0, 255, 0), 2)
for cnt in contours:
x, y, w, h = cv2.boundingRect(cnt)
cv2.rectangle(result, (x, y), (x + w, y + h), (0, 0, 255), 2)
cv2.imwrite("/sdcard/output.jpg", result)
Image Arithmetic Blending#
img1 = cv2.imread("/sdcard/img1.jpg")
img2 = cv2.imread("/sdcard/img2.jpg")
blended = cv2.addWeighted(img1, 0.6, img2, 0.4, 0)
cv2.imwrite("/sdcard/blended.jpg", blended)
Color Segmentation (inRange)#
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
green_lo = np.array([35, 50, 50], dtype=np.uint8)
green_hi = np.array([85, 255, 255], dtype=np.uint8)
mask = cv2.inRange(hsv, green_lo, green_hi)
result = cv2.bitwise_and(img, img, mask=mask)
Histogram Analysis#
hist = cv2.calcHist([img], [0], None, [256], [0, 256])
hist2 = cv2.calcHist([img2], [0], None, [256], [0, 256])
score = cv2.compareHist(hist, hist2, cv2.HISTCMP_CORREL)
Real-time Camera Detection#
Capture frames from the camera, convert to numpy, and process in real-time with OpenCV. An image resolution of 320x240 is recommended for a higher frame rate.
import time, gc
from media.sensor import *
from media.display import *
from media.media import *
import cv2
from ulab import numpy as np
sensor = Sensor(width=1280, height=960, fps=90)
sensor.reset()
sensor.set_framesize(width=320, height=240)
sensor.set_pixformat(Sensor.RGB888) # OpenCV 需 RGB888
sensor.run()
Display.init(Display.ST7701, width=800, height=480, to_ide=True)
try:
while True:
img = sensor.snapshot() # image.Image
img_np = img.to_numpy_ref() # 共享内存转 ndarray
gray = cv2.cvtColor(img_np, cv2.COLOR_BGR2GRAY)
edges = cv2.Canny(gray, 60, 150)
lines = cv2.HoughLinesP(edges, 1, np.pi / 180, 60,
minLineLength=40, maxLineGap=15)
if lines is not None:
for i in range(lines.shape[0]):
x1, y1, x2, y2 = lines[i, 0], lines[i, 1], lines[i, 2], lines[i, 3]
cv2.line(img_np, (int(x1), int(y1)), (int(x2), int(y2)), (0, 255, 0), 2)
gc.collect()
Display.show_image(img) # 直接显示 (OpenCV 已修改共享内存)
finally:
sensor.stop()
Display.deinit()
More real-time detection examples can be found in the
demo_camera_*.pyfiles underresources/examples/24-OpenCV/.
