ContextQMD
Back to Paddleocr

文本图像矫正模块使用教程

docs/version3.x/module_usage/text_image_unwarping.md

3.5.015.4 KB
Original Source

文本图像矫正模块使用教程

一、概述

文本图像矫正的主要目的是针对图像进行几何变换，以纠正图像中的文档扭曲、倾斜、透视变形等问题，以供后续的文本识别进行更加准确。

二、支持模型列表

推理耗时仅包含模型推理耗时，不包含前后处理耗时。表格中的“常规模式”耗时对应本地 <code>paddle_static</code> 推理引擎。

<table> <thead> <tr> <th>模型</th><th>模型下载链接</th> <th>CER </th> <th>GPU推理耗时（ms） [常规模式 / 高性能模式]</th> <th>CPU推理耗时（ms） [常规模式 / 高性能模式]</th> <th>模型存储大小（MB）</th> <th>介绍</th> </tr> </thead> <tbody> <tr> <td>UVDoc</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/UVDoc_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/UVDoc_pretrained.pdparams">训练模型</a></td> <td>0.179</td> <td>19.05 / 19.05</td> <td>- / 869.82</td> <td>30.3</td> <td>高精度文本图像矫正模型</td> </tr> </tbody> </table>

<strong>测试环境说明:</strong>

<ul> <li><b>性能测试环境</b> <ul> <li><strong>测试数据集：</strong><a href="https://www3.cs.stonybrook.edu/~cvl/docunet.html">DocUNet benchmark</a>数据集。</li> <li><strong>硬件配置：</strong> <ul> <li>GPU：NVIDIA Tesla T4</li> <li>CPU：Intel Xeon Gold 6271C @ 2.60GHz</li> </ul> </li> <li><strong>软件环境：</strong> <ul> <li>Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6</li> <li>paddlepaddle-gpu 3.0.0 / paddleocr 3.0.3</li> </ul> </li> </ul> </li> <li><b>推理模式说明</b></li> </ul> <table border="1"> <thead> <tr> <th>模式</th> <th>GPU配置</th> <th>CPU配置</th> <th>加速技术组合</th> </tr> </thead> <tbody> <tr> <td>常规模式</td> <td>FP32精度 / 无TRT加速</td> <td>FP32精度 / 8线程</td> <td>PaddleInference</td> </tr> <tr> <td>高性能模式</td> <td>选择先验精度类型和加速策略的最优组合</td> <td>FP32精度 / 8线程</td> <td>选择先验最优后端（Paddle/OpenVINO/TRT等）</td> </tr> </tbody> </table>

三、快速开始

❗ 在快速开始前，请先安装 PaddleOCR 的 wheel 包，详细请参考 安装教程。

使用一行命令即可快速体验：

bash
paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg

上述示例默认使用 <code>paddle_static</code> 推理引擎，请先按照飞桨框架安装完成 PaddlePaddle 安装。

如果选择 transformers 作为推理引擎，请确保已配置 Transformers 环境，然后执行如下命令：

bash
# 使用 transformers 引擎进行推理
paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \
    --engine transformers

在大多数场景下，默认的 paddle_static 推理引擎通常具备更好的推理性能，建议优先使用。

<b>注：</b>PaddleOCR 官方模型默认从 HuggingFace 获取，如运行环境访问 HuggingFace 不便，可通过环境变量修改模型源为 BOS：PADDLE_PDX_MODEL_SOURCE="BOS"，未来将支持更多主流模型源；

您也可以将图像矫正的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载示例图片到本地。

python
from paddleocr import TextImageUnwarping
model = TextImageUnwarping(model_name="UVDoc")
output = model.predict("doc_test.jpg", batch_size=1)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

上述示例默认使用 <code>paddle_static</code> 推理引擎，请先按照飞桨框架安装完成 PaddlePaddle 安装。

如果选择 transformers 作为推理引擎，请确保已配置 Transformers 环境，然后执行如下代码：

python
from paddleocr import TextImageUnwarping
model = TextImageUnwarping(
    model_name="UVDoc",
    engine="transformers",
)
output = model.predict("doc_test.jpg", batch_size=1)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

在大多数场景下，默认的 paddle_static 推理引擎通常具备更好的推理性能，建议优先使用。

运行后，得到的结果为：

bash
{'res': {'input_path': 'doc_test.jpg', 'page_index': None, 'doctr_img': '...'}}

运行结果参数含义如下：

<ul> <li><code>input_path</code>：表示输入待矫正图像的路径</li> <li><code>doctr_img</code>：表示矫正后的图像结果，由于数据过多不便于直接print，所以此处用<code>...</code>替换，可以通过<code>res.save_to_img()</code>将预测结果保存为图片，通过<code>res.save_to_json()</code>将预测结果保存为json文件。</li> </ul>

可视化图片如下：

相关方法、参数等说明如下：

  • <code>TextImageUnwarping</code>实例化图像矫正模型（此处以<code>UVDoc</code>为例），具体说明如下：
<table> <thead> <tr> <th>参数</th> <th>参数说明</th> <th>参数类型</th> <th>默认值</th> </tr> </thead> <tbody> <tr> <td><code>model_name</code></td> <td><b>含义：</b>模型名称。

<b>说明：</b> 如果设置为<code>None</code>，则使用<code>UVDoc</code>。</td>

<td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>model_dir</code></td> <td><b>含义：</b>模型存储路径。</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>device</code></td> <td><b>含义：</b>用于推理的设备。

<b>说明：</b> <b>例如：</b><code>"cpu"</code>、<code>"gpu"</code>、<code>"npu"</code>、<code>"gpu:0"</code>、<code>"gpu:0,1"</code>。

如指定多个设备，将进行并行推理。

默认情况下，优先使用 GPU 0；若不可用则使用 CPU。

</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine</code></td> <td><b>含义：</b>推理引擎。 <b>说明：</b>支持 <code>None</code>（默认值）、<code>paddle</code>、<code>paddle_static</code>、<code>paddle_dynamic</code>、<code>transformers</code>。保持为默认值 <code>None</code> 时，本地推理默认使用 <code>paddle_static</code> 引擎。详细说明、取值、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine_config</code></td> <td><b>含义：</b>推理引擎配置。 <b>说明：</b>推荐与 <code>engine</code> 搭配使用。详细字段、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。</td> <td><code>dict|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>enable_hpi</code></td> <td><b>含义：</b>是否启用高性能推理。</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>use_tensorrt</code></td> <td><b>含义：</b>是否启用 Paddle Inference 的 TensorRT 子图引擎。</br> <b>说明：</b> 如果模型不支持通过 TensorRT 加速，即使设置了此标志，也不会使用加速。

对于 CUDA 11.8 版本的飞桨，兼容的 TensorRT 版本为 8.x（x>=6），建议安装 TensorRT 8.6.1.6。

</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>precision</code></td> <td><b>含义：</b>当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。

<b>说明：</b> <b>可选项：</b><code>"fp32"</code>、<code>"fp16"</code>。</td>

<td><code>str</code></td> <td><code>"fp32"</code></td> </tr> <tr> <td><code>enable_mkldnn</code></td> <td> <b>含义：</b>是否启用 MKL-DNN 加速推理。

<b>说明：</b> 如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速，即使设置了此标志，也不会使用加速。

</td> <td><code>bool</code></td> <td><code>True</code></td> </tr> <tr> <td><code>mkldnn_cache_capacity</code></td> <td> <b>含义：</b>MKL-DNN 缓存容量。 </td> <td><code>int</code></td> <td><code>10</code></td> </tr> <tr> <td><code>cpu_threads</code></td> <td><b>含义：</b>在 CPU 上推理时使用的线程数量。</td> <td><code>int</code></td> <td><code>10</code></td> </tr> </tbody> </table>
  • 调用图像矫正模型的 <code>predict()</code> 方法进行推理预测，该方法会返回一个结果列表。另外，本模块还提供了 <code>predict_iter()</code> 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 <code>predict_iter()</code> 返回的是一个 <code>generator</code>，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。<code>predict()</code> 方法参数有 <code>input</code> 和 <code>batch_size</code>，具体说明如下：
<table> <thead> <tr> <th>参数</th> <th>参数说明</th> <th>参数类型</th> <th>默认值</th> </tr> </thead> <tr> <td><code>input</code></td> <td><b>含义：</b>待预测数据，支持多种输入类型，必填。

<b>说明：</b>

<ul> <li><b>Python Var</b>：如 <code>numpy.ndarray</code> 表示的图像数据</li> <li><b>str</b>：如图像文件或者PDF文件的本地路径：<code>/root/data/img.jpg</code>；<b>如URL链接</b>，如图像文件或PDF文件的网络URL：<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/img_rot180_demo.jpg">示例</a>；<b>如本地目录</b>，该目录下需包含待预测图像，如本地路径：<code>/root/data/</code>(当前不支持目录中包含PDF文件的预测，PDF文件需要指定到具体文件路径)</li> <li><b>list</b>：列表元素需为上述类型数据，如<code>[numpy.ndarray, numpy.ndarray]</code>，<code>["/root/data/img1.jpg", "/root/data/img2.jpg"]</code>，<code>["/root/data1", "/root/data2"]</code></li> </ul> </td> <td><code>Python Var|str|list</code></td> <td></td> </tr> <tr> <td><code>batch_size</code></td> <td><b>含义：</b>批大小

<b>说明：</b> 可设置为任意正整数。</td>

<td><code>int</code></td> <td>1</td> </tr> </table>
  • 对预测结果进行处理，每个样本的预测结果均为对应的Result对象，且支持打印、保存为图片、保存为<code>json</code>文件的操作:
<table> <thead> <tr> <th>方法</th> <th>方法说明</th> <th>参数</th> <th>参数类型</th> <th>参数说明</th> <th>默认值</th> </tr> </thead> <tr> <td rowspan = "3"><code>print()</code></td> <td rowspan = "3">打印结果到终端</td> <td><code>format_json</code></td> <td><code>bool</code></td> <td>是否对输出内容进行使用 <code>JSON</code> 缩进格式化</td> <td><code>True</code></td> </tr> <tr> <td><code>indent</code></td> <td><code>int</code></td> <td>指定缩进级别，以美化输出的 <code>JSON</code> 数据，使其更具可读性，仅当 <code>format_json</code> 为 <code>True</code> 时有效</td> <td>4</td> </tr> <tr> <td><code>ensure_ascii</code></td> <td><code>bool</code></td> <td>控制是否将非 <code>ASCII</code> 字符转义为 <code>Unicode</code>。设置为 <code>True</code> 时，所有非 <code>ASCII</code> 字符将被转义；<code>False</code> 则保留原始字符，仅当<code>format_json</code>为<code>True</code>时有效</td> <td><code>False</code></td> </tr> <tr> <td rowspan = "3"><code>save_to_json()</code></td> <td rowspan = "3">将结果保存为json格式的文件</td> <td><code>save_path</code></td> <td><code>str</code></td> <td>保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致</td> <td>无</td> </tr> <tr> <td><code>indent</code></td> <td><code>int</code></td> <td>指定缩进级别，以美化输出的 <code>JSON</code> 数据，使其更具可读性，仅当 <code>format_json</code> 为 <code>True</code> 时有效</td> <td>4</td> </tr> <tr> <td><code>ensure_ascii</code></td> <td><code>bool</code></td> <td>控制是否将非 <code>ASCII</code> 字符转义为 <code>Unicode</code>。设置为 <code>True</code> 时，所有非 <code>ASCII</code> 字符将被转义；<code>False</code> 则保留原始字符，仅当<code>format_json</code>为<code>True</code>时有效</td> <td><code>False</code></td> </tr> <tr> <td><code>save_to_img()</code></td> <td>将结果保存为图像格式的文件</td> <td><code>save_path</code></td> <td><code>str</code></td> <td>保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致</td> <td>无</td> </tr> </table>
  • 此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：
<table> <thead> <tr> <th>属性</th> <th>属性说明</th> </tr> </thead> <tr> <td rowspan = "1"><code>json</code></td> <td rowspan = "1">获取预测的<code>json</code>格式的结果</td> </tr> <tr> <td rowspan = "1"><code>img</code></td> <td rowspan = "1">获取格式为<code>dict</code>的可视化图像</td> </tr> </table>

四、二次开发

当前模块暂时不支持微调训练，仅支持推理集成。关于该模块的微调训练，计划在未来支持。

五、推理引擎

关于推理引擎的详细说明、取值、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。

5.1 速度数据

<table border="1"> <thead> <tr> <th>model</th> <th>engine</th> <th>Preprocessing (ms)</th> <th>Inference (ms)</th> <th>PostProcessing (ms)</th> <th>End-to-End (ms)</th> </tr> </thead> <tbody> <tr> <td rowspan="3">UVDoc</td> <td>paddle_static</td> <td>14.96</td> <td>18.60</td> <td>1.93</td> <td>36.66</td> </tr> <tr> <td>paddle_dynamic</td> <td>10.90</td> <td>27.59</td> <td>1.96</td> <td>40.94</td> </tr> <tr> <td>transformers</td> <td>13.54</td> <td>6.74</td> <td>0.91</td> <td>33.07</td> </tr> </tbody> </table>

<strong>测试环境说明:</strong>

<ul> <li><strong>测试数据：</strong>[示例图片](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg)</li> <li><strong>硬件配置：</strong> <ul> <li>GPU：NVIDIA A100 40G</li> <li>CPU：Intel(R) Xeon(R) Gold 6248 CPU @ 2.50GHz</li> </ul> </li> <li><strong>软件环境：</strong> <ul> <li>Ubuntu 22.04 / CUDA 12.6 / cuDNN 9.5</li> <li>paddlepaddle-gpu 3.2.1 / paddleocr 3.5 / transformers 5.4.0 / torch 2.10</li> </ul> </li> </ul>

六、FAQ