# ppocr

**Repository Path**: wyonging/ppocr

## Basic Information

- **Project Name**: ppocr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleOCR C++ 推理部署

基于 **PaddlePaddle C++ Inference** 的 OCR / PP-StructureV3 推理部署项目，支持 PP-OCRv5 文本检测与识别、PP-StructureV3 文档版面分析、表格识别、公式识别。

> 参考文档：[PaddleOCR C++ 推理部署](https://www.paddleocr.ai/latest/version3.x/inference_deployment/local_inference/cpp/OCR.html)

---

## 目录

- [系统架构](#系统架构)
- [环境准备](#环境准备)
- [CPU 编译与运行](#CPU编译与运行)
- [GPU 编译与运行](#gpu-编译与运行)
- [CPU / GPU 性能对比](#cpu--gpu-性能对比)
- [PP-StructureV3 管线流程](#pp-structurev3-管线流程)
- [模块说明](#模块说明)

---

## 系统架构

```
pp-ocr-cpp-infer/
├── CMakeLists.txt              # 根构建脚本：编译 ppocr_core 静态库
│
├── app/
│   ├── CMakeLists.txt          # 应用构建脚本：编译 ppocr 可执行文件
│   ├── cli.cc                  # 完整版 CLI，支持多种 pipeline 和模型
│   └── main.cpp                # PP-StructureV3 交互式 Demo（循环等待图片输入）
│
├── src/                        # OCR 核心代码 → 编译为 ppocr_core.a
│   ├── api/                    # 高层 API 封装
│   │   ├── models/             # 模型接口（文本检测、识别、分类、矫正等）
│   │   └── pipelines/          # Pipeline 接口（OCR、文档预处理、StructureV3）
│   ├── base/                   # 抽象基类（Predictor、Pipeline、BatchSampler、CVResult）
│   ├── common/                 # 通用工具（Paddle 推理引擎、图像预处理、线程池、并行管线）
│   ├── modules/                # 各模块实现
│   │   ├── text_detection/     #    文本检测（DB）
│   │   ├── text_recognition/   #    文本识别（CRNN + CTC）
│   │   ├── image_classification/ # 图像分类（Topk）
│   │   ├── image_unwarping/    #    文档图像矫正（UVDoc）
│   │   ├── layout_analysis/    #    版面分析（DETR）
│   │   ├── table_recognition/  #    表格识别（SLANet）
│   │   └── formula_recognition/ #   公式识别（UniMERNet）
│   ├── pipelines/              # Pipeline 编排实现
│   │   ├── ocr/                #    OCR 管线
│   │   ├── doc_preprocessor/   #    文档预处理管线
│   │   └── structurev3/        #    PP-StructureV3 管线
│   └── utils/                  # 工具函数（YAML 配置、日志、命令行参数、Paddle 选项）
│
├── third_party/                # 第三方依赖
│   ├── paddle_inference/       #    PaddlePaddle 推理库（需自行下载）
│   ├── abseil-cpp/             #    Abseil C++ 库（自动下载）
│   ├── clipper_ver6.4.2/       #    多边形裁剪库（自动下载）
│   └── nlohmann/               #    JSON 库（自动下载）
│
├── models/                     # 推理模型文件（软链接）
├── configs/                    # 管线配置文件（YAML）
├── fonts/                      # 可视化字体文件
├── tools/                      # 构建脚本
│   ├── build.sh                #    一键编译脚本
│   └── build_opencv.sh         #    OpenCV 编译脚本
│
└── general_ocr_002.png         # 测试图片
```

### 编译依赖关系

```
third_party (abseil / clipper / nlohmann)
        ↓
   ppocr_core.a  (src/*.cc)
        ↓
     ┌──────────────────┐
     ↓                  ↓
   ppocr             ppocr_demo
  (cli.cc)          (main.cpp)
  完整版 CLI     StructureV3 交互式 Demo
```

### 架构分层

项目采用严格的分层架构，共 **6 层**：

| 层 | 目录 | 职责 |
|---|------|------|
| 🚪 入口层 | `app/` | CLI 入口和交互式 Demo |
| 📦 API 封装 | `src/api/` | 面向用户的公共接口 |
| 🔗 管线编排 | `src/pipelines/` | 组合多个模块完成复杂任务 |
| 🧩 模型模块 | `src/modules/` | 单个神经网络模型推理（7 个模块） |
| 🏗️ 抽象基类 | `src/base/` | Predictor / Pipeline / BatchSampler / CVResult |
| 🛠️ 基础设施 | `src/common/` + `src/utils/` | 推理引擎 / 预处理 / 线程池 / 配置 / 日志 |

---

## 环境准备

### 1. OpenCV

```bash
./tools/build_opencv.sh
```

`third_party/opencv4` 是编译好的文件。如果系统已安装 OpenCV 4.x，也可直接使用系统库：

```bash
sudo apt install libopencv-dev
```

### 2. PaddlePaddle 推理库

下载 [paddle_inference](https://www.paddleocr.ai/latest/version3.x/inference_deployment/local_inference/cpp/OCR.html) 并解压到：

```
third_party/paddle_inference/
```

### 3. 模型文件

将模型放在 `models/` 目录，支持以下模型：

| 模型 | 用途 | 架构 | 配置特点 |
|------|------|------|---------|
| `PP-OCRv5_server_det` / `PP-OCRv5_mobile_det` | 文本检测 | DB | 960 resize_long |
| `PP-OCRv5_server_rec` / `PP-OCRv5_mobile_rec` | 文本识别 | CRNN+CTC | 标准 CTC 解码 |
| `PP-DocLayout_plus-L` / `PP-DocBlockLayout` | 版面分析 | DETR | 800×800, 多类别 |
| `SLANet_plus` / `SLANeXt` | 表格识别 | Encoder-Decoder | 488×488, HTML 输出 |
| `PP-FormulaNet_plus-L` | 公式识别 | UniMERNet | 768×768, LaTeX 输出 |
| `PP-LCNet_x1_0_doc_ori` | 文档方向分类 | 分类 | 分类模型 |
| `PP-LCNet_x0_25_textline_ori` | 文本行方向 | 分类 | 分类模型 |
| `UVDoc` | 文档矫正 | 矫正 | 文档展平 |


### 4. 字体文件（可选，可视化用）

将 `.ttf` 字体放到 `fonts/` 目录。

---

## CPU编译与运行
```bash
./tools/build.sh
```

## 运行
```
./tools/run_cpu.sh
```

### OCR 管线

```bash
./build/ppocr ocr \
    --input ./general_ocr_002.png \
    --save_path ./output/ \
    --text_detection_model_dir models/PP-OCRv5_server_det_infer \
    --text_recognition_model_dir models/PP-OCRv5_server_rec_infer \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --use_textline_orientation False \
    --device cpu \
    --vis_font_dir ./fonts/simhei.ttf
```

### PP-StructureV3 管线

版面分析 + OCR + 表格 + 公式识别：

```bash
./build/ppocr structurev3 \
    --input ./general_ocr_002.png \
    --save_path ./output/ \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --use_textline_orientation False \
    --device cpu
```

模型路径通过 `src/configs/structurev3.yaml` 配置，也可通过命令行参数覆盖：

---

## GPU 编译与运行

### GPU 编译

```bash
./tools/build_gpu.sh
```

### GPU 运行命令
```
./tools/run_gpu.sh
```

```bash
# OCR 全管线
./build_gpu/app/ppocr ocr \
    --input ./general_ocr_002.png \
    --save_path ./output/ \
    --text_detection_model_dir models/PP-OCRv5_server_det_infer \
    --text_recognition_model_dir models/PP-OCRv5_server_rec_infer \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --use_textline_orientation False \
    --vis_font_dir ./fonts/simhei.ttf

```

```bash
# StructureV3 全管线（默认 gpu:0）
./build_gpu/app/ppocr structurev3 \
    --input ./pp_structure_v3_demo.png \
    --save_path ./output_gpu/ \
    --vis_font_dir ./fonts/simhei.ttf \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --use_textline_orientation False

# 可选：fp16 混合精度推理（--precision fp16 → paddle_fp16，需 GPU 支持）
./build_gpu/app/ppocr structurev3 --input ./pp_structure_v3_demo.png \
    --save_path ./output_gpu/ --precision fp16 --device gpu:0
```

CPU 版用同一命令，仅替换二进制与 `--device cpu`：

```bash
./build/app/ppocr structurev3 --input ./pp_structure_v3_demo.png \
    --save_path ./output_cpu/ --device cpu --vis_font_dir ./fonts/simhei.ttf \
    --use_doc_orientation_classify False --use_doc_unwarping False \
    --use_textline_orientation False
```

### 日常开发
```bash
cd build

# 只改了 cli.cc → 只编译，不动 src/
make ppocr -j$(nproc)

# 改了 main.cpp → 编译 ppocr_demo
make ppocr_demo -j$(nproc)

# 改了 src/ 或 third_party → 重编库 + 可执行文件
make ppocr_core -j$(nproc) && make ppocr -j$(nproc)
```

---

## CPU / GPU 性能对比

以下数据为本仓库在 **同一测试环境** 下实测结果，可复现。

### 测试环境

| 项目 | 配置 |
|------|------|
| CPU | 8 线程，MKLDNN（`--cpu_threads` 默认 8） |
| GPU | NVIDIA GeForce RTX 2060 6GB，驱动 550.144.03 |
| 推理库 | Paddle Inference 3.0.0（CPU 版 / GPU 版 CUDA 11.8 + cuDNN 8.9） |
| 测试输入 | `pp_structure_v3_demo.png`（新闻长文页，含 31 个版面区域） |
| 管线 | structurev3（关闭文档预处理/文本行方向） |

### 端到端耗时

| 指标 | CPU | GPU 冷启动 | GPU 热启动 |
|------|-----|-----------|-----------|
| 墙钟时间 | **28.73s** | 13.54s | **8.38s** |
| CPU user+sys | 188.9s + 14.2s | 8.0s + 3.5s | — |
| 峰值内存 RSS | 2.99 GB | 1.68 GB | — |
| 模型加载+初始化 | ~3s | ~4-5s（含首次 CUDA 上下文创建） | ~4s |

### 各模型推理耗时（`predictor_->Run()` 计时，不含预处理）

| 模型 | 调用次数 | CPU 单次平均 | CPU 合计 | GPU 合计（热） |
|------|---------|------------|---------|--------------|
| PP-DocLayout_plus-L（版面分析） | 1 | 1046.5ms | 1.05s | 0.46s |
| PP-OCRv5_server_det（文本检测） | 1 | 3012.1ms | 3.01s | 0.37s |
| PP-OCRv5_server_rec（文本识别） | 23 | 734.8ms | 16.90s | 0.17s |
| **推理合计** | | | **≈ 21.0s** | **≈ 1.0s** |

> 测试图为纯文章页，**没有表格和公式区域**，因此 `SLANet_plus`、`PP-FormulaNet_plus-L` 未触发推理（模型仍会加载）。

### 结论

- **纯推理加速比 ≈ 21×**（CPU 21.0s → GPU ≈1.0s）
- 识别阶段（rec，CPU 上占推理 80%）GPU 加速 **≈ 99×**（16.90s → 0.17s）
- 端到端加速 **≈ 3.4×**（28.7s → 8.4s）；GPU 模型加载/初始化占 4-5s，占比随图片张数增加而摊薄
- 输出一致性：CPU / GPU 两次运行 JSON 完全一致（31 区域 / 25 文本区 / 136 文本行 / 2382 字）

### 性能统计说明

- 以上「各模型推理耗时」由 `src/common/static_infer.{h,cc}` 中的**计时插桩**统计：在 `predictor_->Run()` 前后用 `steady_clock` 计时累加，模型析构时打印一行汇总（例：`[timing] model=PP-OCRv5_server_rec runs=23 total=16901.0ms avg=734.8ms`）
- 端到端耗时通过 `/usr/bin/time -v` 统计（wall / user / sys / RSS）

---

### 输出结果

在 `output/` 目录下生成：
- 可视化结果图片: `*_ocr_res_img.png`
- 结构化 JSON 结果: `*_res.json`

---

## 模块说明

### 管线（Pipeline）

| 管线名称 | CLI 模式 | 功能 |
|---------|---------|------|
| **OCR** | `ocr` | 文本检测 + 方向分类 + 文本识别 |
| **DocPreprocessor** | `doc_preprocessor` | 文档方向分类 + 矫正 |
| **StructureV3** | `structurev3` | 版面分析 → 按区域 OCR/表格/公式 |

### 模块（Module）

| 模块名称 | CLI 模式 | 功能 |
|---------|---------|------|
| 文本检测 | `text_detection` | DB 文本检测 |
| 文本识别 | `text_recognition` | CRNN CTC 文本识别 |
| 方向分类 | `doc_img_orientation_classification` | 文档方向分类 |
| 文本行方向 | `textline_orientation_classification` | 文本行方向分类 |
| 图像矫正 | `text_image_unwarping` | 文档图像展平 |
| 版面分析 | `structurev3` 管线内置 | DETR 版面区域检测 |
| 表格识别 | `structurev3` 管线内置 | SLANet 表格 HTML 输出 |
| 公式识别 | `structurev3` 管线内置 | UniMERNet LaTeX 输出 |


### 基本用法

```bash
./build/app/ppocr <pipeline_or_module> --input <图像路径> [--其他参数]
```

**模式选择（必填，第一个位置参数）：**

| 模式 | 说明 |
|------|------|
| `ocr` | **完整 OCR pipeline**：检测 → 识别（可选预处理、方向分类） |
| `doc_preprocessor` | 文档预处理 pipeline：方向分类 + 矫正 |
| `text_detection` | 单独跑文本检测模型 |
| `text_recognition` | 单独跑文本识别模型 |
| `doc_img_orientation_classification` | 单独文档方向分类 |
| `textline_orientation_classification` | 单独文本行方向分类 |
| `text_image_unwarping` | 单独文档矫正 |

---

### 一、模型路径 / 名称参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--text_detection_model_dir` | "" | 文本检测模型目录（必填，除非用默认名称） |
| `--text_detection_model_name` | `PP-OCRv5_server_det` | 检测模型名称（配合 `--text_detection_model_dir`） |
| `--text_recognition_model_dir` | "" | 文本识别模型目录（必填） |
| `--text_recognition_model_name` | `PP-OCRv5_server_rec` | 识别模型名称 |
| `--doc_orientation_classify_model_dir` | "" | 文档方向分类模型目录 |
| `--doc_orientation_classify_model_name` | `PP-LCNet_x1_0_doc_ori` | 方向分类模型名称 |
| `--doc_unwarping_model_dir` | "" | 文档矫正模型目录 |
| `--doc_unwarping_model_name` | `UVDoc` | 矫正模型名称 |
| `--textline_orientation_model_dir` | "" | 文本行方向分类模型目录 |
| `--textline_orientation_model_name` | `PP-LCNet_x1_0_textline_ori` | 文本行方向分类模型名称 |
| `--vis_font_dir` | "" | 可视化字体文件路径（编译时加 `-DUSE_FREETYPE=ON` 则必填） |
| `--paddlex_config` | "" | PaddleX pipeline YAML 配置路径 |

---

### 二、Pipeline 功能开关

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--use_doc_orientation_classify` | `true` | 是否启用文档方向分类预处理 |
| `--use_doc_unwarping` | `true` | 是否启用文档矫正预处理 |
| `--use_textline_orientation` | `true` | 是否启用文本行方向分类 |

> 以上三项默认 `true`，完整 OCR 时可按需关闭（`False`）以省去预处理开销。

---

### 三、检测参数（影响文本区域定位）

| 参数 | 默认值 | 说明 | 调整建议 |
|------|--------|------|----------|
| `--text_det_thresh` | `0.3` | 检测像素阈值。输出概率图中 > 此值的像素视为文本像素 | 漏检小字/淡字 → 调低（如 `0.2`）；噪声误检多 → 调高（如 `0.4`） |
| `--text_det_box_thresh` | `0.6` | 检测框阈值。框内像素平均得分 > 此值才视为有效文本区域 | 框太多（误检）→ 调高；框太少（漏检）→ 调低 |
| `--text_det_unclip_ratio` | `1.5` | 文本区域扩展系数。越大，最终框越宽（把字边缘包进去） | 字被切边 → 调大（如 `2.0`）；框太松 → 调小 |
| `--text_det_limit_side_len` | `64` | 输入图像边长限制值 | 配合 limit_type 使用 |
| `--text_det_limit_type` | `min` | 边长限制方式（`min`/`max`）。`min` = 最小边不低于 limit_side_len | 大图降分辨率 → `max` + 较大值；小图放大 → `min` + 较小值 |
| `--text_det_input_shape` | "" | 检测模型输入 shape，格式 `C,H,W`（如 `3,640,640`） | 模型固定输入尺寸时填写 |

---

### 四、识别参数（影响文字解码）

| 参数 | 默认值 | 说明 | 调整建议 |
|------|--------|------|----------|
| `--text_rec_score_thresh` | `0` | 文本识别置信度阈值。得分低于此值的识别结果被丢弃 | 想过滤低质量识别 → 调高（如 `0.5`） |
| `--text_recognition_batch_size` | `6` | 识别批次大小（多个文本框并行识别） | GPU 显存大 → 调大（如 `12`）提速；显存不足 → 调小 |
| `--textline_orientation_batch_size` | `6` | 文本行方向分类批次大小 | 同上 |
| `--text_rec_input_shape` | "" | 识别模型输入 shape，格式 `C,H,W` | 模型固定输入尺寸时填写 |

---

### 五、运行参数

| 参数 | 默认值 | 说明 | 调整建议 |
|------|--------|------|----------|
| `--device` | `cpu`（无 GPU）/ `gpu:0`（编译时 WITH_GPU） | 推理设备 | GPU 环境 → `gpu:0` 或 `gpu:1` 等 |
| `--precision` | `fp32` | 计算精度（`fp32`/`fp16`） | GPU 且模型支持 → `fp16` 提速 |
| `--cpu_threads` | `8` | Paddle 推理线程数（CPU） | CPU 核多 → 调大（如 `16`） |
| `--thread_num` | `1` | pipeline 实例并发线程数 | 多图并行 → 调大 |
| `--enable_mkldnn` | `true` | 是否启用 MKL-DNN 加速（CPU） | 一般保持 true |
| `--mkldnn_cache_capacity` | `10` | MKL-DNN 缓存容量 | 内存足 → 调大（如 `20`） |
| `--lang` | "" | 输入图像语言（如 `ch`、`en`） | 多语言模型时指定 |
| `--ocr_version` | "" | PP-OCR 版本（如 `PP-OCRv5`） | 多版本模型时指定 |
| `--save_path` | `./output/` | 输出目录 | 按需指定 |

---

### 六、参数速查表

| 想要的效果 | 参数 | 调整方向 |
|------------|------|----------|
| 文字检测框太多（噪声误检） | `--text_det_box_thresh` | ↑（如 `0.7`） |
| 文字检测框太少（漏检） | `--text_det_thresh` + `--text_det_box_thresh` | ↓（如 `0.2` / `0.5`） |
| 字被框边缘切掉 | `--text_det_unclip_ratio` | ↑（如 `2.0`） |
| 小图上文字模糊（放大不够） | `--text_det_limit_type=min` + `--text_det_limit_side_len` | ↑（如 `128`） |
| 大图推理慢（降分辨率） | `--text_det_limit_type=max` + `--text_det_limit_side_len` | ↓（如 `640`） |
| 识别结果里混入乱码（置信度低） | `--text_rec_score_thresh` | ↑（如 `0.5`） |
| GPU 上想提速 | `--precision=fp16` + `--text_recognition_batch_size` ↑ | 按显存调 |
| CPU 上想提速 | `--cpu_threads` ↑ + `--enable_mkldnn=true` | 按核数调 |
| 只跑检测、不识别 | 模式 `text_detection` + 只传检测模型参数 | — |
| 关掉预处理（降延迟） | `--use_doc_orientation_classify=False` 等 | — |

---

### 示例：常用调参场景

**场景 1：低对比度文档，文字淡、检测漏**

```bash
./build/app/ppocr ocr \
    --input ./doc.png \
    --text_detection_model_dir models/PP-OCRv5_server_det_infer \
    --text_recognition_model_dir models/PP-OCRv5_server_rec_infer \
    --text_det_thresh 0.2 \
    --text_det_box_thresh 0.5 \
    --use_doc_orientation_classify False \
    --device cpu
```

**场景 2：大分辨率扫描件，降速**

```bash
./build/app/ppocr ocr \
    --input ./scan.png \
    --text_detection_model_dir models/PP-OCRv5_server_det_infer \
    --text_recognition_model_dir models/PP-OCRv5_server_rec_infer \
    --text_det_limit_type max \
    --text_det_limit_side_len 1280 \
    --text_recognition_batch_size 12 \
    --device gpu:0 \
    --precision fp16
```

**场景 3：只跑检测，可视化文本区域**

```bash
./build/app/ppocr text_detection \
    --input ./doc.png \
    --text_detection_model_dir models/PP-OCRv5_server_det_infer \
    --text_det_thresh 0.3 \
    --text_det_box_thresh 0.6 \
    --save_path ./det_output/
```

> **注意**：上述参数均为 gflags 定义，所有参数都支持 `--help` 查看完整列表。参数值在 `args.cc` 中有默认值；CLI 传入会覆盖默认值。