# ms_plugin_prototype

**Repository Path**: ziruiwu/ms_plugin_prototype

## Basic Information

- **Project Name**: ms_plugin_prototype
- **Description**: No description available
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-02-06
- **Last Updated**: 2021-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dataset Plugin

## 简介

datataset plugin 是为 mindspore dataset 数据处理提供插件功能的模块。 此模块囊括了为特定领域（遥感，医疗，气象等）量身制作的但并不经常被大众用户使用的算子。同时dataset plugin也为公共开发者针对mindspore dataset编写独立于mindspore主仓的新算子提供便捷易用的入口。 用户可以通过此模块，执行特定领域的算子或者编写自定义的C++算子。


![](./design.png)


较之于纯Python的算子，dataset plugin算子不受限于Python GIL，顾可以更加高效的执行算子。
## 编程指南和设计:
[请参考此文档](./programming_guide.md)

## 编译和安装:

请按照以下步骤操作编译并安装 dataset plugin：
请尽量确保您使用与Mindspore相同的conda环境来编译dataset plugin。
需要注意的是，dataset plugin目前仅仅支持Linux环境下的编译。
```sh
# 编译release的代码，首次编译由于第三方库的下载和编译，需要稍长的时间
./build.sh -r
# 进入生成whl文件的路径
cd build/package/dist/
# 使用pip安装whl包，请再次确认mindspore已经被安装
pip install dataset_plugin*.whl
# 若之前已经安装了dataset plugin，可以用如下命令卸载并重新安装whl包
pip install --upgrade --force-reinstall dataset_plugin*.whl
```
## 单元用例:
此用例是针对GDALDecode的测试。 其的目是测试dataset plugin 是否可以被动态加载，数据是否可以从mindpore流向插件，执行函数，再由插件返回mindpore。
```sh
# 在运行之前请确保mindspore已经在同一个环境下被安装
cd test
python test_dataset_plugin.py
```
如果测试成功，则可以看到以下输出：
```
Imagefolder + map(plugin_decode): (225, 400, 3)
Imagefolder + map(plugin_decode): (168, 300, 3)
Generator(path to image) + map(plugin_decode): (112, 200, 3)
Generator(path to image) + map(plugin_decode): (56, 100, 3)
```
## 性能测试:
该测试的目的是比较```GDALDecode```与mindspore dataset内置的```Decode```算子的效率。使用的source算子是```ImageFolderDataset```。
```sh
cd scripts
python test_plugin_decode_perf.py --path="/path/to/imagefolder/dataset"
```
如果运行成功，则可以到类似以下的输出：
```
../test/test_data  contains  4 images in total.
{'decode': 'plugin', 'num_samples': 4, 'time_elapsed': 0.0578, 'avg_row_time': 0.0144}
{'decode': 'minddata', 'num_samples': 4, 'time_elapsed': 0.0308, 'avg_row_time': 0.0077}
```
此文件夹内包含的其余测试脚本不在此赘述。

## 支持的算子:

- GDALDecode (支持通过文件名或图像原始数据的解码，详情参考[```test_dataset_plugin.py```](./test/test_dataset_plugin.py)）
- NoOp

## 路径结构:

```
cmake                   #  包含与第三方依赖项相关的cmake和打包whl文件等...
dataset_dependency     #  包含mindspore和dataset_plugin共同依赖的文件
└── shared_include.h
dataset_plugin         # 包含全部的源代码
├── ccsrc               #  包含全部C++源代码
└── dataset_plugin     #  包含了生成Python whl文件的代码
    ├── __init__.py
    └── gdal.py
test                    # 包含测试用例的脚本
├── test_data
```
## 已知问题:
#1 针对同一张图片, ```GDALDecode``` 可能会返回单通道图片，然而 ```c_transforms.Decode``` 会返回三通道的图片。
原因: 无论图片本身的通道数量，```c_transforms.Decode``` 会自动讲读取到底图片转换为三通道的RGB图片. ```GDALDecode``` 并不包含此逻辑，而是尊重图片本身的通道数量。

## 常见错误和解决方案:

错误 #1: 编译器提示缺少sqlite3
解决方案： ```conda install sqlite``` 或者更新到最新的dataset plugin。
原因: 早期的dataset plugin并没用直接引入sqlite3作为其的依赖库，故编译时若系统不自带，则可能报错。

错误 #2: 在执行用例```python test_dataset_plugin```时，遇到内存转储(core dump) 或者 指针释放错误（free pointer error
解决方案: 在根目录下的[CMakeLists.txt](./CMakeLists.txt)文件中找到此行 ```add_compile_definitions(_GLIBCXX_USE_CXX11_ABI=1)``` 若此数值为0，则将之设置成1。若此数值为1，则将之设置成0。
原因: C ++有两种不同的```std :: string```实现方式。使用不同方式的```std::string```的程序在API调用中会出现错误。此处的宏的调整(MACRO)确保了在两个仓中的```std::string```的实现相同。

错误 #3: 在执行用例```python test_dataset_plugin.py```时，遇到以下错误:
```ModuleNotFoundError: No module named 'mindspore'```
解决方案: 请参考[此链接](https://mindspore.cn/install)安装mindspore。
原因: dataset plugin内部调用了mindspore的python文件，从而需要依赖mindspore执行。