--- comments: true --- # 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 paddle_static inference engine.
ModelModel Download Link CER GPU Inference Time (ms)
[Normal Mode / High-Performance Mode]		 CPU Inference Time (ms)
[Normal Mode / High-Performance Mode]		 Model Storage Size (MB) Description
UVDoc Inference Model/Training Model 0.179 19.05 / 19.05 - / 869.82 30.3 High-accuracy text image rectification model
Test Environment Description:
Mode GPU Configuration CPU Configuration Acceleration Technology Combination
Regular Mode FP32 Precision / No TRT Acceleration FP32 Precision / 8 Threads PaddleInference
High-Performance Mode Choose the optimal combination of prior precision type and acceleration strategy FP32 Precision / 8 Threads Choose the optimal prior backend (Paddle/OpenVINO/TRT, etc.)
## 3. Quick Start > ❗ Before starting quickly, please first install the PaddleOCR wheel package. For details, please refer to the [installation tutorial](../installation.md). You can quickly experience it with one command: ```bash paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg ``` The example above uses the paddle_static inference engine by default. To run it, first install PaddlePaddle by following [PaddlePaddle Framework Installation](../paddlepaddle_installation.en.md). If you choose `transformers` as the inference engine, make sure the Transformers environment is configured, and then run the following command: ```bash # Use the transformers engine for inference paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \ --engine transformers ``` If you choose `onnxruntime` as the inference engine, make sure the ONNX Runtime environment is configured, and then run the following command: ```bash # Use the onnxruntime engine for inference paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \ --engine onnxruntime ``` In most scenarios, the default `paddle_static` inference engine delivers better inference performance and is the recommended first choice. Note: 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](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg) locally. ```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") ``` The example above uses the paddle_static inference engine by default. To run it, first install PaddlePaddle by following [PaddlePaddle Framework Installation](../paddlepaddle_installation.en.md). If you choose `transformers` as the inference engine, make sure the Transformers environment is configured, and then run the following code: ```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") ``` If you choose `onnxruntime` as the inference engine, make sure the ONNX Runtime environment is configured, and then run the following code: ```python from paddleocr import TextImageUnwarping model = TextImageUnwarping( model_name="UVDoc", engine="onnxruntime", ) 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") ``` 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: ```bash {'res': {'input_path': 'doc_test.jpg', 'page_index': None, 'doctr_img': '...'}} ``` The meanings of the parameters in the result are as follows: The visualized image is as follows: The relevant methods, parameters, etc., are described as follows: * TextImageUnwarping instantiates the image rectification model (taking UVDoc as an example here), with specific explanations as follows:
Parameter Description Type Default
model_name Meaning: Name of the model str None
model_dir Meaning: Model storage path str None
device Meaning: Device(s) to use for inference.
Description: Examples: cpu, gpu, npu, gpu:0, gpu:0,1.
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. 		str None
engine Meaning: Inference engine.
Description: Supports None (the default), paddle, paddle_static, paddle_dynamic, transformers, and onnxruntime. When left as None, local inference uses the paddle_static engine by default. For detailed descriptions, supported values, compatibility rules, and examples, see Inference Engine and Configuration.		 str|None None
engine_config Meaning: Inference-engine configuration.
Description: Recommended together with engine. For supported fields, compatibility rules, and examples, see Inference Engine and Configuration.		 dict|None None
enable_hpi Meaning: Whether to use the high performance inference. bool False
use_tensorrt Meaning: Whether to use the Paddle Inference TensorRT subgraph engine.
Description: 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.
 bool False
precision Meaning:Precision for TensorRT when using the Paddle Inference TensorRT subgraph engine.
Description: Options: "fp32", "fp16", etc.		 str "fp32"
enable_mkldnn Meaning: Whether to enable MKL-DNN acceleration for inference.
Description: If MKL-DNN is unavailable or the model does not support it, acceleration will not be used even if this flag is set. 		bool True
mkldnn_cache_capacity Meaning:MKL-DNN cache capacity. int 10
cpu_threads Meaning: Number of threads to use for inference on CPUs. int 10
* 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:
Parameter Description Type Default
input Meaning: Input data to be predicted. Required.
Description: Supports multiple input types:
  • Python Var: e.g., numpy.ndarray representing image data
  • str:
    • Local image or PDF file path: /root/data/img.jpg;
    • URL of image or PDF file: e.g., example;
    • Local directory: directory containing images for prediction, e.g., /root/data/ (Note: directories containing PDF files are not supported; PDFs must be specified by exact file path)
  • list: Elements must be of the above types, e.g., [numpy.ndarray, numpy.ndarray], ["/root/data/img1.jpg", "/root/data/img2.jpg"], ["/root/data1", "/root/data2"]
 Python Var|str|list
batch_size Meaning: Batch size
Description: Positive integer.		 int 1
* 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:
Method Description Parameter Type Parameter Description Default Value
print() Print result to terminal format_json bool Whether to format the output content using JSON indentation True
indent int Specifies the indentation level to beautify the output JSON data, making it more readable, effective only when format_json is True 4
ensure_ascii bool Controls whether to escape non-ASCII characters into Unicode. When set to True, all non-ASCII characters will be escaped; False will retain the original characters, effective only when format_json is True False
save_to_json() Save the result as a json format file save_path str The path to save the file. When specified as a directory, the saved file is named consistent with the input file type. None
indent int Specifies the indentation level to beautify the output JSON data, making it more readable, effective only when format_json is True 4
ensure_ascii bool Controls whether to escape non-ASCII characters into Unicode. When set to True, all non-ASCII characters will be escaped; False will retain the original characters, effective only when format_json is True False
save_to_img() Save the result as an image format file save_path str The path to save the file. When specified as a directory, the saved file is named consistent with the input file type. None
* Additionally, the result can be obtained through attributes that provide the visualized images with results and the prediction results, as follows:
Attribute Description
json Get the prediction result in json format
img Get the visualized image in dict format
## 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 Inference Engine and Configuration Description. ### 5.1 Speed Data
model engine Preprocessing (ms) Inference (ms) PostProcessing (ms) End-to-End (ms)
UVDoc paddle_static 14.96 18.60 1.93 36.66
paddle_dynamic 10.90 27.59 1.96 40.94
transformers 13.54 6.74 0.91 33.07
onnxruntime 10.60 8.44 1.75 21.30
Test Environment Description: ## 6. FAQ