OpenCV API

OpenCV API
- OpenCV (cv2) 核心功能 API 一览表（传统 CV 基础篇）
常用功能
- I. 噪声生成
  - 高斯噪声
  - 椒盐噪声
- 亮度/对比度调整

OpenCV API

OpenCV (cv2) 核心功能 API 一览表（传统 CV 基础篇）

以下列表涵盖了图像处理、滤波、特征提取和形态学等基础模块中常用的函数。

Ⅰ. 图像 I/O 与基本操作 (Core Functionality)

功能模块	API 函数	关键参数与用途
图像加载/保存	`cv2.imread(filename, flags)`	加载图像。 `flags` 常用于指定色彩空间：`cv2.IMREAD_GRAYSCALE` (灰度)、`cv2.IMREAD_COLOR` (彩色)。
	`cv2.imwrite(filename, img)`	保存图像。
颜色空间转换	`cv2.cvtColor(src, code)`	转换图像的颜色空间。 `code` 示例：`cv2.COLOR_BGR2GRAY` (最常用)。
图像显示	`cv2.imshow(winname, img)`	显示图像。
	`cv2.waitKey(delay)`	等待按键。必须配合 `imshow` 使用，`delay=0` 表示无限等待。
	`cv2.destroyAllWindows()`	关闭所有窗口。
图像大小调整	`cv2.resize(src, dsize, ...)`	调整图像大小。 `dsize` 为新的 (宽度, 高度) 元组。

Ⅱ. 图像滤波与平滑 (Filtering)

功能模块	API 函数	关键参数与用途	理论对应
高斯滤波	`cv2.GaussianBlur(src, ksize, sigmaX)`	去除高斯噪声。 `ksize` 为 (宽, 高) 核大小（奇数），`sigmaX` 为 X 方向标准差。	线性低通滤波
中值滤波	`cv2.medianBlur(src, ksize)`	去除椒盐噪声。 `ksize` 为核大小（奇数）。	非线性滤波
均值滤波	`cv2.blur(src, ksize)`	简单平均滤波。 `ksize` 为核大小。	线性低通滤波
双边滤波	`cv2.bilateralFilter(...)`	保留边缘的平滑。考虑空间距离和像素值相似度。	高级非线性滤波
直方图均衡化	`cv2.equalizeHist(src)`	对灰度图像的直方图进行均衡化，以自动提高图像的对比度。	直方图均衡化

Ⅲ. 图像梯度与边缘检测 (Gradients & Edges)

功能模块	API 函数	关键参数与用途	理论对应
Sobel 算子	`cv2.Sobel(src, ddepth, dx, dy, ...)`	计算一阶导数（梯度）。 `dx` 或 `dy` 设为 1。`ddepth` 常用于防止溢出（如 `cv2.CV_64F`）。	微分操作
Scharr 算子	`cv2.Scharr(src, ddepth, dx, dy)`	Sobel 的升级版。在某些情况下更精确。	微分操作
Laplacian 算子	`cv2.Laplacian(src, ddepth, ...)`	计算二阶导数。常用于边缘锐化。	二阶微分操作
Canny 检测器	`cv2.Canny(image, threshold1, threshold2)`	最优边缘检测。 `threshold1` 和 `threshold2` 为低、高阈值。	Canny 算法

Ⅳ. 图像阈值与形态学处理 (Thresholding & Morphology)

功能模块	API 函数	关键参数与用途	理论对应
简单阈值	`cv2.threshold(src, thresh, maxval, type)`	固定阈值二值化。 `type` 指定阈值类型（如 `cv2.THRESH_BINARY`）。	点运算/分割
自适应阈值	`cv2.adaptiveThreshold(...)`	局部自适应阈值。用于光照不均的图像分割。	区域分割
结构元素	`cv2.getStructuringElement(shape, ksize)`	创建形态学核。 `shape` 可选矩形、椭圆、交叉等。	形态学基础
腐蚀	`cv2.erode(src, kernel, iterations)`	收缩前景物体。 `iterations` 为重复次数。	形态学操作
膨胀	`cv2.dilate(src, kernel, iterations)`	扩张前景物体。	形态学操作
形态学操作	`cv2.morphologyEx(src, op, kernel)`	执行高级操作。 `op` 可选 `cv2.MORPH_OPEN` (开运算) 或 `cv2.MORPH_CLOSE` (闭运算)。	礼帽/黑帽/开闭运算

Ⅴ. 特征点检测与描述 (Feature Detection)

功能模块	API 函数	关键参数与用途	理论对应
Harris 角点	`cv2.cornerHarris(src, blockSize, ksize, k)`	计算 Harris 响应值 R。	局部梯度分析
Shi-Tomasi 角点	`cv2.goodFeaturesToTrack(...)`	Harris 的改进版。直接返回最佳角点坐标。	局部梯度分析
ORB 特征	`cv2.ORB_create()`	创建 ORB 检测器。适用于速度要求高的嵌入式平台。	快速特征提取
SIFT 特征	`cv2.SIFT_create()`	创建 SIFT 检测器。高精度、高鲁棒性（在某些版本中可能需要单独安装 `opencv-contrib-python`）。	尺度和旋转不变性

补充

函数作用	签名	参数要点	注意事项
颜色空间转换	`cv2.cvtColor(src, code)`	`code` 如 `COLOR_BGR2GRAY`、`COLOR_BGR2HSV`	转换代码须与输入通道匹配
全局直方图均衡化（灰度）	`cv2.equalizeHist(src)`	`src`：8-bit 单通道	仅适用于灰度图；彩色图先分离亮度通道
创建 CLAHE（自适应均衡化）	`cv2.createCLAHE(clipLimit=40.0, tileGridSize=(8,8))`	`clipLimit`：对比度限制；`tileGridSize`：局部网格；返回：CLANE对象；	参数影响局部对比与噪声放大
应用 CLAHE	`clahe.apply(src)`	`src`：8-bit 单通道；返回img对象；	与 `equalizeHist` 相似但局部自适应
计算直方图	`cv2.calcHist(images, channels, mask, histSize, ranges[, accumulate])`	`images` 必为列表（如 `[img]`）；`channels`,`histSize`,`ranges` 为列表；`mask` 可选 uint8	`mask` 与图像尺寸匹配；`ranges` 为半开区间
归一化 / 缩放	`cv2.normalize(src, dst, alpha, beta, norm_type=cv2.NORM_MINMAX)`	`alpha,beta` 目标范围或尺度；`norm_type` 类型	常用于直方图或数值缩放
线性变换并转 uint8	`cv2.convertScaleAbs(src, alpha=1, beta=0)`	`alpha`：比例（对比度）；`beta`：偏移（亮度）	执行 `src*alpha+beta` 后取绝对并饱和截断
线性混合 / 融合	`cv2.addWeighted(src1, alpha, src2, beta, gamma)`	`alpha,beta` 系数；`gamma` 标量	结果为饱和截断，常用于融合或对比度调整
元素级饱和相加	`cv2.add(src1, src2, dst=None, mask=None, dtype=None)`	安全饱和相加	与 NumPy `+` 不同（无模回绕）
高斯模糊	`cv2.GaussianBlur(src, ksize, sigmaX, dst=None, sigmaY=0, borderType=...)`	`ksize` 正奇数对或 `(0,0)`；`sigmaX/Y` 标准差	`ksize` 必须为正奇数（否则断言错误）；`(0,0)` 时根据 sigma 自动计算
中值滤波	`cv2.medianBlur(src, ksize)`	`ksize`：正奇数（≥3）	对椒盐噪声效果好；`ksize` 必须为奇数
查表变换	`cv2.LUT(src, lut)`	`lut`：长度 256 的 `uint8` 查找表	高效实现伽马/任意映射；`lut` dtype 通常为 `uint8`
裁剪数组到指定范围（NumPy）	`np.clip(a, a_min, a_max, out=None)`	`a_min/a_max` 标量或数组	常用于将像素值限定在 `[0,255]` 后再转 `uint8`
计算范数	`cv2.magnitude(x, y)`	计算`sqrt(x^2 + y^2)`	用于Sobel算子计算梯度幅值

常用功能

I. 噪声生成

高斯噪声

高斯噪声是每个像素独立加上服从正态分布 N(mean, sigma^2) 的随机值。关键注意点是先把图像转为浮点数相加、结果要截断到有效范围并转回 uint8（或保持 [0,1] 浮点范围）。

np.random.normal 用于从正态（高斯）分布抽样。

要点： - 函数签名：np.random.normal(loc=0.0, scale=1.0, size=None) - loc：均值 μ（默认 0） - scale：标准差 σ（>0，默认 1）。注意：方差 = σ² - size：输出形状（None → 返回单个标量，tuple → 返回对应形状的数组） - 返回：浮点数组（通常是 float64）；如果 size=None 返回一个标量浮点数。 - 可重复性：用 np.random.seed(123) 固定旧全局生成器，或推荐使用新 API： - rng = np.random.default_rng(123); rng.normal(loc, scale, size)

示例（生成与图像同形状的高斯噪声并添加）：

import numpy as np

# 旧 API（全局）
noise = np.random.normal(0, 25, img.shape)  # img.shape 例如 (H, W, 3)

# 新 API（推荐，线程安全且更可控）
rng = np.random.default_rng(42)
noise = rng.normal(0, 25, size=img.shape)

使用注意： - 噪声是浮点数，给 uint8 的图像加噪前把图像转为 float（避免溢出），加完后 np.clip(..., 0, 255).astype(np.uint8)。 - 若想让噪声强度与像素比率无关，可对图像归一化到 [0,1]，并相应调整 scale（例如 σ=0.05）。 - 大样本下样本均值≈loc，样本方差≈scale**2。

使用代码

原理： - 像素新值 = 原值 + N(μ, σ^2) - μ（mean）通常取 0；σ（sigma）控制噪声强度（uint8 下常用 10–30，归一化浮点图像下用 0.01–0.1）

代码示例（numpy + OpenCV）：

import cv2
import numpy as np

def add_gaussian_noise(img, mean=0, sigma=10):
    # img: numpy array, 灰度或彩色（uint8 或 float）
    if img.dtype == np.uint8:
        img_f = img.astype(np.float32)
        gauss = np.random.normal(mean, sigma, img.shape).astype(np.float32)
        noisy = img_f + gauss
        noisy = np.clip(noisy, 0, 255).astype(np.uint8)
    else:
        # 假设 float 图像范围在 [0,1]
        img_f = img.astype(np.float32)
        gauss = np.random.normal(mean, sigma, img.shape).astype(np.float32)
        noisy = img_f + gauss
        noisy = np.clip(noisy, 0.0, 1.0).astype(img.dtype)
    return noisy

# 用法
img = cv2.imread("image.jpg")          # BGR, uint8
noisy = add_gaussian_noise(img, 0, 25)
cv2.imwrite("noisy.jpg", noisy)

若用 skimage（更简短、自动归一化）：

from skimage.util import random_noise
noisy = (random_noise(img, mode='gaussian', mean=0, var=(sigma/255.0)**2) * 255).astype(np.uint8)

额外注意： - 一定要区别“高斯噪声（像素加随机值）”与“高斯模糊（低通滤波）”两个不同操作。 - 如需可重复结果，先调用 np.random.seed(…) 固定随机数种子。 - 若想控制信噪比（SNR），可通过计算噪声方差与图像信号方差来设置 σ。

椒盐噪声

原理（简短）：

椒盐噪声：随机把部分像素设为 0（pepper）或最大值 255（salt）。
参数说明：amount（总像素比例，0–1），salt_vs_pepper（盐占比，0–1），seed（可重复性）。

integers 是 NumPy 新随机生成器 Generator 的方法，用来从指定整数区间采样整数数组（推荐代替旧的 np.random.randint）。

要点：

签名（常用形式）：rng.integers(low, high=None, size=None, dtype=np.int64, endpoint=False)
- low：下界（包含）。
- high：上界（默认 None 表示采样范围为 [0, low)；若指定则区间为 [low, high)，当 endpoint=True 时变为 [low, high]）。
- size：输出形状（整数或元组）；None 返回单个标量。
- dtype：返回整型类型（默认 np.int64）。
- endpoint：是否包含上界（默认为 False，不包含上界）。
返回：NumPy 整数数组或标量，常用于索引或生成随机坐标。
可重复性：配合 rng = np.random.default_rng(seed) 使用可复现结果。

实现

import numpy as np

def add_salt_pepper_noise(img, amount=0.05, salt_vs_pepper=0.5, seed=None):
    """
    img: uint8 灰度 (H,W) 或 彩色 (H,W,C)
    amount: 总替换比例，例如 0.05 表示 5% 像素被替换
    salt_vs_pepper: 在替换像素中盐(255)占比
    seed: 随机种子（可选）
    """
    rng = np.random.default_rng(seed)
    out = img.copy()
    h, w = img.shape[:2]
    total = h * w
    num_salt = int(np.ceil(amount * total * salt_vs_pepper))
    num_pepper = int(np.ceil(amount * total * (1.0 - salt_vs_pepper)))

    # 盐
    ys = rng.integers(0, h, num_salt)
    xs = rng.integers(0, w, num_salt)
    if img.ndim == 2:
        out[ys, xs] = 255
    else:
        out[ys, xs, :] = 255

    # 胡椒
    ys = rng.integers(0, h, num_pepper)
    xs = rng.integers(0, w, num_pepper)
    if img.ndim == 2:
        out[ys, xs] = 0
    else:
        out[ys, xs, :] = 0

    return out

补充：若你也想修正高斯噪声生成（避免把噪声直接 cast 为 uint8 导致错误），用下面的方式：

sigma = 25
noise = np.random.normal(0, sigma, gray_img.shape).astype(np.float32)
noisy_gauss = np.clip(gray_img.astype(np.float32) + noise, 0, 255).astype(np.uint8)

亮度/对比度调整

先概览可用方法（按常用性与用途）： - 基本亮度/对比度：cv2.convertScaleAbs / cv2.addWeighted
- 伽马校正（非线性亮度调整）：cv2.LUT + 查表法
- 直方图均衡化 / 自适应直方图（增强对比度）：cv2.equalizeHist / cv2.createCLAHE
- 归一化 / 拉伸对比度：cv2.normalize 或手动线性变换（float → clip → uint8）

示例代码（常用）：

1) 线性亮度/对比度（推荐）

# new = alpha * img + beta
out = cv2.convertScaleAbs(img, alpha=1.2, beta=30)   # alpha 控制对比度, beta 控制亮度
# 等价写法
out2 = cv2.addWeighted(img, 1.2, img, 0, 30)

2) 伽马校正（改变中间亮部而非线性）

gamma = 0.8  # <1 更亮, >1 更暗
inv = 1.0 / gamma
table = (np.arange(256) / 255.0) ** inv * 255
table = np.clip(table, 0, 255).astype('uint8')
out = cv2.LUT(img, table)

3) 直方图均衡化（灰度图提高全局对比）

gray_eq = cv2.equalizeHist(gray_img)         # 灰度图
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8,8))
gray_clahe = clahe.apply(gray_img)

4) 彩色图建议（调整亮度在 V 通道）

hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV).astype(np.float32)
hsv[...,2] = np.clip(hsv[...,2] * 1.1 + 10, 0, 255)
out = cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2BGR)

参数提示（经验值）： - alpha（对比度）：1.0（无变化）到 2~3（显著增强）
- beta（亮度）：-100 到 +100（视场景）
- gamma：0.4–2.5（<1 增亮，>1 变暗）
- CLAHE clipLimit：1.5–3.0，tileGridSize 常用 (8,8)

小贴士： - 对于 convertScaleAbs，输入 uint8 可直接用；若需要更精细控制先转 float，变换后 clip 并转回 uint8。
- 彩色图最好在亮度通道（HSV V 或 LAB L）上处理，避免破坏色彩饱和度。