Table Classification Module Usage Tutorial¶

I. Overview¶

The table classification module is a key component of a computer vision system, responsible for classifying input table images. The performance of this module directly affects the accuracy and efficiency of the entire table recognition process. The table classification module typically receives table images as input and then, through deep learning algorithms, classifies them into predefined categories based on the characteristics and content of the images, such as wired tables and wireless tables. The classification results of the table classification module are provided as output for use in table recognition-related pipelines.

II. Supported Model List¶

Model	Model Download Link	Top1 Acc(%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)
PP-LCNet_x1_0_table_cls	Inference Model/Training Model	94.2	2.35 / 0.47	4.03 / 1.35	6.6M

Test Environment Description:

Performance Test Environment
Test Dataset: PaddleX Internal Self-built Evaluation Dataset.
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.)

III. Quick Integration¶

❗ Before quick integration, please install the PaddleX wheel package first. For details, please refer to the PaddleX Local Installation Guide.

After installing the wheel package, you can complete the inference of the table classification module with just a few lines of code. You can switch between models under this module at will, and you can also integrate the model inference of the table classification module into your project. Before running the following code, please download the example image to your local machine.

from paddlex import create_model
model = create_model(model_name="PP-LCNet_x1_0_table_cls")
output = model.predict("table_recognition.jpg", batch_size=1)
for res in output:
    res.print(json_format=False)
    res.save_to_json("./output/res.json")

After running the code, the result obtained is:

{'res': {'input_path': 'table_recognition.jpg', "page_index": None, 'class_ids': array([0, 1], dtype=int32), 'scores': array([0.84421, 0.15579], dtype=float32), 'label_names': ['wired_table', 'wireless_table']}}

The meanings of the parameters in the running results are as follows: - input_path: Indicates the path of the input image. - page_index：If the input is a PDF file, this 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 of the prediction result. - label_names: Indicates the class name of the prediction result.

The descriptions of the related methods and parameters are as follows:

create_model instantiates a table classification model (here we use PP-LCNet_x1_0_table_cls as an example), and the specific descriptions are as follows:

Parameter	Parameter Description	Parameter Type	Optional	Default Value
`model_name`	Model name	`str`	No	`None`
`model_dir`	Model storage path	`str`	No	`None`

The model_name must be specified. After specifying the model_name, the default model parameters in PaddleX will be used. On this basis, if model_dir is specified, the user-defined model will be used.
Call the predict() method of the table classification model to perform inference prediction. The predict() method has parameters input and batch_size, and the specific descriptions are as follows:

Parameter	Parameter Description	Parameter Type	Optional	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, this directory should contain the 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

Process the prediction results. Each sample's prediction result is a corresponding Result object, and 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 result 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. It is only effective when `format_json` is `True`	4
		`ensure_ascii`	`bool`	Control whether to escape non-`ASCII` characters to `Unicode`. When set to `True`, all non-`ASCII` characters will be escaped; `False` retains the original characters. It is only effective when `format_json` is `True`	`False`
`save_to_json()`	Save the result as a JSON file	`save_path`	`str`	The path to save the file. If it is a directory, the saved file will be named consistently with the input file type	None
		`indent`	`int`	Specify the indentation level to beautify the output `JSON` data, making it more readable. It is only effective when `format_json` is `True`	4
		`ensure_ascii`	`bool`	Control whether to escape non-`ASCII` characters to `Unicode`. When set to `True`, all non-`ASCII` characters will be escaped; `False` retains the original characters. It is only effective when `format_json` is `True`	`False`

In addition, it also supports obtaining visual images with results and 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

For more information on the usage of PaddleX's single-model inference API, please refer to PaddleX Single-Model Python Script Usage Instructions.

IV. Secondary Development¶

If you aim to improve the accuracy of existing models, you can leverage PaddleX's secondary development capabilities to develop a better table classification model. Before using PaddleX to develop a table classification model, please ensure that you have installed the table classification part of PaddleX according to the PaddleX Local Installation Guide.

4.1 Data Preparation¶

Before training the model, you need to prepare the dataset for the corresponding task module. PaddleX provides a data validation function for each module, and only data that passes the validation can be used for model training. In addition, PaddleX provides a demo dataset for each module, and you can complete subsequent development based on the official demo data. If you want to use your private dataset for model training, please refer to the PaddleX Image Classification Task Module Data Annotation Guide.

4.1.1 Downloading Demo Data¶

You can use the following command to download the demo dataset to a specified folder:

cd /path/to/paddlex
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/table_cls_examples.tar -P ./dataset
tar -xf ./dataset/table_cls_examples.tar -C ./dataset/

4.1.2 Data Validation¶

Data validation can be completed with a single line of command:

python main.py -c paddlex/configs/modules/table_classification/PP-LCNet_x1_0_table_cls.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/table_cls_examples

After executing the above command, PaddleX will verify the dataset and collect basic information about it. If the command runs successfully, it will print the message Check dataset passed ! in the log. The verification result file is saved at ./output/check_dataset_result.json, and related outputs will be stored in the ./output/check_dataset directory under the current directory. This output directory includes visualized example sample images and sample distribution histograms.

👉 Verification Result Details (Click to Expand)

  "done_flag": true,
  "check_pass": true,
  "attributes": {
    "label_file": "..\/..\/..\/docs_for_rc\/test_for_doc\/table_cls_examples\/label.txt",
    "num_classes": 2,
    "train_samples": 410,
    "train_sample_paths": [
      "check_dataset\/demo_img\/img_14707_0.png",
      "check_dataset\/demo_img\/img_14346_1.png",
      "check_dataset\/demo_img\/img_14707_3.png",
      "check_dataset\/demo_img\/img_12881_4.png",
      "check_dataset\/demo_img\/img_1676_4.png",
      "check_dataset\/demo_img\/img_14909_3.png",
      "check_dataset\/demo_img\/img_3530_4.png",
      "check_dataset\/demo_img\/img_5471_4.png",
      "check_dataset\/demo_img\/img_8396_4.png",
      "check_dataset\/demo_img\/img_13019_2.png"
    ],
    "val_samples": 102,
    "val_sample_paths": [
      "check_dataset\/demo_img\/img_4345_3.png",
      "check_dataset\/demo_img\/img_15063_0.png",
      "check_dataset\/demo_img\/img_747_3.png",
      "check_dataset\/demo_img\/img_5535_2.png",
      "check_dataset\/demo_img\/img_15250_2.png",
      "check_dataset\/demo_img\/img_4791_4.png",
      "check_dataset\/demo_img\/img_2562_2.png",
      "check_dataset\/demo_img\/img_15248_2.png",
      "check_dataset\/demo_img\/img_4178_3.png",
      "check_dataset\/demo_img\/img_11090_0.png"
    ]
  },
  "analysis": {
    "histogram": "check_dataset\/histogram.png"
  },
  "dataset_path": "table_cls_examples",
  "show_type": "image",
  "dataset_type": "ClsDataset"

In the above verification results, check_pass being True indicates that the dataset format meets the requirements. The explanations for the other metrics are as follows:

attributes.num_classes: The number of classes in this dataset is 2;
attributes.train_samples: The number of training samples in this dataset is 410;
attributes.val_samples: The number of validation samples in this dataset is 102;
attributes.train_sample_paths: A list of relative paths for the visualization images of the training samples in this dataset;
attributes.val_sample_paths: A list of relative paths for the visualization images of the validation samples in this dataset;

In addition, the dataset verification has analyzed the distribution of sample counts for all classes in the dataset and generated a histogram (histogram.png):

4.1.3 Dataset Format Conversion/Dataset Splitting (Optional)¶

After you complete the data verification, you can convert the dataset format by modifying the configuration file or adding hyperparameters. You can also re-split the training/validation ratio of the dataset.

👉 Details of Format Conversion/Dataset Splitting (Click to Expand)

(1) Dataset Format Conversion

Table classification does not support data conversion at the moment.

(2) Dataset Splitting

The parameters for dataset splitting can be set by modifying the fields under CheckDataset in the configuration file. Some example explanations of the parameters in the configuration file are as follows:

CheckDataset:
split:
enable: Whether to re-split the dataset. When set to True, the dataset will be re-split. The default value is False;
train_percent: If re-splitting the dataset, you need to set the percentage of the training set. It should be an integer between 0 and 100, and it must sum up to 100 with the value of val_percent;

For example, if you want to re-split the dataset with 90% for the training set and 10% for the validation set, you need to modify the configuration file as follows:

......
CheckDataset:
  ......
  split:
    enable: True
    train_percent: 90
    val_percent: 10
  ......

Then execute the command:

python main.py -c paddlex/configs/modules/table_classification/PP-LCNet_x1_0_table_cls.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/table_cls_examples

After the dataset splitting is executed, the original annotation file will be renamed to xxx.bak in the original path.

The above parameters can also be set by appending command-line arguments:

python main.py -c paddlex/configs/modules/table_classification/PP-LCNet_x1_0_table_cls.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/table_cls_examples \
    -o CheckDataset.split.enable=True \
    -o CheckDataset.split.train_percent=90 \
    -o CheckDataset.split.val_percent=10

4.2 Model Training¶

Training a model can be done with a single command. For example, to train the table classification model PP-LCNet_x1_0_table_cls:

python main.py -c paddlex/configs/modules/table_classification/PP-LCNet_x1_0_table_cls.yaml  \
    -o Global.mode=train \
    -o Global.dataset_dir=./dataset/table_cls_examples

Specify the .yaml configuration file path for the model (here it is PP-LCNet_x1_0_table_cls.yaml. When training other models, the corresponding configuration file needs to be specified. The correspondence between models and configurations can be found in PaddleX Model List (CPU/GPU)).
Set the mode to model training: -o Global.mode=train
Specify the training dataset path: -o Global.dataset_dir Other related parameters can be set by modifying the fields under Global and Train in the .yaml configuration file, or by appending parameters in the command line. For example, to specify training on the first 2 GPUs: -o Global.device=gpu:0,1; to set the number of training epochs to 10: -o Train.epochs_iters=10. For more modifiable parameters and their detailed explanations, refer to the configuration file description of the corresponding model task module PaddleX General Model Configuration Parameters.

👉 More Details (Click to Expand)

During model training, PaddleX will automatically save the model weight files, with the default directory being output. If you need to specify a different save path, you can set it through the -o Global.output field in the configuration file.
PaddleX abstracts away the concepts of dynamic graph weights and static graph weights for you. During model training, both dynamic and static graph weights will be generated. By default, static graph weights are used for model inference.
After model training is completed, all outputs are saved in the specified output directory (default is ./output/), typically including the following:
train_result.json: The training result record file, which logs whether the training task was completed successfully, as well as the metrics of the generated weights and related file paths;
train.log: The training log file, which records changes in model metrics and loss during the training process;
config.yaml: The training configuration file, which logs the hyperparameter settings for this training session;
.pdparams、.pdema、.pdopt.pdstate、.pdiparams、.pdmodel: Model weight-related files, including network parameters, optimizer, EMA, static graph network parameters, and static graph network structure, etc.

4.3 Model Evaluation¶

After completing model training, you can evaluate the specified model weight file on the validation set to verify the model's accuracy. With PaddleX, model evaluation can be completed with a single command:

python main.py -c  paddlex/configs/modules/table_classification/PP-LCNet_x1_0_table_cls.yaml  \
    -o Global.mode=evaluate \
    -o Global.dataset_dir=./dataset/table_cls_examples

Similar to model training, the following steps are required:

Specify the path of the model's .yaml configuration file (here it is PP-LCNet_x1_0_table_cls.yaml)
Specify the mode as model evaluation: -o Global.mode=evaluate
Specify the validation dataset path: -o Global.dataset_dir Other related parameters can be set by modifying the fields under Global and Evaluate in the .yaml configuration file. For details, please refer to PaddleX Common Model Configuration File Parameter Description.

👉 More Information (Click to Expand)

When evaluating the model, you need to specify the path of the model weight file. Each configuration file has a default weight save path built in. If you need to change it, you can simply set it by appending command-line parameters, such as -o Evaluate.weight_path=./output/best_model/best_model.pdparams.

After completing the model evaluation, an evaluate_result.json file will be generated, which records the evaluation results. Specifically, it records whether the evaluation task was completed normally and the model's evaluation metrics, including val.top1 and val.top5.

4.4 Model Inference and Model Integration¶

After completing the training and evaluation of the model, you can use the trained model weights for inference prediction or integrate them into Python.

4.4.1 Model Inference¶

Inference prediction can be performed via the command line with just one command. Before running the following code, please download the example image to your local machine. Note that due to network issues, the link may not be accessible. If you encounter any problems, please check the validity of the link and try again.

python main.py -c paddlex/configs/modules/table_classification/PP-LCNet_x1_0_table_cls.yaml \
    -o Global.mode=predict \
    -o Predict.model_dir="./output/best_model/inference" \
    -o Predict.input="table_recognition.jpg"

Similar to model training and evaluation, the following steps are required:

Specify the path of the model's .yaml configuration file (here it is PP-LCNet_x1_0_table_cls.yaml)
Specify the mode as model inference prediction: -o Global.mode=predict
Specify the model weight path: -o Predict.model_dir="./output/best_model/inference"
Specify the input data path: -o Predict.input="..."

Other related parameters can be set by modifying the fields under Global and Predict in the .yaml configuration file. For details, please refer to PaddleX Common Model Configuration File Parameter Description.

4.4.2 Model Integration¶

The model can be directly integrated into the PaddleX pipeline or directly integrated into your own project.

1.Pipeline Integration

The table classification module can be integrated into the PaddleX pipeline such as General Table Classification Pipeline v2. You just need to replace the model path to update the table classification module in the related pipeline. In pipeline integration, you can deploy the model you obtained using high-performance deployment and service-oriented deployment.

2.Module Integration

The weights you generate can be directly integrated into the table classification module. You can refer to the Python example code in Quick Integration. Just replace the model with the path of the model you have trained.

You can also use the PaddleX high-performance inference plugin to optimize the inference process of your model and further improve efficiency. For detailed procedures, please refer to the PaddleX High-Performance Inference Guide.