You need to enable JavaScript to run this app.
导航
手势识别
最近更新时间:2023.06.28 14:39:18首次发布时间:2022.02.25 17:16:51
简介

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

手势检测关键点索引图

手势检测关键点索引图.jpg

技术规格
支持平台Android、iOS、Windows、Mac
支持手势类型45
支持同时跟踪人手数目20
支持输入格式RGBA8888、BGRA8888、BGR888、RGB888、NV21、NV12、YUV420P
支持最小输入尺寸短边360
内存占用<6M (测试设备OppoR11)
手势检测速度<6ms(测试设备iPhone7)
C 接口

对应头文件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
	);

参数说明

参数名参数类型参数说明
handlebef_effect_handler_t创建的手势检测句柄
configunsigned int手势检测算法的配置,目前无用

返回值

成功返回 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
	);

参数说明

参数名参数类型参数说明
envJNIEnv *jni 环境指针
contextjobjectjni 对象
handlebef_effect_handle_t创建的手势检测句柄
licensePathconst char *授权文件字符串

返回值

成功返回 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
	);

参数说明

参数名参数类型参数说明
handlebef_effect_handle_t创建的手势检测句柄
licensePathconst char *授权文件字符串

返回值

成功返回 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);

参数说明

参数名参数类型参数说明
handlebef_ai_hand_sdk_handle创建的手势检测句柄
typebef_ai_hand_model_type模型文件类型,见备注
strModelPathconst char *模型文件路径

备注

  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
	);

参数说明

参数名参数类型参数说明
handlebef_ai_hand_sdk_handle创建的手势检测句柄
typebef_ai_hand_param_type参数类型,见备注
valuefloat模型文件路径

备注

  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
	);

参数说明

参数名参数类型参数说明
handlebef_effect_handler_t创建的手势检测句柄
imageconst unsigned char *输入图片的数据指针
pixel_formatbef_ai_pixel_format输入图片的格式
image_widthint输入图像的宽度(单位,像素)
image_heightint输入图像的高度(单位,像素)
image_strideint输入图像的每一行步长(单位,字节)
orientationbef_ai_rotate_type输入图像的转向,见备注
detection_configunsigned long long请求检测的模块,见备注
p_hand_infobef_ai_hand_info存放结果信息,外部分配内存
delayframecountint输出结果的延迟,见备注

备注

  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);

参数说明

参数名参数类型参数说明
handlebef_ai_hand_sdk_handle创建的手势检测句柄

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

Java 接口说明

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

1. 初始化手势检测句柄

public int createHandle(
	Context context,
	String licensePath
	);

参数说明

参数名参数类型参数说明
contextContext上下文
licensePathString授权文件路径

返回值

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

2. 设置模型文件

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

参数说明

参数名参数类型参数说明
modelTypeBytedEffectConstants.HandModelType模型类型,见备注
modelPathString授权文件路径

备注

  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)

参数说明

参数名参数类型参数说明
paramTypeBytedEffectConstants.HandParamType参数类型,见备注
paramValuefloat参数值

备注

  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
	);

参数说明

参数名参数类型参数说明
bufferByteBuffer参数类型,见备注
pixel_formatBytedEffectConstants.PixlFormat图像格式,见备注
image_widthint图像宽度(单位,像素)
image_heightint图像高度(单位,像素)
image_strideint图像数据行宽(单位,字节)
orientationBytedEffectConstants.Rotation图像方向,见备注
detectconfigint请求检测模块,见备注
delayFrameCountint输出结果的延迟,见备注

备注

  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;
    }
}
  1. 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;
    }
}
  1. detectconfig

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

  2. 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比心 Aimage
heart_b比心 Bimage
heart_c比心 Cimage
heart_d比心 Dimage
okOKimage
hand_open手张开image
thumb_up点赞image
thumb_down差评image
rock摇滚1image
namaste合十image
palm_up手心向上image
fist握拳image
index_finger_up食指朝上image
double_finger_up双指朝上image
victory胜利image
big_v大Vimage
phonecall打电话image
beg作揖image
thanks感谢image
cabbage卷心菜image
threeimage
fourimage
pistol手枪image
rock2摇滚2image
holdface捧脸image
salute敬礼image
spread讨红包image
pray祈祷image
qigong龟波气功image
slide发红包image
palm_down手掌朝下image
clapping鼓掌(动态)image
punching击拳(动态)image
naruto1image
naruto2image
naruto3image
naruto4image
naruto5image
naruto7image
naruto8image
naruto9image
naruto10image
naruto11image
naruto12image
raisehands举手image
pistol2双指比枪image
spiderman蜘蛛侠image