PaddleOCR/docs/version3.x/module_usage/text_line_orientation_classification.en.md

comments
true

Text Line Orientation Classification Module Tutorial

1. Overview

The text line orientation classification module primarily distinguishes the orientation of text lines and corrects them using post-processing. In processes such as document scanning and license/certificate photography, to capture clearer images, the capture device may be rotated, resulting in text lines in various orientations. Standard OCR pipelines cannot handle such data well. By utilizing image classification technology, the orientation of text lines can be predetermined and adjusted, thereby enhancing the accuracy of OCR processing.

2. Supported Model List

Model	Model Download Link	Top-1 Accuracy (%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms)	Model Size (M)	Description
PP-LCNet_x0_25_textline_ori	Inference Model/Training Model	98.85	-	-	0.32	Text line classification model based on PP-LCNet_x0_25, with two classes: 0 degrees and 180 degrees
PP-LCNet_x1_0_textline_ori	Inference Model/Training Model	99.42	-	-	6.5	Text line classification model based on PP-LCNet_x1_0, with two classes: 0 degrees and 180 degrees

❗ Note: The text line orientation classification model has been recently upgraded, and PP-LCNet_x1_0_textline_ori has been added. If you need to use the pre-upgrade model weights, please click the download link.

Test Environment Description:

• Performance Test Environment
  • Test Dataset： PaddleX Self-built Dataset, Covering Multiple Scenarios Such as Documents and Certificates, Containing 1000 Images.
  • Hardware Configuration：
    • GPU: NVIDIA Tesla T4
    • CPU: Intel Xeon Gold 6271C @ 2.60GHz
    • Other Environments: Ubuntu 20.04 / cuDNN 8.6 / TensorRT 8.5.2.2
• Inference Mode Description

Mode	GPU Configuration	CPU Configuration	Acceleration Technology Combination
Normal Mode	FP32 Precision / No TRT Acceleration	FP32 Precision / 8 Threads	PaddleInference
High-Performance Mode	Optimal combination of pre-selected precision types and acceleration strategies	FP32 Precision / 8 Threads	Pre-selected optimal backend (Paddle/OpenVINO/TRT, etc.)

3. Quick Integration

❗ Before starting, please install the wheel package of PaddleOCR. For detailed instructions, refer to the Installation Guide.

You can quickly experience the functionality with a single command:

paddleocr text_line_orientation_classification -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/textline_rot180_demo.jpg

You can also integrate the text line orientation classification model into your project. Run the following code after downloading the example image to your local machine.

from paddleocr import TextLineOrientationClassification
model = TextLineOrientationClassification(model_name="PP-LCNet_x0_25_textline_ori")
output = model.predict("textline_rot180_demo.jpg",  batch_size=1)
for res in output:
    res.print(json_format=False)
    res.save_to_img("./output/demo.png")
    res.save_to_json("./output/res.json")

After running, the result obtained is:

{'res': {'input_path': 'textline_rot180_demo.jpg', 'page_index': None, 'class_ids': array([1], dtype=int32), 'scores': array([0.99864], dtype=float32), 'label_names': ['180_degree']}}

The meanings of the running results parameters are as follows:

• input_path：Indicates the path of the input image.
• page_index：If the input is a PDF file, it indicates the current page number of the PDF; otherwise, it is None.
• class_ids：Indicates the class ID of the prediction result.
• scores：Indicates the confidence score of the prediction result.
• label_names：Indicates the class name of the prediction result. The visualization image is as follows:

The explanations for the methods, parameters, etc., are as follows:

• TextLineOrientationClassification instantiates a textline classification model (here, PP-LCNet_x0_25_textline_ori is used as an example), and the specific explanations are as follows:

Parameter	Parameter Description	Parameter Type	Options	Default Value
model_name	Name of the model	str	None	PP-LCNet_x0_25_textline_ori
model_dir	Path to store the model	str	None	None
device	The device used for model inference	str	It supports specifying specific GPU card numbers, such as "gpu:0", other hardware card numbers, such as "npu:0", or CPU, such as "cpu".	gpu:0
use_hpip	Whether to enable the high-performance inference plugin	bool	None	False
hpi_config	High-performance inference configuration	dict | None	None	None

• The model_name must be specified. After specifying model_name, the default model parameters built into PaddleX are used. If model_dir is specified, the user-defined model is used.

• Call the predict() method of the text line orientation classification model for inference. This method will return a list of results. In addition, this module also provides a predict_iter() method. Both methods accept the same parameters and return the same results, but predict_iter() returns a generator, which is more suitable for processing large datasets or when you want to save memory. You can choose either method according to your needs. The parameters of the predict() method are input and batch_size, as described below:

Parameter	Parameter Description	Parameter Type	Options	Default Value
input	Data to be predicted, supporting multiple input types	Python Var/str/list	Python variable, such as image data represented by numpy.ndarray File path, such as the local path of an image file: /root/data/img.jpg URL link, such as the network URL of an image file: Example Local directory, the directory should contain data files to be predicted, such as the local path: /root/data/ List, the elements of the list should be of the above-mentioned data types, such as [numpy.ndarray, numpy.ndarray], [\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"], [\"/root/data1\", \"/root/data2\"]	None
batch_size	Batch size	int	Any integer	1

• The prediction results are processed, and the prediction result for each sample is of type dict. It supports operations such as printing, saving as an image, and saving as a json file:

Method	Method Description	Parameter	Parameter Type	Parameter Description	Default Value
print()	Print the results to the terminal	format_json	bool	Whether to format the output content using JSON indentation	True
		indent	int	Specify the indentation level to beautify the output JSON data, making it more readable, only effective when format_json is True	4
		ensure_ascii	bool	Control whether to escape non-ASCII characters to Unicode. If set to True, all non-ASCII characters will be escaped; False retains the original characters, only effective when format_json is True	False
save_to_json()	Save the results as a JSON file	save_path	str	The path to save the file. If it is a directory, the saved file name will be consistent with the input file name	None
		indent	int	Specify the indentation level to beautify the output JSON data, making it more readable, only effective when format_json is True	4
		ensure_ascii	bool	Control whether to escape non-ASCII characters to Unicode. If set to True, all non-ASCII characters will be escaped; False retains the original characters, only effective when format_json is True	False
save_to_img()	Save the results as an image file	save_path	str	The path to save the file. If it is a directory, the saved file name will be consistent with the input file name	None

• Additionally, it supports obtaining the visualization image with results and the prediction results through attributes, as follows:

Attribute	Attribute Description
json	Get the prediction result in json format
img	Get the visualization image in dict format

4. Custom Development

Since PaddleOCR does not natively support training for text line orientation classification, refer to PaddleX's Custom Development Guide for training. Trained models can seamlessly integrate into PaddleOCR's API for inference.