Re-Identification算法说明¶

REVISION HISTORY¶

Revision No.	Description	Date
3.0	First version	05/14/2024

1. 概述¶

1.1. 算法说明¶

重识别算法(Re-Identification, ReID)包括以下功能：行人重识别、车辆重识别

主要算法模型说明如下：

模型	功能	输入维度(w*h)	输入格式
reid_person_12y.img	行人重识别模型	256*128	yuvsp420_nv12
reid_vehicle_22y.img	车辆重识别模型	256*256	yuvsp420_nv12

2. API参考¶

该功能模块提供以下API:

API名称	功能
ALGO_REID_CreateHandle	创建句柄
ALGO_REID_InitHandle	初始化句柄
ALGO_REID_GetInputAttr	获取模型的属性信息
ALGO_REID_GetFeatureDimension	获取特征的维度
ALGO_REID_SetParams	设置算法可配置参数
ALGO_REID_FeatureExtract	目标特征提取
ALGO_REID_FeatureCompare	目标特征比对
ALGO_REID_DeInitHandle	反初始化句柄
ALGO_REID_ReleaseHandle	删除句柄
ALGO_REID_PersonQuality	行人质量检测
ALGO_REID_CalculateSimilarity	特征相似度检测

2.1. ALGO_REID_CreateHandle¶

功能

创建句柄

语法

MI_S32 ALGO_REID_CreateHandle(void **handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.2. ALGO_REID_InitHandle¶

功能

初始化句柄

语法

MI_S32 ALGO_REID_InitHandle(void *handle, const ReIdInit_t *init_info);

形参

参数名称描述输入/输出

handle 句柄输入

init_info 配置ipu_firmware_path路径、模型文件夹路径等初始化参数输入
返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.3. ALGO_REID_GetInputAttr¶

功能

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

语法

MI_S32 ALGO_REID_GetInputAttr(void *handle, ReIdInputAttr_t *input_attr);

形参

参数名称描述输入/输出

handle 句柄输入

input_attr 输入属性输出
返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.4. ALGO_REID_GetFeatureDimension¶

功能

获取特征的维度

语法

MI_S32 ALGO_REID_GetFeatureDimension(void *handle, MI_S32 *feat_dim);

形参

参数名称描述输入/输出

handle 句柄输入

feat_dim 特征维度输出
返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.5. ALGO_REID_SetParams¶

功能

设置算法的可配置参数

语法

MI_S32 ALGO_REID_SetParams(void *handle, const ReIdParams_t *params);

形参

参数名称描述输入/输出

handle 句柄输入

ReIdParams_t 参数结构体输入
返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.6. ALGO_REID_FeatureExtract¶

功能

目标特征提取

语法

MI_S32 ALGO_REID_FeatureExtract(void *handle, ReIdInput_t *algo_input, MI_FLOAT *feature);

形参

参数名称描述输入/输出

handle 句柄输入

algo_input 输入buffer 输入

feature 指向输出目标特征数组的指针（数组长度必须与特征维度一致）输出
返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.7. ALGO_REID_FeatureCompare¶

功能

目标特征比对

语法

MI_S32 ALGO_REID_FeatureCompare(void *handle, MI_FLOAT *g_features, MI_FLOAT *q_features, MI_S32 batch, ReIdRes_t results[REID_RESULT_TOP_K], MI_S32 *num_results);

形参

参数名称	描述	输入/输出
handle	句柄	输入
g_features	目标特征	输入
q_features	特征底库	输入
batch	底库数目	输入
results	比对结果（数据按相似度从大到小排列）	输出
num_results	输出比对结果的长度	输出

返回值

返回值描述

0 成功

其他错误码
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.8. ALGO_REID_DeInitHandle¶

功能

反初始化句柄

语法

MI_S32 ALGO_REID_DeInitHandle (void* handle)；

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.9. ALGO_REID_ReleaseHandle¶

功能

删除句柄

语法

MI_S32 ALGO_REID_ReleaseHandle (void* handle)；

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.10. ALGO_REID_PersonQuality¶

功能

行人质量检测

语法

MI_S32 ALGO_REID_PersonQuality(void *handle, ReIdInput_t *algo_input, PersonQualityOut_t *person_quality_out);

形参

参数名称描述输入/输出

handle 句柄输入

algo_input 输入buffer 输入

person_quality_out 行人质量相关结构体输出
返回值

返回值描述

0 成功
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

2.11. ALGO_REID_CalculateSimilarity¶

功能

特征相似度检测

语法

MI_S32 ALGO_REID_CalculateSimilarity(void *handle, MI_FLOAT *g_features, MI_FLOAT *q_features, MI_S32 feat_dim, MI_FLOAT *similarity);

形参

参数名称描述输入/输出

handle 句柄输入

g_features 特征输入

q_features 特征输入

feat_dim 特征维度输入

similarity 特征相似度输出
返回值

返回值描述

0 成功
依赖
- 头文件：sgs_reid_api.h
- 库文件：libssgsalgo_reid.a/libssgsalgo_reid.so

3. 结构体说明¶

REID相关数据类型定义如下：

数据类型	定义
ReIdInit_t	算法初始化性结构体
ReIdParams_t	算法可配置参数结构体
ReIdInputAttr_t	算法输入属性相关结构体
AlgoReID_Input_t	算法输入相关结构体
ReIdRes_t	算法结果相关结构体
PersonQualityOut_t	行人质量相关结构体

3.1 ReIdInit_t¶

说明

算法初始化性结构体

定义

typedef struct
{
    char ipu_firmware_path[MAX_REID_STRLEN];
    char model_path[MAX_REID_STRLEN];
    MI_BOOL create_device;
    MI_BOOL destroy_device;
} ReIdInit_t;

成员

成员名称	描述
ipu_firmware_bin	ipu_firmware_path路径
model_path	reid模型路径
create_device	设置是否算法库内创建IPU_Device, 默认为false
destroy_device	设置是否算法库内销毁IPU_Device, 默认为false

相关数据类型及接口

ALGO_REID_InitHandle

3.2 ReIdParams_t¶

说明

算法可配置参数结构体

定义

typedef struct
{
    MI_FLOAT threshold;
} ReIdParams_t;

成员

成员名称描述

threshold 特征比对阈值（0.0~1.0），默认为0.5
相关数据类型及接口

ALGO_REID_SetParams

3.3 ReIdInputAttr_t¶

说明

算法输入结构体

定义

typedef struct ReIdInputAttr_
{
    MI_U32 width;
    MI_U32 height;
    MI_IPU_ELEMENT_FORMAT format;
}ReIdInputAttr_t;

成员

成员名称描述

width 模型输入的宽度

height 模型输入的高度

format 模型输入的图像格式
相关数据类型及接口

ALGO_REID_GetInputAttr

3.4 ReIdInput_t¶

说明

算法输入相关结构体

定义

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

成员

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

相关数据类型及接口

ALGO_REID_FeatureExtract

3.5 ReIdRes_t¶

说明

算法结果相关结构体

定义

typedef struct ReIdRes_{
    MI_FLOAT conf;
    MI_U32 id;
}ReIdRes_t;

成员

成员名称描述

conf 匹配目标相似度

id 匹配ID
相关数据类型及接口

ALGO_REID_FeatureCompare

3.6 PersonQualityOut_t¶

说明

行人质量相关结构体

定义

typedef struct
{
    MI_FLOAT quality_score;
    MI_U32 cls;
    MI_FLOAT cls_score;
} PersonQualityOut_t;

成员

成员名称描述

quality_score 行人质量得分

cls 行人姿势类别，0表示站立，1表示坐，2表示其他

cls_score 行人姿势类别得分
相关数据类型及接口

ALGO_REID_FeatureCompare

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	无效的算法输出数据维度

成员名称	描述
width	模型输入的宽度
height	模型输入的高度
format	模型输入的图像格式

成员名称	描述
quality_score	行人质量得分
cls	行人姿势类别，0表示站立，1表示坐，2表示其他
cls_score	行人姿势类别得分

返回值	描述
0	成功
其他	错误码

返回值	描述
0	成功
其他	错误码

返回值	描述
0	成功
其他	错误码

返回值	描述
0	成功
其他	错误码