手势识别

手势识别SDK提供多达45种手势分类及关键点跟踪、分割能力,具有跟踪稳定、性能开销小等特点，可应用于手势交互场景中。

手势检测关键点索引图

对应头文件bef_effect_ai_hand.h

接口说明

1. 创建手势检测句柄

BEF_SDK_API bef_effect_result_t
bef_effect_ai_hand_detect_create(
	bef_ai_hand_sdk_handle *handle,
	unsigned int config
	);

参数说明

返回值

成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

2. 手势检测授权

Android

BEF_SDK_API bef_effect_result_t
bef_effect_ai_hand_check_license(
	JNIEnv* env,
	jobject context,
	bef_effect_handle_t handle, 
	const char *licensePath
	);

参数说明

返回值

成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

ios

BEF_SDK_API bef_effect_result_t
bef_effect_ai_hand_check_license(
	bef_effect_handle_t handle, 
	const char *licensePath
	);

参数说明

返回值

成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

3. 设置模型文件

BEF_SDK_API bef_effect_result_t
bef_effect_ai_hand_detect_setmodel(
	bef_effect_handle_t handle,
	bef_ai_hand_model_type type,
	const char * strModelPath);

参数说明

备注

1. type

   使用时参考 bef_ai_hand_model_type

typedef enum {
    BEF_HAND_MODEL_DETECT = 0x0001,       // 检测手，必须加载
    BEF_HAND_MODEL_BOX_REG = 0x0002,      // 检测手框，必须加载
    BEF_HAND_MODEL_GESTURE_CLS = 0x0004,  // 手势分类，可选
    BEF_HAND_MODEL_KEY_POINT = 0x0008,    // 手关键点，可选
    BEF_HAND_MODEL_SEGMENT = 0x0010,    // 可见性点，可选
} bef_ai_hand_model_type;

返回值

成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

4. 设置参数

BEF_SDK_API bef_effect_result_t
bef_effect_ai_hand_detect_setparam(
	bef_effect_handle_t handle,
	bef_ai_hand_param_type type,
	float value
	);

参数说明

备注

1. type

   使用时参考 bef_ai_hand_param_type

typedef enum {
    BEF_HAND_REFRESH_FRAME_INTERVAL = 1,      // 设置检测刷新帧数, 暂不支持
    BEF_HAND_MAX_HAND_NUM = 2,                // 设置最多的手的个数，默认为1，目前最多设置为2；
    BEF_HAND_DETECT_MIN_SIDE = 3,             // 设置检测的最短边长度, 默认192
    BEF_HAND_CLS_SMOOTH_FACTOR = 4,           // 设置分类平滑参数，默认0.7， 数值越大分类越稳定
    BEF_HAND_USE_ACTION_SMOOTH = 5,           // 设置是否使用类别平滑，默认1，使用类别平滑；不使用平滑，设置为0
    BEF_HAND_ALGO_LOW_POWER_MODE = 6,         // 降级模式，默认走高级的版本。如果
    BEF_HAND_ALGO_AUTO_MODE = 7,              // 降级模式，默认走高级的版本。如果
    // 如果设置为 HAND_ALGO_AUTO_MODE 模式，则可以以下参数来设置算法降级的阈值
    BEF_HAND_ALGO_TIME_ELAPSED_THRESHOLD = 8, // 算法耗时阈值，默认为 20ms
    BEF_HAND_ALGO_MAX_TEST_FRAME = 9,         // 设置运行时测试算法的执行的次数, 默认是 150 次
    BEF_HAND_IS_USE_DOUBLE_GESTURE = 10,      // 设置是否使用双手手势， 默认为true
    BEF_HNAD_ENLARGE_FACTOR_REG = 11,         // 设置回归模型的输入初始框的放大比列
    BEF_HAND_NARUTO_GESTURE = 12,             // 设置支持火影忍者手势，默认为false，如果开启，则支持包括火影在内的45类手势识别
} bef_ai_hand_param_type;

返回值

成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

5. 手势检测

BEF_SDK_API bef_effect_result_t
bef_effect_ai_hand_detect(
	bef_ai_hand_sdk_handle handle,
	const unsigned char *image,
	bef_ai_pixel_format pixel_format,
	int image_width,
	int image_height,
	int image_stride,
	bef_ai_rotate_type orientation,
	unsigned long long detection_config,
	bef_ai_hand_info *p_hand_info,
	int delayframecount
	);

参数说明

备注

1. orientation

   参数具体请参考 bef_effect_ai_public_public_define.h 中的 bef_ai_rotate_type

2. detection_config

   请求检测的模块，为 hand_model_type 的按位与操作，目前只有HAND_MODEL_GESTURE_CLS 和 HAND_MODEL_KEY_POINT 是可选的

3. delayframecount

   输出结果的延迟，算法会在 delayframecount 帧之后返回检测的结果，值越大检测结果越稳定，默认值为 4

返回值

成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

6. 销毁手势检测句柄

BEF_SDK_API void
bef_effect_ai_hand_detect_destroy(bef_ai_hand_sdk_handle handle);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

手势检测相关的函数定义在 com.bytedance.labcv.effectsdk.HandDetect.java 中。

1. 初始化手势检测句柄

public int createHandle(
	Context context,
	String licensePath
	);

参数说明

返回值

成功返回BEF_RESULT_SUC，否则返回对应的错误码

2. 设置模型文件

public int setModel(
	BytedEffectConstants.HandModelType modelType,
	String modelPath)

参数说明

备注

1. modelType

   使用时参考 com.bytedance.labcv.effectsdk.BytedEffectConstants.HandModelType

public enum HandModelType {
    /**
     * 检测手，必须加载
     */
    BEF_HAND_MODEL_DETECT(0x0001),
    /**
     * 检测手位置框，必须加载
     */
    BEF_HAND_MODEL_BOX_REG(0x0002),
    /**
     * 手势分类，可选
     */
    BEF_HAND_MODEL_GESTURE_CLS(0x0004),
    /**
     * 手关键点，可选
     */
    BEF_HAND_MODEL_KEY_POINT(0x0008);
    private int value;
    HandModelType(int value) {
        this.value = value;
    }
    public int getValue() {
        return value;
    }
}

返回值

成功返回BEF_RESULT_SUC，否则返回对应的错误码

3. 设置参数

public int setParam(
	BytedEffectConstants.HandParamType paramType,
	float paramValue)

参数说明

备注

1. paramType

   使用时参考 com.bytedance.labcv.effectsdk.BytedEffectConstants.HandParamType

public enum HandParamType {
    /**
     * 设置最多的手的个数，默认为1，目前最多设置为2
     */
    BEF_HAND_MAX_HAND_NUM(2),
    /**
     * 设置检测的最短边长度, 默认192
     */
    BEF_HAND_DETECT_MIN_SIDE(3),
    /**
     * 设置分类平滑参数，默认0.7， 数值越大分类越稳定
     */
    BEF_HAND_CLS_SMOOTH_FACTOR(4),
    /**
     * 设置是否使用类别平滑，默认1，使用类别平滑；不使用平滑，设置为0
     */
    BEF_HAND_USE_ACTION_SMOOTH(5),
    /**
     * 降级模式，在低端机型使用，可缩短算法执行时间，但准确率也会降低。默认为0，使用高级模式；如设置为1，则使用降级模式。
     */
    BEF_HAND_ALGO_LOW_POWER_MODE(6),
    /**
     * 自动降级模式，如果检测阈值超过BEF_HAND_ALGO_TIME_ELAPSED_THRESHOLD，则走降级模式，否则，走高级模式。
     * 默认为0，使用高级模式；如设置为1，则使用自动降级模式
     */
    BEF_HAND_ALGO_AUTO_MODE(7),
    /**
     * 算法耗时阈值，默认为 15ms
     */
    BEF_HAND_ALGO_TIME_ELAPSED_THRESHOLD(8),
    /**
     * 设置运行时测试算法的执行的次数, 默认是 150 次
     */
    BEF_HAND_ALGO_MAX_TEST_FRAME(9),
    /**
     * 设置是否使用双手手势， 默认为true
     */
    BEF_HAND_IS_USE_DOUBLE_GESTURE(10),
    /**
     * 设置回归模型的输入初始框的放大比列
     */
    BEF_HNAD_ENLARGE_FACTOR_REG(11),
    /**
     * 设置支持火影忍者手势，默认为false，如果开启，则支持包括火影在内的45类手势识别
     */
    BEF_HAND_NARUTO_GESTUER(12);
    private int value;
    HandParamType(int value) {
        this.value = value;
    }
    public int getValue() {
        return value;
    }
}

返回值

成功返回BEF_RESULT_SUC，否则返回对应的错误码

4. 手势检测

public BefHandInfo detectHand(
	ByteBuffer buffer, 
	BytedEffectConstants.PixlFormat pixel_format,
	int image_width, 
	int image_height,
	int image_stride, 
	BytedEffectConstants.Rotation orientation,
	int detectconfig,
	int delayFrameCount
	);

参数说明

备注

1. pixel_format

   使用时参考 com.bytedance.labcv.effectsdk.BytedEffectConstants.PixlFormat

public enum PixlFormat {
    RGBA8888(0),
    BGRA8888(1),
    BGR888(2),
    RGB888(3),
    BEF_AI_PIX_FMT_YUV420P(5),
    BEF_AI_PIX_FMT_NV12(6),
    BEF_AI_PIX_FMT_NV21(7);
    private int value;
    PixlFormat(int value) {
        this.value = value;
    }
    public int getValue() {
        return value;
    }
}

2. orientation

   使用时参考 com.bytedance.labcv.effectsdk.BytedEffectConstants.Rotation

public enum Rotation {
    /**
     * 图像不需要旋转，图像中的人脸为正脸
     */
    CLOCKWISE_ROTATE_0(0),
    /**
     * 图像需要顺时针旋转90度，使图像中的人脸为正
     */
    CLOCKWISE_ROTATE_90(1),
    /**
     * 图像需要顺时针旋转180度，使图像中的人脸为正
     */
    CLOCKWISE_ROTATE_180(2),
    /**
     * 图像需要顺时针旋转270度，使图像中的人脸为正
     */
    CLOCKWISE_ROTATE_270(3);
    public int id = 0;
    Rotation(int id) {
        this.id = id;
    }
}

3. detectconfig

   使用时参考 com.bytedance.labcv.effectsdk.BytedEffectConstants.HandModelType ，需要使用哪一个功能，则将对应功能的枚举变量进行与操作。

4. delayFrameCount

   输出结果的延迟，算法会在 delayframecount 帧之后返回检测的结果，值越大检测结果越稳定，默认值为 4

返回值

成功返回BEF_RESULT_SUC，否则返回对应的错误码

5. 销毁手势检测句柄

public void release();

FAQ

1.如果出现任何异常，请查看是否有以下类型日志

答：建议首先查看以下tag输出Error类型的日志：

bef_effect_ai 和SMASH_E_LOG 以及 EffectSDK

2.手势识别设置后没有效果

答：建议按照以下步骤排查

• 请确认手势检测句柄初始化是否成功
• 请确认手势检测句柄已经授权成功
• 如果初始化成功，请检查设置的输入图像数据完整且类型支持

错误码

错误码请参考错误码表

6. 手势说明

英文名	手势名	手势展示
heart_a	比心 A
heart_b	比心 B
heart_c	比心 C
heart_d	比心 D
ok	OK
hand_open	手张开
thumb_up	点赞
thumb_down	差评
rock	摇滚1
namaste	合十
palm_up	手心向上
fist	握拳
index_finger_up	食指朝上
double_finger_up	双指朝上
victory	胜利
big_v	大V
phonecall	打电话
beg	作揖
thanks	感谢
cabbage	卷心菜
three	三
four	四
pistol	手枪
rock2	摇滚2
holdface	捧脸
salute	敬礼
spread	讨红包
pray	祈祷
qigong	龟波气功
slide	发红包
palm_down	手掌朝下
clapping	鼓掌（动态）
punching	击拳（动态）
naruto1	子
naruto2	丑
naruto3	寅
naruto4	卯
naruto5	辰
naruto7	午
naruto8	未
naruto9	申
naruto10	酉
naruto11	戌
naruto12	亥
raisehands	举手
pistol2	双指比枪
spiderman	蜘蛛侠