## 2. Quick Start
The pre-trained model pipelines provided by PaddleX can be quickly experienced. You can experience the seal text recognition pipeline locally using the command line or Python.
Before using the seal text recognition pipeline locally, please ensure that you have completed the installation of the PaddleX wheel package according to the [PaddleX Local Installation Tutorial](../../../installation/installation.en.md).
### 2.1 Command Line Experience
You can quickly experience the seal text recognition pipeline with a single command. Use the [test file](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/seal_text_det.png), and replace `--input` with the local path for prediction.
```bash
paddlex --pipeline seal_recognition \
--input seal_text_det.png \
--use_doc_orientation_classify False \
--use_doc_unwarping False \
--device gpu:0 \
--save_path ./output
```
The relevant parameter descriptions can be referred to in the parameter explanations of [2.1.2 Integration via Python Script](#212-integration-via-python-script).
After running, the results will be printed to the terminal, as follows:
| Parameter |
Description |
Type |
Options |
Default Value |
input |
Data to be predicted, supports multiple input types (required) |
Python Var|str|list |
- Python Var: Image data represented by
numpy.ndarray
- str: Local path of an image or PDF file, e.g.,
/root/data/img.jpg; URL link, e.g., the network URL of an image or PDF file: Example; Local directory, containing images to be predicted, e.g., /root/data/ (currently does not support prediction of PDF files in directories; PDF files must be specified with an exact file path)
- List: Elements of the list must be of the above types, e.g.,
[numpy.ndarray, numpy.ndarray], [\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"], [\"/root/data1\", \"/root/data2\"]
|
None |
device |
Inference device for the pipeline |
str|None |
- CPU: e.g.,
cpu for CPU inference;
- GPU: e.g.,
gpu:0 for inference using the first GPU;
- NPU: e.g.,
npu:0 for inference using the first NPU;
- XPU: e.g.,
xpu:0 for inference using the first XPU;
- MLU: e.g.,
mlu:0 for inference using the first MLU;
- DCU: e.g.,
dcu:0 for inference using the first DCU;
- None: If set to
None, the default value from the pipeline initialization will be used. During initialization, the local GPU device 0 will be prioritized; if unavailable, the CPU device will be used.
|
None |
use_doc_orientation_classify |
Whether to use the document orientation classification module |
bool|None |
- bool:
True or False;
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as True.
|
None |
use_doc_unwarping |
Whether to use the document unwarping module |
bool|None |
- bool:
True or False;
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as True.
|
None |
use_layout_detection |
Whether to use the layout detection module |
bool|None |
- bool:
True or False;
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as True.
|
None |
layout_threshold |
Confidence threshold for layout detection; only scores above this threshold will be output |
float|dict|None |
- float: Any float greater than
0
- dict: Key is the int category ID, value is any float greater than
0
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as 0.5
|
None |
layout_nms |
Whether to use Non-Maximum Suppression (NMS) for layout detection post-processing |
bool|None |
- bool:
True or False;
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as True.
|
None |
layout_unclip_ratio |
Expansion ratio of detection box edges; if not specified, the default value from the PaddleX official model configuration will be used |
float|list|None |
- float: Any float greater than 0, e.g., 1.1, which means expanding the width and height of the detection box by 1.1 times while keeping the center unchanged
- list: e.g., [1.2, 1.5], which means expanding the width of the detection box by 1.2 times and the height by 1.5 times while keeping the center unchanged
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as 1.0
|
layout_merge_bboxes_mode |
Merging mode for detection boxes in layout detection output; if not specified, the default value from the PaddleX official model configuration will be used |
string|None |
- large: When set to
large, only the largest external box will be retained for overlapping detection boxes, and the internal overlapping boxes will be removed.
- small: When set to
small, only the smallest internal box will be retained for overlapping detection boxes, and the external overlapping boxes will be removed.
- union: No filtering of boxes will be performed; both internal and external boxes will be retained.
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as large.
|
None |
seal_det_limit_side_len |
Side length limit for seal text detection |
int|None |
- int: Any integer greater than
0
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as 736
|
None |
seal_rec_score_thresh |
Text recognition threshold; text results with scores above this threshold will be retained |
float|None |
- float: Any float greater than
0
- None: If set to
None, the default value from the pipeline initialization will be used, initialized as 0.0. This means no threshold is applied.
|
None |
(3) Process the prediction results. The prediction result for each sample is of `dict` type and supports operations such as printing, saving as an image, and saving as a `json` file:
| Method |
Description |
Parameter |
Parameter Type |
Parameter Description |
Default Value |
print() |
Print 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 for better readability, effective only 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 will retain the original characters, effective only when format_json is True |
False |
save_to_json() |
Save results as a json file |
save_path |
str |
The file path to save the results. When it is a directory, the saved file name will be consistent with the input file type |
None |
indent |
int |
Specify the indentation level to beautify the output JSON data for better readability, effective only 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 will retain the original characters, effective only when format_json is True |
False |
save_to_img() |
Save results as an image file |
save_path |
str |
The file path to save the results, supports directory or file path |
None |
- Calling the `print()` method will print the results to the terminal, and the explanations of the printed content are as follows:
- `input_path`: `(str)` The input path of the image to be predicted.
- `model_settings`: `(Dict[str, bool])` The model parameters required for pipeline configuration.
- `use_doc_preprocessor`: `(bool)` Controls whether to enable the document preprocessing sub-pipeline.
- `use_layout_detection`: `(bool)` Controls whether to enable the layout detection sub-module.
- `layout_det_res`: `(Dict[str, Union[List[numpy.ndarray], List[float]]])` The output result of the layout detection sub-module. Only exists when `use_layout_detection=True`.
- `input_path`: `(Union[str, None])` The image path accepted by the layout detection module. Saved as `None` when the input is a `numpy.ndarray`.
- `page_index`: `(Union[int, None])` Indicates the current page number of the PDF if the input is a PDF file; otherwise, it is `None`.
- `boxes`: `(List[Dict])` A list of detected layout seal regions, with each element containing the following fields:
- `cls_id`: `(int)` The class ID of the detected seal region.
- `score`: `(float)` The confidence score of the detected region.
- `coordinate`: `(List[float])` The coordinates of the four corners of the detection box, in the order of x1, y1, x2, y2, representing the x-coordinate of the top-left corner, the y-coordinate of the top-left corner, the x-coordinate of the bottom-right corner, and the y-coordinate of the bottom-right corner.
- `seal_res_list`: `List[Dict]` A list of seal text recognition results, with each element containing the following fields:
- `input_path`: `(Union[str, None])` The image path accepted by the seal text recognition pipeline. Saved as `None` when the input is a `numpy.ndarray`.
- `page_index`: `(Union[int, None])` Indicates the current page number of the PDF if the input is a PDF file; otherwise, it is `None`.
- `model_settings`: `(Dict[str, bool])` The model configuration parameters for the seal text recognition pipeline.
- `use_doc_preprocessor`: `(bool)` Controls whether to enable the document preprocessing sub-pipeline.
- `use_textline_orientation`: `(bool)` Controls whether to enable the text line orientation classification sub-module.
- `doc_preprocessor_res`: `(Dict[str, Union[str, Dict[str, bool], int]])` The output result of the document preprocessing sub-pipeline. Only exists when `use_doc_preprocessor=True`.
- `input_path`: `(Union[str, None])` The image path accepted by the document preprocessing sub-pipeline. Saved as `None` when the input is a `numpy.ndarray`.
- `model_settings`: `(Dict)` The model configuration parameters for the preprocessing sub-pipeline.
- `use_doc_orientation_classify`: `(bool)` Controls whether to enable document orientation classification.
- `use_doc_unwarping`: `(bool)` Controls whether to enable document unwarping.
- `angle`: `(int)` The predicted result of document orientation classification. When enabled, it takes values [0, 1, 2, 3], corresponding to [0°, 90°, 180°, 270°]; when disabled, it is -1.
- `dt_polys`: `(List[numpy.ndarray])` A list of polygon boxes for seal text detection. Each detection box is represented by a numpy array of multiple vertex coordinates, with the array shape being (n, 2).
- `dt_scores`: `(List[float])` A list of confidence scores for text detection boxes.
- `text_det_params`: `(Dict[str, Dict[str, int, float]])` Configuration parameters for the text detection module.
- `limit_side_len`: `(int)` The side length limit value during image preprocessing.
- `limit_type`: `(str)` The handling method for side length limits.
- `thresh`: `(float)` The confidence threshold for text pixel classification.
- `box_thresh`: `(float)` The confidence threshold for text detection boxes.
- `unclip_ratio`: `(float)` The expansion ratio for text detection boxes.
- `text_type`: `(str)` The type of seal text detection, currently fixed as "seal".
- `text_rec_score_thresh`: `(float)` The filtering threshold for text recognition results.
- `rec_texts`: `(List[str])` A list of text recognition results, containing only texts with confidence scores above `text_rec_score_thresh`.
- `rec_scores`: `(List[float])` A list of confidence scores for text recognition, filtered by `text_rec_score_thresh`.
- `rec_polys`: `(List[numpy.ndarray])` A list of text detection boxes filtered by confidence score, in the same format as `dt_polys`.
- `rec_boxes`: `(numpy.ndarray)` An array of rectangular bounding boxes for detection boxes; the seal recognition pipeline returns an empty array.
- Calling the `save_to_json()` method will save the above content to the specified `save_path`. If a directory is specified, the saved path will be `save_path/{your_img_basename}_res.json`. If a file is specified, it will be saved directly to that file. Since JSON files do not support saving numpy arrays, `numpy.array` types will be converted to list format.
- Calling the `save_to_img()` method will save the visualization results to the specified `save_path`. If a directory is specified, the saved path will be `save_path/{your_img_basename}_seal_res_region1.{your_img_extension}`. If a file is specified, it will be saved directly to that file. (The pipeline usually contains multiple result images, so it is not recommended to specify a specific file path directly, as multiple images will be overwritten, and only the last image will be retained.)
* Additionally, you can obtain visualized images with results and prediction results through attributes, as follows:
The seal text recognition pipeline includes a seal text detection module and a text recognition module, as well as optional layout detection module, document image orientation classification module, and text image correction module.
If you prioritize model accuracy, choose a model with higher accuracy. If you prioritize inference speed, choose a model with faster inference speed. If you prioritize model storage size, choose a model with smaller storage size.
### 2.1.2 Python Script Integration
* The above command line is for quickly experiencing and viewing the effect. Generally, in a project, you often need to integrate through code. You can complete the quick inference of the pipeline with just a few lines of code. The inference code is as follows:
```python
from paddlex import create_pipeline
pipeline = create_pipeline(pipeline="seal_recognition")
output = pipeline.predict(
"seal_text_det.png",
use_doc_orientation_classify=False,
use_doc_unwarping=False,
)
for res in output:
res.print() ## 打印预测的结构化输出
res.save_to_img("./output/") ## 保存可视化结果
res.save_to_json("./output/") ## 保存可视化结果
```
In the above Python script, the following steps were executed:
(1) The OCR production line object was instantiated via `create_pipeline()`, with the specific parameters described as follows:
