0
# OpenCV-Python
1

2
Pre-built Python bindings for OpenCV (Open Source Computer Vision Library), providing comprehensive computer vision and image processing capabilities with over 2500 algorithms. OpenCV is the industry-standard library for computer vision tasks including image and video processing, object detection, face recognition, feature extraction, camera calibration, machine learning, and real-time analysis.
3

4
## Package Information
5

6
- **Package Name**: opencv-python
7
- **Language**: Python
8
- **Installation**: `pip install opencv-python`
9
- **Official Documentation**: https://docs.opencv.org/4.x/
10

11
## Package Variants
12

13
OpenCV-Python is available in four variants (install only one):
14

15
1. **opencv-python** - Main modules for desktop environments (includes GUI)
16
2. **opencv-contrib-python** - Main + contrib/extra experimental modules (includes GUI)
17
3. **opencv-python-headless** - Main modules without GUI dependencies (for servers/Docker)
18
4. **opencv-contrib-python-headless** - Main + contrib modules without GUI (for servers/Docker)
19

20
## Core Imports
21

22
```python
23
import cv2
24
```
25

26
All OpenCV functionality is accessed through the `cv2` module.
27

28
## Basic Usage
29

30
```python
31
import cv2
32
import numpy as np
33

34
# Read an image
35
image = cv2.imread('photo.jpg')
36

37
# Convert to grayscale
38
gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
39

40
# Apply Gaussian blur
41
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
42

43
# Detect edges using Canny
44
edges = cv2.Canny(blurred, 50, 150)
45

46
# Display the result (requires GUI)
47
cv2.imshow('Edges', edges)
48
cv2.waitKey(0)
49
cv2.destroyAllWindows()
50

51
# Save the result
52
cv2.imwrite('edges.jpg', edges)
53

54
# Video capture from camera
55
cap = cv2.VideoCapture(0)
56
ret, frame = cap.read()
57
cap.release()
58
```
59

60
## Architecture
61

62
OpenCV is organized into modular components:
63

64
- **Core Module** - Fundamental data structures (Mat arrays), basic operations, linear algebra
65
- **Image Processing** - Filtering, transformations, color conversion, histograms, feature detection
66
- **Video I/O** - Reading and writing video files and camera streams
67
- **GUI Module** - Window management, event handling, simple UI elements (highgui)
68
- **Video Analysis** - Motion analysis, object tracking, background subtraction
69
- **Camera Calibration** - Camera calibration, stereo vision, 3D reconstruction
70
- **2D Features** - Feature detection and description (SIFT, ORB, AKAZE)
71
- **Object Detection** - Cascade classifiers, HOG descriptor, DNN module
72
- **Deep Learning** - DNN inference engine supporting multiple frameworks
73
- **Machine Learning** - Statistical ML algorithms (SVM, KNN, Decision Trees, Neural Networks)
74

75
### Image Representation
76

77
OpenCV represents images as NumPy arrays:
78
- **Color images**: `(height, width, channels)` - default BGR color order
79
- **Grayscale images**: `(height, width)`
80
- **Default data type**: `numpy.uint8` (values 0-255)
81
- **Coordinate system**: Origin (0,0) at top-left, X-axis right, Y-axis down
82

83
**Important**: OpenCV uses **BGR** color order (not RGB). Use `cv2.cvtColor()` to convert between color spaces.
84

85
## Capabilities
86

87
### Core Operations and Array Manipulation
88

89
Core functionality for working with multi-dimensional arrays (images, matrices) including arithmetic operations, logical operations, array transformations, linear algebra, and random number generation.
90

91
```python { .api }
92
# Arithmetic operations
93
def add(src1, src2, dst=None, mask=None, dtype=None): ...
94
def subtract(src1, src2, dst=None, mask=None, dtype=None): ...
95
def multiply(src1, src2, dst=None, scale=None, dtype=None): ...
96
def divide(src1, src2, dst=None, scale=None, dtype=None): ...
97
def addWeighted(src1, alpha, src2, beta, gamma, dst=None, dtype=None): ...
98

99
# Logical operations
100
def bitwise_and(src1, src2, dst=None, mask=None): ...
101
def bitwise_or(src1, src2, dst=None, mask=None): ...
102
def bitwise_xor(src1, src2, dst=None, mask=None): ...
103
def bitwise_not(src, dst=None, mask=None): ...
104

105
# Array transformations
106
def flip(src, flipCode, dst=None): ...
107
def rotate(src, rotateCode, dst=None): ...
108
def transpose(src, dst=None): ...
109
def split(m): ...
110
def merge(mv, dst=None): ...
111

112
# Statistics and analysis
113
def mean(src, mask=None): ...
114
def norm(src1, normType=None, mask=None): ...
115
def normalize(src, dst, alpha=None, beta=None, norm_type=None, dtype=None, mask=None): ...
116
def minMaxLoc(src, mask=None): ...
117
def meanStdDev(src, mean=None, stddev=None, mask=None): ...
118
def countNonZero(src): ...
119

120
# Mathematical operations
121
def sqrt(src, dst=None): ...
122
def pow(src, power, dst=None): ...
123
def exp(src, dst=None): ...
124
def log(src, dst=None): ...
125

126
# Fourier transforms
127
def dft(src, dst=None, flags=0, nonzeroRows=0): ...
128
def idft(src, dst=None, flags=0, nonzeroRows=0): ...
129

130
# Image border operations
131
def copyMakeBorder(src, top, bottom, left, right, borderType, dst=None, value=None): ...
132
```
133

134
[Core Operations](./core-operations.md)
135

136
### Image I/O and Video Capture
137

138
Reading and writing images and videos, capturing from cameras and video files, codec configuration.
139

140
```python { .api }
141
# Image I/O
142
def imread(filename, flags=None): ...
143
def imwrite(filename, img, params=None): ...
144
def imdecode(buf, flags): ...
145
def imencode(ext, img, params=None): ...
146
def imreadmulti(filename, mats, flags=None): ...
147
def imcount(filename, flags=None): ...
148
def haveImageReader(filename): ...
149
def haveImageWriter(filename): ...
150

151
# Video capture
152
class VideoCapture:
153
    def __init__(self, index): ...
154
    def read(self): ...
155
    def grab(self): ...
156
    def retrieve(self, image=None, flag=None): ...
157
    def get(self, propId): ...
158
    def set(self, propId, value): ...
159
    def release(self): ...
160
    def isOpened(self): ...
161

162
# Video writing
163
class VideoWriter:
164
    def __init__(self, filename, fourcc, fps, frameSize, isColor=True): ...
165
    def write(self, image): ...
166
    def release(self): ...
167
    def isOpened(self): ...
168

169
def VideoWriter_fourcc(*args): ...
170
```
171

172
[Image and Video I/O](./image-video-io.md)
173

174
### Image Processing and Filtering
175

176
Comprehensive image processing including smoothing, edge detection, morphological operations, geometric transformations, color space conversion, and histogram operations.
177

178
```python { .api }
179
# Filtering
180
def blur(src, ksize, dst=None, anchor=None, borderType=None): ...
181
def GaussianBlur(src, ksize, sigmaX, dst=None, sigmaY=None, borderType=None): ...
182
def medianBlur(src, ksize, dst=None): ...
183
def bilateralFilter(src, d, sigmaColor, sigmaSpace, dst=None, borderType=None): ...
184
def filter2D(src, ddepth, kernel, dst=None, anchor=None, delta=None, borderType=None): ...
185
def Sobel(src, ddepth, dx, dy, dst=None, ksize=None, scale=None, delta=None, borderType=None): ...
186
def Laplacian(src, ddepth, dst=None, ksize=None, scale=None, delta=None, borderType=None): ...
187
def Canny(image, threshold1, threshold2, edges=None, apertureSize=None, L2gradient=None): ...
188

189
# Corner detection
190
def goodFeaturesToTrack(image, maxCorners, qualityLevel, minDistance, corners=None, mask=None, blockSize=3, useHarrisDetector=False, k=0.04): ...
191
def cornerHarris(src, blockSize, ksize, k, dst=None, borderType=None): ...
192
def cornerSubPix(image, corners, winSize, zeroZone, criteria): ...
193

194
# Morphological operations
195
def erode(src, kernel, dst=None, anchor=None, iterations=None, borderType=None, borderValue=None): ...
196
def dilate(src, kernel, dst=None, anchor=None, iterations=None, borderType=None, borderValue=None): ...
197
def morphologyEx(src, op, kernel, dst=None, anchor=None, iterations=None, borderType=None, borderValue=None): ...
198
def getStructuringElement(shape, ksize, anchor=None): ...
199

200
# Geometric transformations
201
def resize(src, dsize, dst=None, fx=None, fy=None, interpolation=None): ...
202
def warpAffine(src, M, dsize, dst=None, flags=None, borderMode=None, borderValue=None): ...
203
def warpPerspective(src, M, dsize, dst=None, flags=None, borderMode=None, borderValue=None): ...
204
def getRotationMatrix2D(center, angle, scale): ...
205
def getAffineTransform(src, dst): ...
206
def getPerspectiveTransform(src, dst): ...
207

208
# Color conversion
209
def cvtColor(src, code, dst=None, dstCn=None): ...
210

211
# Thresholding
212
def threshold(src, thresh, maxval, type, dst=None): ...
213
def adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C, dst=None): ...
214

215
# Segmentation
216
def connectedComponents(image, labels=None, connectivity=8, ltype=None): ...
217
def connectedComponentsWithStats(image, labels=None, stats=None, centroids=None, connectivity=8, ltype=None): ...
218
def grabCut(img, mask, rect, bgdModel, fgdModel, iterCount, mode=None): ...
219
```
220

221
[Image Processing](./image-processing.md)
222

223
### Contour Detection and Shape Analysis
224

225
Finding and analyzing contours, calculating shape properties, fitting geometric primitives, and shape matching.
226

227
```python { .api }
228
# Contour detection
229
def findContours(image, mode, method, contours=None, hierarchy=None, offset=None): ...
230
def drawContours(image, contours, contourIdx, color, thickness=None, lineType=None, hierarchy=None, maxLevel=None, offset=None): ...
231

232
# Contour analysis
233
def contourArea(contour, oriented=None): ...
234
def arcLength(curve, closed): ...
235
def approxPolyDP(curve, epsilon, closed, approxCurve=None): ...
236
def convexHull(points, hull=None, clockwise=None, returnPoints=None): ...
237
def boundingRect(array): ...
238
def minAreaRect(points): ...
239
def minEnclosingCircle(points): ...
240
def fitEllipse(points): ...
241
def moments(array, binaryImage=None): ...
242
def HuMoments(m, hu=None): ...
243
def matchShapes(contour1, contour2, method, parameter): ...
244
def pointPolygonTest(contour, pt, measureDist): ...
245
```
246

247
[Contours and Shapes](./contours-shapes.md)
248

249
### Feature Detection and Description
250

251
Detecting and describing features for image matching, object recognition, and tracking.
252

253
```python { .api }
254
# SIFT (Scale-Invariant Feature Transform)
255
class SIFT(cv2.Feature2D):
256
    @staticmethod
257
    def create(nfeatures=None, nOctaveLayers=None, contrastThreshold=None, edgeThreshold=None, sigma=None): ...
258

259
# ORB (Oriented FAST and Rotated BRIEF)
260
class ORB(cv2.Feature2D):
261
    @staticmethod
262
    def create(nfeatures=None, scaleFactor=None, nlevels=None, edgeThreshold=None, firstLevel=None, WTA_K=None, scoreType=None, patchSize=None, fastThreshold=None): ...
263

264
# AKAZE
265
class AKAZE(cv2.Feature2D):
266
    @staticmethod
267
    def create(descriptor_type=None, descriptor_size=None, descriptor_channels=None, threshold=None, nOctaves=None, nOctaveLayers=None, diffusivity=None): ...
268

269
# Feature2D base class methods
270
class Feature2D:
271
    def detect(self, image, mask=None): ...
272
    def compute(self, image, keypoints, descriptors=None): ...
273
    def detectAndCompute(self, image, mask, descriptors=None): ...
274

275
# Feature matching
276
class BFMatcher(cv2.DescriptorMatcher):
277
    def __init__(self, normType=None, crossCheck=None): ...
278

279
class FlannBasedMatcher(cv2.DescriptorMatcher):
280
    def __init__(self, indexParams=None, searchParams=None): ...
281

282
class DescriptorMatcher:
283
    def match(self, queryDescriptors, trainDescriptors, mask=None): ...
284
    def knnMatch(self, queryDescriptors, trainDescriptors, k, mask=None, compactResult=None): ...
285

286
# Drawing
287
def drawKeypoints(image, keypoints, outImage, color=None, flags=None): ...
288
def drawMatches(img1, keypoints1, img2, keypoints2, matches1to2, outImg, matchColor=None, singlePointColor=None, matchesMask=None, flags=None): ...
289
```
290

291
[Feature Detection](./feature-detection.md)
292

293
### Object Detection and Recognition
294

295
Pre-trained classifiers for detecting faces, eyes, pedestrians, and other objects, plus QR code detection.
296

297
```python { .api }
298
# Cascade classifier
299
class CascadeClassifier:
300
    def __init__(self, filename=None): ...
301
    def load(self, filename): ...
302
    def detectMultiScale(self, image, scaleFactor=None, minNeighbors=None, flags=None, minSize=None, maxSize=None): ...
303

304
# HOG descriptor
305
class HOGDescriptor:
306
    def __init__(self): ...
307
    def compute(self, img, winStride=None, padding=None, locations=None): ...
308
    def detectMultiScale(self, img, hitThreshold=None, winStride=None, padding=None, scale=None, finalThreshold=None, useMeanshiftGrouping=None): ...
309
    def setSVMDetector(self, _svmdetector): ...
310
    @staticmethod
311
    def getDefaultPeopleDetector(): ...
312

313
# QR code detection
314
class QRCodeDetector:
315
    def __init__(self): ...
316
    def detect(self, img, points=None): ...
317
    def decode(self, img, points, straight_qrcode=None): ...
318
    def detectAndDecode(self, img, points=None, straight_qrcode=None): ...
319
```
320

321
**Data files**: Haar cascade XML files are included via `cv2.data.haarcascades` path.
322

323
[Object Detection](./object-detection.md)
324

325
### Camera Calibration and 3D Reconstruction
326

327
Camera calibration, stereo vision, pose estimation, and 3D reconstruction from 2D images.
328

329
```python { .api }
330
# Camera calibration
331
def calibrateCamera(objectPoints, imagePoints, imageSize, cameraMatrix, distCoeffs, rvecs=None, tvecs=None, flags=None, criteria=None): ...
332
def findChessboardCorners(image, patternSize, corners=None, flags=None): ...
333
def findCirclesGrid(image, patternSize, centers=None, flags=None, blobDetector=None): ...
334
def drawChessboardCorners(image, patternSize, corners, patternWasFound): ...
335
def cornerSubPix(image, corners, winSize, zeroZone, criteria): ...
336

337
# Pose estimation
338
def solvePnP(objectPoints, imagePoints, cameraMatrix, distCoeffs, rvec=None, tvec=None, useExtrinsicGuess=None, flags=None): ...
339
def projectPoints(objectPoints, rvec, tvec, cameraMatrix, distCoeffs, imagePoints=None, jacobian=None, aspectRatio=None): ...
340
def Rodrigues(src, dst=None, jacobian=None): ...
341

342
# Undistortion
343
def undistort(src, cameraMatrix, distCoeffs, dst=None, newCameraMatrix=None): ...
344
def undistortPoints(src, cameraMatrix, distCoeffs, dst=None, R=None, P=None): ...
345
def getOptimalNewCameraMatrix(cameraMatrix, distCoeffs, imageSize, alpha, newImgSize=None, centerPrincipalPoint=None): ...
346
def initUndistortRectifyMap(cameraMatrix, distCoeffs, R, newCameraMatrix, size, m1type, map1=None, map2=None): ...
347

348
# Stereo
349
def stereoCalibrate(objectPoints, imagePoints1, imagePoints2, cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, imageSize, R=None, T=None, E=None, F=None, flags=None, criteria=None): ...
350
def stereoRectify(cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, imageSize, R, T, R1=None, R2=None, P1=None, P2=None, Q=None, flags=None, alpha=None, newImageSize=None): ...
351

352
# Homography and fundamental matrix
353
def findHomography(srcPoints, dstPoints, method=None, ransacReprojThreshold=None, mask=None, maxIters=None, confidence=None): ...
354
def findFundamentalMat(points1, points2, method=None, param1=None, param2=None, mask=None): ...
355
```
356

357
[Camera Calibration](./camera-calibration.md)
358

359
### Video Analysis and Object Tracking
360

361
Motion estimation, optical flow, background subtraction, and object tracking algorithms.
362

363
```python { .api }
364
# Optical flow
365
def calcOpticalFlowPyrLK(prevImg, nextImg, prevPts, nextPts, status=None, err=None, winSize=None, maxLevel=None, criteria=None, flags=None, minEigThreshold=None): ...
366
def calcOpticalFlowFarneback(prev, next, flow, pyr_scale, levels, winsize, iterations, poly_n, poly_sigma, flags): ...
367
def buildOpticalFlowPyramid(img, pyramid, winSize, maxLevel, withDerivatives=True, pyrBorder=None, derivBorder=None, tryReuseInputImage=True): ...
368
def readOpticalFlow(path): ...
369
def writeOpticalFlow(path, flow): ...
370

371
# Background subtraction
372
class BackgroundSubtractorMOG2(cv2.BackgroundSubtractor):
373
    def apply(self, image, fgmask=None, learningRate=None): ...
374
    def getBackgroundImage(self, backgroundImage=None): ...
375

376
class BackgroundSubtractorKNN(cv2.BackgroundSubtractor):
377
    def apply(self, image, fgmask=None, learningRate=None): ...
378
    def getBackgroundImage(self, backgroundImage=None): ...
379

380
def createBackgroundSubtractorMOG2(history=None, varThreshold=None, detectShadows=None): ...
381
def createBackgroundSubtractorKNN(history=None, dist2Threshold=None, detectShadows=None): ...
382

383
# Mean shift
384
def meanShift(probImage, window, criteria): ...
385
def CamShift(probImage, window, criteria): ...
386

387
# Tracking (newer API)
388
class TrackerDaSiamRPN(cv2.Tracker): ...
389
class TrackerMIL(cv2.Tracker): ...
390
class TrackerKCF(cv2.Tracker): ...
391

392
# Kalman filter
393
class KalmanFilter:
394
    def __init__(self, dynamParams, measureParams, controlParams=None, type=None): ...
395
    def predict(self, control=None): ...
396
    def correct(self, measurement): ...
397
```
398

399
[Video Analysis](./video-analysis.md)
400

401
### Deep Neural Networks (DNN Module)
402

403
Deep learning inference engine supporting models from TensorFlow, PyTorch, Caffe, ONNX, and Darknet.
404

405
```python { .api }
406
# Loading models
407
def dnn.readNet(model, config=None, framework=None): ...
408
def dnn.readNetFromCaffe(prototxt, caffeModel=None): ...
409
def dnn.readNetFromTensorflow(model, config=None): ...
410
def dnn.readNetFromONNX(onnxFile): ...
411
def dnn.readNetFromDarknet(cfgFile, darknetModel=None): ...
412

413
# Blob operations
414
def dnn.blobFromImage(image, scalefactor=None, size=None, mean=None, swapRB=None, crop=None, ddepth=None): ...
415
def dnn.blobFromImages(images, scalefactor=None, size=None, mean=None, swapRB=None, crop=None, ddepth=None): ...
416

417
# Neural network class
418
class dnn.Net:
419
    def setInput(self, blob, name=None, scalefactor=None, mean=None): ...
420
    def forward(self, outputName=None): ...
421
    def setPreferableBackend(self, backendId): ...
422
    def setPreferableTarget(self, targetId): ...
423
    def getLayerNames(self): ...
424
    def getUnconnectedOutLayersNames(self): ...
425

426
# Non-maximum suppression
427
def dnn.NMSBoxes(bboxes, scores, score_threshold, nms_threshold, eta=None, top_k=None): ...
428
```
429

430
[Deep Neural Networks](./dnn.md)
431

432
### Machine Learning
433

434
Statistical machine learning algorithms including SVM, decision trees, neural networks, k-nearest neighbors, and clustering.
435

436
```python { .api }
437
# SVM
438
class ml.SVM(cv2.ml.StatModel):
439
    @staticmethod
440
    def create(): ...
441
    def train(self, samples, layout, responses): ...
442
    def predict(self, samples, results=None, flags=None): ...
443
    def setKernel(self, kernelType): ...
444
    def setType(self, val): ...
445

446
# K-Nearest Neighbors
447
class ml.KNearest(cv2.ml.StatModel):
448
    @staticmethod
449
    def create(): ...
450
    def findNearest(self, samples, k, results=None, neighborResponses=None, dist=None): ...
451

452
# Decision Trees
453
class ml.DTrees(cv2.ml.StatModel):
454
    @staticmethod
455
    def create(): ...
456

457
# Random Forest
458
class ml.RTrees(cv2.ml.DTrees):
459
    @staticmethod
460
    def create(): ...
461

462
# Neural Networks
463
class ml.ANN_MLP(cv2.ml.StatModel):
464
    @staticmethod
465
    def create(): ...
466
    def setLayerSizes(self, _layer_sizes): ...
467
    def setActivationFunction(self, type, param1=None, param2=None): ...
468
    def setTrainMethod(self, method, param1=None, param2=None): ...
469

470
# Base class
471
class ml.StatModel:
472
    def train(self, samples, layout, responses): ...
473
    def predict(self, samples, results=None, flags=None): ...
474
    def save(self, filename): ...
475
    @staticmethod
476
    def load(filename): ...
477

478
# K-means clustering
479
def kmeans(data, K, bestLabels, criteria, attempts, flags, centers=None): ...
480
```
481

482
[Machine Learning](./machine-learning.md)
483

484
### GUI and Visualization
485

486
Window management, image display, trackbars, mouse event handling, and user interaction (not available in headless packages).
487

488
```python { .api }
489
# Window operations
490
def imshow(winname, mat): ...
491
def namedWindow(winname, flags=None): ...
492
def destroyWindow(winname): ...
493
def destroyAllWindows(): ...
494
def waitKey(delay=None): ...
495
def resizeWindow(winname, width, height): ...
496
def moveWindow(winname, x, y): ...
497
def setWindowTitle(winname, title): ...
498

499
# Trackbar
500
def createTrackbar(trackbarname, winname, value, count, onChange): ...
501
def getTrackbarPos(trackbarname, winname): ...
502
def setTrackbarPos(trackbarname, winname, pos): ...
503
def setTrackbarMin(trackbarname, winname, minval): ...
504
def setTrackbarMax(trackbarname, winname, maxval): ...
505

506
# Mouse events
507
def setMouseCallback(winname, onMouse, param=None): ...
508

509
# ROI selection
510
def selectROI(windowName, img, showCrosshair=None, fromCenter=None): ...
511
def selectROIs(windowName, img, showCrosshair=None, fromCenter=None): ...
512

513
# Drawing functions
514
def line(img, pt1, pt2, color, thickness=None, lineType=None, shift=None): ...
515
def circle(img, center, radius, color, thickness=None, lineType=None, shift=None): ...
516
def rectangle(img, pt1, pt2, color, thickness=None, lineType=None, shift=None): ...
517
def ellipse(img, center, axes, angle, startAngle, endAngle, color, thickness=None, lineType=None, shift=None): ...
518
def polylines(img, pts, isClosed, color, thickness=None, lineType=None, shift=None): ...
519
def fillPoly(img, pts, color, lineType=None, shift=None, offset=None): ...
520
def putText(img, text, org, fontFace, fontScale, color, thickness=None, lineType=None, bottomLeftOrigin=None): ...
521
```
522

523
[GUI and Drawing](./gui-drawing.md)
524

525
### Computational Photography
526

527
Advanced image processing for inpainting, denoising, HDR imaging, seamless cloning, and artistic effects.
528

529
```python { .api }
530
# Inpainting
531
def inpaint(src, inpaintMask, inpaintRadius, flags, dst=None): ...
532

533
# Denoising
534
def fastNlMeansDenoising(src, dst=None, h=None, templateWindowSize=None, searchWindowSize=None): ...
535
def fastNlMeansDenoisingColored(src, dst=None, h=None, hColor=None, templateWindowSize=None, searchWindowSize=None): ...
536

537
# Seamless cloning
538
def seamlessClone(src, dst, mask, p, flags, blend=None): ...
539

540
# Stylization
541
def stylization(src, dst=None, sigma_s=None, sigma_r=None): ...
542
def pencilSketch(src, dst1=None, dst2=None, sigma_s=None, sigma_r=None, shade_factor=None): ...
543
def detailEnhance(src, dst=None, sigma_s=None, sigma_r=None): ...
544
def edgePreservingFilter(src, dst=None, flags=None, sigma_s=None, sigma_r=None): ...
545

546
# HDR
547
def createMergeMertens(contrast_weight=None, saturation_weight=None, exposure_weight=None): ...
548
def createTonemapDrago(gamma=None, saturation=None, bias=None): ...
549
def createTonemapReinhard(gamma=None, intensity=None, light_adapt=None, color_adapt=None): ...
550
```
551

552
[Computational Photography](./computational-photography.md)
553

554
### Image Stitching
555

556
Creating panoramas from multiple images.
557

558
```python { .api }
559
class Stitcher:
560
    @staticmethod
561
    def create(mode=None): ...
562
    def stitch(self, images, masks=None): ...
563
    def estimateTransform(self, images, masks=None): ...
564
    def composePanorama(self, images=None): ...
565

566
def createStitcher(try_use_gpu=None): ...
567
```
568

569
### ArUco Marker Detection
570

571
Detecting and using ArUco fiducial markers for augmented reality and camera pose estimation.
572

573
```python { .api }
574
# Dictionary
575
def aruco.getPredefinedDictionary(name): ...
576

577
# Detection
578
class aruco.ArucoDetector:
579
    def __init__(self, dictionary, detectorParams=None): ...
580
    def detectMarkers(self, image, corners=None, ids=None, rejectedImgPoints=None): ...
581

582
# Drawing
583
def aruco.drawDetectedMarkers(image, corners, ids=None, borderColor=None): ...
584
def aruco.drawMarker(dictionary, id, sidePixels, img=None, borderBits=None): ...
585

586
# Pose estimation
587
def aruco.estimatePoseSingleMarkers(corners, markerLength, cameraMatrix, distCoeffs, rvecs=None, tvecs=None): ...
588
```
589

590
[ArUco Markers](./aruco.md)
591

592
## Types
593

594
### Core Data Structures
595

596
```python { .api }
597
class Mat:
598
    """
599
    Multi-dimensional dense array class - the primary data structure for images and matrices.
600
    In Python, Mat objects are represented as NumPy arrays.
601

602
    Images are stored with shape (height, width) for grayscale or (height, width, channels) for color.
603
    OpenCV uses BGR color order by default, not RGB.
604
    """
605
    pass
606

607
class UMat:
608
    """
609
    Unified memory array for transparent GPU acceleration via OpenCL.
610
    Provides the same interface as Mat but can execute operations on GPU when available.
611
    """
612
    pass
613

614
# Scalar type
615
"""
616
4-element vector used to pass pixel values. In Python bindings, scalars are represented as tuples.
617
For BGR images: (b, g, r) or (b, g, r, alpha)
618
For grayscale: (value,) or just value
619
Example: cv2.circle(img, (100, 100), 50, (255, 0, 0), 2)  # Blue circle
620
"""
621

622
# Point types
623
"""
624
Points are represented as tuples in Python bindings:
625
- Point (2D integer): (x, y)
626
- Point2f (2D float): (x, y)
627
- Point3 (3D integer): (x, y, z)
628
- Point3f (3D float): (x, y, z)
629

630
Examples:
631
  center = (100, 200)  # Point
632
  corner = (50.5, 75.3)  # Point2f
633
  vertex = (10, 20, 30)  # Point3
634
"""
635

636
# Size type
637
"""
638
Size of a 2D rectangle. In Python bindings, sizes are represented as tuples (width, height).
639
Example: img_resized = cv2.resize(img, (640, 480))  # Resize to 640x480
640
"""
641

642
# Rect type
643
"""
644
Rectangle defined by top-left corner and size. In Python bindings, rectangles are represented as tuples.
645
Format: (x, y, width, height)
646
Example: roi = (50, 100, 200, 150)  # Rectangle at (50,100) with 200x150 size
647
"""
648

649
class RotatedRect:
650
    """Rotated rectangle represented by center, size, and angle"""
651
    center: tuple  # (x, y) center coordinates
652
    size: tuple  # (width, height)
653
    angle: float  # rotation angle in degrees
654
    def __init__(self, center, size, angle): ...
655

656
# Range type
657
"""
658
Integer range [start, end) - includes start, excludes end.
659
In Python bindings, ranges are represented as tuples (start, end) or use Python slice notation.
660
Example: subarray = array[0:10] or with tuple (0, 10) in certain functions
661
"""
662

663
# TermCriteria type
664
"""
665
Termination criteria for iterative algorithms. In Python bindings, represented as a tuple.
666
Format: (type, maxCount, epsilon)
667
- type: cv2.TERM_CRITERIA_COUNT, cv2.TERM_CRITERIA_EPS, or combined with | operator
668
- maxCount: maximum number of iterations
669
- epsilon: required accuracy
670

671
Example: criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_COUNT, 30, 0.001)
672
"""
673

674
class KeyPoint:
675
    """Data structure for salient point detectors"""
676
    pt: tuple  # (x, y) coordinates of the keypoint
677
    size: float  # diameter of the meaningful keypoint neighborhood
678
    angle: float  # computed orientation of the keypoint (-1 if not applicable)
679
    response: float  # response by which the strongest keypoints have been selected
680
    octave: int  # octave (pyramid layer) from which the keypoint has been extracted
681
    class_id: int  # object class (if the keypoints need to be clustered by an object they belong to)
682

683
class DMatch:
684
    """Match between two keypoint descriptors"""
685
    queryIdx: int  # query descriptor index
686
    trainIdx: int  # train descriptor index
687
    imgIdx: int  # train image index
688
    distance: float  # distance between descriptors (lower is better)
689

690
# Random Number Generation
691
"""
692
Note: The cv2.RNG class is not directly available in Python bindings.
693
For random number generation, use NumPy's random module instead:
694
- np.random.uniform(a, b) - Generate uniform random numbers
695
- np.random.normal(mean, std) - Generate Gaussian random numbers
696
- np.random.randint(low, high) - Generate random integers
697

698
Example:
699
  import numpy as np
700
  random_values = np.random.uniform(0, 255, (100, 100, 3)).astype(np.uint8)
701
"""
702
```
703

704
### Common Constants
705

706
Color conversion codes (partial list):
707
```python { .api }
708
COLOR_BGR2GRAY: int
709
COLOR_BGR2RGB: int
710
COLOR_BGR2HSV: int
711
COLOR_BGR2LAB: int
712
COLOR_GRAY2BGR: int
713
COLOR_HSV2BGR: int
714
COLOR_LAB2BGR: int
715
```
716

717
Interpolation methods:
718
```python { .api }
719
INTER_NEAREST: int  # nearest neighbor interpolation
720
INTER_LINEAR: int  # bilinear interpolation
721
INTER_CUBIC: int  # bicubic interpolation
722
INTER_LANCZOS4: int  # Lanczos interpolation over 8x8 neighborhood
723
```
724

725
Threshold types:
726
```python { .api }
727
THRESH_BINARY: int
728
THRESH_BINARY_INV: int
729
THRESH_TRUNC: int
730
THRESH_TOZERO: int
731
THRESH_TOZERO_INV: int
732
THRESH_OTSU: int  # Otsu's algorithm
733
```
734

735
Data types:
736
```python { .api }
737
CV_8U: int   # 8-bit unsigned integer
738
CV_8S: int   # 8-bit signed integer
739
CV_16U: int  # 16-bit unsigned integer
740
CV_16S: int  # 16-bit signed integer
741
CV_32S: int  # 32-bit signed integer
742
CV_32F: int  # 32-bit floating point
743
CV_64F: int  # 64-bit floating point
744
```
745

746
Norm types:
747
```python { .api }
748
NORM_L1: int        # L1 norm (sum of absolute values)
749
NORM_L2: int        # L2 norm (Euclidean distance)
750
NORM_INF: int       # Infinity norm (maximum absolute value)
751
NORM_HAMMING: int   # Hamming distance for binary descriptors
752
NORM_HAMMING2: int  # Hamming distance with 2-bit precision
753
```
754

755
Comparison operators:
756
```python { .api }
757
CMP_EQ: int  # Equal (==)
758
CMP_GT: int  # Greater than (>)
759
CMP_GE: int  # Greater than or equal (>=)
760
CMP_LT: int  # Less than (<)
761
CMP_LE: int  # Less than or equal (<=)
762
CMP_NE: int  # Not equal (!=)
763
```
764

765
K-means clustering flags:
766
```python { .api }
767
KMEANS_RANDOM_CENTERS: int     # Random initial centers
768
KMEANS_PP_CENTERS: int         # K-means++ center initialization
769
KMEANS_USE_INITIAL_LABELS: int # Use user-provided initial labels
770
```
771

772
TermCriteria types:
773
```python { .api }
774
TermCriteria_COUNT: int   # Stop after maxCount iterations
775
TermCriteria_EPS: int     # Stop when desired accuracy (epsilon) is reached
776
TermCriteria_MAX_ITER: int  # Same as TermCriteria_COUNT
777
```
778

779
## Error Handling
780

781
```python { .api }
782
class error(Exception):
783
    """OpenCV error exception"""
784
    pass
785
```
786

787
OpenCV raises `cv2.error` exceptions when operations fail. Common scenarios include:
788
- Invalid image format or dimensions
789
- File not found or cannot be read
790
- Unsupported operation or invalid parameters
791
- Insufficient memory
792

793
## Platform Notes
794

795
### Headless vs GUI Packages
796

797
- **Standard packages** (`opencv-python`, `opencv-contrib-python`): Include GUI functionality via highgui module
798
- **Headless packages** (`opencv-python-headless`, `opencv-contrib-python-headless`): No GUI dependencies, smaller Docker images
799

800
Headless packages do not support:
801
- `cv2.imshow()`, `cv2.namedWindow()`, and other highgui functions
802
- Interactive windows, trackbars, and mouse callbacks
803
- Use headless packages for servers, Docker containers, or when using alternative GUI frameworks
804

805
### Data Files
806

807
Haar cascade XML files for object detection are included in all packages:
808

809
```python
810
import cv2
811
import os
812

813
# Access Haar cascades directory
814
cascades_path = cv2.data.haarcascades
815

816
# Load a cascade classifier
817
face_cascade = cv2.CascadeClassifier(
818
    os.path.join(cascades_path, 'haarcascade_frontalface_default.xml')
819
)
820
```
821

822
## Additional Resources
823

824
- Official OpenCV documentation: https://docs.opencv.org/4.x/
825
- OpenCV-Python tutorials: https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html
826
- OpenCV GitHub repository: https://github.com/opencv/opencv
827
- OpenCV-Python package repository: https://github.com/opencv/opencv-python
828