[Doc] Add docs for ppocr ppseg examples (#1429)

* add docs for examples * add english doc * fix * fix docs
2025-10-21 15:49:31 +08:00 · 2023-02-28 20:13:01 +08:00
parent 010f12db3d
commit c8bcada1a2
22 changed files with 2983 additions and 5 deletions
--- a/examples/vision/segmentation/paddleseg/cpu-gpu/c/README.md
+++ b/examples/vision/segmentation/paddleseg/cpu-gpu/c/README.md
@@ -0,0 +1,184 @@
+English | [简体中文](README_CN.md)
+# PaddleSeg C Deployment Example
+
+This directory provides `infer.c` to finish the deployment of PaddleSeg on CPU/GPU.
+
+Before deployment, two steps require confirmation
+
+- 1. Software and hardware should meet the requirements. Please refer to [FastDeploy Environment Requirements](../../../../../docs/en/build_and_install/download_prebuilt_libraries.md)  
+- 2.  Download the precompiled deployment library and samples code according to your development environment. Refer to [FastDeploy Precompiled Library](../../../../../docs/en/build_and_install/download_prebuilt_libraries.md)
+
+Taking inference on Linux as an example, the compilation test can be completed by executing the following command in this directory. FastDeploy version 1.0.4 or above (x.x.x>=1.0.4) is required to support this model.
+
+```bash
+mkdir build
+cd build
+# Download the FastDeploy precompiled library. Users can choose your appropriate version in the `FastDeploy Precompiled Library` mentioned above
+wget https://bj.bcebos.com/fastdeploy/release/cpp/fastdeploy-linux-x64-x.x.x.tgz
+tar xvf fastdeploy-linux-x64-x.x.x.tgz
+cmake .. -DFASTDEPLOY_INSTALL_DIR=${PWD}/fastdeploy-linux-x64-x.x.x
+make -j
+
+# Download model, image files
+wget https://bj.bcebos.com/paddlehub/fastdeploy/PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
+tar -xvf PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
+wget https://paddleseg.bj.bcebos.com/dygraph/demo/cityscapes_demo.png
+
+
+# CPU inference
+./infer_demo PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer cityscapes_demo.png 0
+# GPU inference
+./infer_demo PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer cityscapes_demo.png 1
+```
+
+The above command works for Linux or MacOS. For SDK in Windows, refer to:
+- [How to use FastDeploy C++ SDK in Windows](../../../../../docs/en/faq/use_sdk_on_windows.md)
+
+The visualized result after running is as follows
+
+<div  align="center">  
+<img src="https://user-images.githubusercontent.com/16222477/191712880-91ae128d-247a-43e0-b1e3-cafae78431e0.jpg", width=512px, height=256px />
+</div>
+
+
+## PaddleSeg C Interface
+
+### RuntimeOption
+
+```c
+FD_C_RuntimeOptionWrapper* FD_C_CreateRuntimeOptionWrapper()
+```
+
+> Create a RuntimeOption object, and return a pointer to manipulate it.
+>
+> **Return**
+>
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): Pointer to manipulate RuntimeOption object.
+
+
+```c
+void FD_C_RuntimeOptionWrapperUseCpu(
+     FD_C_RuntimeOptionWrapper* fd_c_runtime_option_wrapper)
+```
+
+> Enable Cpu inference.
+>
+> **Params**
+>
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): Pointer to manipulate RuntimeOption object.
+
+```c
+void FD_C_RuntimeOptionWrapperUseGpu(
+    FD_C_RuntimeOptionWrapper* fd_c_runtime_option_wrapper,
+    int gpu_id)
+```
+> Enable Gpu inference.
+>
+> **Params**
+>
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): Pointer to manipulate RuntimeOption object.
+
+> * **gpu_id**(int): gpu id
+
+
+### Model
+
+```c
+FD_C_PaddleSegWrapper* FD_C_CreatePaddleSegWrapper(
+    const char* model_file, const char* params_file, const char* config_file,
+    FD_C_RuntimeOptionWrapper* fd_c_runtime_option_wrapper,
+    const FD_C_ModelFormat model_format
+)
+```
+
+> Create a PaddleSeg model object, and return a pointer to manipulate it.
+>
+> **Params**
+>
+> * **model_file**(const char*): Model file path
+> * **params_file**(const char*): Parameter file path
+> * **config_file**(const char*): config file path
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): Backend inference configuration. None by default, which is the default configuration
+> * **model_format**(FD_C_ModelFormat): Model format
+>
+> **Return**
+>
+> * **fd_c_ppseg_wrapper**(FD_C_PaddleSegWrapper*): Pointer to manipulate PaddleSeg object.
+
+
+
+#### Read and write image
+
+```c
+FD_C_Mat FD_C_Imread(const char* imgpath)
+```
+
+> Read an image, and return a pointer to cv::Mat.
+>
+> **Params**
+>
+> * **imgpath**(const char*): image path
+>
+> **Return**
+>
+> * **imgmat**(FD_C_Mat): pointer to cv::Mat object which holds the image.
+
+
+```c
+FD_C_Bool FD_C_Imwrite(const char* savepath,  FD_C_Mat img);
+```
+
+> Write image to a file.
+>
+> **Params**
+>
+> * **savepath**(const char*): save path
+> * **img**(FD_C_Mat): pointer to cv::Mat object
+>
+> **Return**
+>
+> * **result**(FD_C_Bool): bool to indicate success or failure
+
+
+#### Prediction
+
+```c
+FD_C_Bool FD_C_PaddleSegWrapperPredict(
+    FD_C_PaddleSegWrapper* fd_c_ppseg_wrapper,
+    FD_C_Mat img,
+    FD_C_SegmentationResult* result)
+```
+>
+> Predict an image, and generate result.
+>
+> **Params**
+> * **fd_c_ppseg_wrapper**(FD_C_PaddleSegWrapper*): Pointer to manipulate PaddleSeg object.
+> * **img**（FD_C_Mat）: pointer to cv::Mat object, which can be obained by FD_C_Imread interface
+> * **result**(FD_C_SegmentationResult*): Segmentation prediction results, Refer to [Vision Model Prediction Results](../../../../../docs/api/vision_results/) for SegmentationResult
+
+
+#### Result
+
+```c
+FD_C_Mat FD_C_VisSegmentation(FD_C_Mat im,
+                              FD_C_SegmentationResult* result,
+                              float weight)
+```
+>
+> Visualize segmentation results and return visualization image.
+>
+> **Params**
+> * **im**(FD_C_Mat): pointer to input image
+> * **segmentation_result**(FD_C_SegmentationResult*): pointer to C FD_C_SegmentationResult structure
+> * **weight**(float): weight transparent weight of visualized result image
+>
+> **Return**
+> * **vis_im**(FD_C_Mat): pointer to visualization image.
+
+
+## Other Documents
+
+- [PPSegmentation Model Description](../../)
+- [PaddleSeg Python Deployment](../python)
+- [Model Prediction Results](../../../../../docs/api/vision_results/)
+- [How to switch the model inference backend engine](../../../../../docs/cn/faq/how_to_change_backend.md)
--- a/examples/vision/segmentation/paddleseg/cpu-gpu/c/README_CN.md
+++ b/examples/vision/segmentation/paddleseg/cpu-gpu/c/README_CN.md
@@ -0,0 +1,185 @@
+[English](README.md) | 简体中文
+# PaddleSeg C部署示例
+
+本目录下提供`infer.c`来调用C API快速完成PaddleSeg模型在CPU/GPU上部署的示例。
+
+在部署前，需确认以下两个步骤
+
+- 1. 软硬件环境满足要求，参考[FastDeploy环境要求](../../../../../docs/cn/build_and_install/download_prebuilt_libraries.md)  
+- 2. 根据开发环境，下载预编译部署库和samples代码，参考[FastDeploy预编译库](../../../../../docs/cn/build_and_install/download_prebuilt_libraries.md)
+
+以Linux上推理为例，在本目录执行如下命令即可完成编译测试，支持此模型需保证FastDeploy版本1.0.4以上(x.x.x>=1.0.4)
+
+```bash
+mkdir build
+cd build
+# 下载FastDeploy预编译库，用户可在上文提到的`FastDeploy预编译库`中自行选择合适的版本使用
+wget https://bj.bcebos.com/fastdeploy/release/cpp/fastdeploy-linux-x64-x.x.x.tgz
+tar xvf fastdeploy-linux-x64-x.x.x.tgz
+cmake .. -DFASTDEPLOY_INSTALL_DIR=${PWD}/fastdeploy-linux-x64-x.x.x
+make -j
+
+# 下载PP-LiteSeg模型文件和测试图片
+wget https://bj.bcebos.com/paddlehub/fastdeploy/PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
+tar -xvf PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
+wget https://paddleseg.bj.bcebos.com/dygraph/demo/cityscapes_demo.png
+
+
+# CPU推理
+./infer_demo PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer cityscapes_demo.png 0
+# GPU推理
+./infer_demo PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer cityscapes_demo.png 1
+```
+
+以上命令只适用于Linux或MacOS, Windows下SDK的使用方式请参考:  
+- [如何在Windows中使用FastDeploy C++ SDK](../../../../../docs/cn/faq/use_sdk_on_windows.md)
+
+如果用户使用华为昇腾NPU部署, 请参考以下方式在部署前初始化部署环境:
+- [如何使用华为昇腾NPU部署](../../../../../docs/cn/faq/use_sdk_on_ascend.md)
+
+运行完成可视化结果如下图所示
+
+<div  align="center">  
+<img src="https://user-images.githubusercontent.com/16222477/191712880-91ae128d-247a-43e0-b1e3-cafae78431e0.jpg", width=512px, height=256px />
+</div>
+
+
+## PaddleSeg C API接口
+
+### 配置
+
+```c
+FD_C_RuntimeOptionWrapper* FD_C_CreateRuntimeOptionWrapper()
+```
+
+> 创建一个RuntimeOption的配置对象，并且返回操作它的指针。
+>
+> **返回**
+>
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): 指向RuntimeOption对象的指针
+
+
+```c
+void FD_C_RuntimeOptionWrapperUseCpu(
+     FD_C_RuntimeOptionWrapper* fd_c_runtime_option_wrapper)
+```
+
+> 开启CPU推理
+>
+> **参数**
+>
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): 指向RuntimeOption对象的指针
+
+```c
+void FD_C_RuntimeOptionWrapperUseGpu(
+    FD_C_RuntimeOptionWrapper* fd_c_runtime_option_wrapper,
+    int gpu_id)
+```
+> 开启GPU推理
+>
+> **参数**
+>
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): 指向RuntimeOption对象的指针
+> * **gpu_id**(int): 显卡号
+
+
+### 模型
+
+```c
+FD_C_PaddleSegWrapper* FD_C_CreatePaddleSegWrapper(
+    const char* model_file, const char* params_file, const char* config_file,
+    FD_C_RuntimeOptionWrapper* fd_c_runtime_option_wrapper,
+    const FD_C_ModelFormat model_format
+)
+```
+> 创建一个PaddleSeg的模型，并且返回操作它的指针。
+>
+> **参数**
+>
+> * **model_file**(const char*): 模型文件路径
+> * **params_file**(const char*): 参数文件路径
+> * **config_file**(const char*): 配置文件路径
+> * **fd_c_runtime_option_wrapper**(FD_C_RuntimeOptionWrapper*): 指向RuntimeOption的指针，表示后端推理配置
+> * **model_format**(FD_C_ModelFormat): 模型格式
+>
+> **返回**
+>
+> * **fd_c_ppseg_wrapper**(FD_C_PaddleSegWrapper*): 指向PaddleSeg模型对象的指针
+
+
+
+#### 读写图像
+
+```c
+FD_C_Mat FD_C_Imread(const char* imgpath)
+```
+
+> 读取一个图像，并且返回cv::Mat的指针。
+>
+> **参数**
+>
+> * **imgpath**(const char*): 图像文件路径
+>
+> **返回**
+>
+> * **imgmat**(FD_C_Mat): 指向图像数据cv::Mat的指针。
+
+
+```c
+FD_C_Bool FD_C_Imwrite(const char* savepath,  FD_C_Mat img);
+```
+
+> 将图像写入文件中。
+>
+> **参数**
+>
+> * **savepath**(const char*): 保存图像的路径
+> * **img**(FD_C_Mat): 指向图像数据的指针
+>
+> **返回**
+>
+> * **result**(FD_C_Bool): 表示操作是否成功
+
+
+#### Predict函数
+
+```c
+FD_C_Bool FD_C_PaddleSegWrapperPredict(
+    FD_C_PaddleSegWrapper* fd_c_ppseg_wrapper,
+    FD_C_Mat img,
+    FD_C_SegmentationResult* result)
+```
+>
+> 模型预测接口，输入图像直接并生成分类结果。
+>
+> **参数**
+> * **fd_c_ppseg_wrapper**(FD_C_PaddleSegWrapper*): 指向PaddleSeg模型的指针
+> * **img**（FD_C_Mat）: 输入图像的指针，指向cv::Mat对象，可以调用FD_C_Imread读取图像获取
+> * **result**FD_C_SegmentationResult*): Segmentation检测结果，SegmentationResult说明参考[视觉模型预测结果](../../../../../docs/api/vision_results/)
+
+
+#### Predict结果
+
+```c
+FD_C_Mat FD_C_VisSegmentation(FD_C_Mat im,
+                              FD_C_SegmentationResult* result,
+                              float weight)
+```
+>
+> 对结果进行可视化，返回可视化的图像。
+>
+> **参数**
+> * **im**(FD_C_Mat): 指向输入图像的指针
+> * **segmentation_result**(FD_C_SegmentationResult*): 指向 FD_C_SegmentationResult结构的指针
+> * **weight**(float): 透明度权重
+>
+> **返回**
+> * **vis_im**(FD_C_Mat): 指向可视化图像的指针
+
+
+## 其它文档
+
+- [PPSegmentation 系列模型介绍](../../)
+- [PaddleSeg Python部署](../python)
+- [模型预测结果说明](../../../../../docs/api/vision_results/)
+- [如何切换模型推理后端引擎](../../../../../docs/cn/faq/how_to_change_backend.md)