# 图像预处理与颜色过滤

> ImageProcessor 的尺寸调整、灰度转换、去噪与二值化能力，以及 ColorFilter 的 HSV 颜色空间过滤机制

- Repository: sml2h3/ddddocr
- GitHub: https://github.com/sml2h3/ddddocr
- Human wiki: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-10e2eae686bf
- Complete Markdown: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-10e2eae686bf/llms-full.txt

## Source Files

- `ddddocr/preprocessing/image_processor.py`
- `ddddocr/preprocessing/color_filter.py`
- `ddddocr/preprocessing/__init__.py`
- `ddddocr/utils/image_io.py`

---

<details>
<summary>相关源文件</summary>
以下文件用于生成此维基页面：
- [ddddocr/preprocessing/image_processor.py](ddddocr/preprocessing/image_processor.py)
- [ddddocr/preprocessing/color_filter.py](ddddocr/preprocessing/color_filter.py)
- [ddddocr/preprocessing/__init__.py](ddddocr/preprocessing/__init__.py)
- [ddddocr/utils/image_io.py](ddddocr/utils/image_io.py)
- [ddddocr/utils/validators.py](ddddocr/utils/validators.py)
- [ddddocr/utils/exceptions.py](ddddocr/utils/exceptions.py)
- [ddddocr/core/ocr_engine.py](ddddocr/core/ocr_engine.py)
</details>

# 图像预处理与颜色过滤

ddddocr 的图像预处理子系统位于 `ddddocr/preprocessing/` 包中，包含两个核心类：`ImageProcessor` 和 `ColorFilter`。它们负责在图像送入 OCR 推理引擎之前完成尺寸归一化、灰度转换、噪声去除、对比度增强和基于 HSV 颜色空间的区域过滤。这一层是 OCR 准确率的关键保障——不规范的输入尺寸或背景噪声会直接降低识别效果。

## 模块结构

`ddddocr/preprocessing/__init__.py` 导出了两个公共类，形成预处理子系统的全部对外接口：

```python
from .color_filter import ColorFilter
from .image_processor import ImageProcessor
```

两个类均依赖 `ddddocr/utils/` 中的工具函数完成图像格式转换（PIL ↔ numpy）和参数校验，同时通过 `safe_import_opencv()` 安全加载 OpenCV，确保在缺少 cv2 时给出明确的安装指导而非静默失败。

Sources: [ddddocr/preprocessing/__init__.py:7-13](ddddocr/preprocessing/__init__.py), [ddddocr/utils/exceptions.py:84-98](ddddocr/utils/exceptions.py)

## ImageProcessor：图像处理流水线

`ImageProcessor` 是一个纯静态方法集合，所有方法均为 `@staticmethod`，无需实例化即可调用。核心能力分为四类：尺寸调整、颜色空间转换、噪声处理与图像增强。

### 尺寸调整（resize_image）

`resize_image` 接受 PIL Image、目标尺寸 `(width, height)` 和可选的宽高比保持标志。当 `keep_aspect_ratio=True` 时，方法计算宽高两个方向的缩放比例，取较小值作为统一缩放因子，确保图像不被拉伸变形。

```python
# 计算缩放比例
width_ratio = target_width / original_width
height_ratio = target_height / original_height
scale_ratio = min(width_ratio, height_ratio)
```

默认重采样方法为 `Image.LANCZOS`（高质量 Lanczos 滤波），适合 OCR 场景下的文字清晰度需求。

Sources: [ddddocr/preprocessing/image_processor.py:22-60](ddddocr/preprocessing/image_processor.py)

### 灰度转换（convert_to_grayscale）

`convert_to_grayscale` 封装了 PIL 的 `'L'` 模式转换，将 RGB 或 RGBA 图像降为单通道灰度图。这是 OCR 模型推理前的必要步骤——多数 OCR 模型期望单通道输入。

Sources: [ddddocr/preprocessing/image_processor.py:63-79](ddddocr/preprocessing/image_processor.py)

### 噪声去除（remove_noise）

`remove_noise` 使用 OpenCV 的中值滤波（`cv2.medianBlur`），默认核大小为 3×3。中值滤波对椒盐噪声特别有效，同时能较好地保留文字边缘锐度，优于均值滤波。方法内部根据输入数组的维度自动区分彩色图像和灰度图像的处理路径，但实际上两者调用的 OpenCV 函数相同。

Sources: [ddddocr/preprocessing/image_processor.py:169-197](ddddocr/preprocessing/image_processor.py)

### 图像二值化（binarize_image）

`binarize_image` 支持三种二值化策略：

| 方法 | 参数值 | 实现方式 | 适用场景 |
|------|--------|----------|----------|
| 固定阈值 | `'simple'` | `cv2.threshold` + `THRESH_BINARY` | 光照均匀的简单验证码 |
| Otsu 自动阈值 | `'otsu'` | `cv2.threshold` + `THRESH_OTSU` | 光照不均匀、直方图双峰 |
| 自适应阈值 | `'adaptive'` | `cv2.adaptiveThreshold` + `GAUSSIAN_C` | 复杂背景、局部光照差异大 |

方法内部会先将非灰度图像转为 `'L'` 模式，再执行二值化。

Sources: [ddddocr/preprocessing/image_processor.py:200-238](ddddocr/preprocessing/image_processor.py)

### 图像增强

`ImageProcessor` 还提供两种基于 PIL `ImageEnhance` 的增强方法：

- **`enhance_contrast`**：对比度增强，接受 `factor` 参数（默认 1.5），大于 1 增强、小于 1 降低。
- **`enhance_sharpness`**：锐度增强，同样基于 `factor` 控制强度。

两者均通过延迟导入 `PIL.ImageEnhance` 避免不必要的模块加载。

Sources: [ddddocr/preprocessing/image_processor.py:125-166](ddddocr/preprocessing/image_processor.py)

### OCR 预处理流水线（preprocess_for_ocr）

`preprocess_for_ocr` 将上述单项能力组装为一条完整的 OCR 预处理流水线：

```
RGBA 透明背景处理 → 尺寸调整（保持宽高比，目标高度 64px）→ 对比度增强 → 中值滤波去噪 → 灰度转换
```

其中 PNG 透明背景处理委托给 `image_io.png_rgba_black_preprocess`，它创建白色背景并将透明图层合成上去。

Sources: [ddddocr/preprocessing/image_processor.py:241-287](ddddocr/preprocessing/image_processor.py), [ddddocr/utils/image_io.py:59-79](ddddocr/utils/image_io.py)

## ColorFilter：HSV 颜色空间过滤

`ColorFilter` 实现基于 HSV（色相-饱和度-明度）颜色空间的图像过滤，用于从复杂背景中提取特定颜色区域的文字或图形。

### 设计原理

HSV 颜色空间比 RGB 更适合颜色过滤，因为色相（H）通道独立编码颜色信息，不受明度和饱和度干扰。`ColorFilter` 将用户指定的颜色需求转化为 HSV 范围掩码，通过逐像素匹配保留目标颜色区域，其余区域设为白色。

### 内置颜色预设

`COLOR_PRESETS` 字典定义了 10 种常见颜色的 HSV 范围值：

| 颜色 | HSV 范围数 | 色相区间 | 备注 |
|------|-----------|----------|------|
| `red` | 2 | 0–10, 170–180 | 红色跨越 0°/180° 边界，需两个范围 |
| `blue` | 1 | 100–130 | — |
| `green` | 1 | 40–80 | — |
| `yellow` | 1 | 20–40 | — |
| `orange` | 1 | 10–20 | — |
| `purple` | 1 | 130–170 | — |
| `cyan` | 1 | 80–100 | — |
| `black` | 1 | H: 0–180, S: 0–255, V: 0–50 | 低明度区域 |
| `white` | 1 | H: 0–180, S: 0–30, V: 200–255 | 低饱和度高明度 |
| `gray` | 1 | H: 0–180, S: 0–30, V: 50–200 | 低饱和度中明度 |

所有预设的 S/V 下限均为 50，避免将接近灰色的像素误纳入。

Sources: [ddddocr/preprocessing/color_filter.py:23-34](ddddocr/preprocessing/color_filter.py)

### 初始化与参数校验

构造函数接受 `colors`（预设颜色名列表）和 `custom_ranges`（自定义 HSV 范围列表）两个可选参数，至少提供其一。参数校验由 `validators.validate_color_filter_params` 完成，检查项包括：

- `colors` 中每个元素必须是字符串
- `custom_ranges` 中每个元素必须是二元组，包含两个三元组
- H 通道值范围 0–180，S/V 通道值范围 0–255
- 每个范围的下界不能大于上界

Sources: [ddddocr/preprocessing/color_filter.py:36-66](ddddocr/preprocessing/color_filter.py), [ddddocr/utils/validators.py:83-137](ddddocr/utils/validators.py)

### 核心过滤流程（filter_image）

`filter_image` 的处理流程如下：

```
输入图像 → RGB→BGR → BGR→HSV → 逐范围生成掩码 → 合并掩码 → 应用掩码 → 背景设白色 → BGR→RGB → 输出
```

关键步骤：

1. **颜色空间转换**：输入统一转为 BGR（OpenCV 格式），再转 HSV
2. **掩码生成**：对每个 HSV 范围调用 `cv2.inRange` 生成二值掩码，通过 `cv2.bitwise_or` 合并
3. **掩码应用**：`cv2.bitwise_and` 保留匹配区域，非匹配区域设为白色 `[255, 255, 255]`

`get_mask` 方法提供同样的掩码生成逻辑但不应用滤镜，返回原始二值掩码供下游自定义处理。

Sources: [ddddocr/preprocessing/color_filter.py:68-148](ddddocr/preprocessing/color_filter.py)

### 动态范围管理

`ColorFilter` 提供运行时修改颜色范围的能力：

- `add_color_range(lower, upper)` — 追加自定义 HSV 范围
- `add_preset_color(color)` — 追加预设颜色
- `clear_ranges()` — 清空所有范围
- `get_ranges()` — 获取当前范围副本
- `get_available_colors()` — 类方法，列出所有预设颜色名
- `get_color_range(color)` — 类方法，查询指定颜色的 HSV 范围

Sources: [ddddocr/preprocessing/color_filter.py:150-220](ddddocr/preprocessing/color_filter.py)

## OCR 引擎中的集成

`OCREngine` 在推理前将 `ColorFilter` 和 `ImageProcessor` 串联使用：

1. **颜色过滤**（可选）：如果用户指定了 `color_filter_colors` 或 `color_filter_custom_ranges`，先创建 `ColorFilter` 实例对图像进行颜色过滤。过滤失败时仅打印警告并跳过，不影响后续流程。
2. **图像预处理**：`_preprocess_image` 根据模型类型选择不同的尺寸策略：
   - 默认模型：固定目标高度 64px，宽度按比例计算，然后灰度转换
   - 自定义模型（`use_import_onnx`）：根据 `resize` 配置决定是否固定宽高或保持宽高比；根据 `channel` 配置决定是否灰度转换
3. **标准化**：像素值归一化到 `[0, 1]`，维度从 HWC 转为 CHW 格式

```python
# OCR引擎中的集成示例
color_filter = ColorFilter(colors=color_filter_colors,
                           custom_ranges=color_filter_custom_ranges)
pil_image = color_filter.filter_image(pil_image)
# ...
image = ImageProcessor.resize_image(image, (target_width, target_height))
image = ImageProcessor.convert_to_grayscale(image)
```

Sources: [ddddocr/core/ocr_engine.py:130-196](ddddocr/core/ocr_engine.py)

## 图像 I/O 工具层

`ddddocr/utils/image_io.py` 提供预处理模块依赖的基础图像格式转换函数：

| 函数 | 功能 |
|------|------|
| `image_to_numpy` | PIL Image → numpy 数组，支持自动模式转换 |
| `numpy_to_image` | numpy 数组 → PIL Image |
| `png_rgba_black_preprocess` | RGBA 透明背景转白色背景 |
| `load_image_from_input` | 统一加载入口，支持 bytes、base64、文件路径、PIL Image、numpy 数组 |
| `base64_to_image` / `get_img_base64` | base64 编解码 |

`load_image_from_input` 是 OCR 引擎的统一图像加载入口，支持 5 种输入格式，内部通过类型分发路由到对应的解码逻辑。字符串输入优先尝试文件路径，失败后作为 base64 解码。

Sources: [ddddocr/utils/image_io.py:18-209](ddddocr/utils/image_io.py)

## 错误处理策略

预处理模块采用统一的异常层次结构：所有图像处理异常抛出 `ImageProcessError`（继承自 `DDDDOCRError`），OpenCV 导入失败时通过 `safe_import_opencv` 提供跨平台安装指导。`ColorFilter` 的构造函数通过 `validate_color_filter_params` 在初始化阶段即拦截非法参数，遵循"快速失败"原则。

Sources: [ddddocr/utils/exceptions.py:22-23](ddddocr/utils/exceptions.py), [ddddocr/utils/validators.py:83-137](ddddocr/utils/validators.py)