检测算法

REVISION HISTORY¶

Revision No.	Description	Date
1.0	First version	04/25/2023
1.1	Second version	10/30/2023
3.0	Third version	04/11/2024
3.1	Remove deprecated models introduction	10/31/2024
3.2	Add ALGO_DET_SortResult API	12/03/2024
3.3	Adjust models description	12/06/2024

1. 概述¶

1.1. 算法说明¶

主要检测算法的检测类别说明如下：

人脸检测(SYFL)输出的类别共1类，分别为人脸(class_id=0);
火焰烟雾(SFSD)输出的类别共2类，分别为火焰(class_id=0)、烟雾(class_id=1);
人+车+宠物+人头+人脸检测(SD)输出的类别共10类，分别为行人(class_id=0)、自行车(class_id=1)、轿车(class_id=2) 、摩托车(class_id=3)、公交车(class_id=4)、卡车(class_id=5)、猫(class_id=6)、狗(class_id=7)、人头(class_id=8)、人脸(class_id=9);
人+人头+人脸检测(SPD)输出的类别共3类，分别为行人(class_id=0)、人头(class_id=1)、人脸(class_id=2);
包裹检测(SBD)输出的类别共1类，分别为包裹(class_id=0);
模型命名中的y表示YUV输入; 数字表示分辨率，具体分辨率可以通过ALGO_DET_GetInputAttr 获取;

2. API参考¶

该功能模块提供以下API:

API名称	功能
ALGO_DET_CreateHandle	创建句柄
ALGO_DET_InitHandle	初始化句柄
ALGO_DET_SetParams	设置可配置参数
ALGO_DET_GetInputAttr	获取模型的输入属性信息
ALGO_DET_Run	运行检测算法
ALGO_DET_SortResult	对检测结果进行排序
ALGO_DET_DeinitHandle	反初始化句柄
ALGO_DET_ReleaseHandle	释放句柄

2.1 ALGO_DET_CreateHandle¶

功能

创建句柄

语法

MI_S32 ALGO_DET_CreateHandle(void **handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.2 ALGO_DET_InitHandle¶

功能

初始化句柄

语法

MI_S32 ALGO_DET_InitHandle(void *handle, DetInit_t *init_info);

形参

参数名称描述输入/输出

handle 句柄输入

init_info 检测算法配置项,详见DetInit_t 输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.3 ALGO_DET_SetParams¶

功能

设置检测算法的可配置参数

语法

MI_S32 ALGO_DET_SetParams(void *handle, const DetParams_t *params);

形参

参数名称描述输入/输出

handle 句柄输入

params 可配置参数输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.4 ALGO_DET_GetInputAttr¶

功能

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

语法

MI_S32 ALGO_DET_GetInputAttr(void *handle, DetInputAttr_t *input_attr);

形参

参数名称描述输入/输出

handle 句柄输入

input_attr 保存模型输入属性的指针，详见DetInputAttr_t 输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.5 ALGO_DET_Run¶

功能

运行检测算法

语法

MI_S32 ALGO_DET_Run(void *handle, const DetInput_t *algo_input, DetBox_t bboxes[MAX_DET_OBJECT], MI_S32 *num_bboxes);

形参

参数名称	描述	输入/输出
handle	句柄	输入
algo_input	输入图像的buffer信息	输入
bboxes	用于保存检测结果框的数组	输入
num_bboxes	用于保存检测结果框个数的指针	输入

返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.6. ALGO_DET_SortResult¶

功能

对检测结果进行排序

语法

MI_S32 ALGO_DET_SortResult(void *handle, const DetSortInput_t *sort_input, DetBox_t bboxes[MAX_DET_OBJECT], MI_S32 *num_bboxes);

形参

参数名称	描述	输入/输出
handle	句柄	输入
sort_input	排序输入结构体	输入
bboxes	用于保存排序结果框的数组	输入
num_bboxes	用于保存排序结果框个数的指针	输入

返回值

返回值描述

0 成功。注意：该接口会修改输入bboxes和num_bboxes

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.7 ALGO_DET_DeinitHandle¶

功能

反初始化检测算法

语法

MI_S32 ALGO_DET_DeinitHandle(void *handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

2.8 ALGO_DET_ReleaseHandle¶

功能

释放句柄占用资源

语法

MI_S32 ALGO_DET_ReleaseHandle(void *handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
依赖
- 头文件：sgs_det_api.h
- 库文件：libsgsalgo_det.a / libsgsalgo_det.so

3. 结构体说明¶

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

数据类型	定义
DetInputAttr_t	算法输入格式结构体
DetBox_t	算法输出结构体
DetInit_t	算法初始化参数相关结构体
DetInput_t	算法输入图像数据信息
DetParams_t	算法可配置参数结构体
DetSortInput_t	结果排序输入结构体

3.1 DetInputAttr_t¶

说明

定义模型的输入分辨率大小及pixel类型

定义

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

成员

成员名称描述

width 模型输入数据的宽

height 模型输入数据的高

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

ALGO_DET_GetInputAttr

3.2 DetBox_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;
}DetBox_t;

成员

成员名称描述

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

class_id 检测结果框的类别ID

score 检测结果框的分值

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

ALGO_DET_Run

3.3 DetInit_t¶

说明

检测算法初始化参数

定义

typedef struct
{
    char ipu_firmware_path[MAX_DET_STRLEN]; // ipu_firmware.bin path
    char model_path[MAX_DET_STRLEN];        // detect model path
    MI_BOOL create_device;                  // set false to create ipu device outside algo lib
    MI_BOOL destroy_device;                 // set false to destroy ipu device outside algo lib
    void *model_buffer;                     // set it when load model from memory
    MI_U32 model_buffer_len;                // set it when load model from memory
}DetInit_t;

成员

成员名称	描述
ipu_firmware_path	Ipu firmware路径
model_path	模型文件路径
create_device	是否在算法库内进行IPU device的创建，默认为true，即在库内创建，在需同时调用算法库时可设置为false并在外部手动创建IPU device
destroy_device	是否在算法库内进行IPU device的销毁，默认为true，即在库内销毁，在需同时调用算法库时可设置为false并在外部手动销毁IPU device
model_buffer	使用model_path时请设置为NULL，将model_path置空并且设置model_buffer和model_buffer_len可用于从模型内存块初始化算法
model_buffer_len	使用model_path时请设置为NULL，设置model_buffer内存块长度

相关数据类型及接口

ALGO_DET_InitHandle

3.4 DetInput_t¶

说明

检测算法输入

定义

typedef struct
{
    void *p_vir_addr;
    MI_PHY phy_addr;
    MI_U32 buf_size;
    MI_U64 pts;
    MI_U16 width;
    MI_U16 height;
}DetInput_t;

成员

成员名称	描述
p_vir_addr	输入buffer的虚拟地址
phy_addr	输入buffer的物理地址
buf_size	输入buffer的长度
pts	输入buffer时间戳
width	输入buffer帧像素宽度
height	输入buffer帧像素高度

相关数据类型及接口

ALGO_DET_Run

3.5 DetParams_t¶

说明

检测算法可配置项

定义

typedef struct
{
    MI_FLOAT conf_threshold;         // default=0.5
    MI_S32 disp_width;               // default=1920
    MI_S32 disp_height;              // default=1080
    MI_BOOL ignore_static_objects;   // default=false
    MI_FLOAT static_sensitive;       // default=0.85
    MI_BOOL stable_bbox;             // default=false
    MI_FLOAT stable_sensitive;       // default=0.63
    MI_S32 ignore_frame_number;      // [0-5] ignore the id first number box of detect,default=0
    MI_BOOL strict_mode;             // default=false
}DetParams_t;

成员

成员名称	描述
conf_threshold	检测目标的score阈值，取值0.0~1.0，默认0.5，数值调大：误检减少但召回率降低，数值调小：召回率提升但误检增多
disp_width	显示码流的分辨率宽度(用于映射检测框位置)，默认值1920
disp_height	显示码流的分辨率高度(用于映射检测框位置)，默认值1080
ignore_static_objects	是否忽略检测到的静态目标，默认值false，即不忽略
static_sensitive	判断物体是否为静态目标的灵敏度，取值0.0~1.0，默认值为0.85，取值越大越倾向于保留小幅运动的框
stable_bbox	是否开启稳框，默认值为false，即不开启
stable_sensitive	稳框算法的灵敏度，取值0.0~1.0，默认值为0.63，取值越小稳框效果越强
ignore_frame_number	设置忽略一个目标的检测到的前n帧，用于过滤偶尔闪现的误检,取值0~5,默认值为0，即不忽略
strict_mode	是否开启strict模式，开启后可降低误检，默认false

相关数据类型及接口

ALGO_DET_SetParams

3.6 DetSortInput_t¶

说明

检测算法相关配置项

定义

typedef struct
{
    MI_S32 class_indexs[MAX_DET_CLASSES];
    MI_S32 class_num;
    DetSortType_e sort_type;
}DetSortInput_t;

成员

成员名称描述

class_indexs 需要排序的类别索引

class_num 需要排序的类别数目

sort_type 排序方法类型
相关数据类型及接口

ALGO_DET_SortResult

4. 枚举类型说明¶

检测枚举类型定义如下：

数据类型	定义
Label_FD_Face_e	人脸检测算法class_id和类别名称的对应
Label_FSD_e	烟火检测算法class_id和类别名称的对应
Label_SD_e	人+车+宠物+人头+人脸检测算法class_id和类别名称的对应
Label_SPD_e	人+人头+人脸检测算法class_id和类别名称的对应
Label_BD_e	包裹检测算法class_id和类别名称的对应

4.1 Label_FD_Face_e¶

说明

人脸检测模型类别和class_id的对应关系

定义

typedef enum
{
    E_FD_FACE = 0,
}Label_FD_Face_e;

成员

成员名称描述

E_FD_FACE 人脸类别(class_id=0)
相关数据类型及接口

DetBox_t

4.2 Label_FSD_e¶

说明

定义火焰烟雾检测模型类别和class_id的对应关系

定义

typedef enum
{
    E_FSD_FIRE,
    E_FSD_SMOKE
}Label_FSD_e;

成员

成员名称描述

E_FSD_FIRE 火焰类别(class_id=0)

E_FSD_SMOKE 烟雾类别(class_id=1)
相关数据类型及接口

DetBox_t

4.3 Label_SD_e¶

说明

定义人+车+宠物+人头+人脸检测模型类别和class_id的对应关系

定义

typedef enum
{
    E_SD_PERSON = 0,
    E_SD_BICYCLE,
    E_SD_CAR,
    E_SD_MOTOCYCLE,
    E_SD_BUS,
    E_SD_TRUCK,
    E_SD_CAT,
    E_SD_DOG,
    E_SD_HEAD,
    E_SD_FACE,
}LABEL_SD_e;

成员

成员名称	描述
E_SD_PERSON	行人类别(class_id=0)
E_SD_BICYCLE	自行车类别(class_id=1)
E_SD_CAR	轿车类别(class_id=2)
E_SD_MOTOCYCLE	摩托车类别(class_id=3)
E_SD_BUS	公交车类别(class_id=4)
E_SD_TRUCK	卡车类别(class_id=5)
E_SD_CAT	猫类别(class_id=6)
E_SD_DOG	狗类别(class_id=7)
E_SD_HEAD	人头类别(class_id=8)
E_SD_FACE	人脸类别(class_id=9)

相关数据类型及接口

DetBox_t

4.4 Label_SPD_e¶

说明

定义人+人头+人脸检测模型类别和class_id的对应关系

定义

typedef enum
{
    E_SPD_PERSON = 0,
    E_SPD_HEAD,
    E_SPD_FACE
}LABEL_SPD_e;

成员

成员名称描述

E_SPD_PERSON 行人类别(class_id=0)

E_SPD_HEAD 人头类别(class_id=1)

E_SPD_FACE 人脸类别(class_id=2)
相关数据类型及接口

DetBox_t

4.5 Label_BD_e¶

说明

定义包裹检测模型类别和class_id的对应关系

定义

typedef enum
{
    E_BD_BAG = 0,
}LABEL_BD_e;

成员

成员名称描述

E_BD_BAG 包裹类别(class_id=0)
相关数据类型及接口

DetBox_t

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	无效的算法输出数据维度
E_ALGO_INVALID_DECODE_MODE	13	无效的解码模式
E_ALGO_MODEL_INVOKE_ERROR	14	模型invoke错误

返回值	描述
0	成功。注意：该接口会修改输入bboxes和num_bboxes
其它	失败(详见错误码)

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

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

成员名称	描述
class_indexs	需要排序的类别索引
class_num	需要排序的类别数目
sort_type	排序方法类型

成员名称	描述
E_FSD_FIRE	火焰类别(class_id=0)
E_FSD_SMOKE	烟雾类别(class_id=1)

成员名称	描述
E_SPD_PERSON	行人类别(class_id=0)
E_SPD_HEAD	人头类别(class_id=1)
E_SPD_FACE	人脸类别(class_id=2)