--- 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 > 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 Top-1 Accuracy (%) GPU Inference Time (ms)
[Normal Mode / High-Performance Mode]		 CPU Inference Time (ms) Model Storage Size (MB) Description
PP-LCNet_x0_25_textline_ori Inference Model/Training Model 98.85 2.16 / 0.41 2.37 / 0.73 0.96 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 - / - 2.98 / 2.98 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 was upgraded on May 26, 2025, 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:
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](../installation.en.md). You can quickly experience the functionality with a single command: ```bash paddleocr textline_orientation_classification -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/textline_rot180_demo.jpg ``` 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 textline_orientation_classification -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/textline_rot180_demo.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 textline_orientation_classification -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/textline_rot180_demo.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 text line orientation classification model into your project. Run the following code after downloading the [example image](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/textline_rot180_demo.jpg) to your local machine. ```python 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") ``` 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 TextLineOrientationClassification model = TextLineOrientationClassification( model_name="PP-LCNet_x0_25_textline_ori", engine="transformers", ) 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") ``` 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 TextLineOrientationClassification model = TextLineOrientationClassification( model_name="PP-LCNet_x0_25_textline_ori", engine="onnxruntime", ) 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") ``` In most scenarios, the default `paddle_static` inference engine delivers better inference performance and is the recommended first choice. If you want to use the trained model with the `paddle_dynamic` or `transformers` engine, refer to the [Weight Conversion](#52-weight-conversion) section in the [Inference Engine](#5-inference-engine) section below to convert the model from the `pdparams` format to the `safetensors` format using PaddleX. After running, the result obtained is: ```bash {'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: 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 Description Type Default
model_name Meaning: Model name.
Description: If set to None, PP-LCNet_x0_25_textline_ori will be used.		 str|None None
model_dir Meaning:Model storage path. str|None None
device Meaning: Device for inference.
Description: For example: "cpu", "gpu", "npu", "gpu:0", "gpu:0,1".
If multiple devices are specified, parallel inference will be performed.
By default, GPU 0 is used if available; otherwise, CPU is used. 		str|None 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 enable 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: Computation precision when using the TensorRT subgraph engine in Paddle Inference.
Description: Options: "fp32", "fp16".		 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
* Use the predict() method of the text line direction classification model to perform inference. This method returns a list of results. In addition, this module also provides the predict_iter() method. Both methods accept the same parameters and return the same result format. The difference is that predict_iter() returns a generator, which processes and retrieves prediction results step by step. It is suitable for handling large datasets or memory-efficient scenarios. You can choose either method based on your actual needs. The predict() method accepts the parameters input and batch_size, which are described in detail below:
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
* 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 Meaning:Data to be predicted,
Description: 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 Meaning: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](https://paddlepaddle.github.io/PaddleX/latest/en/module_usage/tutorials/ocr_modules/textline_orientation_classification.html#iv-custom-development) for training. Trained models can seamlessly integrate into PaddleOCR's API for inference. If you want to use the `paddle_dynamic` or `transformers` engine with the trained model, please refer to the [Weight Conversion](#52-weight-conversion) section in [Inference Engine](#5-inference-engine) later in this document to convert the model from the `pdparams` format to the `safetensors` format using PaddleX. ## 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)
PP-LCNet_x0_25_textline_ori paddle_static 0.30 2.89 0.06 3.34
paddle_dynamic 0.28 6.52 0.08 6.98
transformers 1.30 3.76 0.15 5.36
onnxruntime 0.27 0.76 0.05 1.16
PP-LCNet_x1_0_textline_ori paddle_static 0.33 3.20 0.06 3.69
paddle_dynamic 0.29 7.60 0.07 8.06
transformers 1.28 3.47 0.14 5.04
onnxruntime 0.27 0.77 0.05 1.16
Test Environment Description: ### 5.2 Weight Conversion When using the inference engine, the system will automatically download the official pre-trained model. If you need to use a self-trained model with the `paddle_dynamic` or `transformers` engine, please refer to the [PaddleX Text Line Orientation Classification Module Weight Conversion](https://paddlepaddle.github.io/PaddleX/latest/en/module_usage/tutorials/ocr_modules/textline_orientation_classification.html#442) section to convert the model from the `pdparams` format to the `safetensors` format using PaddleX. This allows seamless integration into the PaddleOCR API for inference. If you need to use a self-trained model with the `onnxruntime` engine, refer to [PaddleX Obtain ONNX Models](https://paddlepaddle.github.io/PaddleX/latest/pipeline_deploy/paddle2onnx.html) to obtain the ONNX model, so it can be seamlessly integrated into the PaddleOCR API for inference.