Add readme for OCRResult (#227)

* Add PaddleOCR Support * Add PaddleOCR Support * Add PaddleOCRv3 Support * Add PaddleOCRv3 Support * Update README.md * Update README.md * Update README.md * Update README.md * Add PaddleOCRv3 Support * Add PaddleOCRv3 Supports * Add PaddleOCRv3 Suport * Fix Rec diff * Remove useless functions * Remove useless comments * Add PaddleOCRv2 Support * Add PaddleOCRv3 & PaddleOCRv2 Support * remove useless parameters * Add utils of sorting det boxes * Fix code naming convention * Fix code naming convention * Fix code naming convention * Fix bug in the Classify process * Imporve OCR Readme * Fix diff in Cls model * Update Model Download Link in Readme * Fix diff in PPOCRv2 * Improve OCR readme * Imporve OCR readme * Improve OCR readme * Improve OCR readme * Imporve OCR readme * Improve OCR readme * Fix conflict * Add readme for OCRResult * Improve OCR readme * Add OCRResult readme * Improve OCR readme * Improve OCR readme
2025-10-05 16:48:03 +08:00 · 2022-09-15 13:09:53 +08:00
parent 0805ead0ed
commit 12368dcb16
9 changed files with 90 additions and 52 deletions
--- a/docs/api/vision_results/README.md
+++ b/docs/api/vision_results/README.md
@@ -10,3 +10,4 @@ FastDeploy根据视觉模型的任务类型，定义了不同的结构体(`csrcs
 | FaceDetectionResult | [C++/Python文档](./face_detection_result.md) | 目标检测返回结果 | SCRFD、RetinaFace系列模型等 |
 | FaceRecognitionResult | [C++/Python文档](./face_recognition_result.md) | 目标检测返回结果 | ArcFace、CosFace系列模型等 |
 | MattingResult | [C++/Python文档](./matting_result.md) | 目标检测返回结果 | MODNet系列模型等 |
+| OCRResult | [C++/Python文档](./ocr_result.md) | 文本框检测，分类和文本识别返回结果 | OCR系列模型等 |
--- a/docs/api/vision_results/ocr_result.md
+++ b/docs/api/vision_results/ocr_result.md
@@ -0,0 +1,42 @@
+# OCRResult OCR预测结果
+
+OCRResult代码定义在`fastdeploy/vision/common/result.h`中，用于表明图像检测和识别出来的文本框，文本框方向分类，以及文本框内的文本内容
+
+## C++ 定义
+
+```c++
+fastdeploy::vision::OCRResult
+```  
+
+```c++
+struct OCRResult {
+  std::vector<std::array<int, 8>> boxes;
+  std::vector<std::string> text;
+  std::vector<float> rec_scores;
+  std::vector<float> cls_scores;
+  std::vector<int32_t> cls_labels;
+  ResultType type = ResultType::OCR;
+  void Clear();
+  std::string Str();
+};
+```
+
+- **boxes**: 成员变量，表示单张图片检测出来的所有目标框坐标，`boxes.size()`表示单张图内检测出的框的个数，每个框以8个int数值依次表示框的4个坐标点，顺序为左下，右下，右上，左上
+- **text**: 成员变量，表示多个文本框内被识别出来的文本内容，其元素个数与`boxes.size()`一致
+- **rec_scores**: 成员变量，表示文本框内识别出来的文本的置信度，其元素个数与`boxes.size()`一致
+- **cls_scores**: 成员变量，表示文本框的分类结果的置信度，其元素个数与`boxes.size()`一致
+- **cls_labels**: 成员变量，表示文本框的方向分类类别，其元素个数与`boxes.size()`一致
+- **Clear()**: 成员函数，用于清除结构体中存储的结果
+- **Str()**: 成员函数，将结构体中的信息以字符串形式输出（用于Debug）
+
+## Python 定义
+
+```python
+fastdeploy.vision.OCRResult  
+```
+
+- **boxes**: 成员变量，表示单张图片检测出来的所有目标框坐标，`boxes.size()`表示单张图内检测出的框的个数，每个框以8个int数值依次表示框的4个坐标点，顺序为左下，右下，右上，左上
+- **text**: 成员变量，表示多个文本框内被识别出来的文本内容，其元素个数与`boxes.size()`一致
+- **rec_scores**: 成员变量，表示文本框内识别出来的文本的置信度，其元素个数与`boxes.size()`一致
+- **cls_scores**: 成员变量，表示文本框的分类结果的置信度，其元素个数与`boxes.size()`一致
+- **cls_labels**: 成员变量，表示文本框的方向分类类别，其元素个数与`boxes.size()`一致
--- a/examples/vision/README.md
+++ b/examples/vision/README.md
@@ -10,6 +10,7 @@
 | FaceDetection | 人脸检测，输入图像，检测图像中人脸位置，并返回检测框坐标及人脸关键点             | [FaceDetectionResult](../../docs/api/vision_results/face_detection_result.md)   |
 | FaceRecognition | 人脸识别，输入图像，返回可用于相似度计算的人脸特征的embedding            | [FaceRecognitionResult](../../docs/api/vision_results/face_recognition_result.md)   |
 | Matting | 抠图，输入图像，返回图片的前景每个像素点的Alpha值            | [MattingResult](../../docs/api/vision_results/matting_result.md)   |
+| OCR | 文本框检测，分类，文本框内容识别，输入图像，返回文本框坐标，文本框的方向类别以及框内的文本内容            | [OCRResult](../../docs/api/vision_results/ocr_result.md)   |
 ## FastDeploy API设计

 视觉模型具有较有统一任务范式，在设计API时（包括C++/Python），FastDeploy将视觉模型的部署拆分为四个步骤
--- a/examples/vision/ocr/PPOCRSystemv2/cpp/README.md
+++ b/examples/vision/ocr/PPOCRSystemv2/cpp/README.md
@@ -40,6 +40,9 @@ wget https://gitee.com/paddlepaddle/PaddleOCR/raw/release/2.6/ppocr/utils/ppocr_
 ./infer_demo ./ch_PP-OCRv2_det_infer ./ch_ppocr_mobile_v2.0_cls_infer ./ch_PP-OCRv2_rec_infer ./ppocr_keys_v1.txt ./12.jpg 2
 ```

+以上命令只适用于Linux或MacOS, Windows下SDK的使用方式请参考:  
+- [如何在Windows中使用FastDeploy C++ SDK](../../../../../docs/compile/how_to_use_sdk_on_windows.md)
+
 运行完成可视化结果如下图所示

 <img width="640" src="https://user-images.githubusercontent.com/109218879/185826024-f7593a0c-1bd2-4a60-b76c-15588484fa08.jpg">
@@ -74,21 +77,18 @@ PPOCRSystemv2 的初始化，由检测，识别模型串联构成(无分类器)
 > * **DBDetector**(model): OCR中的检测模型
 > * **Recognizer**(model): OCR中的识别模型

-
 #### Predict函数

-> ```
-> std::vector<std::vector<fastdeploy::vision::OCRResult>> ocr_results =
-> PPOCRSystemv2.Predict(std::vector<cv::Mat> cv_all_imgs);
->  
+> ```  
+> bool Predict(cv::Mat* img, fastdeploy::vision::OCRResult* result);
 > ```
 >
-> 模型预测接口，输入一个可装入多张图片的图片列表，后可输出检测结果。
+> 模型预测接口，输入一张图片，返回OCR预测结果
 >
 > **参数**
 >
-> > * **cv_all_imgs**: 输入图像，注意需为HWC，BGR格式
-> > * **ocr_results**: OCR结果,包括由检测模型输出的检测框位置,分类模型输出的方向分类,以及识别模型输出的识别结果, OCRResult说明参考[视觉模型预测结果](../../../../../docs/api/vision_results/)
+> > * **img**: 输入图像，注意需为HWC，BGR格式
+> > * **result**: OCR预测结果,包括由检测模型输出的检测框位置,分类模型输出的方向分类,以及识别模型输出的识别结果, OCRResult说明参考[视觉模型预测结果](../../../../../docs/api/vision_results/)


 ## DBDetector C++接口
@@ -142,7 +142,8 @@ Recognizer类初始化时,需要在label_path参数中,输入识别模型所需

 > > * **cls_thresh**(double): 当分类模型输出的得分超过此阈值，输入的图片将被翻转，默认为0.9

+## 其它文档

- [模型介绍](../../)
- [Python部署](../python)
- [视觉模型预测结果](../../../../../docs/api/vision_results/)
+- [PPOCR 系列模型介绍](../../)
+- [PPOCRv2 Python部署](../python)
+- [模型预测结果说明](../../../../../docs/api/vision_results/)
--- a/examples/vision/ocr/PPOCRSystemv2/python/README.md
+++ b/examples/vision/ocr/PPOCRSystemv2/python/README.md
@@ -42,29 +42,27 @@ python infer.py --det_model ch_PP-OCRv2_det_infer --cls_model ch_ppocr_mobile_v2
 ## PPOCRSystemv2 Python接口

 ```
-fastdeploy.vision.ocr.PPOCRSystemv2(ocr_det = det_model._model, ocr_cls = cls_model._model, ocr_rec = rec_model._model)
+fd.vision.ocr.PPOCRSystemv2(det_model=det_model, cls_model=cls_model, rec_model=rec_model)
 ```
-
-PPOCRSystemv2的初始化,输入的参数是检测模型，分类模型和识别模型
+PPOCRSystemv2的初始化,输入的参数是检测模型，分类模型和识别模型，其中cls_model可选，如无需求，可设置为None

 **参数**

-> * **ocr_det**(model): OCR中的检测模型
-> * **ocr_cls**(model): OCR中的分类模型
-> * **ocr_rec**(model): OCR中的识别模型
+> * **det_model**(model): OCR中的检测模型
+> * **cls_model**(model): OCR中的分类模型
+> * **rec_model**(model): OCR中的识别模型

 ### predict函数

 > ```
-> result = PPOCRSystemv2.predict(img_list)
+> result = ocr_system.predict(im)
 > ```
 >
-> 模型预测接口，输入的是一个可包含多个图像的list
+> 模型预测接口，输入是一张图片
 >
 > **参数**
 >
-> > * **img_list**(list[np.ndarray]): 输入数据的list，每张图片注意需为HWC，BGR格式
-> > * **result**(float): OCR结果,包括由检测模型输出的检测框位置,分类模型输出的方向分类,以及识别模型输出的识别结果,
+> > * **im**(np.ndarray): 输入数据，每张图片注意需为HWC，BGR格式

 > **返回**
 >
@@ -124,6 +122,6 @@ Recognizer类初始化时,需要在rec_label_file参数中,输入识别模型所

 ## 其它文档

- [PPOCR系列模型介绍](../../)
+- [PPOCR 系列模型介绍](../../)
 - [PPOCRv2 C++部署](../cpp)
- [模型预测结果说明](../../../../../docs/api/vision_results/)
+- [模型预测结果说明](../../../../../docs/api/vision_results/)
--- a/examples/vision/ocr/PPOCRSystemv3/cpp/README.md
+++ b/examples/vision/ocr/PPOCRSystemv3/cpp/README.md
@@ -40,6 +40,9 @@ wget https://gitee.com/paddlepaddle/PaddleOCR/raw/release/2.6/ppocr/utils/ppocr_
 ./infer_demo ./ch_PP-OCRv3_det_infer ./ch_ppocr_mobile_v2.0_cls_infer ./ch_PP-OCRv3_rec_infer ./ppocr_keys_v1.txt ./12.jpg 2
 ```

+以上命令只适用于Linux或MacOS, Windows下SDK的使用方式请参考:  
+- [如何在Windows中使用FastDeploy C++ SDK](../../../../../docs/compile/how_to_use_sdk_on_windows.md)
+
 运行完成可视化结果如下图所示

 <img width="640" src="https://user-images.githubusercontent.com/109218879/185826024-f7593a0c-1bd2-4a60-b76c-15588484fa08.jpg">
@@ -55,7 +58,7 @@ fastdeploy::application::ocrsystem::PPOCRSystemv3(fastdeploy::vision::ocr::DBDet
                fastdeploy::vision::ocr::Recognizer* rec_model);
 ```

-PPOCRSystemv2 的初始化，由检测，分类和识别模型串联构成
+PPOCRSystemv3 的初始化，由检测，分类和识别模型串联构成

 **参数**

@@ -67,7 +70,7 @@ PPOCRSystemv2 的初始化，由检测，分类和识别模型串联构成
 fastdeploy::application::ocrsystem::PPOCRSystemv3(fastdeploy::vision::ocr::DBDetector* det_model,
                fastdeploy::vision::ocr::Recognizer* rec_model);
 ```
-PPOCRSystemv2 的初始化，由检测，识别模型串联构成(无分类器)
+PPOCRSystemv3 的初始化，由检测，识别模型串联构成(无分类器)

 **参数**

@@ -76,18 +79,16 @@ PPOCRSystemv2 的初始化，由检测，识别模型串联构成(无分类器)

 #### Predict函数

-> ```
-> std::vector<std::vector<fastdeploy::vision::OCRResult>> ocr_results =
-> PPOCRSystemv3.Predict(std::vector<cv::Mat> cv_all_imgs);
->  
+> ```  
+> bool Predict(cv::Mat* img, fastdeploy::vision::OCRResult* result);
 > ```
 >
-> 模型预测接口，输入一个可装入多张图片的图片列表，后可输出检测结果。
+> 模型预测接口，输入一张图片，返回OCR预测结果
 >
 > **参数**
 >
-> > * **cv_all_imgs**: 输入图像，注意需为HWC，BGR格式
-> > * **ocr_results**: OCR结果,包括由检测模型输出的检测框位置,分类模型输出的方向分类,以及识别模型输出的识别结果, OCRResult说明参考[视觉模型预测结果](../../../../../docs/api/vision_results/)
+> > * **img**: 输入图像，注意需为HWC，BGR格式
+> > * **result**: OCR预测结果,包括由检测模型输出的检测框位置,分类模型输出的方向分类,以及识别模型输出的识别结果, OCRResult说明参考[视觉模型预测结果](../../../../../docs/api/vision_results/)


 ## DBDetector C++接口
@@ -141,7 +142,8 @@ Recognizer类初始化时,需要在label_path参数中,输入识别模型所需

 > > * **cls_thresh**(double): 当分类模型输出的得分超过此阈值，输入的图片将被翻转，默认为0.9

+## 其它文档

- [模型介绍](../../)
- [Python部署](../python)
- [视觉模型预测结果](../../../../../docs/api/vision_results/)
+- [PPOCR 系列模型介绍](../../)
+- [PPOCRv3 Python部署](../python)
+- [模型预测结果说明](../../../../../docs/api/vision_results/)
--- a/examples/vision/ocr/PPOCRSystemv3/python/README.md
+++ b/examples/vision/ocr/PPOCRSystemv3/python/README.md
@@ -41,29 +41,27 @@ python infer.py --det_model ch_PP-OCRv3_det_infer --cls_model ch_ppocr_mobile_v2
 ## PPOCRSystemv3 Python接口

 ```
-fastdeploy.vision.ocr.PPOCRSystemv3(ocr_det = det_model._model, ocr_cls = cls_model._model, ocr_rec = rec_model._model)
+fd.vision.ocr.PPOCRSystemv3(det_model=det_model, cls_model=cls_model, rec_model=rec_model)
 ```
-
-PPOCRSystemv3的初始化,输入的参数是检测模型，分类模型和识别模型
+PPOCRSystemv3的初始化,输入的参数是检测模型，分类模型和识别模型，其中cls_model可选，如无需求，可设置为None

 **参数**

-> * **ocr_det**(model): OCR中的检测模型
-> * **ocr_cls**(model): OCR中的分类模型
-> * **ocr_rec**(model): OCR中的识别模型
+> * **det_model**(model): OCR中的检测模型
+> * **cls_model**(model): OCR中的分类模型
+> * **rec_model**(model): OCR中的识别模型

 ### predict函数

 > ```
-> result = PPOCRSystemv3.predict(img_list)
+> result = ocr_system.predict(im)
 > ```
 >
-> 模型预测接口，输入的是一个可包含多个图像的list
+> 模型预测接口，输入是一张图片
 >
 > **参数**
 >
-> > * **img_list**(list[np.ndarray]): 输入数据的list，每张图片注意需为HWC，BGR格式
-> > * **result**(float): OCR结果,包括由检测模型输出的检测框位置,分类模型输出的方向分类,以及识别模型输出的识别结果,
+> > * **im**(np.ndarray): 输入数据，每张图片注意需为HWC，BGR格式

 > **返回**
 >
@@ -123,6 +121,6 @@ Recognizer类初始化时,需要在rec_label_file参数中,输入识别模型所

 ## 其它文档

- [PPOCR系列模型介绍](../../)
+- [PPOCR 系列模型介绍](../../)
 - [PPOCRv3 C++部署](../cpp)
 - [模型预测结果说明](../../../../../docs/api/vision_results/)
--- a/examples/vision/ocr/README.md
+++ b/examples/vision/ocr/README.md
@@ -17,8 +17,3 @@
 | PPOCRv2_mobile |[ch_ppocr_mobile_v2.0_det](https://bj.bcebos.com/paddlehub/fastdeploy/ch_ppocr_mobile_v2.0_det_infer.tar.gz) | [ch_ppocr_mobile_v2.0_cls](https://bj.bcebos.com/paddlehub/fastdeploy/ch_ppocr_mobile_v2.0_cls_infer.tar.gz) | [ch_ppocr_mobile_v2.0_rec](https://bj.bcebos.com/paddlehub/fastdeploy/ch_ppocr_mobile_v2.0_rec_infer.tar.gz) | [ppocr_keys_v1.txt](https://bj.bcebos.com/paddlehub/fastdeploy/ppocr_keys_v1.txt) | OCRv2系列原始超轻量模型，支持中英文、多语种文本检测,比PPOCRv2更加轻量 |
 | PPOCRv2_server |[ch_ppocr_server_v2.0_det](https://bj.bcebos.com/paddlehub/fastdeploy/ch_ppocr_server_v2.0_det_infer.tar.gz) | [ch_ppocr_mobile_v2.0_cls](https://bj.bcebos.com/paddlehub/fastdeploy/ch_ppocr_mobile_v2.0_cls_infer.tar.gz) | [ch_ppocr_server_v2.0_rec](https://bj.bcebos.com/paddlehub/fastdeploy/ch_ppocr_server_v2.0_rec_infer.tar.gz) |[ppocr_keys_v1.txt](https://bj.bcebos.com/paddlehub/fastdeploy/ppocr_keys_v1.txt) | OCRv2服务器系列模型, 支持中英文、多语种文本检测，比超轻量模型更大，但效果更好|

-
-## 详细部署文档
-
- [Python部署](python)
- [C++部署](cpp)
--- a/fastdeploy/vision/vision_pybind.cc
+++ b/fastdeploy/vision/vision_pybind.cc
@@ -56,7 +56,7 @@ void BindVision(pybind11::module& m) {
      .def(pybind11::init())
      .def_readwrite("boxes", &vision::OCRResult::boxes)
      .def_readwrite("text", &vision::OCRResult::text)
-      .def_readwrite("score", &vision::OCRResult::rec_scores)
+      .def_readwrite("rec_scores", &vision::OCRResult::rec_scores)
      .def_readwrite("cls_scores", &vision::OCRResult::cls_scores)
      .def_readwrite("cls_labels", &vision::OCRResult::cls_labels)
      .def("__repr__", &vision::OCRResult::Str)