Text Image Rectification Module Usage Tutorial

1. Overview

The primary purpose of text image rectification is to perform geometric transformations on images to correct distortions, inclinations, perspective deformations, etc., in the document images for more accurate subsequent text recognition.

2. Supported Model List

The inference time only includes the model inference time and does not include the time for pre- or post-processing. The "Normal Mode" values correspond to the local <code>paddle_static</code> inference engine.

<table> <thead> <tr> <th>Model</th><th>Model Download Link</th> <th>CER</th> <th>GPU Inference Time (ms) [Normal Mode / High-Performance Mode]</th> <th>CPU Inference Time (ms) [Normal Mode / High-Performance Mode]</th> <th>Model Storage Size (MB)</th> <th>Description</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">Inference Model</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/UVDoc_pretrained.pdparams">Training Model</a></td> <td>0.179</td> <td>19.05 / 19.05</td> <td>- / 869.82</td> <td>30.3</td> <td>High-accuracy text image rectification model</td> </tr> </tbody> </table>

<strong>Test Environment Description:</strong>

<ul> <li><b>Performance Test Environment</b> <ul> <li><strong>Test Dataset:</strong> <a href="https://www3.cs.stonybrook.edu/~cvl/docunet.html">DocUNet benchmark</a> dataset.</li> <li><strong>Hardware Configuration:</strong> <ul> <li>GPU: NVIDIA Tesla T4</li> <li>CPU: Intel Xeon Gold 6271C @ 2.60GHz</li> </ul> </li> <li><strong>Software Environment:</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>Inference Mode Explanation</b></li> </ul> <table border="1"> <thead> <tr> <th>Mode</th> <th>GPU Configuration</th> <th>CPU Configuration</th> <th>Acceleration Technology Combination</th> </tr> </thead> <tbody> <tr> <td>Regular Mode</td> <td>FP32 Precision / No TRT Acceleration</td> <td>FP32 Precision / 8 Threads</td> <td>PaddleInference</td> </tr> <tr> <td>High-Performance Mode</td> <td>Choose the optimal combination of prior precision type and acceleration strategy</td> <td>FP32 Precision / 8 Threads</td> <td>Choose the optimal prior backend (Paddle/OpenVINO/TRT, etc.)</td> </tr> </tbody> </table>

3. Quick Start

❗ Before starting quickly, please first install the PaddleOCR wheel package. For details, please refer to the installation tutorial.

You can quickly experience it with one command:

The example above uses the <code>paddle_static</code> inference engine by default. To run it, first install PaddlePaddle by following PaddlePaddle Framework Installation.

If you choose transformers as the inference engine, make sure the Transformers environment is configured, and then run the following command:

In most scenarios, the default paddle_static inference engine delivers better inference performance and is the recommended first choice.

<b>Note: </b>The official models would be download from HuggingFace by default. If can't access to HuggingFace, please set the environment variable PADDLE_PDX_MODEL_SOURCE="BOS" to change the model source to BOS. In the future, more model sources will be supported.

You can also integrate the model inference from the image rectification module into your project. Before running the following code, please download the sample image locally.

The example above uses the <code>paddle_static</code> inference engine by default. To run it, first install PaddlePaddle by following PaddlePaddle Framework Installation.

If you choose transformers as the inference engine, make sure the Transformers environment is configured, and then run the following code:

In most scenarios, the default paddle_static inference engine delivers better inference performance and is the recommended first choice.

After running, the result obtained is:

The meanings of the parameters in the result are as follows:

<ul> <li><code>input_path</code>：Indicates the path of the image to be rectified</li> <li><code>doctr_img</code>：Indicates the rectified image result. Due to the large amount of data, it is not convenient to print directly, so it is replaced here with<code>...</code>.You can use<code>res.save_to_img()</code>to save the prediction result as an image, and <code>res.save_to_json()</code> to save the prediction result as a json file.</li> </ul>

The visualized image is as follows:

The relevant methods, parameters, etc., are described as follows:

• <code>TextImageUnwarping</code> instantiates the image rectification model (taking <code>UVDoc</code> as an example here), with specific explanations as follows:

<table> <thead> <tr> <th>Parameter</th> <th>Description</th> <th>Type</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>model_name</code></td> <td><b>Meaning:</b> Name of the model</td> <td><code>str</code></td> <td><code>None</code></td> </tr> <tr> <td><code>model_dir</code></td> <td><b>Meaning:</b> Model storage path</td> <td><code>str</code></td> <td><code>None</code></td> </tr> <tr> <td><code>device</code></td> <td><b>Meaning:</b> Device(s) to use for inference.

<b>Description:</b> <b>Examples:</b> <code>cpu</code>, <code>gpu</code>, <code>npu</code>, <code>gpu:0</code>, <code>gpu:0,1</code>.

If multiple devices are specified, inference will be performed in parallel. Note that parallel inference is not always supported.

By default, GPU 0 will be used if available; otherwise, the CPU will be used.

</td> <td><code>str</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine</code></td> <td><b>Meaning:</b> Inference engine. <b>Description:</b> Supports <code>None</code> (the default), <code>paddle</code>, <code>paddle_static</code>, <code>paddle_dynamic</code>, and <code>transformers</code>. When left as <code>None</code>, local inference uses the <code>paddle_static</code> engine by default. For detailed descriptions, supported values, compatibility rules, and examples, see <a href="../inference_engine.en.md">Inference Engine and Configuration</a>.</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine_config</code></td> <td><b>Meaning:</b> Inference-engine configuration. <b>Description:</b> Recommended together with <code>engine</code>. For supported fields, compatibility rules, and examples, see <a href="../inference_engine.en.md">Inference Engine and Configuration</a>.</td> <td><code>dict|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>enable_hpi</code></td> <td><b>Meaning:</b> Whether to use the high performance inference.</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>use_tensorrt</code></td> <td><b>Meaning:</b> Whether to use the Paddle Inference TensorRT subgraph engine.

<b>Description:</b> If the model does not support acceleration through TensorRT, setting this flag will not enable acceleration.

For Paddle with CUDA version 11.8, the compatible TensorRT version is 8.x (x>=6), and it is recommended to install 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>Meaning:</b>Precision for TensorRT when using the Paddle Inference TensorRT subgraph engine.

<b>Description:</b> <b>Options:</b> <code>"fp32"</code>, <code>"fp16"</code>, etc.</td>

<td><code>str</code></td> <td><code>"fp32"</code></td> </tr> <tr> <td><code>enable_mkldnn</code></td> <td> <b>Meaning:</b> Whether to enable MKL-DNN acceleration for inference.

<b>Description:</b> If MKL-DNN is unavailable or the model does not support it, acceleration will not be used even if this flag is set.

</td> <td><code>bool</code></td> <td><code>True</code></td> </tr> <tr> <td><code>mkldnn_cache_capacity</code></td> <td> <b>Meaning:</b>MKL-DNN cache capacity. </td> <td><code>int</code></td> <td><code>10</code></td> </tr> <tr> <td><code>cpu_threads</code></td> <td><b>Meaning:</b> Number of threads to use for inference on CPUs.</td> <td><code>int</code></td> <td><code>10</code></td> </tr> </tbody> </table>

• Call the <code>predict()</code> method of the image rectification model for inference prediction. This method will return a result list. Additionally, this module also provides a <code>predict_iter()</code> method. Both methods are consistent in terms of parameter acceptance and result return. The difference is that <code>predict_iter()</code> returns a <code>generator</code>, which can process and obtain prediction results step by step, suitable for handling large datasets or scenarios where memory saving is desired. You can choose to use either of these methods according to your actual needs. The <code>predict()</code> method has parameters <code>input</code> and <code>batch_size</code>, with specific explanations as follows:

<table> <thead> <tr> <th>Parameter</th> <th>Description</th> <th>Type</th> <th>Default</th> </tr> </thead> <tr> <td><code>input</code></td> <td><b>Meaning:</b> Input data to be predicted. Required.

<b>Description:</b> Supports multiple input types:

<ul> <li><b>Python Var</b>: e.g., <code>numpy.ndarray</code> representing image data</li> <li><b>str</b>: <ul> <li>Local image or PDF file path: <code>/root/data/img.jpg</code>;</li> <li><b>URL</b> of image or PDF file: e.g., <a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_doc_preprocessor_002.png">example</a>;</li> <li><b>Local directory</b>: directory containing images for prediction, e.g., <code>/root/data/</code> (Note: directories containing PDF files are not supported; PDFs must be specified by exact file path)</li> </ul> </li> <li><b>list</b>: Elements must be of the above types, e.g., <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>Meaning:</b> Batch size

<b>Description:</b> Positive integer.</td>

<td><code>int</code></td> <td>1</td> </tr> </table>

• Process the prediction results. The prediction result for each sample is a corresponding Result object, which supports printing, saving as an image, and saving as a <code>json</code> file:

<table> <thead> <tr> <th>Method</th> <th>Description</th> <th>Parameter</th> <th>Type</th> <th>Parameter Description</th> <th>Default Value</th> </tr> </thead> <tr> <td rowspan = "3"><code>print()</code></td> <td rowspan = "3">Print result to terminal</td> <td><code>format_json</code></td> <td><code>bool</code></td> <td>Whether to format the output content using <code>JSON</code> indentation</td> <td><code>True</code></td> </tr> <tr> <td><code>indent</code></td> <td><code>int</code></td> <td>Specifies the indentation level to beautify the output <code>JSON</code> data, making it more readable, effective only when <code>format_json</code> is <code>True</code></td> <td>4</td> </tr> <tr> <td><code>ensure_ascii</code></td> <td><code>bool</code></td> <td>Controls whether to escape non-<code>ASCII</code> characters into <code>Unicode</code>. When set to <code>True</code>, all non-<code>ASCII</code> characters will be escaped; <code>False</code> will retain the original characters, effective only when <code>format_json</code> is <code>True</code></td> <td><code>False</code></td> </tr> <tr> <td rowspan = "3"><code>save_to_json()</code></td> <td rowspan = "3">Save the result as a json format file</td> <td><code>save_path</code></td> <td><code>str</code></td> <td>The path to save the file. When specified as a directory, the saved file is named consistent with the input file type.</td> <td>None</td> </tr> <tr> <td><code>indent</code></td> <td><code>int</code></td> <td>Specifies the indentation level to beautify the output <code>JSON</code> data, making it more readable, effective only when <code>format_json</code> is <code>True</code></td> <td>4</td> </tr> <tr> <td><code>ensure_ascii</code></td> <td><code>bool</code></td> <td>Controls whether to escape non-<code>ASCII</code> characters into <code>Unicode</code>. When set to <code>True</code>, all non-<code>ASCII</code> characters will be escaped; <code>False</code> will retain the original characters, effective only when <code>format_json</code> is <code>True</code></td> <td><code>False</code></td> </tr> <tr> <td><code>save_to_img()</code></td> <td>Save the result as an image format file</td> <td><code>save_path</code></td> <td><code>str</code></td> <td>The path to save the file. When specified as a directory, the saved file is named consistent with the input file type.</td> <td>None</td> </tr> </table>

• Additionally, the result can be obtained through attributes that provide the visualized images with results and the prediction results, as follows:

<table> <thead> <tr> <th>Attribute</th> <th>Description</th> </tr> </thead> <tr> <td rowspan = "1"><code>json</code></td> <td rowspan = "1">Get the prediction result in <code>json</code> format</td> </tr> <tr> <td rowspan = "1"><code>img</code></td> <td rowspan = "1">Get the visualized image in <code>dict</code> format</td> </tr> </table>

4. Secondary Development

The current module does not support fine-tuning training and only supports inference integration. Concerning fine-tuning training for this module, there are plans to support it in the future.

5. Inference Engine

For detailed descriptions, values, compatibility rules, and examples of the inference engine, please refer to <a href="../inference_engine.en.md">Inference Engine and Configuration Description</a>.

5.1 Speed Data

<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>Test Environment Description:</strong>

<ul> <li><strong>Test Data:</strong> [Sample Image](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg)</li> <li><strong>Hardware Configuration:</strong> <ul> <li>GPU: NVIDIA A100 40G</li> <li>CPU: Intel(R) Xeon(R) Gold 6248 CPU @ 2.50GHz</li> </ul> </li> <li><strong>Software Environment:</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>

6. FAQ