# openocr

**Repository Path**: pangxiongfei/openocr

## Basic Information

- **Project Name**: openocr
- **Description**: 开源嵌入式ocr构建库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenOCR — 基于 ncnn 的轻量级端侧 OCR 工程

在嵌入式 / 端侧设备上离线运行的轻量 OCR 工程：以 [ncnn](https://github.com/Tencent/ncnn) 为推理引擎，封装 [PaddleOCR-ncnn-CPP](https://github.com/Avafly/PaddleOCR-ncnn-CPP)（支持 PP-OCRv3/4/5/6），对图片做文本检测 + 方向分类 + 文字识别，无需云端、无需 PaddlePaddle / Paddle-Lite。

---

## 一、工程意义

- **端侧离线 OCR**：在 ARM Linux（树莓派、嵌入式板卡）上直接推理，无网络依赖、无授权费用。
- **ncnn 高性能推理**：轻量、低依赖的深度学习前向引擎，针对移动 / 嵌入式优化（OpenMP 多线程、可选 FP16）。
- **PP-OCR 高精度模型**：采用百度 PP-OCRv6 系列模型（检测 / 识别 / 方向分类），中英文识别精度高、体积小。
- **一体化可复现构建**：`build.sh` 统一完成「解压原始包 → 编译 ncnn → 编译测试 / Demo」，支持 **x86 本机** 与 **aarch64 / arm 交叉编译**，产物按架构隔离到 `output/<arch>/`，不污染源码。
- **双重验证**：
  - `ocr_test`：ncnn 库冒烟测试，验证工具链、头文件与库版本匹配、模型可加载。
  - `ocr_demo`：调用 PaddleOCR-ncnn-CPP 做真实 OCR，端到端验证识别效果。

---

## 二、目录结构

```
openocr/
├── org/                      # 原始压缩包（ncnn 引擎 / OCR 封装 / 模型权重）
│   ├── ncnn-*.zip                 # ncnn 推理引擎源码
│   ├── PaddleOCR-ncnn-CPP-0.3.0.zip  # OCR 封装（解压为 PaddleOCR-ncnn-CPP，含 v6 模型，默认使用）
│   └── PP-OCRv5_mobile_archive.tar.gz    # 模型权重归档
├── source/                  # 由 org/ 解压得到（幂等，已解压则跳过）
│   ├── ncnn-*/                    # ncnn 源码
│   ├── PaddleOCR-ncnn-CPP/        # OCR 封装源码（支持 PP-OCRv3/4/5/6）+ 自带 v6 模型
│   └── PaddleOCR-ncnn-CPP/models/ # 识别模型（PP_OCRv6_medium_*, PP_LCNet_*, ppocr_keys_v6.txt）
├── output/<arch>/           # 构建产物（按架构隔离）
│   ├── ncnn/                     # 编译安装后的 ncnn 头文件 + 静态库
│   ├── build/                    # 中间构建目录（ncnn / demo）
│   ├── ocr_test                  # 冒烟测试程序（默认构建，仅 ncnn）
│   ├── ocr_demo                  # 真实 OCR 程序（BUILD_DEMO=1 时生成）
│   └── ocr_config.json           # OCR 配置（BUILD_DEMO=1 时生成，绝对路径模型）
├── main.c                   # 统一入口源码：基础模式=ncnn 冒烟测试；
│                            #   BUILD_DEMO=1 下为真实 OCR 工具（支持 -c/-f/-d）
├── test/                    # 示例图片目录（含 testimage.bmp，可用于 -d 批量）
├── build.sh                 # 顶层构建脚本
└── README.md
```

> 架构 `<arch>` 取值：`host`（本机 x86_64）、`aarch64-linux-gnu`、`arm-linux-gnueabihf`。

---

## 三、环境依赖

| 场景 | 必需依赖 | 说明 |
|---|---|---|
| 基础构建（默认，生成 `ocr_test`） | `bash`、`cmake`(≥3.10)、`ninja`、`g++`、`unzip`、`tar` | 编译 ncnn 与冒烟测试，**不需要** OpenCV |
| 交叉编译（aarch64 / arm） | 对应工具链 `aarch64-linux-gnu-*` 或 `arm-linux-gnueabihf-*` | 仅编译 `ocr_test`；本机未提供同架构 OpenCV 时自动跳过 Demo |
| OCR Demo（`BUILD_DEMO=1`） | `gcc-8` / `g++-8`、`pkg-config`、OpenCV（≥4，`pkg-config opencv4` 可找到） | 仅本机(host)支持；`g++-8` 提供 `<filesystem>`，OpenCV 提供 `cv::imread/imwrite` 等图像接口 |

### 依赖安装（Ubuntu / Debian 示例）

```bash
# 1) 基础构建依赖（必装，所有场景都需要）
sudo apt update
sudo apt install -y build-essential cmake ninja-build unzip tar pkg-config

# 2) OCR Demo 依赖（仅 BUILD_DEMO=1 时需要）
#    2.1 OpenCV 4（提供图像读写与基础处理）
sudo apt install -y libopencv-dev
#    2.2 gcc / g++ 8（提供 <filesystem> 支持，与系统默认 g++ 解耦）
sudo apt install -y gcc-8 g++-8
```

> 说明：
> - `build.sh` 统一使用 **Ninja** 生成器（`-G Ninja`），因此 `ninja` 是构建的硬依赖，不能只用 `make` 替代。
> - **OpenCV 仅参与 `ocr_demo`（真实 OCR）的编译**。缺失时 `build.sh` 会跳过 Demo 编译并提示，**不影响** `ocr_test` 与 ncnn 的构建（即基础验证仍可进行）。
> - `gcc-8` / `g++-8` 仅在 `BUILD_DEMO=1` 时由 CMake 显式指定（`-DCMAKE_CXX_COMPILER=g++-8`），基础构建使用系统默认 `g++`。
> - 交叉编译目标（aarch64 / arm）本机未安装对应架构 OpenCV 与 `gcc-8` 工具链，故 `BUILD_DEMO=1` 在该场景下被自动跳过。
>
> `build.sh` 默认使用 `PaddleOCR-ncnn-CPP`（源码与 v6 模型一体，支持 PP-OCRv3/4/5/6，适合交叉编译嵌入式部署）；`PaddleOCR-Lite-Document-main` 仅支持 PP-OCRv5 且路径硬编码，已移除。

---

## 四、编译方法

### 1. 本机编译（含 ncnn + 冒烟测试）

```bash
cd openocr
./build.sh                 # 等价于 ARCH=host
```

产物：`output/host/ocr_test`、`output/host/ncnn/`。

### 2. 交叉编译到 ARM

```bash
./build.sh aarch64-linux-gnu        # 交叉编译到 aarch64
# 或
ARCH=arm-linux-gnueabihf ./build.sh # 交叉编译到 armhf
```

产物：`output/aarch64-linux-gnu/ocr_test`、`output/aarch64-linux-gnu/ncnn/`，需拷贝到目标板运行。

### 3. 编译 OCR Demo（真实文字识别）

```bash
BUILD_DEMO=1 ./build.sh host
```

额外产物：`output/host/ocr_demo`、`output/host/ocr_config.json`。

### 4. 清理重建

```bash
./build.sh --clean       # 删除 source/ 与 output/ 后重新解压并编译
```

---

## 五、使用方法

### 1. 冒烟测试 `ocr_test`（验证库与工具链）

```bash
./output/host/ocr_test
# 输出示例：
#   ncnn version: 20260728 (1.0.20260728)
#   net created | num_threads=4 use_vulkan=0 lightmode=1
#   OCR smoke test OK
```

可选：传入模型做加载就绪检查（参数为 `.param` 与 `.bin`）：

```bash
./output/host/ocr_test <model>.param <model>.bin
```

### 2. 真实 OCR `ocr_demo`

`ocr_demo` 由顶层 `main.c` 经 `PaddleOCR-ncnn-CPP` 引擎编译而成，参数如下：

| 参数 | 含义 | 必填 |
|---|---|---|
| `-c <config.json>` | OCR 配置文件（含 det/cls/rec 模型绝对路径，由 `build.sh` 生成） | 是 |
| `-f <image.bmp>` | 对**单个**图片做识别 | 至少其一 |
| `-d <dir>` | 对**目录下所有图片**（`*.bmp/*.jpg/*.png/...`）批量识别 | 至少其一 |

`-f` 与 `-d` 可单独或同时使用。

```bash
# 单文件识别
./output/host/ocr_demo -c ./output/host/ocr_config.json -f ./test/testimage.bmp

# 目录批量识别（递归遍历目录下所有图片，按文件名排序）
./output/host/ocr_demo -c ./output/host/ocr_config.json -d ./test

# 混合：既识别单文件，也批量识别目录
./output/host/ocr_demo -c ./output/host/ocr_config.json -f ./test/testimage.bmp -d ./test
```

- `-c` 指定的 `ocr_config.json` 模型路径为绝对路径，由 `build.sh` 在 `BUILD_DEMO=1` 时生成，无需关心运行目录。
- 支持常见图片格式（BMP / JPG / PNG / TIFF / WEBP 等），不限于 BMP。
- 输出：每个图片标题下打印检测到的文本行（前缀为置信度分数）。
- 未指定 `-c` 或 `-f/-d` 时会打印用法并退出。

---

## 六、验证示例图片

工程内置示例图片 `test/testimage.bmp`，按以下步骤端到端验证：

```bash
BUILD_DEMO=1 ./build.sh host
# 单文件
./output/host/ocr_demo -c ./output/host/ocr_config.json -f ./test/testimage.bmp
# 或目录批量（遍历 test/ 下所有图片）
./output/host/ocr_demo -c ./output/host/ocr_config.json -d ./test
```

---

## 七、常见问题

- **`ocr_config.json` 找不到 / `fopen ... failed`**
  说明直接跑了 `ocr_test`（冒烟测试，不是 OCR 程序），且未用 `BUILD_DEMO=1` 构建。
  `ocr_config.json` 与 `ocr_demo` 只在 `BUILD_DEMO=1` 时生成。请按「六、验证示例图片」重新构建。

- **交叉编译产物在本机无法运行**
  `output/aarch64-linux-gnu/ocr_test` 是 ARM 架构 ELF，需拷贝到 aarch64 / arm 目标板执行；本机可用 `file output/aarch64-linux-gnu/ocr_test` 确认架构。

- **`BUILD_DEMO=1` 提示缺少 OpenCV / g++-8**
  Demo 依赖 OpenCV（`pkg-config --exists opencv4`）与 `g++-8`（`<filesystem>` 支持）。未安装时会自动跳过 Demo 编译并给出提示，不影响 `ocr_test` 构建。

- **ncnn 在 GCC 8.x 下编译报 AVX512 内建函数错误**
  `build.sh` 已默认加 `-DNCNN_AVX512=OFF` 规避，无需手动处理。

---

## 八、相关项目与参考

本工程基于以下上游项目（原 `readme.txt` 记录的上游链接，已合并于此）：

- **[PaddleOCR-ncnn-CPP](https://github.com/Avafly/PaddleOCR-ncnn-CPP)**（Avafly）：OCR 封装实现，支持 PP-OCRv3/4/5/6，本工程默认使用的封装。
- **[PaddleOCR-Lite-Document](https://github.com/Qengineering/PaddleOCR-Lite-Document)**（Qengineering）：面向树莓派的 ncnn 版 PaddleOCR（仅 PP-OCRv5），曾作为备选封装；因路径硬编码、不支持 PP-OCRv6 未采用。
- **[ncnn](https://github.com/Tencent/ncnn)**（Tencent）：轻量级高性能神经网络推理引擎，本工程的推理后端。