手势识别算法

REVISION HISTORY¶

Revision No.	Description	Date
101	Initial release	03/22/2024

1. 算法描述¶

手势识别算法主要对13种手势进行识别：

静态手势（10类）：L、dislike、ok、fist、stop、like、yes、one、call、rock
动态手势（3类）：wave_up、wave_down、grip
使用时请遵照如下图所示的标准手势，以保证算法的识别效果：

2. 接口调用流程¶

算法接口调用流程为 ALGO_HandPose_CreateHandle->ALGO_HandPose_InitHandle->ALGO_HandPose_GetInputAttr->ALGO_HandPose_SetParams->ALGO_HandPose_Detect->ALGO_HandPose_Cls->ALGO_HandPose_DeinitHandle->ALGO_HandPose_ReleaseHandle.

3. 功能模块API¶

API名	功能
ALGO_HandPose_CreateHandle	创建句柄
ALGO_HandPose_InitHandle	初始化句柄
ALGO_HandPose_GetInputAttr	获取输入属性
ALGO_HandPose_SetParams	设置参数
ALGO_HandPose_Detect	人手部检测
ALGO_HandPose_Cls	手势识别
ALGO_HandPose_DeinitHandle	句柄反初始化
ALGO_HandPose_ReleaseHandle	释放句柄

3.1. ALGO_HandPose_CreateHandle¶

功能

创建句柄

语法

MI_S32 ALGO_HandPose_CreateHandle(void** handle);

形参

参数名称 描述 输入/输出

handle 句柄输出
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.2. ALGO_HandPose_InitHandle¶

功能

初始化句柄

语法

MI_S32 ALGO_HandPose_InitHandle(void *handle, const PoseInit_t *init);

形参

参数名称 描述 输入/输出

handle 句柄输入

init 初始化参数输入
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.3. ALGO_HandPose_GetInputAttr¶

功能

获取输入属性

语法

MI_S32 ALGO_HandPose_GetInputAttr(void *handle, PoseInputAttr_t *det_input_attr, PoseInputAttr_t *cls_input_attr);

形参

参数名称	描述	输入/输出
handle	句柄	输入
det_input_attr	检测模型输入属性（宽、高、图像格式）	输出
cls_input_attr	识别模型输入属性（宽、高、图像格式）	输出

返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.4. ALGO_HandPose_SetParams¶

功能

设置参数

语法

MI_S32 ALGO_HandPose_SetParams(void *handle, const PoseParams_t* params);

形参

参数名称 描述 输入/输出

handle 句柄输入

params 参数输入
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.5. ALGO_HandPose_Detect¶

功能

人手部检测

语法

MI_S32 ALGO_HandPose_Detect(void *handle, const PoseInput_t *input, PoseBox_t boxes[MAX_POSE_OBJECT], MI_S32 *num_boxes);

形参

参数名称 描述 输入/输出

handle 句柄输入

input 检测模型输入数据800*480 yuv420_nv12 输入

boxes 检测框结果输出

num_boxes 检测框个数输出
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.6. ALGO_HandPose_Cls¶

功能

手部姿态识别，识别13种手势中的哪种手势

语法

MI_S32 ALGO_HandPose_Cls(void *handle,  const PoseInput_t *input, PoseBox_t* box, PoseCls_t* cls);

形参

参数名称 描述 输入/输出

handle 句柄输入

input 识别模型输入数据224*224 yuv420_nv12 输入

box 手部检测框输入

cls 手部姿态结果输出
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.7. ALGO_HandPose_DeinitHandle¶

功能

句柄反初始化

语法

MI_S32 ALGO_HandPose_DeinitHandle(void *handle);

形参

参数名称 描述 输入/输出

handle 句柄输入
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

3.8. ALGO_HandPose_ReleaseHandle¶

功能

释放句柄

语法

MI_S32 ALGO_HandPose_ReleaseHandle(void *handle);

形参

参数名称 描述 输入/输出

handle 句柄输入
返回值

0：成功。

非0：失败。
依赖

头文件：sgs_pose_api.h

库文件：libsgsalgo_pose.so, libsgsalgo_pose.a

4. 数据类型¶

数据类型	定义
PoseInit_t	初始化参数结构体
PoseInput_t	输入图像属性结构体
PoseInputAttr_t	模型输入数据结构体
PoseCls_t	手势识别结果结构体
PoseBox_t	手部检测框结构体
PoseParams_t	输入参数结构体
HandPoseClass_e	手势类别信息
HandKeyPoint_e	手部关键点类别信息

4.1. PoseInit_t¶

说明

初始化参数结构体

定义

typedef struct
{
    char ipu_firmware_path[MAX_POSE_STRLEN];
    char pose_model[MAX_POSE_STRLEN];
    char cls_model[MAX_POSE_STRLEN];
    MI_BOOL create_device;
    MI_BOOL destroy_device;
} PoseInit_t;

成员

成员名称	描述
ipu_firmware_path	ipu_firmware_bin路径
pose_model	检测模型路径（如: ./models/handpose_det48y_20240313.img）
cls_model	识别模型路径（如：./models/handpose_cls_20240222.img）
create_device	是否创建device：若为false，需要在算法库外自行创建device；若为true，在算法库内部自动创建device
destroy_device	是否销毁device：若为false，需要在算法库外自行销毁device，若为true，在算法库内部自动销毁device

相关接口

ALGO_HandPose_InitHandle

4.2. PoseInput_t¶

说明

输入图像数据结构体

定义

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

成员

成员名称 描述

p_vir_addr 虚拟地址

phy_addr 物理地址

buf_size 数据大小

pts 时间戳可不赋值

width 图片宽

height 图片高
相关数据类型及接口

ALGO_HandPose_Detect

ALGO_HandPose_Cls

4.3. PoseInputAttr_t¶

说明

模型输入属性结构体

定义

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

成员

成员名称 描述

width 输入图片宽

height 输入图片高

format 输入图片格式
相关数据类型及接口

ALGO_HandPose_GetInputAttr

4.4. PoseCls_t¶

说明

手势识别结果结构体

定义

typedef struct
{
    MI_S32 cls;
    MI_FLOAT score;
} PoseCls_t;

成员

成员名称 描述

cls 手势类别（对应关系见HandPoseClass_e）

score 手势类别得分
相关数据类型及接口

ALGO_HandPose_Cls

4.5. PoseBox_t¶

说明

手部检测框结构体

定义

typedef struct
{
    MI_U32 x;
    MI_U32 y;
    MI_U32 width;
    MI_U32 height;
    MI_S32 cls;
    MI_FLOAT score;
    MI_U64 pts;
    MI_FLOAT keypts[MAX_POSE_NUM_KEYPTS][2];
    MI_U64 track_id;
} PoseBox_t;

成员

成员名称	描述
x	框的左上横坐标
y	框的左上纵坐标
width	框的宽
height	框的高
cls	框的类别
score	框的分值
pts	时间戳可不赋值
keypts	关键点序列
track_id	跟踪id

相关数据类型及接口

ALGO_HandPose_Detect

ALGO_HandPose_Cls

4.6. PoseParams_t¶

说明

输入参数结构体

定义

typedef struct
{
    MI_S32 disp_width;
    MI_S32 disp_height;
    MI_FLOAT min_width;
    MI_FLOAT min_height;
    MI_FLOAT det_threshold;
    MI_FLOAT cls_threshold;
    MI_FLOAT attr_threshold[MAX_POSE_NUM_ATTR];
} PoseParams_t;

成员

成员名称	描述
disp_width	显示宽度
disp_height	显示高度
min_width	检测的最小宽度
min_height	检测的最小高度
det_threshold	检测阈值
cls_threshold	识别阈值（阈值越高识别标准越严格）
attr_threshold	属性阈值（手势识别中无用）

相关数据类型及接口

ALGO_HandPose_SetParams

4.7. HandPoseClass_e¶

说明

手势类别信息

定义

typedef enum
{
    E_HAND_POSE_NONE = 0,
    E_HAND_POSE_CALL,
    E_HAND_POSE_DISLIKE,
    E_HAND_POSE_FIST,
    E_HAND_POSE_FOUR,
    E_HAND_POSE_LIKE,
    E_HAND_POSE_MUTE,
    E_HAND_POSE_OK,
    E_HAND_POSE_ONE,
    E_HAND_POSE_PALM,
    E_HAND_POSE_PEACE,
    E_HAND_POSE_ROCK,
    E_HAND_POSE_STOP,
    E_HAND_POSE_STOP_INV,
    E_HAND_POSE_THREE,
    E_HAND_POSE_TWO_UP,
    E_HAND_POSE_TWO_UP_INV,
    E_HAND_POSE_THREE2,
    E_HAND_POSE_PEACE_INV,
    E_HAND_POSE_DOWN_INV,
    E_HAND_POSE_L,
    E_HAND_POSE_WAVE_UP,
    E_HAND_POSE_WAVE_DOWN,
    E_HAND_POSE_GRIP,
    E_NUM_HAND_POSE
} HandPoseClass_e;

相关数据类型及接口

PoseCls_t

ALGO_HandPose_Cls

4.8. HandKeyPoint_e¶

说明

手部关键点类别信息

定义

typedef enum
{
    E_WRIST = 0,
    E_THUMB_CMC,
    E_THUMB_MCP,
    E_THUMB_IP,
    E_THUMB_TIP,
    E_INDEX_FINGER_MCP,
    E_INDEX_FINGER_PIP,
    E_INDEX_FINGER_DIP,
    E_INDEX_FINGER_TIP,
    E_MIDDLE_FINGER_MCP,
    E_MIDDLE_FINGER_PIP,
    E_MIDDLE_FINGER_DIP,
    E_MIDDLE_FINGER_TIP,
    E_RING_FINGER_MCP,
    E_RING_FINGER_PIP,
    E_RING_FINGER_DIP,
    E_RING_FINGER_TIP,
    E_PINKY_MCP,
    E_PINKY_PIP,
    E_PINKY_DIP,
    E_PINKY_TIP,
    E_NUM_HAND_KEYPTS
} HandKeyPoint_e;

图例
相关数据类型及接口

PoseBox_t

ALGO_HandPose_Detect

ALGO_HandPose_Cls

成员名称	描述
p_vir_addr	虚拟地址
phy_addr	物理地址
buf_size	数据大小
pts	时间戳可不赋值
width	图片宽
height	图片高

成员名称	描述
width	输入图片宽
height	输入图片高
format	输入图片格式

成员名称	描述
cls	手势类别（对应关系见HandPoseClass_e）
score	手势类别得分