python-opencv

快速参考

函数	用途	注意事项
cv2.imread(path)	加载图像	路径无效时返回 None（不会报错！）
cv2.imwrite(path, img)	保存图像	需要 BGR，而不是 RGB
cv2.cvtColor(img, code)	颜色转换	默认使用 BGR，而不是 RGB
cv2.VideoCapture(src)	视频/摄像头输入	务必检查 isOpened() 并调用 release()
cv2.VideoWriter(...)	保存视频	需要 BGR 帧，编解码器也很重要
cv2.resize(img, (w, h))	调整图像大小	尺寸为（宽度，高度），而不是（高度，宽度）

坐标系	顺序	用途
NumPy 索引	img[row, col] = img[y, x]	访问像素
图像形状	(height, width, channels)	形状为（行数、列数、通道数）
OpenCV 函数	(x, y)	绘图函数
调整大小/ROI	(width, height)	尺寸参数

颜色转换	代码	说明
BGR 转 RGB	cv2.COLOR_BGR2RGB	用于 Matplotlib 显示
BGR 转灰度	cv2.COLOR_BGR2GRAY	输出单通道
BGR 转 HSV	cv2.COLOR_BGR2HSV	H：0-179，S/V：0-255

插值方式	最适合	速度
INTER_NEAREST	追求速度，可接受像素化	最快
INTER_LINEAR	通用（默认）	快
INTER_AREA	缩小图像	中等
INTER_CUBIC	高质量放大	慢
INTER_LANCZOS4	最佳放大效果	最慢

何时使用此技能

适用于计算机视觉和图像处理：

• 加载、显示和保存图像
• 从摄像头或文件采集视频
• 图像滤波和变换
• 边缘和轮廓检测
• 目标检测和模板匹配
• 特征检测和匹配
• 使用 DNN 模块进行深度学习推理

相关技能：

• 对于 NumPy 数组：参见 python-fundamentals-313
• 对于异步处理：参见 python-asyncio
• 对于类型提示：参见 python-type-hints

---

OpenCV Python 完整指南（2025）

概述

OpenCV（开源计算机视觉库）是最受欢迎的计算机视觉库。Python 绑定（opencv-python）通过 NumPy 数组提供对所有功能的访问。OpenCV 默认使用 BGR 颜色格式，这是一个关键注意事项。

安装

# 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__)"

关键注意事项

• OpenCV 使用 BGR，而不是 RGB；在 Matplotlib/PIL 中显示前进行转换，并在调用 cv2.imwrite 前转回。
• 图像形状为 (height, width, channels)，NumPy 索引为 img[row, col]，但 OpenCV 绘图函数使用 (x, y)。
• cv2.imread 遇到缺失或无法解码的文件时会返回 None；使用图像前务必检查。
• VideoCapture 和 GUI 窗口必须在 finally 或上下文管理器清理流程中释放/关闭。
• NumPy 运算可能导致 uint8 溢出；必要时请使用 OpenCV 运算或显式进行浮点归一化。

请阅读 references/opencv-critical-gotchas.md，查看完整保留的示例和安全模式。

参考索引

详细的 API 模式和代码示例已拆分为针对特定任务的参考资料。请加载与用户任务相匹配的文件。

关键注意事项 -> references/opencv-critical-gotchas.md

阅读此文件，查看最常见 OpenCV 故障模式的完整示例：

• BGR/RGB 转换：与 Matplotlib 和 PIL 集成，以及正确使用 cv2.imwrite
• 坐标顺序：形状、NumPy 索引、绘图函数、ROI 切片
• 图像加载失败：cv2.imread 的 None 检查和 pathlib 验证
• 视频清理：VideoCapture 释放模式和上下文管理器包装器
• 数据类型安全：uint8 溢出、cv2.add、浮点归一化、Canny 的数据类型要求

核心操作 -> references/opencv-core-operations.md

日常使用 OpenCV 时请阅读此文档：

• 图像输入/输出：cv2.imread 标志、从 URL 加载、cv2.imwrite 质量参数、批量加载多张图像
• 视频捕获与写入：摄像头/文件捕获、VideoWriter 编码器（mp4v、XVID、H264）、FPS/分辨率检测
• 色彩空间转换：BGR/RGB/HSV/Gray/Lab、HSV 颜色检测（红色/绿色/蓝色范围，以及红色双范围）、白平衡辅助函数
• 图像滤波：GaussianBlur、medianBlur、bilateralFilter、Sobel/Laplacian/Canny 边缘检测、形态学操作（erode、dilate、open、close、gradient、tophat）
• 轮廓检测：findContours、面积/周长、边界框、轮廓近似、层级关系
• 图像缩放与变换：保持宽高比缩放、旋转、仿射/透视变换、warpAffine 与 warpPerspective 的区别
• 模板匹配：cv2.matchTemplate、多尺度匹配、TM_CCOEFF_NORMED 阈值处理
• 特征检测：ORB、SIFT、AKAZE 关键点；BFMatcher 和 FLANN 匹配器；比率测试
• DNN 模块：使用 cv2.dnn.readNet 处理 ONNX/TF/Caffe、blob 预处理、YOLO/MobileNet 推理
• 显示图像：cv2.imshow + waitKey 循环、使用 Matplotlib 解决 Jupyter 中的 cv2.imshow 问题
• 性能提示：向量化 NumPy、连续数组、使用 cv2.UMat 进行 OpenCL 运算、cv2.cuda GPU 运算
• 绘图函数：rectangle、circle、line、ellipse、polylines、fillPoly、putText、getTextSize

高级模式 -> references/opencv-advanced-patterns.md

处理专门的计算机视觉流水线时请阅读此文档：

• 背景减除：MOG2、KNN
• 目标跟踪：CSRT、KCF、MOSSE、多目标跟踪器
• 相机标定：棋盘格角点检测、内参/畸变矩阵、undistort
• 立体视觉：StereoBM、StereoSGBM、视差图
• 光流：Lucas-Kanade 稀疏光流、Farneback 稠密光流
• 图像拼接：使用 cv2.Stitcher 拼接全景图
• 人脸检测：Haar 级联、DNN 人脸检测器
• ArUco 标记：标记检测与姿态估计

触发短语

当用户提及以下任意内容时，应激活此技能：OpenCV、cv2、BGR、图像处理、轮廓、Canny、Hough 变换、模板匹配、ORB/SIFT/AKAZE、VideoCapture、VideoWriter、cv2.dnn、cv2.cuda、Python 计算机视觉。