手势识别SDK提供多达45种手势分类及关键点跟踪、分割能力,具有跟踪稳定、性能开销小等特点,可应用于手势交互场景中。
支持平台 | Android、iOS、Windows、Mac |
---|---|
支持手势类型 | 45 |
支持同时跟踪人手数目 | 20 |
支持输入格式 | RGBA8888、BGRA8888、BGR888、RGB888、NV21、NV12、YUV420P |
支持最小输入尺寸 | 短边360 |
内存占用 | <6M (测试设备OppoR11) |
手势检测速度 | <6ms(测试设备iPhone7) |
对应头文件bef_effect_ai_hand.h
接口说明
BEF_SDK_API bef_effect_result_t bef_effect_ai_hand_detect_create( bef_ai_hand_sdk_handle *handle, unsigned int config );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
handle | bef_effect_handler_t | 创建的手势检测句柄 |
config | unsigned int | 手势检测算法的配置,目前无用 |
返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
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 );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
env | JNIEnv * | jni 环境指针 |
context | jobject | jni 对象 |
handle | bef_effect_handle_t | 创建的手势检测句柄 |
licensePath | const char * | 授权文件字符串 |
返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
BEF_SDK_API bef_effect_result_t bef_effect_ai_hand_check_license( bef_effect_handle_t handle, const char *licensePath );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
handle | bef_effect_handle_t | 创建的手势检测句柄 |
licensePath | const char * | 授权文件字符串 |
返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
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);
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
handle | bef_ai_hand_sdk_handle | 创建的手势检测句柄 |
type | bef_ai_hand_model_type | 模型文件类型,见备注 |
strModelPath | const char * | 模型文件路径 |
备注
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
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 );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
handle | bef_ai_hand_sdk_handle | 创建的手势检测句柄 |
type | bef_ai_hand_param_type | 参数类型,见备注 |
value | float | 模型文件路径 |
备注
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
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 );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
handle | bef_effect_handler_t | 创建的手势检测句柄 |
image | const unsigned char * | 输入图片的数据指针 |
pixel_format | bef_ai_pixel_format | 输入图片的格式 |
image_width | int | 输入图像的宽度(单位,像素) |
image_height | int | 输入图像的高度(单位,像素) |
image_stride | int | 输入图像的每一行步长(单位,字节) |
orientation | bef_ai_rotate_type | 输入图像的转向,见备注 |
detection_config | unsigned long long | 请求检测的模块,见备注 |
p_hand_info | bef_ai_hand_info | 存放结果信息,外部分配内存 |
delayframecount | int | 输出结果的延迟,见备注 |
备注
orientation
参数具体请参考 bef_effect_ai_public_public_define.h 中的 bef_ai_rotate_type
detection_config
请求检测的模块,为 hand_model_type 的按位与操作,目前只有HAND_MODEL_GESTURE_CLS 和 HAND_MODEL_KEY_POINT 是可选的
delayframecount
输出结果的延迟,算法会在 delayframecount 帧之后返回检测的结果,值越大检测结果越稳定,默认值为 4
返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
BEF_SDK_API void bef_effect_ai_hand_detect_destroy(bef_ai_hand_sdk_handle handle);
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
handle | bef_ai_hand_sdk_handle | 创建的手势检测句柄 |
返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
手势检测相关的函数定义在 com.bytedance.labcv.effectsdk.HandDetect.java 中。
public int createHandle( Context context, String licensePath );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
context | Context | 上下文 |
licensePath | String | 授权文件路径 |
返回值
成功返回BEF_RESULT_SUC,否则返回对应的错误码
public int setModel( BytedEffectConstants.HandModelType modelType, String modelPath)
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
modelType | BytedEffectConstants.HandModelType | 模型类型,见备注 |
modelPath | String | 授权文件路径 |
备注
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,否则返回对应的错误码
public int setParam( BytedEffectConstants.HandParamType paramType, float paramValue)
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
paramType | BytedEffectConstants.HandParamType | 参数类型,见备注 |
paramValue | float | 参数值 |
备注
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,否则返回对应的错误码
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 );
参数说明
参数名 | 参数类型 | 参数说明 |
---|---|---|
buffer | ByteBuffer | 参数类型,见备注 |
pixel_format | BytedEffectConstants.PixlFormat | 图像格式,见备注 |
image_width | int | 图像宽度(单位,像素) |
image_height | int | 图像高度(单位,像素) |
image_stride | int | 图像数据行宽(单位,字节) |
orientation | BytedEffectConstants.Rotation | 图像方向,见备注 |
detectconfig | int | 请求检测模块,见备注 |
delayFrameCount | int | 输出结果的延迟,见备注 |
备注
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; } }
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; } }
detectconfig
使用时参考 com.bytedance.labcv.effectsdk.BytedEffectConstants.HandModelType ,需要使用哪一个功能,则将对应功能的枚举变量进行与操作。
delayFrameCount
输出结果的延迟,算法会在 delayframecount 帧之后返回检测的结果,值越大检测结果越稳定,默认值为 4
返回值
成功返回BEF_RESULT_SUC,否则返回对应的错误码
public void release();
答:建议首先查看以下tag输出Error类型的日志:
bef_effect_ai 和SMASH_E_LOG 以及 EffectSDK
答:建议按照以下步骤排查
错误码请参考错误码表
英文名 | 手势名 | 手势展示 |
---|---|---|
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 | 蜘蛛侠 |