cutThenThink/docs/ocr_module.md

OCR 模块文档

概述

OCR 模块提供文字识别功能，支持本地 PaddleOCR 识别和云端 OCR API 扩展。

目录结构

src/core/ocr.py            # OCR 模块主文件
examples/ocr_example.py    # 使用示例
tests/test_ocr.py          # 测试脚本

核心组件

1. 数据模型

OCRResult

单行识别结果

@dataclass
class OCRResult:
    text: str              # 识别的文本
    confidence: float      # 置信度 (0-1)
    bbox: List[List[float]]  # 文本框坐标 [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
    line_index: int        # 行索引

OCRBatchResult

批量识别结果

@dataclass
class OCRBatchResult:
    results: List[OCRResult]  # 所有识别结果
    full_text: str            # 完整文本
    total_confidence: float   # 平均置信度
    success: bool             # 是否成功
    error_message: Optional[str]  # 错误信息

OCRLanguage

支持的语言

class OCRLanguage(str, Enum):
    CHINESE = "ch"               # 中文
    ENGLISH = "en"               # 英文
    MIXED = "chinese_chinese"    # 中英混合

2. OCR 引擎

BaseOCREngine (抽象基类)

所有 OCR 引擎的基类

class BaseOCREngine(ABC):
    @abstractmethod
    def recognize(self, image, preprocess: bool = True) -> OCRBatchResult:
        """识别图像中的文本"""

PaddleOCREngine

本地 PaddleOCR 识别引擎

# 创建引擎
config = {
    'lang': 'ch',      # 语言
    'use_gpu': False,  # 是否使用 GPU
    'show_log': False  # 是否显示日志
}
engine = PaddleOCREngine(config)

# 识别
result = engine.recognize(image_path, preprocess=False)

配置参数:

• lang: 语言 (ch/en/chinese_chinese)
• use_gpu: 是否使用 GPU 加速
• show_log: 是否显示 PaddleOCR 日志

CloudOCREngine

云端 OCR 适配器（预留接口）

# 配置（需要根据具体 API 实现）
config = {
    'api_endpoint': 'https://api.example.com/ocr',
    'api_key': 'your_key',
    'provider': 'custom',
    'timeout': 30
}
engine = CloudOCREngine(config)

3. 图像预处理器

ImagePreprocessor

提供图像增强和预处理功能

# 单独使用
processor = ImagePreprocessor()
image = processor.load_image("image.png")

# 调整大小
resized = processor.resize_image(image, max_width=2000)

# 增强对比度
contrasted = processor.enhance_contrast(image, factor=1.5)

# 增强锐度
sharpened = processor.enhance_sharpness(image, factor=1.5)

# 去噪
denoised = processor.denoise(image)

# 二值化
binary = processor.binarize(image, threshold=127)

# 综合预处理
processed = processor.preprocess(
    image,
    resize=True,
    enhance_contrast=True,
    enhance_sharpness=True,
    denoise=False,
    binarize=False
)

4. 工厂类

OCRFactory

根据模式创建对应的引擎

# 创建本地引擎
local_engine = OCRFactory.create_engine("local", {'lang': 'ch'})

# 创建云端引擎
cloud_engine = OCRFactory.create_engine("cloud", {'api_endpoint': '...'})

快速开始

安装依赖

pip install paddleocr paddlepaddle

基本使用

from src.core.ocr import recognize_text

# 快速识别
result = recognize_text(
    image="path/to/image.png",
    mode="local",
    lang="ch",
    use_gpu=False,
    preprocess=False
)

if result.success:
    print(f"识别文本: {result.full_text}")
    print(f"平均置信度: {result.total_confidence:.2f}")

带预处理的识别

result = recognize_text(
    image="path/to/image.png",
    mode="local",
    lang="ch",
    preprocess=True  # 启用预处理
)

批量处理

from src.core.ocr import PaddleOCREngine

engine = PaddleOCREngine({'lang': 'ch'})

for image_path in image_list:
    result = engine.recognize(image_path)
    print(f"{image_path}: {result.full_text[:50]}...")

自定义预处理

from src.core.ocr import preprocess_image, recognize_text
from PIL import Image

# 预处理图像
processed = preprocess_image(
    "input.png",
    resize=True,
    enhance_contrast=True,
    enhance_sharpness=True
)

# 识别预处理后的图像
result = recognize_text(processed, mode="local", lang="ch")

测试

运行测试脚本:

# 基本测试
python tests/test_ocr.py --image /path/to/image.png

# 指定语言
python tests/test_ocr.py --image /path/to/image.png --lang en

# 使用 GPU
python tests/test_ocr.py --image /path/to/image.png --gpu

# 仅测试预处理
python tests/test_ocr.py --image /path/to/image.png --preprocess-only

支持的输入格式

• 文件路径: 字符串路径
• PIL Image: PIL.Image.Image 对象
• NumPy 数组: numpy.ndarray

# 三种方式都可以
result1 = recognize_text("/path/to/image.png")
result2 = recognize_text(Image.open("/path/to/image.png"))
result3 = recognize_text(numpy.array(Image.open("/path/to/image.png")))

性能优化建议

1. GPU 加速: 如果有 NVIDIA GPU，设置 use_gpu=True
2. 图像大小: 自动调整到合理大小（max_width=2000）
3. 预处理: 对低质量图像启用预处理可提高准确率
4. 批量处理: 复用引擎实例处理多张图片

常见问题

Q: 如何提高识别准确率？

A:

1. 对低质量图片启用预处理 (preprocess=True)
2. 确保图片分辨率足够
3. 选择正确的语言参数
4. 尝试不同的预处理组合

Q: 如何处理中英混合文本？

A:

result = recognize_text(image, lang="chinese_chinese")

Q: 如何获取每行的坐标？

A:

for line_result in result.results:
    print(f"文本: {line_result.text}")
    print(f"坐标: {line_result.bbox}")

Q: 云端 OCR 如何使用？

A: CloudOCREngine 是预留接口，需要根据具体的云服务 API 实现 _send_request 方法。

扩展云端 OCR

如需扩展云端 OCR，继承 CloudOCREngine 并实现 _send_request 方法:

class CustomCloudOCREngine(CloudOCREngine):
    def _send_request(self, image_data: bytes) -> Dict[str, Any]:
        # 发送 API 请求
        # 返回标准格式: {"text": "...", "confidence": 0.95}
        pass

    def recognize(self, image, preprocess=False) -> OCRBatchResult:
        # 实现具体逻辑
        pass

API 参考

recognize_text()

快捷识别函数

def recognize_text(
    image,              # 图像（路径、PIL Image、numpy 数组）
    mode: str = "local",      # OCR 模式
    lang: str = "ch",          # 语言
    use_gpu: bool = False,     # 是否使用 GPU
    preprocess: bool = False,  # 是否预处理
    **kwargs
) -> OCRBatchResult

preprocess_image()

快捷预处理函数

def preprocess_image(
    image_path: str,
    output_path: Optional[str] = None,
    resize: bool = True,
    enhance_contrast: bool = True,
    enhance_sharpness: bool = True,
    denoise: bool = False,
    binarize: bool = False
) -> Image.Image