OpenCV

Python 绑定 cv2：安装、BGR 与 ndarray、读写与视频、几何与滤波、轮廓与 DNN 入口；链回 ndarray 与官方 OpenCV 手册。

Python 通过 cv2 使用 OpenCV：C++ 实现的计算机视觉库，图像在内存中多为 NumPy ndarray（如 uint8、形状 (H, W, 3)）。适合脚本、桌面工具、服务端图像预处理；与 asyncio 无直接关系，重算常放线程/进程池。

pip install opencv-python          # 主模块，多数场景够用
# pip install opencv-contrib-python  # contrib 扩展；与上面二选一，勿重复安装

适用性：浏览器 / Pyodide 通常没有完整 cv2；Web 侧常用 OpenCV.js 等，勿假设 pip install 在 WASM 可用。

何时用 cv2

场景	建议
读图、缩放、滤波、边缘、轮廓等传统 CV	`cv2` 开箱即用
与 NumPy 矩阵运算、批处理结合	数组互操作无拷贝或视图需注意
深度学习推理（ONNX 等）	`cv2.dnn` 或专用框架（PyTorch、ONNX Runtime）
仅要在网页里做简单滤镜	考虑 Canvas / WebGL / OpenCV.js，而非服务器 `cv2`

BGR：imread / imshow 默认 蓝-绿-红，与 PIL、网页 RGB 相反；显示或送模型前用 cvtColor 统一。

原地修改：许多函数 就地改 传入数组；要保留原图先 img.copy()。

模块成员总览

核心约定

概念	说明
`Mat` / `ndarray`	入参、返回值多为 NumPy 数组；`(H, W)` 灰度，`(H, W, 3)` BGR
坐标	`(x, y)` 为列、行；ROI 切片 `img[y1:y2, x1:x2]`

读写与显示

名称	说明
`imread(path, flags)`	读图；失败返回 `None`
`imwrite(path, img)`	写图；扩展名定格式
`imshow(winname, mat)`	窗口显示；须 `waitKey`
`waitKey(delay)`	等待按键（毫秒）；`0` 为无限等
`destroyAllWindows()`	关闭窗口

视频

名称	说明
`VideoCapture(index_or_path)`	摄像头或视频文件
`read()`	`(ret, frame)`
`VideoWriter(...)`	写视频；`fourcc` 指定编码

常用处理（节选）

类别	代表 API
几何	`resize`、`flip`、`warpAffine`
色彩	`cvtColor`、`split`、`merge`
绘制	`line`、`rectangle`、`circle`、`putText`
滤波 / 边缘	`GaussianBlur`、`Canny`
形态学	`erode`、`dilate`、`morphologyEx`
轮廓	`findContours`、`drawContours`、`boundingRect`
DNN	`dnn.readNetFromONNX`、`blobFromImage`、`setInput`、`forward`

读图与显示

import cv2
import numpy as np

img = cv2.imread("photo.jpg")
if img is None:
    raise FileNotFoundError("photo.jpg")

rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
h, w = img.shape[:2]

import cv2

img = cv2.imread("in.png")
cv2.imshow("preview", img)
cv2.waitKey(0)
cv2.destroyAllWindows()
cv2.imwrite("out.jpg", img)

无头服务器（无 GUI）上 imshow 无效；用 imwrite、视频文件或 Web 预览。

视频与摄像头

import cv2

cap = cv2.VideoCapture(0)
if not cap.isOpened():
    raise RuntimeError("cannot open camera")

while True:
    ok, frame = cap.read()
    if not ok:
        break
    cv2.imshow("cam", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

方法	说明
`read()`	`ret` 为 False 表示结束或失败
`get(prop)` / `set(prop)`	如 `CAP_PROP_FRAME_WIDTH`
`release()`	释放设备

几何、色彩与绘制

small = cv2.resize(img, (320, 240), interpolation=cv2.INTER_AREA)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)  # BGR 绿色

操作	API
缩放	`resize(..., interpolation=)`
裁剪	`img[y:y+h, x:x+w]`
色彩空间	`cvtColor` + `COLOR_*` 常量
文字	`putText`（中文常改 PIL / contrib `freetype`）

滤波、边缘与轮廓

blur = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blur, 50, 150)

contours, hierarchy = cv2.findContours(
    edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
)
for cnt in contours:
    x, y, w, h = cv2.boundingRect(cnt)
    cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 2)

findContours 输入须为 单通道二值 uint8；OpenCV 4.x 返回 (contours, hierarchy)。
背景/前景反相会导致轮廓为空或错乱。

DNN 推理（入口）

net = cv2.dnn.readNetFromONNX("model.onnx")
blob = cv2.dnn.blobFromImage(
    img, scalefactor=1 / 255.0, size=(640, 640), swapRB=True
)
net.setInput(blob)
out = net.forward()

部署时核对 输入尺寸、scale、RGB/BGR（swapRB） 与训练一致。

与 NumPy / PIL

from PIL import Image

rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
pil_img = Image.fromarray(rgb)
bgr = cv2.cvtColor(np.array(pil_img.convert("RGB")), cv2.COLOR_RGB2BGR)

matplotlib 显示前须转 RGB，否则偏蓝。

模块	关系
`numpy`	图像矩阵；见 ndarray
`PIL` / Pillow	RGB 互转、中文渲染
`threading` / `multiprocessing`	CPU 密集批处理、避免阻塞 asyncio
`matplotlib`	可视化（注意 BGR→RGB）

易错点（排错速记）

imread 为 None：路径错误、中文路径（Windows 可用 np.fromfile + imdecode）、文件损坏。
颜色偏蓝/红：未做 BGR ↔ RGB。
imshow 一闪而过：未 waitKey 或进程已退出。
服务器弹窗失败：无显示环境；勿依赖 imshow。
同时装 opencv-python 与 opencv-contrib-python：包冲突。
DNN 结果全错：swapRB、size、归一化与训练不一致。
WebAssembly：完整 cv2 通常不可用。

资料：OpenCV 文档 · Python 教程