移动侦测跟踪算法

REVISION HISTORY¶

Revision No.	Description	Date
1.0	First version	11/21/2023
2.0	Sync with latest api	08/06/2024

1. 概述¶

1.1. 算法说明¶

移动侦测跟踪算法实现对画面中的运动物体的检测和跟踪。

2. API参考¶

该功能模块提供以下API:

API名称	功能
ALGO_MDT_CreateHandle	创建句柄
ALGO_MDT_InitHandle	初始化句柄
ALGO_MDT_SetParams	设置算法的可定制参数
ALGO_MDT_Run	运行移动侦测和跟踪算法
ALGO_MDT_Track	运行跟踪算法
ALGO_MDT_GetMdMask	获取运动区域的mask
ALGO_MDT_DeinitHandle	反初始化句柄
ALGO_MDT_ReleaseHandle	释放句柄
ALGO_MDT_Detect	运行移动侦测算法

2.1. ALGO_MDT_CreateHandle¶

功能

创建算法句柄。

语法

MI_S32 ALGO_MDT_CreateHandle(void **handle);

形参

参数名称描述输入/输出

handle 指向句柄的指针输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.2. ALGO_MDT_InitHandle¶

功能

初始化算法句柄。

语法

MI_S32 ALGO_MDT_InitHandle(void *handle, const MdtInit_t *init_info);

形参

参数名称描述输入/输出

handle 句柄输入

init_info 算法初始化参数（详见MdtInit_t）输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.3. ALGO_MDT_SetParams¶

功能

设置算法的可定制参数。

语法

MI_S32 ALGO_MDT_SetParams(void *handle, const MdtParams_t *params);

形参

参数名称描述输入/输出

handle 句柄输入

params 算法可定制参数（详见MdtParams_t ）输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.4. ALGO_MDT_Run¶

功能

运行运动目标检测和跟踪算法。

语法

MI_S32 ALGO_MDT_Run(void *handle, const MdtInput_t* prev_frame, const MdtInput_t* current_frame, MdtBox_t boxes[MAX_NUM_MDT_OBJS], MI_S32 *num_boxes);

形参

参数名称	描述	输入/输出
handle	句柄	输入
prev_frame	前一帧输入图像的结构体指针（详见MdtInput_t）	输入
current_frame	当前帧输入图像的结构体指针（详见MdtInput_t）	输入
boxes	用于保存输出结果框的数组（详见MdtBox_t）	输出
num_boxes	用于保存输出结果框个数的指针	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.5. ALGO_MDT_Track¶

功能

运行跟踪算法。

语法

MI_S32 ALGO_MDT_Track(void *handle, const MdtInput_t* current_frame, MdtBox_t boxes[MAX_NUM_MDT_OBJS], MI_S32 *num_boxes, MdtStage_e *mdt_stage);

形参

参数名称	描述	输入/输出
handle	句柄	输入
current_frame	当前帧输入图像的结构体指针（详见MdtInput_t）	输入
boxes	既是输入也是输出结果框，输入是检测的结果，输出是跟踪后的结果（详见MdtBox_t）	输入/输出
num_boxes	既是输入也是输出，输入是检测结果框的个数，输出是跟踪结果框个数的指针	输入/输出
mdt_stage	算法模式的指针（详见MdtStage_e）	输入

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.6. ALGO_MDT_GetMdMask¶

功能

获取运动区域的mask。

语法

MI_S32 ALGO_MDT_GetMdMask(void *handle, const MdtInput_t *prev_frame, const MdtInput_t *current_frame, MI_U8* mask, MI_S32 mask_w, MI_S32 mask_h);

形参

参数名称	描述	输入/输出
handle	句柄	输入
prev_frame	前一帧输入图像的结构体指针（详见MdtInput_t）	输入
current_frame	当前帧输入图像的结构体指针（详见MdtInput_t）	输入
mask	用于保存mask数据的内存指针（需要外部分配且长度必须为mask_w*mask_height），运动区域值为255，静止区域值为0	输出
mask_w	mask的宽度	输入
mask_h	mask的高度	输入

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.7. ALGO_MDT_DeinitHandle¶

功能

反初始化句柄。

语法

MI_S32 ALGO_MDT_DeinitHandle(void *handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.8. ALGO_MDT_ReleaseHandle¶

功能

释放句柄。

语法

MI_S32 ALGO_MDT_ReleaseHandle(void *handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

2.9. ALGO_MDT_Detect¶

功能

运行运动目标检测算法。

语法

MI_S32 ALGO_MDT_Detect(void *handle, const MdtInput_t *prev_frame, const MdtInput_t *current_frame, MdtBox_t boxes[MAX_NUM_MDT_OBJS], MI_S32 *num_boxes);

形参

参数名称	描述	输入/输出
handle	句柄	输入
prev_frame	前一帧输入图像的结构体指针（详见MdtInput_t）	输入
current_frame	当前帧输入图像的结构体指针（详见MdtInput_t）	输入
boxes	用于保存输出结果框的数组（详见MdtBox_t）	输出
num_boxes	用于保存输出结果框个数的指针	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖
- 头文件：sgs_mdt_api.h
- 库文件：libsgsalgo_mdt.a / libsgsalgo_mdt.so

3. 结构体说明¶

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

数据类型	定义
MdtInit_t	算法初始化参数结构体
MdtParams_t	算法可定制参数结构体
MdtInput_t	算法输入图像帧结构体
MdtBox_t	算法输出框结构体
MdtStage_e	算法模式

3.1 MdtInit_t¶

说明

算法初始化参数结构体。

定义

typedef struct
{
    MI_S32 ive_handle;
    MI_U32 in_width;
    MI_U32 in_height;
    MI_U32 in_stride;
} MdtInit_t;

成员

成员名称描述

ive_handle MI_IVE模块的handle

in_width 输出图像的宽度

in_height 输出图像的高度

in_stride 输出图像buffer进行内存对齐后的行长度
相关数据类型及接口

ALGO_MDT_InitHandle

3.2 MdtParams_t¶

说明

算法可定制参数结构体。

定义

typedef struct
{
    MI_FLOAT track_threshold;   // 0.0 ~ 1.0 default 0.3
    MI_U8 detect_threshold;     // 0 ~ 255, default 8
    MI_FLOAT min_width;         // 0.0 ~ 1.0 default 0.06
    MI_FLOAT min_height;        // 0.0 ~ 1.0 default 0.1
    MI_FLOAT max_width;         // 0.0 ~ 1.0 default 0.3
    MI_FLOAT max_height;        // 0.0 ~ 1.0 default 1.0
    MI_FLOAT max_frame_gap;     // 0.0 ms ~ INF ms default 100ms
} MdtParams_t;

成员

成员名称	描述
track_threshold	跟踪算法的阈值，取值越小跟踪连贯性更好但是跟踪准确度越低，范围0-1，默认值0.3
detect_threshold	检测算法的阈值（判定运动物体的最小帧间差异），取值越小检测灵敏度越高，范围0-255，默认值8
min_width	最小目标宽度（归一化，相对于整个画面的宽度），范围0-1，默认值0.06
min_height	最小目标高度（归一化，相对于整个画面的高度），范围0-1，默认值0.1
max_width	最大目标宽度（归一化，相对于整个画面的宽度），范围0-1，默认值0.3
max_height	最大目标宽度（归一化，相对于整个画面的高度），范围0-1，默认值1.0
max_frame_gap	最大帧间间隔时间（间隔超过这一时间的两帧将会被忽略，当不需要对帧间间隔过滤时可设置为0.0，单位ms），默认值100.0

相关数据类型及接口

ALGO_MDT_SetParams

3.3 MdtInput_t¶

说明

输入图像帧的信息结构体。

定义

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

成员

成员名称描述

p_vir_addr 输入图像帧的虚拟地址

phy_addr 输入图像帧的物理地址

buf_size 输入图像帧的buffer长度

pts 输入图像帧的时间戳
相关数据类型及接口

ALGO_MDT_Run

ALGO_MDT_Track

ALGO_MDT_GetMdMask

3.4 MdtBox_t¶

说明

算法输出框的结构体。

定义

typedef struct
{
    MI_U32 x;
    MI_U32 y;
    MI_U32 width;
    MI_U32 height;
    MI_FLOAT score;
    MI_U64 track_id;
    MI_U64 pts;
} MdtBox_t;

成员

成员名称描述

x，y, width, height 结果框的左上点坐标和宽高

score 跟踪结果的分值

track_id 跟踪id

pts 对应帧的时间戳
相关数据类型及接口

ALGO_MDT_Run

ALGO_MDT_Track

3.5 MdtStage_e¶

说明

算法模式。

定义

typedef enum
{
    E_MDT_STAGE_INIT = 0,
    E_MDT_STAGE_DETECT,
    E_MDT_STAGE_TRACK,
} MdtStage_e;

成员

成员名称描述

E_MDT_STAGE_INIT 算法初始化

E_MDT_STAGE_DETECT 运动目标检测

E_MDT_STAGE_TRACK 运动目标跟踪
相关数据类型及接口

ALGO_MDT_Track

4. 错误码 ¶

错误码	数值	描述
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错误
E_ALGO_INVALID_FILE	15	无效的文件

成员名称	描述
ive_handle	MI_IVE模块的handle
in_width	输出图像的宽度
in_height	输出图像的高度
in_stride	输出图像buffer进行内存对齐后的行长度

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

成员名称	描述
x，y, width, height	结果框的左上点坐标和宽高
score	跟踪结果的分值
track_id	跟踪id
pts	对应帧的时间戳

成员名称	描述
E_MDT_STAGE_INIT	算法初始化
E_MDT_STAGE_DETECT	运动目标检测
E_MDT_STAGE_TRACK	运动目标跟踪

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

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

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

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