python-opencv

---
name: "python-opencv"
description: "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…"
license: "MIT"
---

## 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

```bash
# 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](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](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](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](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.