JosiahSiegel/python-opencv

Quick Reference

| Function | Purpose | Gotcha | |----------|---------|--------| | cv2.imread(path) | Load image | Returns None if path invalid (no error!) | | cv2.imwrite(path, img) | Save image | Expects BGR, not RGB | | cv2.cvtColor(img, code) | Color conversion | BGR is default, not RGB | | cv2.VideoCapture(src) | Video/camera input | Always check isOpened() and release() | | cv2.VideoWriter(...) | Save video | Expects BGR frames, codec matters | | cv2.resize(img, (w, h)) | Resize image | Size is (width, height), not (height, width) |

| Coordinate System | Order | Usage | |-------------------|-------|-------| | NumPy indexing | img[row, col] = img[y, x] | Pixel access | | Image shape | (height, width, channels) | Shape is (rows, cols, ch) | | OpenCV functions | (x, y) | Drawing functions | | Resize/ROI | (width, height) | Size parameters |

| Color Conversion | Code | Note | |------------------|------|------| | BGR to RGB | cv2.COLOR_BGR2RGB | For Matplotlib display | | BGR to Gray | cv2.COLOR_BGR2GRAY | Single channel output | | BGR to HSV | cv2.COLOR_BGR2HSV | H: 0-179, S/V: 0-255 |

| Interpolation | Best For | Speed | |---------------|----------|-------| | INTER_NEAREST | Speed, pixelated OK | Fastest | | INTER_LINEAR | General purpose (default) | Fast | | INTER_AREA | Downscaling | Medium | | INTER_CUBIC | Upscaling quality | Slow | | INTER_LANCZOS4 | Best upscaling | Slowest |

When to Use This Skill

Use for computer vision and image processing:

• Loading, displaying, and saving images
• Video capture from cameras or files
• Image filtering and transformations
• Edge and contour detection
• Object detection and template matching
• Feature detection and matching
• Deep learning inference with DNN module

Related skills:

• For NumPy arrays: see python-fundamentals-313
• For async processing: see python-asyncio
• For type hints: see python-type-hints

---

OpenCV Python Complete Guide (2025)

Overview

OpenCV (Open Source Computer Vision Library) is the most popular computer vision library. Python bindings (opencv-python) provide access to all functionality through NumPy arrays. OpenCV uses BGR color format by default, which is a critical gotcha.

Installation

# CPU-only (most common)
pip install opencv-python

# With contrib modules (SIFT, SURF, extra features)
pip install opencv-contrib-python

# Headless (no GUI, for servers)
pip install opencv-python-headless

# Verify installation
python -c "import cv2; print(cv2.__version__)"

Key Gotchas

• OpenCV uses BGR, not RGB; convert before Matplotlib/PIL display and convert back before cv2.imwrite.
• Image shape is (height, width, channels), NumPy indexing is img[row, col], but OpenCV drawing functions use (x, y).
• cv2.imread returns None on missing or undecodable files; always check before using the image.
• VideoCapture and GUI windows must be released/closed in finally or context-manager cleanup paths.
• NumPy arithmetic can overflow on uint8; use OpenCV arithmetic or explicit float normalization when needed.

Read references/opencv-critical-gotchas.md for the full preserved examples and safe patterns.

Reference Map

The detailed API patterns and code recipes have been split into focused references. Load the file that matches the user's task.

Critical Gotchas -> references/opencv-critical-gotchas.md

Read this for full examples of the most common OpenCV failure modes:

• BGR/RGB conversion: Matplotlib and PIL integration, correct cv2.imwrite usage
• Coordinate ordering: shape, NumPy indexing, drawing functions, ROI slicing
• Failed image loads: cv2.imread None checks and pathlib validation
• Video cleanup: VideoCapture release patterns and context-manager wrapper
• Dtype safety: uint8 overflow, cv2.add, float normalization, Canny dtype expectations

Core Operations -> references/opencv-core-operations.md

Read this for everyday OpenCV work:

• Image I/O: cv2.imread flags, loading from URLs, cv2.imwrite quality params, multi-image batch loading
• Video Capture and Writing: camera/file capture, VideoWriter codecs (mp4v, XVID, H264), FPS/resolution probing
• Color Space Conversions: BGR/RGB/HSV/Gray/Lab, HSV color detection (red/green/blue ranges with dual-range red), white-balance helpers
• Image Filtering: GaussianBlur, medianBlur, bilateralFilter, Sobel/Laplacian/Canny edge detection, morphological ops (erode, dilate, open, close, gradient, tophat)
• Contour Detection: findContours, area/perimeter, bounding boxes, contour approximation, hierarchy
• Image Resizing and Transformations: aspect-ratio-preserving resize, rotation, affine/perspective transforms, warpAffine vs warpPerspective
• Template Matching: cv2.matchTemplate, multi-scale matching, TM_CCOEFF_NORMED thresholding
• Feature Detection: ORB, SIFT, AKAZE keypoints; BFMatcher and FLANN matchers; ratio test
• DNN Module: cv2.dnn.readNet for ONNX/TF/Caffe, blob preprocessing, YOLO/MobileNet inference
• Displaying Images: cv2.imshow + waitKey loops, Jupyter cv2.imshow workaround with Matplotlib
• Performance Tips: vectorized NumPy, contiguous arrays, cv2.UMat for OpenCL, cv2.cuda GPU operations
• Drawing Functions: rectangle, circle, line, ellipse, polylines, fillPoly, putText, getTextSize

Advanced Patterns -> references/opencv-advanced-patterns.md

Read this for specialized computer-vision pipelines:

• Background Subtraction: MOG2, KNN
• Object Tracking: CSRT, KCF, MOSSE, multi-object trackers
• Camera Calibration: chessboard corner detection, intrinsic/distortion matrices, undistort
• Stereo Vision: StereoBM, StereoSGBM, disparity maps
• Optical Flow: Lucas-Kanade sparse, Farneback dense
• Image Stitching: cv2.Stitcher panorama assembly
• Face Detection: Haar cascades, DNN face detector
• ArUco Markers: marker detection and pose estimation

Triggering Phrases

This skill should activate when the user mentions any of: OpenCV, cv2, BGR, image processing, contours, Canny, Hough transform, template matching, ORB/SIFT/AKAZE, VideoCapture, VideoWriter, cv2.dnn, cv2.cuda, computer vision in Python.