From 97b454b884903e7daefb3352abcc368e9c0d8a95 Mon Sep 17 00:00:00 2001 From: Zhang Zelun <33217105+BluebirdStory@users.noreply.github.com> Date: Mon, 19 May 2025 22:57:10 +0800 Subject: [PATCH] add docs for text_image_unwarping (#15177) --- .../module_usage/text_image_unwarping.en.md | 288 ++++++++++++++++++ .../module_usage/text_image_unwarping.md | 2 + 2 files changed, 290 insertions(+) create mode 100644 docs/version3.x/module_usage/text_image_unwarping.en.md diff --git a/docs/version3.x/module_usage/text_image_unwarping.en.md b/docs/version3.x/module_usage/text_image_unwarping.en.md new file mode 100644 index 0000000000..3e5e5c3544 --- /dev/null +++ b/docs/version3.x/module_usage/text_image_unwarping.en.md @@ -0,0 +1,288 @@ +--- + +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 + + + + + + + + + + + + + + + + + + +
ModelModel Download LinkCERModel Storage Size (M)Description
UVDocInference Model/Training Model0.17930.3 MHigh-accuracy text image rectification model
+ +Test Environment Description: + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModeGPU ConfigurationCPU ConfigurationAcceleration Technology Combination
Regular ModeFP32 Precision / No TRT AccelerationFP32 Precision / 8 ThreadsPaddleInference
High-Performance ModeChoose the optimal combination of prior precision type and acceleration strategyFP32 Precision / 8 ThreadsChoose 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](../ppocr/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 +``` + +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") +``` + +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: +- `input_path`: Indicates the path of the image to be rectified +- `doctr_img`: Indicates the rectified image result. Due to the large amount of data, it is not convenient to print directly, so it is replaced here with `...`. You can use `res.save_to_img()` to save the prediction result as an image, and `res.save_to_json()` to save the prediction result as a json file. + +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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionTypeOptionsDefault Value
model_nameModel NamestrAll model names supported by PaddleXNone
model_dirModel Storage PathstrNoneNone
deviceModel Inference DevicestrSupports specifying specific GPU card numbers, such as “gpu:0”, specific hardware card numbers, such as “npu:0”, CPU as “cpu”.gpu:0
use_hpipWhether to enable high-performance inference pluginboolNoneFalse
hpi_configHigh-Performance Inference Configurationdict | NoneNoneNone
+ +* Among them, `model_name` must be specified. After specifying `model_name`, the default model parameters built into PaddleX are used. When `model_dir` is specified, the user-defined model is used. + +* 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: + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionTypeOptionsDefault Value
inputData to be predicted, supports multiple input typesPython Var/str/dict/list +
    +
  • Python Variable, such as numpy.ndarray representing image data
    • +
  • 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, which should contain data files to be predicted, such as the local path: /root/data/
    • +
  • List, where list elements must be of the above types, such as [numpy.ndarray, numpy.ndarray], ["/root/data/img1.jpg", "/root/data/img2.jpg"], ["/root/data1", "/root/data2"]
    • +
+		None
batch_sizeBatch SizeintAny integer1
+ +* 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescriptionParameterTypeParameter DescriptionDefault Value
print()Print result to terminalformat_jsonboolWhether to format the output content using JSON indentationTrue
indentintSpecifies the indentation level to beautify the output JSON data, making it more readable, effective only when format_json is True4
ensure_asciiboolControls 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 TrueFalse
save_to_json()Save the result as a json format filesave_pathstrThe path to save the file. When specified as a directory, the saved file is named consistent with the input file type.None
indentintSpecifies the indentation level to beautify the output JSON data, making it more readable, effective only when format_json is True4
ensure_asciiboolControls 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 TrueFalse
save_to_img()Save the result as an image format filesave_pathstrThe 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: + + + + + + + + + + + + + + + + + +
AttributeDescription
jsonGet the prediction result in json format
imgGet 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. FAQ diff --git a/docs/version3.x/module_usage/text_image_unwarping.md b/docs/version3.x/module_usage/text_image_unwarping.md index ecfcae7bcd..5144528e07 100644 --- a/docs/version3.x/module_usage/text_image_unwarping.md +++ b/docs/version3.x/module_usage/text_image_unwarping.md @@ -285,3 +285,5 @@ for res in output: ## 四、二次开发 当前模块暂时不支持微调训练，仅支持推理集成。关于该模块的微调训练，计划在未来支持。 + +## 五、FAQ