OpenCv常见的函数

OpenCV2 扩展接口说明（cv2 / numpy 代码片段）

说明：本文件用于配合扩展右侧侧栏的拖拽代码片段。侧栏节点的“接口”主要对应 OpenCV Python（cv2）与 NumPy（numpy）在代码中会用到的 API。本说明覆盖当前插件版本（侧栏配置 dist/views/Algorithms/config.js）里出现的所有函数/调用点。

注意：OpenCV Python API 在不同小版本（4.5/4.8/4.9 等）可能存在参数默认值或额外可选参数差异。下文以 OpenCV 4.x 的常见签名为准。

---

1. 图片 / 视频读取、显示与保存

1.1 import cv2

• 说明：导入 OpenCV Python 绑定。
• 参数：无

1.2 import numpy as np

• 说明：用于图像矩阵/坐标计算、np.zeros 等。
• 参数：无

---

1.3 cv2.imread(filename[, flags])

• 签名：cv2.imread(filename, flags=cv2.IMREAD_COLOR)
• 参数
  • filename：str，图像文件路径。
  • flags：int，读取模式
    • 常用：cv2.IMREAD_COLOR（彩色 BGR，默认）
    • cv2.IMREAD_GRAYSCALE（灰度）
    • cv2.IMREAD_UNCHANGED（不改变通道/alpha）
• 返回值
  • numpy.ndarray：图像矩阵（BGR 或灰度）
  • 读失败时可能返回 None

1.4 cv2.imshow(winname, mat)

• 签名：cv2.imshow(winname, mat)
• 参数
  • winname：str，窗口标题
  • mat：图像矩阵（numpy.ndarray）
• 说明：必须配合 cv2.waitKey(...) 才能正常刷新窗口事件循环。

1.5 cv2.waitKey([delay])

• 签名：cv2.waitKey(delay=0) -> int
• 参数
  • delay：int，等待时间（毫秒）
    • 0：无限等待直到按键
    • >0：等待对应毫秒后继续
• 返回值
  • 按键编码（ASCII/键码）。常见写法：cv2.waitKey(1) & 0xFF == ord('q')

1.6 cv2.destroyAllWindows()

• 签名：cv2.destroyAllWindows()
• 参数：无
• 说明：关闭所有 HighGUI 窗口。

1.7 cv2.imwrite(filename, img[, params])

• 签名：cv2.imwrite(filename, img, params=None) -> bool
• 参数
  • filename：str，输出路径
  • img：numpy.ndarray，要保存的图像
  • params：list/tuple，保存参数（常用于 JPEG 质量等）
• 返回值
  • bool：是否写入成功

---

1.8 cv2.VideoCapture(index|filename)

• 签名（常见）：cv2.VideoCapture(source, apiPreference=cv2.CAP_ANY)
• 参数
  • source：
    • 摄像头：设备索引 int（例如 0）
    • 视频文件：str 路径（例如 'video.mp4'）
  • apiPreference：int（可选），指定后端偏好
• 返回值
  • cv2.VideoCapture 对象

1.9 cap.read()

• 签名：ret, frame = cap.read()
• 返回值
  • ret：bool，是否成功读取
  • frame：numpy.ndarray，BGR 图像（读取成功时）

1.10 cv2.VideoWriter_fourcc(c1, c2, c3, c4)

• 签名：cv2.VideoWriter_fourcc(c1, c2, c3, c4) -> int
• 参数
  • c1..c4：int/char，四个编码字符
• 说明
  • 常见方式：cv2.VideoWriter_fourcc(*'XVID') 或 cv2.VideoWriter_fourcc('M','J','P','G')

1.11 cv2.VideoWriter(filename, fourcc, fps, frameSize[, isColor])

• 签名（常见）：cv2.VideoWriter(filename, fourcc, fps, frameSize, isColor=True)
• 参数
  • filename：str，输出视频路径（如 'output.avi'）
  • fourcc：int，编码四字符值（由 VideoWriter_fourcc 产生）
  • fps：float，帧率
  • frameSize：tuple(width, height)
  • isColor：bool（可选），是否为彩色视频（一般 True）
• 返回值
  • cv2.VideoWriter 对象

1.12 out.write(image)

• 签名：out.write(image) -> None
• 参数
  • image：numpy.ndarray，单帧图像
• 说明
  • image 的宽高必须与 VideoWriter 创建时 frameSize 一致（否则写入可能失败或出现变形）。

---

1.13 cap.release()

• 签名：cap.release() -> None
• 说明：释放摄像头或视频文件资源。

---

2. 图片基本处理

2.1 img.shape

• 说明：NumPy 图像矩阵的 shape
  • 彩色 BGR：(height, width, channels)
  • 灰度：(height, width)

2.2 cv2.resize(src, dsize[, dst[, fx[, fy[, interpolation]]]])

• 签名（常见）：cv2.resize(src, dsize, dst=None, fx=0, fy=0, interpolation=cv2.INTER_LINEAR)
• 参数
  • src：源图像
  • dsize：(width, height)
  • dst：输出图像（可选）
  • fx, fy：缩放比例（当 dsize 未指定时常用）
  • interpolation：插值方法（如 INTER_LINEAR, INTER_AREA）

2.3 cv2.getRotationMatrix2D(center, angle, scale)

• 签名：cv2.getRotationMatrix2D(center, angle, scale)
• 参数
  • center：(x, y)，旋转中心
  • angle：float，旋转角度（度）
  • scale：float，缩放比例
• 返回值
  • numpy.ndarray（2x3 仿射矩阵）

2.4 cv2.warpAffine(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]])

• 签名（常见）：cv2.warpAffine(src, M, dsize, dst=None, flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=0)
• 参数
  • src：源图像
  • M：2x3 仿射矩阵
  • dsize：(width, height)
  • dst：输出图像（可选）
  • flags：组合标志（常见为插值 INTER_*，可按需叠加 cv2.WARP_INVERSE_MAP 等）
  • borderMode：边界模式（如 cv2.BORDER_CONSTANT、cv2.BORDER_REPLICATE 等）
  • borderValue：边界常量值（当 borderMode=cv2.BORDER_CONSTANT）

2.5 cv2.getPerspectiveTransform(src, dst)

• 签名：cv2.getPerspectiveTransform(src, dst) -> M
• 参数
  • src：源四点坐标，numpy.ndarray，shape (4,2)
  • dst：目标四点坐标，shape (4,2)
• 返回值
  • 透视矩阵 3x3

2.6 cv2.warpPerspective(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]])

• 签名（常见）：cv2.warpPerspective(src, M, dsize, dst=None, flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=0)
• 参数
  • src：源图像
  • M：3x3 透视矩阵
  • dsize：(width, height)
  • dst：输出图像（可选）
  • flags：组合标志（常见为插值 INTER_*）
  • borderMode：边界模式
  • borderValue：边界常量值（当 borderMode=BORDER_CONSTANT）

2.7 裁剪（NumPy 切片）

• 表达式：cropped = img[y1:y2, x1:x2]
• 参数/含义
  • y1, y2：行区间（先 y 后 x）
  • x1, x2：列区间

---

3. 颜色空间转换与通道处理

3.1 cv2.cvtColor(src, code[, dstCn])（常见）

• 签名：cv2.cvtColor(src, code[, dst[, dstCn]])
• 参数
  • src：源图像
  • code：颜色空间转换码，如
    • cv2.COLOR_BGR2GRAY
    • cv2.COLOR_BGR2HSV
  • dst：输出容器（可选）
  • dstCn：输出通道数（可选）
• 返回值：转换后的图像矩阵

3.2 cv2.split(m[, mv])

• 签名：cv2.split(m) -> list
• 参数
  • m：多通道图像
  • mv：输出数组列表（可选）
• 返回值
  • 通道列表：例如 BGR 三通道返回 [b, g, r]

3.3 cv2.merge(mv[, dst])

• 签名：cv2.merge(mv, dst=None) -> merged
• 参数
  • mv：通道列表/元组（顺序必须正确）
  • dst：输出容器（可选）

---

4. 绘图

4.1 cv2.line(img, pt1, pt2, color[, thickness[, lineType[, shift]]])

• 参数
  • img：绘制目标图像
  • pt1, pt2：端点坐标 (x, y)
  • color：BGR 三元组，如 (0,255,0)
  • thickness：线宽，int
  • lineType：线型（可选）
  • shift：坐标小数位数（可选）

4.2 cv2.rectangle(img, pt1, pt2, color[, thickness[, lineType[, shift]]])

• 参数
  • pt1：左上角
  • pt2：右下角
  • thickness：-1 表示实心矩形

4.3 cv2.circle(img, center, radius, color[, thickness[, lineType[, shift]]])

• 参数
  • center：圆心 (x,y)
  • radius：半径
  • thickness：线宽，-1 可表示填充圆

4.4 cv2.putText(img, text, org, fontFace, fontScale, color[, thickness[, lineType[, bottomLeftOrigin]]])

• 参数
  • text：文本字符串
  • org：文字左下角起点 (x,y)（除非设置 bottomLeftOrigin=False）
  • fontFace：字体类型，如 cv2.FONT_HERSHEY_SIMPLEX
  • fontScale：字号缩放倍数
  • color：BGR 颜色
  • thickness：线宽
  • lineType：线型
  • bottomLeftOrigin：坐标原点在左下角/左上角

---

5. 图像滤波与阈值处理

5.1 cv2.GaussianBlur(src, ksize, sigmaX[, sigmaY[, borderType]])

• 参数
  • src：源图像
  • ksize：核大小 (width,height)，必须为正奇数
  • sigmaX：X 方向标准差；0 表示由核自动推算
  • sigmaY：Y 方向标准差（可选，若不填常等于 sigmaX）
  • borderType：边界类型（可选）

5.2 cv2.medianBlur(src, ksize)

• 参数
  • src：源图像
  • ksize：孔径，必须为奇数且大于 1

5.3 cv2.bilateralFilter(src, d, sigmaColor, sigmaSpace[, borderType])

• 参数
  • src：源图像
  • d：邻域直径
  • sigmaColor：颜色空间 sigma
  • sigmaSpace：坐标空间 sigma
  • borderType：边界类型（可选）

5.4 cv2.adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C[, dst])

• 参数
  • src：输入单通道灰度图
  • maxValue：二值化输出的最大值
  • adaptiveMethod：自适应算法
    • cv2.ADAPTIVE_THRESH_MEAN_C
    • cv2.ADAPTIVE_THRESH_GAUSSIAN_C
  • thresholdType：阈值类型（如 cv2.THRESH_BINARY / cv2.THRESH_BINARY_INV）
  • blockSize：邻域大小（必须为奇数）
  • C：常数（从局部均值/加权均值中减去）

5.5 cv2.threshold(src, thresh, maxval, thresholdType[, dst])

• 签名：ret, dst = cv2.threshold(src, thresh, maxval, thresholdType)
• 参数
  • src：输入单通道图
  • thresh：阈值
  • maxval：输出最大值
  • thresholdType：如
    • cv2.THRESH_BINARY
    • cv2.THRESH_BINARY_INV
    • cv2.THRESH_OTSU（与 thresh 配合时用于 OTSU）
  • dst：输出容器（可选）
• 返回值
  • ret：实际阈值
  • dst：二值化结果

---

6. 形态学操作

6.1 cv2.getStructuringElement(shape, ksize[, anchor])

• 参数
  • shape：结构元素形状
    • cv2.MORPH_RECT
    • cv2.MORPH_ELLIPSE
    • cv2.MORPH_CROSS
  • ksize：核大小（如 (5,5)）
  • anchor：锚点（可选）
• 返回值
  • 结构元素核矩阵

6.2 cv2.erode(src, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]])

• 参数
  • src：源图像
  • kernel：结构元素
  • dst：输出容器（可选）
  • anchor：锚点（可选）
  • iterations：迭代次数
  • borderType/borderValue：边界模式与边界值

6.3 cv2.dilate(src, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]])

• 参数含义同 erode。

6.4 cv2.morphologyEx(src, op, kernel[, dst[, borderType[, borderValue]]])

• 参数
  • op：形态学类型
    • cv2.MORPH_OPEN（开运算）
    • cv2.MORPH_CLOSE（闭运算）
  • 其它参数同 erode/dilate

---

7. 边缘检测与轮廓查找

7.1 cv2.Canny(image, threshold1, threshold2[, edges[, apertureSize[, L2gradient]]])

• 参数
  • image：输入单通道图（通常为灰度）
  • threshold1：低阈值
  • threshold2：高阈值
  • apertureSize：Sobel 算子孔径（可选）
  • L2gradient：是否使用更精确的 L2 梯度距离（可选）
• 返回值
  • 边缘二值图

7.2 cv2.findContours(image, mode, method[, contours[, hierarchy[, offset]]])

• 签名：contours, hierarchy = cv2.findContours(image, mode, method)
• 参数
  • image：二值图（通常经过阈值/二值化）
  • mode：轮廓检索模式，如 cv2.RETR_EXTERNAL/cv2.RETR_TREE
  • method：轮廓近似方法，如 cv2.CHAIN_APPROX_SIMPLE / cv2.CHAIN_APPROX_NONE
  • contours/hierarchy：输出容器（OpenCV Python 中通常不手动传）
  • offset：轮廓坐标偏移（可选）
• 返回值
  • contours：轮廓列表
  • hierarchy：层级信息（与 mode 有关）

7.3 cv2.drawContours(image, contours, contourIdx, color[, thickness[, lineType[, hierarchy[, maxLevel[, offset]]]]])

• 参数
  • image：绘制目标图像
  • contours：轮廓列表
  • contourIdx：绘制哪一个轮廓
    • -1：全部
  • color：BGR 颜色
  • thickness：线宽（-1 可填充）
  • lineType：线型（可选）
  • hierarchy：层级信息（可选）
  • maxLevel：最大层级（可选）
  • offset：绘制偏移（可选）

7.4 cv2.contourArea(contour[, oriented])

• 参数
  • contour：单个轮廓
  • oriented：是否使用有向面积（可选，默认 False）
• 返回值
  • 面积（float）

7.5 cv2.arcLength(curve, closed)

• 参数
  • curve：轮廓点序列
  • closed：是否为闭合曲线（True/False）
• 返回值
  • 周长（float）

7.6 cv2.boundingRect(points)

• 参数
  • points：轮廓点集合（numpy 数组）
• 返回值
  • (x, y, w, h)

7.7 cv2.minAreaRect(points)

• 参数
  • points：点集合（轮廓）
• 返回值
  • ((cx, cy), (w, h), angle)：最小外接矩形（旋转矩形）

7.8 cv2.boxPoints(rect)

• 参数
  • rect：minAreaRect 的返回值
• 返回值
  • 4 个顶点坐标（浮点），绘制通常需要转整型：np.intp(box)

---

8. 特征检测与匹配

8.1 cv2.SIFT_create([nfeatures[, nOctaveLayers[, contrastThreshold[, edgeThreshold[, sigma]]]]])

• 返回值：SIFT 对象
• 参数（可选）
  • nfeatures：特征点数量上限
  • nOctaveLayers：金字塔层数
  • contrastThreshold：对比度阈值
  • edgeThreshold：边缘阈值
  • sigma：高斯核系数
• 说明
  • SIFT 可能取决于 OpenCV 构建是否包含（某些发行版可能缺失）。

8.2 sift.detectAndCompute(image, mask=None)

• 参数
  • image：输入图像
  • mask：可选掩膜
• 返回值
  • kp：关键点列表
  • des：描述符矩阵

8.3 cv2.ORB_create([nfeatures[, scaleFactor[, nlevels[, edgeThreshold[, firstLevel[, WTA_K[, scoreType[, patchSize[, fastThreshold]]]]]]]]])

• 返回值：ORB 对象
• 参数（常见可选）
  • nfeatures：特征数量
  • scaleFactor：金字塔比例
  • nlevels：金字塔层数
  • edgeThreshold：边缘阈值
  • firstLevel：最初层
  • WTA_K：比较方式
  • scoreType：评分类型
  • patchSize：补丁大小
  • fastThreshold：FAST 阈值

8.4 cv2.BFMatcher(normType[, crossCheck])

• 签名：bf = cv2.BFMatcher(normType, crossCheck=False)
• 参数
  • normType：距离度量
    • ORB 通常用 cv2.NORM_HAMMING
    • SIFT 常用 cv2.NORM_L2
  • crossCheck：bool，是否互相交叉匹配（开启更严格）

8.5 bf.match(queryDescriptors, trainDescriptors[, mask])

• 返回值
  • matches：list[DMatch]
• 参数
  • queryDescriptors：查询描述符
  • trainDescriptors：训练描述符
  • mask：可选掩膜

8.6 cv2.drawMatches(img1, keypoints1, img2, keypoints2, matches1to2, outImg[, ...])

• 常用签名：cv2.drawMatches(img1, keypoints1, img2, keypoints2, matches1to2, outImg=None, matchColor=None, singlePointColor=None, matchesMask=None, flags=2)
• 参数
  • img1, img2：两幅图像
  • keypoints1, keypoints2：关键点列表（list[cv2.KeyPoint]）
  • matches1to2：匹配列表（list[cv2.DMatch]）
  • outImg：输出背景图；为 None 时使用拼接后的默认背景
  • matchColor：匹配连线颜色（BGR 或标量；可选）
  • singlePointColor：单点颜色（BGR；可选）
  • matchesMask：匹配掩膜（用于只显示部分匹配；可选）
  • flags：绘制标志（如显示关键点/连线的组合；可选）

---

9. 视频处理与摄像头控制

9.1 cap.set(propId, value)

• 签名：cap.set(propId, value) -> bool
• 参数
  • propId：属性 ID（如 cv2.CAP_PROP_FRAME_WIDTH、cv2.CAP_PROP_FRAME_HEIGHT、cv2.CAP_PROP_FPS）
  • value：属性值（float/int）
• 返回值
  • 是否设置成功（受设备/后端影响，未必一定成功）

9.2 cap.get(propId)

• 签名：cap.get(propId) -> float
• 参数
  • propId：属性 ID
• 返回值
  • 当前属性值（float）

9.3 cap.release()

• 说明：释放资源。

9.4 out.write(frame)

• 说明：写入一帧（见第 1 部分 VideoWriter.write）。

---

10. 其他实用功能

10.1 np.zeros(shape, dtype=np.float64, order='C', ...)

• 签名：np.zeros(shape, dtype=float, order='C')
• 参数
  • shape：输出数组形状，如 (height, width, channels)
  • dtype：数据类型（图像常用 np.uint8）
  • order：内存排列方式（通常默认即可）

10.2 np.hstack(tup)

• 签名：np.hstack(tup) -> ndarray
• 参数
  • tup：要拼接的数组序列
• 说明
  • 横向拼接：要求除拼接轴外，其它维度尺寸一致。

10.3 np.vstack(tup)

• 签名：np.vstack(tup) -> ndarray
• 参数
  • tup：要拼接的数组序列
• 说明
  • 纵向拼接：要求除拼接轴外，其它维度尺寸一致。

10.4 鼠标回调 cv2.setMouseCallback

(1) def mouse_callback(event, x, y, flags, param):

• 函数签名（你需要实现/用户自定义）：
  • mouse_callback(event, x, y, flags, param)
• 参数
  • event：鼠标事件类型（常见如 cv2.EVENT_LBUTTONDOWN、cv2.EVENT_MOUSEMOVE 等）
  • x, y：鼠标坐标（相对于窗口左上角）
  • flags：事件附加信息（按键组合、滚轮等）
  • param：你在 setMouseCallback 里传的自定义参数

(2) cv2.setMouseCallback(winname, onMouse[, param])

• 签名：cv2.setMouseCallback(winname, onMouse, param=None)
• 参数
  • winname：窗口名
  • onMouse：回调函数（即 mouse_callback）
  • param：可选，自定义参数透传给回调

10.5 cv2.matchTemplate(image, templ, method[, result[, mask]])

• 签名：cv2.matchTemplate(image, templ, method[, result[, mask]]) -> result
• 参数
  • image：待匹配图像
  • templ：模板图像（必须比 image 小）
  • method：匹配方法，如
    • cv2.TM_CCOEFF_NORMED
    • cv2.TM_SQDIFF 等
  • result：输出结果矩阵（可选）
  • mask：掩膜（可选，部分方法支持）
• 返回值
  • result：匹配得分矩阵

10.6 cv2.minMaxLoc(src[, mask])

• 签名：cv2.minMaxLoc(src[, mask]) -> (minVal, maxVal, minLoc, maxLoc)
• 参数
  • src：输入得分矩阵（一般来自 matchTemplate 的 res）
  • mask：可选掩膜
• 返回值
  • minVal, maxVal：最小/最大得分
  • minLoc, maxLoc：最小/最大得分位置 (x, y)

---

维护与对应关系

• 本文件覆盖插件侧栏中“当前出现的全部 API 调用点”。
• 若你后续在 dist/views/Algorithms/config.js（或 dist/views/Custom/config.js）里新增了 codeStr，需要把新增的 API 同步追加到此文件。