Skip to content

Commit 97b454b

Browse files
BluebirdStoryBluebirdStory
authored
add docs for text_image_unwarping (#15177)
1 parent cffce64 commit 97b454b

File tree

2 files changed

+290
-0
lines changed

2 files changed

+290
-0
lines changed

‎docs/version3.x/module_usage/text_image_unwarping.en.md

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
---
2+
3+
comments: true
4+
5+
---
6+
7+
# Text Image Rectification Module Usage Tutorial
8+
9+
## 1. Overview
10+
11+
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.
12+
13+
## 2. Supported Model List
14+
15+
<table>
16+
<thead>
17+
<tr>
18+
<th>Model</th><th>Model Download Link</th>
19+
<th>CER</th>
20+
<th>Model Storage Size (M)</th>
21+
<th>Description</th>
22+
</tr>
23+
</thead>
24+
<tbody>
25+
<tr>
26+
<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>
27+
<td>0.179</td>
28+
<td>30.3 M</td>
29+
<td>High-accuracy text image rectification model</td>
30+
</tr>
31+
</tbody>
32+
</table>
33+
34+
<strong>Test Environment Description:</strong>
35+
36+
<ul>
37+
<li><b>Performance Test Environment</b>
38+
<ul>
39+
<li><strong>Test Dataset:</strong> <a href="https://www3.cs.stonybrook.edu/~cvl/docunet.html">DocUNet benchmark</a> dataset.</li>
40+
<li><strong>Hardware Configuration:</strong>
41+
<ul>
42+
<li>GPU: NVIDIA Tesla T4</li>
43+
<li>CPU: Intel Xeon Gold 6271C @ 2.60GHz</li>
44+
<li>Other Environment: Ubuntu 20.04 / cuDNN 8.6 / TensorRT 8.5.2.2</li>
45+
</ul>
46+
</li>
47+
</ul>
48+
</li>
49+
<li><b>Inference Mode Explanation</b></li>
50+
</ul>
51+
52+
<table border="1">
53+
<thead>
54+
<tr>
55+
<th>Mode</th>
56+
<th>GPU Configuration</th>
57+
<th>CPU Configuration</th>
58+
<th>Acceleration Technology Combination</th>
59+
</tr>
60+
</thead>
61+
<tbody>
62+
<tr>
63+
<td>Regular Mode</td>
64+
<td>FP32 Precision / No TRT Acceleration</td>
65+
<td>FP32 Precision / 8 Threads</td>
66+
<td>PaddleInference</td>
67+
</tr>
68+
<tr>
69+
<td>High-Performance Mode</td>
70+
<td>Choose the optimal combination of prior precision type and acceleration strategy</td>
71+
<td>FP32 Precision / 8 Threads</td>
72+
<td>Choose the optimal prior backend (Paddle/OpenVINO/TRT, etc.)</td>
73+
</tr>
74+
</tbody>
75+
</table>
76+
77+
## 3. Quick Start
78+
79+
> ❗ Before starting quickly, please first install the PaddleOCR wheel package. For details, please refer to the [installation tutorial](../ppocr/installation.md).
80+
81+
You can quickly experience it with one command:
82+
83+
```bash
84+
paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg
85+
```
86+
87+
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](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg) locally.
88+
89+
```python
90+
from paddleocr import TextImageUnwarping
91+
model = TextImageUnwarping(model_name="UVDoc")
92+
output = model.predict("doc_test.jpg", batch_size=1)
93+
for res in output:
94+
res.print()
95+
res.save_to_img(save_path="./output/")
96+
res.save_to_json(save_path="./output/res.json")
97+
```
98+
99+
After running, the result obtained is:
100+
101+
```bash
102+
{'res': {'input_path': 'doc_test.jpg', 'page_index': None, 'doctr_img': '...'}}
103+
```
104+
105+
The meanings of the parameters in the result are as follows:
106+
- `input_path`: Indicates the path of the image to be rectified
107+
- `doctr_img`: 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 `...`. You can use `res.save_to_img()` to save the prediction result as an image, and `res.save_to_json()` to save the prediction result as a json file.
108+
109+
The visualized image is as follows:
110+
111+
<img src="https://raw.githubusercontent.com/cuicheng01/PaddleX_doc_images/refs/heads/main/images/modules/image_unwarp/doc_test_res.jpg">
112+
113+
The relevant methods, parameters, etc., are described as follows:
114+
115+
* `TextImageUnwarping` instantiates the image rectification model (taking `UVDoc` as an example here), with specific explanations as follows:
116+
<table>
117+
<thead>
118+
<tr>
119+
<th>Parameter</th>
120+
<th>Description</th>
121+
<th>Type</th>
122+
<th>Options</th>
123+
<th>Default Value</th>
124+
</tr>
125+
</thead>
126+
<tr>
127+
<td><code>model_name</code></td>
128+
<td>Model Name</td>
129+
<td><code>str</code></td>
130+
<td>All model names supported by PaddleX</td>
131+
<td>None</td>
132+
</tr>
133+
<tr>
134+
<td><code>model_dir</code></td>
135+
<td>Model Storage Path</td>
136+
<td><code>str</code></td>
137+
<td>None</td>
138+
<td>None</td>
139+
</tr>
140+
<tr>
141+
<td><code>device</code></td>
142+
<td>Model Inference Device</td>
143+
<td><code>str</code></td>
144+
<td>Supports specifying specific GPU card numbers, such as “gpu:0”, specific hardware card numbers, such as “npu:0”, CPU as “cpu”.</td>
145+
<td><code>gpu:0</code></td>
146+
</tr>
147+
<tr>
148+
<td><code>use_hpip</code></td>
149+
<td>Whether to enable high-performance inference plugin</td>
150+
<td><code>bool</code></td>
151+
<td>None</td>
152+
<td><code>False</code></td>
153+
</tr>
154+
<tr>
155+
<td><code>hpi_config</code></td>
156+
<td>High-Performance Inference Configuration</td>
157+
<td><code>dict</code> | <code>None</code></td>
158+
<td>None</td>
159+
<td><code>None</code></td>
160+
</tr>
161+
</table>
162+
163+
* Among them, `model_name` must be specified. After specifying `model_name`, the default model parameters built into PaddleX are used. When `model_dir` is specified, the user-defined model is used.
164+
165+
* Call the `predict()` method of the image rectification model for inference prediction. This method will return a result list. Additionally, this module also provides a `predict_iter()` method. Both methods are consistent in terms of parameter acceptance and result return. The difference is that `predict_iter()` returns a `generator`, 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 `predict()` method has parameters `input` and `batch_size`, with specific explanations as follows:
166+
167+
<table>
168+
<thead>
169+
<tr>
170+
<th>Parameter</th>
171+
<th>Description</th>
172+
<th>Type</th>
173+
<th>Options</th>
174+
<th>Default Value</th>
175+
</tr>
176+
</thead>
177+
<tr>
178+
<td><code>input</code></td>
179+
<td>Data to be predicted, supports multiple input types</td>
180+
<td><code>Python Var</code>/<code>str</code>/<code>dict</code>/<code>list</code></td>
181+
<td>
182+
<ul>
183+
<li><b>Python Variable</b>, such as <code>numpy.ndarray</code> representing image data</li>
184+
<li><b>File Path</b>, such as the local path of an image file: <code>/root/data/img.jpg</code></li>
185+
<li><b>URL Link</b>, such as the network URL of an image file: <a href = "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png">Example</a></li>
186+
<li><b>Local Directory</b>, which should contain data files to be predicted, such as the local path: <code>/root/data/</code></li>
187+
<li><b>List</b>, where list elements must be of the above types, such as <code>[numpy.ndarray, numpy.ndarray]</code>, <code>["/root/data/img1.jpg", "/root/data/img2.jpg"]</code>, <code>["/root/data1", "/root/data2"]</code></li>
188+
</ul>
189+
</td>
190+
<td>None</td>
191+
</tr>
192+
<tr>
193+
<td><code>batch_size</code></td>
194+
<td>Batch Size</td>
195+
<td><code>int</code></td>
196+
<td>Any integer</td>
197+
<td>1</td>
198+
</tr>
199+
</table>
200+
201+
* 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 `json` file:
202+
203+
<table>
204+
<thead>
205+
<tr>
206+
<th>Method</th>
207+
<th>Description</th>
208+
<th>Parameter</th>
209+
<th>Type</th>
210+
<th>Parameter Description</th>
211+
<th>Default Value</th>
212+
</tr>
213+
</thead>
214+
<tr>
215+
<td rowspan = "3"><code>print()</code></td>
216+
<td rowspan = "3">Print result to terminal</td>
217+
<td><code>format_json</code></td>
218+
<td><code>bool</code></td>
219+
<td>Whether to format the output content using <code>JSON</code> indentation</td>
220+
<td><code>True</code></td>
221+
</tr>
222+
<tr>
223+
<td><code>indent</code></td>
224+
<td><code>int</code></td>
225+
<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>
226+
<td>4</td>
227+
</tr>
228+
<tr>
229+
<td><code>ensure_ascii</code></td>
230+
<td><code>bool</code></td>
231+
<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>
232+
<td><code>False</code></td>
233+
</tr>
234+
<tr>
235+
<td rowspan = "3"><code>save_to_json()</code></td>
236+
<td rowspan = "3">Save the result as a json format file</td>
237+
<td><code>save_path</code></td>
238+
<td><code>str</code></td>
239+
<td>The path to save the file. When specified as a directory, the saved file is named consistent with the input file type.</td>
240+
<td>None</td>
241+
</tr>
242+
<tr>
243+
<td><code>indent</code></td>
244+
<td><code>int</code></td>
245+
<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>
246+
<td>4</td>
247+
</tr>
248+
<tr>
249+
<td><code>ensure_ascii</code></td>
250+
<td><code>bool</code></td>
251+
<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>
252+
<td><code>False</code></td>
253+
</tr>
254+
<tr>
255+
<td><code>save_to_img()</code></td>
256+
<td>Save the result as an image format file</td>
257+
<td><code>save_path</code></td>
258+
<td><code>str</code></td>
259+
<td>The path to save the file. When specified as a directory, the saved file is named consistent with the input file type.</td>
260+
<td>None</td>
261+
</tr>
262+
</table>
263+
264+
* Additionally, the result can be obtained through attributes that provide the visualized images with results and the prediction results, as follows:
265+
266+
<table>
267+
<thead>
268+
<tr>
269+
<th>Attribute</th>
270+
<th>Description</th>
271+
</tr>
272+
</thead>
273+
<tr>
274+
<td rowspan = "1"><code>json</code></td>
275+
<td rowspan = "1">Get the prediction result in <code>json</code> format</td>
276+
</tr>
277+
<tr>
278+
<td rowspan = "1"><code>img</code></td>
279+
<td rowspan = "1">Get the visualized image in <code>dict</code> format</td>
280+
</tr>
281+
282+
</table>
283+
284+
## 4. Secondary Development
285+
286+
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.
287+
288+
## 5. FAQ

‎docs/version3.x/module_usage/text_image_unwarping.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,3 +285,5 @@ for res in output:
285285
## 四、二次开发
286286

287287
当前模块暂时不支持微调训练，仅支持推理集成。关于该模块的微调训练，计划在未来支持。
288+
289+
## 五、FAQ

0 commit comments

Comments
 (0)