# 通用 OCR 产线 C++ 部署 - Windows

- [1. 环境准备](#1)
    - [1.1 编译 OpenCV 库](#11-编译-opencv-库)
    - [1.2 编译 Paddle Inference](#12-编译-paddle-inference)
- [2. 开始运行](#2-开始运行)
    - [2.1 编译预测 demo](#21-编译预测-demo)
    - [2.2 准备模型](#22-准备模型)
    - [2.3 运行预测 demo](#23-运行预测-demo)
    - [2.4 C++ API 集成](#24-c-api-集成)
- [3. 额外功能](#3-额外功能)
    - [3.1 可视化文本识别结果](#31-可视化文本识别结果)  

## 1. 准备环境

- **本章节编译运行时用到的源代码位于 [PaddleOCR/deploy/cpp_infer](https://github.com/PaddlePaddle/PaddleOCR/tree/main/deploy/cpp_infer) 目录下。**

- Windows 环境：
    - visual studio 2022
    - cmake 3.29

### 1.1 编译 OpenCV 库

可以选择直接下载 OpenCV 官网提供的预编译包或者手动编译源码，下文分别进行具体说明。

#### 1.1.1 直接下载预编译包（推荐）

在 [OpenCV 官网](https://opencv.org/releases/) 下载适用于 Windows 的 .exe 预编译包，运行后自动解压出 OpenCV 的预编译库和相关文件夹。

以 opencv 4.7.0为例，[opencv-4.7.0-windows.exe下载地址](https://github.com/opencv/opencv/releases/download/4.7.0/opencv-4.7.0-windows.exe)下载解压后，会在当前的文件夹中生成 `opencv/` 的子文件夹，其中 `opencv/build` 为预编译库，在后续编译通用 OCR 产线 demo 时，将作为 OpenCV 安装库的路径使用。


#### 1.1.1 源码编译

首先需要下载 OpenCV 源码，以 opencv 4.7.0为例，[opencv 4.7.0下载地址](https://paddle-model-ecology.bj.bcebos.com/paddlex/cpp/libs/opencv-4.7.0.tgz)，下载解压后，会在当前的文件夹中生成 `opencv-4.7.0/` 的子文件夹。

- Step 1：构建 Visual Studio 项目

在 cmake-gui 中指定 `opencv-4.7.0` 源码路径，并指定编译生成目录为 `opencv-4.7.0/build`，默认安装路径为 `opencv-4.7.0/build/install`，此安装路径用于后续编译 demo。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_step1.png"/>

- Step 2：选择目标平台

选择目标平台为 x64 ，然后点击 finish。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_step2.png"/>

- Step 3 ：生成 Visual Studio 项目

依次点击 Configure  ->  Generate  ->  Open in Project，将进入 Visual Studio 2022 编译界面。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_step3.png"/>

- Step 4：执行编译

点击开始生成解决方案，完成编译后，点击 INSTALL，运行后完成安装。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_step4.png"/>

### 1.2 编译 Paddle Inference

可以选择直接下载预编译包或者手动编译源码。

#### 1.2.1 直接下载预编译包（推荐）

[Paddle Inference 官网](https://www.paddlepaddle.org.cn/inference/v3.0/guides/install/download_lib.html#windows) 上提供了 Windows 预测库，可以在官网查看并选择合适的预编译包。

下载后解压，会在当前的文件夹中生成 `paddle_inference/` 的子文件夹。目录结构为：

```
paddle_inference
├── paddle # paddle核心库和头文件
├── third_party # 第三方依赖库和头文件
└── version.txt # 版本和编译信息
```

#### 1.2.2 源码编译预测库

可以选择通过源码自行编译预测库，源码编译可灵活配置各类功能和依赖，以适应不同的硬件和软件环境。详细步骤请参考 [Windows 下源码编译](https://www.paddlepaddle.org.cn/inference/v3.0/guides/install/compile/source_compile_under_Windows.html)。

## 2. 开始运行

### 2.1 编译预测 demo

在编译预测 demo 前，请确保您已经按照 1.1 和 1.2 节编译好 OpenCV 库和 Paddle Inference 预测库。

编译步骤如下：

- Step 1：构建 Visual Studio 项目

在 cmake-gui 中指定 `deploy\cpp_infer` 源码路径，并指定编译生成目录为 `deploy\cpp_infer\build`，以下编译步骤说明均以 `D:\PaddleOCR\deploy\cpp_infer` 作为示例源码路径。第一次点击 Configure 报错是正常的，在后续弹出的编译选项中，添加 OpenCV 的安装路径和 Paddle Inference 预测库路径。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/windows_step1.png"/>

- Step 2：选择目标平台

选择目标平台为 x64 ，然后点击 finish。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/windows_step2.png"/>

- Step 3：配置 cmake 编译选项

    - OPENCV_DIR：填写 OpenCV 安装路径。
    - OpenCV_DIR：同 OPENCV_DIR。
    - PADDLE_LIB：paddle_inference 路径。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/windows_step3.png"/>

- Step 4：生成 Visual Studio 项目

依次点击 Configure  ->  Generate  ->  Open in Project，将进入 Visual Studio 2022 编译界面。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/windows_step4.png"/>

- Step 5：执行编译

在开始生成解决方案之前，执行下面步骤：

1. 将 `Debug` 改为 `Release`。
2. 下载[dirent.h](https://paddleocr.bj.bcebos.com/deploy/cpp_infer/cpp_files/dirent.h)，并拷贝到  Visual Studio 的 include 文件夹下，如 `C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\VS\include`。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/windows_step5.png"/>

- Step 6：编译结果

编译完成后，可执行文件位于 `deploy/cpp_infer/build/Release/ppocr.exe` 。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/windows_step6.png"/>

- Step 7：demo 预测

运行之前，将下面文件拷贝到 `deploy\cpp_infer\build\Release\` 文件夹下。

1. `paddle_inference\paddle\lib\paddle_inference.dll`
2. `paddle_inference\paddle\lib\common.dll`
3. `deploy\cpp_infer\build\bin\Release\abseil_dll.dll`
4. `deploy\cpp_infer\build\third_party\clipper_ver6.4.2\cpp\Release\polyclipping.dll`
5. `opencv-4.7.0\build\install\bin\opencv_world470.dll`

### 2.2 准备模型

该步骤参考 [通用 OCR 产线 C++ 部署 - Linux —— 2.2 准备模型](./OCR.md#22-准备模型)小节。

### 2.3 运行预测 demo

参考 [通用 OCR 产线 C++ 部署 - Linux —— 2.3 运行预测 demo](./OCR.md#23-运行预测-demo)小节。

### 2.4 C++ API 集成

参考 [通用 OCR 产线 C++ 部署 - Linux —— 2.4 C++ API 集成](./OCR.md#24-c-api-集成)小节。

## 3. 额外功能

### 3.1 可视化文本识别结果

我们需要 FreeType 去完成字体的渲染，所以需要自己编译包含 FreeType 的 OpenCV，注意仅支持 OpenCV 4.x 版本。
FreeType 属于 opencv_contrib 模块，需要下载 OpenvCV 和 opencv_contrib 源码，注意版本一致。以下以 opencv-4.7.0 为例，[opencv-4.7.0 下载](https://paddle-model-ecology.bj.bcebos.com/paddlex/cpp/libs/opencv-4.7.0.tgz)，[opencv_contrib-4.7.0 下载](https://paddle-model-ecology.bj.bcebos.com/paddlex/cpp/libs/opencv_contrib-4.7.0.tgz)。

- Step 1：编译 freetype 和 harfbuzz

    - [下载pkg-config](https://sourceforge.net/projects/pkgconfiglite/)
    - [下载freetype2](https://download.savannah.gnu.org/releases/freetype/)
    - [下载harfbuzz](https://github.com/harfbuzz/harfbuzz)

解压 pkg-config 后添加其 bin 目录到系统 PATH 环境变量。
freetype 编译，需手动更改其安装路径，示例如下：

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_freetype_step1.png"/>

再次 Configure， 然后点击 Generate， 完成后，点击 Open Project 按钮，打开 VS ，编译。
VS里ALL_BUILD, INSTALL. 会在构建文件夹的 install 目录下生成所需的 include 和 lib 文件。

然后将 freetype 安装路径添加至系统环境变量。

harfbuzz 编译，需手动更改其安装路径，示例如下：

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_freetype_step2.png"/>

设置好上面两项后，再次点击 Configure 按钮，选择 Advanced Options ，填写 freetype 安装路径。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_freetype_step3.png"/>

然后将 harfbuzz 安装路径添加至系统环境变量。

- Step 2：修改 opencv_contrib-4.7.0 下的 `modules/freetype/CMakeLists.txt`

```bash
set(the_description "FreeType module. It enables to draw strings with outlines and mono-bitmaps/gray-bitmaps.")
 
find_package(Freetype REQUIRED)
 
# find_package(HarfBuzz) is not included in cmake
set(HARFBUZZ_DIR "$ENV{HARFBUZZ_DIR}" CACHE PATH "HarfBuzz directory")
find_path(HARFBUZZ_INCLUDE_DIRS
    NAMES hb-ft.h PATH_SUFFIXES harfbuzz
    HINTS ${HARFBUZZ_DIR}/include)
find_library(HARFBUZZ_LIBRARIES
    NAMES harfbuzz
    HINTS ${HARFBUZZ_DIR}/lib)
find_package_handle_standard_args(HARFBUZZ
    DEFAULT_MSG HARFBUZZ_LIBRARIES HARFBUZZ_INCLUDE_DIRS)
 
if(NOT FREETYPE_FOUND)
  message(STATUS "freetype2:   NO")
else()
  message(STATUS "freetype2:   YES")
endif()
 
if(NOT HARFBUZZ_FOUND)
  message(STATUS "harfbuzz:   NO")
else()
  message(STATUS "harfbuzz:   YES")
endif()
 
if(FREETYPE_FOUND AND HARFBUZZ_FOUND)
  ocv_define_module(freetype opencv_core opencv_imgproc PRIVATE_REQUIRED ${FREETYPE_LIBRARIES} ${HARFBUZZ_LIBRARIES} WRAP python)
  ocv_include_directories(${FREETYPE_INCLUDE_DIRS} ${HARFBUZZ_INCLUDE_DIRS})
else()
  ocv_module_disable(freetype)
endif()
```

- Step 3 编译 OpenCV

1. 设置 `OPENCV_EXTRA_MODULES_PATH` 项，填入 opencv-contrib-4.7.0 的目录下的 modules 目录。
2. 勾选 `WITH_FREETYPE` 项，必须先编译 freetype 和 harfbuzz。
3. 如果需要支持 freetype，则需要在 Opencv 的 Cmake 配置中加入 freetype 的相关路径。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_freetype_step4.png"/>

搜索 harfbuzz，加入 harfbuzz，加入 的相关路径。

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/opencv_freetype_step5.png"/>

完成后，再次在 Cmake 界面，点击 configure， 确定没报错后，点击 Generate，最后点击 Open Project，打开 Visual studio，找到 ALL_BUILD 右键Build， 等待编译完成后， 找到 INSTALL 右键 Build。

注意：如果完成编译包含 FreeType 的 OpenCV，在编译通用 OCR 产线 demo 时，需要在 2.1节 Step 3 配置编译选项时勾选 `USE_FREETYPE` 开启文字渲染功能，并且在运行demo时显示指定 `--vis_font_dir your_ttf_path` 提供相应ttf字体文件路径。

编译包含 FreeType 的 OpenCV 生成 demo 可视化文本识别结果：

<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/paddleocr/deployment/cpp/ocr_res_with_freetype.png"/>
