跨模态分割算法

REVISION HISTORY¶

Revision No.	Description	Date
1.0	First version	11/01/2023

1. 算法说明¶

跨模态分割算法(Open Vocabulary Segmentation，简称OvSeg)，可以根据文本提示搜索得到图像中的对应目标，并输出目标在图像中所处的mask区域，具备开放域目标的检测和分割能力。

2. API参考¶

该功能模块提供以下API:

API名称	功能
ALGO_OVSEG_CreateHandle	创建句柄
ALGO_OVSEG_InitHandle	初始化句柄
ALGO_OVSEG_GetInputAttr	获取模型的属性信息
ALGO_OVSEG_SetThreshold	设置阈值
ALGO_OVSEG_RunDet	运行检测算法
ALGO_OVSEG_RunSeg	运行分割算法
ALGO_OVSEG_DeinitHandle	终止算法
ALGO_OVSEG_ReleaseHandle	释放句柄

2.1 ALGO_OVSEG_CreateHandle¶

功能

创建句柄

语法

MI_S32 ALGO_OVSEG_CreateHandle(void **handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.2 ALGO_OVSEG_InitHandle¶

功能

初始化句柄

语法

MI_S32 ALGO_OVSEG_InitHandle(void *handle, OvSegInitInfo_t *init_info);

形参

参数名称描述输入/输出

handle 句柄输入

init_info 检测算法配置项，详见OvSegInitInfo_t 输入
返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.3 ALGO_OVSEG_GetInputAttr¶

功能

获取模型的属性信息，包括模型输入分辨率以及输入数据的类型

语法

MI_S32 ALGO_OVSEG_GetInputAttr(void *handle, OvSegInputAttr_t *input_attr);

形参

参数名称描述输入/输出

handle 句柄输入

input_attr 保存属性信息指针，详见OvSegInputAttr_t 输入
返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.4 ALGO_OVSEG_SetThreshold¶

功能

设置检测阈值

语法

MI_S32 ALGO_OVSEG_SetThreshold(void *handle, OvSegThreshold_t threshold);

形参

参数名称描述输入/输出

handle 句柄输入

threshold 阈值输入
返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.5 ALGO_OVSEG_RunDet¶

功能

运行检测算法，得到目标框（目前仅输出超过阈值并且分值最高的一个框）

语法

MI_S32 ALGO_OVSEG_RunDet(void* handle, const OvSegAlgo_Input_t *img_input, char* text, OvSegBox_t *bboxes, MI_S16* num_boxes);

形参

参数名称	描述	输入/输出
handle	句柄	输入
img_input	输入图像的buffer信息	输入
text	输入希望检测到的目标的文本	输入
bboxes	用于保存检测结果框的数组	输入
num_bboxes	用于保存检测结果框个数的指针	输入

返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.6 ALGO_OVSEG_RunSeg¶

功能

运行分割算法，得到检测目标的分割mask

语法

MI_S32 ALGO_OVSEG_RunSeg(void* handle, const OvSegAlgo_Input_t *img_input, const OvSegBox_t *in_box, MI_U8* out_mask, MI_S16 out_mask_w, MI_S16 out_mask_h, MI_S16 out_mask_stride);

形参

参数名称	描述	输入/输出
handle	句柄	输入
img_input	输入图像的buffer信息	输入
in_box	输入检测得到的目标框	输入
out_mask	输出分割结果的mask指针	输出
out_mask_w	输出分割结果的mask的宽度	输出
out_mask_h	输出分割结果的mask的高度	输出
out_mask_h	输出分割结果的mask每一行的字节数（用于适应存在内存对齐的情况）	输出

返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.7 ALGO_OVSEG_DeinitHandle¶

功能

停止算法

语法

MI_S32 ALGO_OVSEG_DeinitHandle(void *handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

2.8 ALGO_OVSEG_ReleaseHandle¶

功能

释放句柄占用资源

语法

MI_S32 ALGO_OVSEG_ReleaseHandle(void *handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败（详见错误码)
依赖
- 头文件：sstar_ovseg_api.h
- 库文件：libsstaralgo_ovseg.a

3. 数据类型¶

检测相关结构体定义如下：

数据类型	定义
OvSegInitInfo_t	算法初始化参数结构体
OvSegInputAttr_t	算法输入图像buffer结构体
OvSegThreshold_t	算法输入阈值结构体
OvSegBox_t	算法输出框结构体
OvSegAlgo_Input_t	算法输入图像数据信息

3.1 OvSegInitInfo_t¶

说明

算法初始化参数结构体

定义

typedef struct
{
    char ipu_firmware_path[OVSEG_MAX_STRLEN];
    char det_model_path[OVSEG_MAX_STRLEN];
    char seg_model_path[OVSEG_MAX_STRLEN];
    char vocab_path[OVSEG_MAX_STRLEN];
}OvSegInitInfo_t;

成员

成员名称	描述
ipu_firmware_path[MAX_OVSEG_STRLEN]	ipu_firmware_path路径
det_model_path[MAX_OVSEG_STRLEN]	检测模型文件路径
seg_model_path[MAX_OVSEG_STRLEN]	分割模型文件路径
vocab_path	词表文件路径

相关数据类型及接口

ALGO_OVSEG_InitHandle

3.2 OvSegInputAttr_t¶

说明

定义分辨率大小和模型输入像素类型

定义

typedef struct{
    MI_U32 width;
    MI_U32 height;
    MI_IPU_ELEMENT_FORMAT format;
}OvSegInputAttr_t;

成员

成员名称描述

width 模型输入数据的宽

height 模型输入数据的高

format 模型输入数据的类型
相关数据类型及接口

ALGO_OVSEG_GetInputAttr

3.3 OvSegThreshold_t¶

说明

定义模型的阈值

定义

typedef struct
{
    MI_FLOAT det_threshold;
    MI_FLOAT seg_threshold;
}OvSegThreshold_t;

成员

成员名称描述

det_threshold 检测模型的阈值

seg_threshold 分割模型的阈值
相关数据类型及接口

ALGO_OVSEG_SetThreshold

3.4 OvSegBox_t¶

说明

算法输出检测框结构体

定义

typedef struct
{
    MI_U32 x;
    MI_U32 y;
    MI_U32 width;
    MI_U32 height;
    MI_U32 class_id;
    MI_FLOAT score;
    MI_U64 pts;
}Box_t;

成员

成员名称描述

x，y, width, height 检测结果框的位置

class_id 检测结果框的类别ID

score 检测结果框的分值

pts 送入检测帧的时间戳
相关数据类型及接口

ALGO_OVSEG_RunDet

ALGO_OVSEG_RunSeg

3.5 OvSegAlgo_Input_t¶

说明

检测/分割算法的输入buffer数据结构

定义

typedef struct
{
    void *p_vir_addr;
    MI_PHY phy_addr;
    MI_U32 buf_size;
    MI_U64 pts;
}OvSegAlgo_Input_t;

成员

成员名称描述

p_vir_addr 输入buffer的虚拟地址

phy_addr 输入buffer的物理地址

buf_size 输入buffer的长度

pts 输入buffer时间戳
相关数据类型及接口

ALGO_OVSEG_RunDet

ALGO_OVSEG_RunSeg

5. 错误码 ¶

错误码	数值	描述
E_ALGO_SUCCESS	0	操作成功
E_ALGO_HANDLE_NULL	1	算法句柄为空
E_ALGO_INVALID_PARAM	2	无效的输入参数
E_ALGO_DEVICE_FAULT	3	硬件错误
E_ALGO_LOADMODEL_FAIL	4	加载模型失败
E_ALGO_INIT_FAIL	5	算法初始化失败
E_ALGO_NOT_INIT	6	算法尚未初始化
E_ALGO_INPUT_DATA_NULL	7	算法输入数据为空
E_ALGO_INVALID_INPUT_SIZE	8	无效的算法输入数据维度
E_ALGO_INVALID_LICENSE	9	无效的license许可
E_ALGO_MEMORY_OUT	10	内存不足
E_ALGO_FILEIO_ERROR	11	文件读写操作错误
E_ALGO_INVALID_OUTPUT_SIZE	12	无效的算法输出数据维度

成员名称	描述
width	模型输入数据的宽
height	模型输入数据的高
format	模型输入数据的类型

成员名称	描述
det_threshold	检测模型的阈值
seg_threshold	分割模型的阈值

成员名称	描述
x，y, width, height	检测结果框的位置
class_id	检测结果框的类别ID
score	检测结果框的分值
pts	送入检测帧的时间戳

成员名称	描述
p_vir_addr	输入buffer的虚拟地址
phy_addr	输入buffer的物理地址
buf_size	输入buffer的长度
pts	输入buffer时间戳

返回值	描述
0	成功
其它	失败（详见错误码)

返回值	描述
0	成功
其它	失败（详见错误码)

返回值	描述
0	成功
其它	失败（详见错误码)

返回值	描述
0	成功
其它	失败（详见错误码)