人脸检测与分析SDK提供人脸关键点检测和人脸属性分析的能力，具备检测速度快、跟踪稳定、性能开销低等特点。

人脸106关键点索引图

人脸280关键点索引图

280关键点是在106关键点的基础上，拓展增加了嘴唇、虹膜、眉毛关键点。

人脸106/240/280关键点检测

详细接口说明查看头文件：bef_effect_ai_face_detect.h

调用示例

1.初始化

NSString *faceModel = [resourceBundleName stringByAppendingString:@"/ttfacemodel/tt_face_v5.0.model"];

NSString *faceExtraModel = [resourceBundleName stringByAppendingString:@"/ttfacemodel/tt_face_extra_v8.0.model"];

// 人脸检测初始化，传入算法模型文件路径
// 这里使用了 BEF_DETECT_FULL, 因此会加载嘟嘴和眨眼模块
result = bef_effect_ai_face_detect_create(BEF_DETECT_SMALL_MODEL | BEF_DETECT_FULL, faceModel.UTF8String, &faceDetectHandle);

// 检查人脸检测license
result = bef_effect_ai_face_check_license(faceDetectHandle, FACE106_LICENSE.UTF8String, FACE106_LICENSE.length);

//设置调用参数
result = bef_effect_ai_face_detect_setparam(faceDetectHandle, BEF_FACE_PARAM_FACE_DETECT_INTERVAL, 15);
   

result = bef_effect_ai_face_detect_setparam(faceDetectHandle, BEF_FACE_PARAM_MAX_FACE_NUM, 2);

result = bef_effect_ai_face_detect_add_extra_model(faceDetectHandle,TT_MOBILE_FACE_280_DETECT, faceExtraModel.UTF8String
);

2.人脸检测

bef_ai_face_info faceInfo;
// 这里不使用眨眼和嘟嘴功能，所以不设置，如果要眨眼和嘟功能，可使用
// BEF_DETECT_MODE_VIDEO | BEF_FACE_DETECT | BEF_EYE_BLINK | BEF_MOUTH_POUT|BEF_DETECT_EYEBALL | BEF_BROW_JUMP

bef_effect_result_t ret = bef_effect_ai_face_detect(faceDetectHandle, buffer,
                                                        BEF_AI_PIX_FMT_BGRA8888,
                                                         width, height,
                                                         bytesPerRow,
                                                         [self getDeviceOrientation],
                                                         BEF_DETECT_MODE_VIDEO | BEF_FACE_DETECT,
                                                         &faceInfo);

3.销毁句柄：

bef_effect_ai_face_detect_destroy(faceDetectHandle);

接口说明

1. 创建人脸106关键点检测句柄

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_detect_create(
	unsigned long long config,
 	const char * strModelPath,
 	bef_effect_handle_t *handle
);

参数说明

返回值

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

备注

人脸检测算法的可配置选项如下

● 设置模型类型

我们目前只提供小模型一种模型,且该选项必须设置。

● 设置检测模式

检测模式分为视频检测和图片检测两类，其中图片检测模式分为普通模式和高级模式，高级模式相比普通模式检测效果更好，能检测到更小的人脸，但相应耗时会增加。检测模式选项如下表所示。如果没有设置，默认检测模式为BEF_DETECT_MODE_VIDEO。

● 设置可检测的特征

可检测的人脸特征选项如下表所示。

创建人脸检测句柄时，config = 模型类型（必须设置）|检测模式（缺省值为缺省值为BEF_DETECT_MODE_VIDEO）|可检测的特征（必须设置）

2. 人脸检测授权

android接口

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_check_license(
    JNIEnv* env,
    jobject context, 
    bef_effect_handle_t handle, 
    const char *license_path
);

参数说明

返回值

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

ios接口

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_check_license(
	bef_effect_handle_t handle,
    const char *license_path
);

参数说明

返回值

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

3. 设置人脸检测240/280关键点模型

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_detect_add_extra_model(
    bef_effect_handle_t handle,
    unsigned long long config,
    const char *param_path
);

参数说明

返回值

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

备注

设置人脸检测240/280关键点检测模型时，使用的是步骤1中创建的106关键点检测的handle,240/280关键点是基于106关键点检测结果的扩展。

config可以设置的值有

// Config-240，TT_MOBILE_FACE_240_DETECT
  // Config-280，TT_MOBILE_FACE_280_DETECT
  // Config-240 快速模式, TT_MOBILE_FACE_240_DETECT | TT_MOBILE_FACE_240_DETECT_FASTMODE
  // Config-280 快速模式, TT_MOBILE_FACE_280_DETECT | TT_MOBILE_FACE_240_DETECT_FASTMODE

4. 设置人脸检测参数

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_detect_setparam(
	bef_effect_handle_t handle,
	bef_face_detect_type type,
	float value
);

参数说明

返回值

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

5. 检测人脸关键点

人脸关键点检测结果定义在bef_effect_ai_face_detect.h中，具体如下：

// 眼睛,眉毛,嘴唇详细检测结果, 280点结果
typedef struct bef_ai_face_ext_info_t {
   int eye_count;                  // 检测到眼睛数量
   int eyebrow_count;              // 检测到眉毛数量
   int lips_count;                 // 检测到嘴唇数量
   int iris_count;                 // 检测到虹膜数量
  
   bef_ai_fpoint eye_left[22];        // 左眼关键点
   bef_ai_fpoint eye_right[22];       // 右眼关键点
   bef_ai_fpoint eyebrow_left[13];    // 左眉毛关键点
   bef_ai_fpoint eyebrow_right[13];   // 右眉毛关键点
   bef_ai_fpoint lips[64];            // 嘴唇关键点
   bef_ai_fpoint left_iris[20];       // 左虹膜关键点
   bef_ai_fpoint right_iris[20];      // 右虹膜关键点
} bef_ai_face_ext_info;


// 供106点使用
typedef struct bef_ai_face_106_st {
   bef_ai_rect rect;                // 代表面部的矩形区域
   float score;                  // 置信度
   bef_ai_fpoint points_array[106]; // 人脸106关键点的数组
   float visibility_array[106];  // 对应点的能见度，点未被遮挡1.0, 被遮挡0.0
   float yaw;                    // 水平转角,真实度量的左负右正
   float pitch;                  // 俯仰角,真实度量的上负下正
   float roll;                   // 旋转角,真实度量的左负右正
   float eye_dist;               // 两眼间距
   int ID;                       // faceID: 每个检测到的人脸拥有唯一的faceID.人脸跟踪丢失以后重新被检测到,会有一个新的faceID
   unsigned int action;          // 动作, 定义在bef_ai_effect_face_detect.h 
   unsigned int tracking_cnt;
} bef_ai_face_106, *p_bef_ai_face_106;


// @brief 检测结果
typedef struct bef_ai_face_info_st {
   bef_ai_face_106 base_infos[BEF_MAX_FACE_NUM];          // 检测到的人脸信息
   bef_ai_face_ext_info extra_infos[BEF_MAX_FACE_NUM];    // 眼睛，眉毛，嘴唇关键点等额外的信息
   int face_count;                                     // 检测到的人脸数目
} bef_ai_face_info, *p_bef_ai_face_info;

人脸关键点检测调用如下接口：

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_detect(
	bef_effect_handle_t 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 detect_config,
	bef_ai_face_info *p_face_info
);

参数说明

返回值

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

6. 销毁人脸检测句柄

BEF_SDK_API void bef_effect_ai_face_detect_destroy(
	bef_effect_handle_t handle
);

参数说明

人脸属性检测

详细接口说明查看头文件：bef_effect_ai_face_attribute.h

1. 创建人脸属性检测句柄

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_create(
	unsigned long long config,
	const char * strModelPath,
	bef_effect_handle_t *handle
);

参数说明

返回值

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

2. 人脸属性检测授权

android接口

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_check_license(
	JNIEnv* env,
    jobject context, 
    bef_effect_handle_t handle, 
    const char *license_path
);

参数说明

返回值

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

ios接口

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_check_license(
	bef_effect_handle_t handle,
    const char *license_path
);

参数说明

返回值

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

3. 设置人脸属性检测参数

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_setparam(
	bef_effect_handle_t handle,
	bef_ai_face_attribute_param_config_type type,
	float value
);

参数说明

返回值

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

4. 检测人脸属性

人脸属性检测结果定义在头文件bef_effect_ai_face_attribute.h中，具体如下：

BEF_FACE_ATTRIBUTE_AGE          = 0x00000001,     //年龄
 BEF_FACE_ATTRIBUTE_GENDER       = 0x00000002,     //性别
 BEF_FACE_ATTRIBUTE_EXPRESSION   = 0x00000004,     //表情
 BEF_FACE_ATTRIBUTE_ATTRACTIVE   = 0x00000008,     //颜值
 BEF_FACE_ATTRIBUTE_HAPPINESS    = 0x00000010,     //开心程度
 BEF_FACE_ATTRIBUTE_RACIAL       = 0x00000020,     //肤色
} bef_ai_face_attribute_types;

typedef enum {
 BEF_FACE_ATTRIBUTE_ForceDetect = 0x10000000,     //未加平滑的裸数据，重置缓存，在切换摄像头时等上下帧剧烈变化时使用
                               //用于处理切换摄像头，跟踪的人脸ID 混淆的问题
} bef_ai_face_attribut_config;

/*
*@brief 肤色类别枚举
**/
typedef enum {
 BEF_FACE_ATTRIBUTE_WHITE = 0,                   //白种人
 BEF_FACE_ATTRIBUTE_YELLOW = 1,                  //黄种人
 BEF_FACE_ATTRIBUTE_INDIAN = 2,                  //印度人
 BEF_FACE_ATTRIBUTE_BLACK = 3,                   //黑种人
 BEF_FACE_ATTRIBUTE_NUM_RACIAL = 4,              //支持的肤色个数
}bef_ai_face_attribute_racial_type;

/*
*@brief 表情类别枚举
**/
typedef enum {
 BEF_FACE_ATTRIBUTE_ANGRY = 0,                   //生气
 BEF_FACE_ATTRIBUTE_DISGUST = 1,                 //厌恶
 BEF_FACE_ATTRIBUTE_FEAR = 2,                    //害怕
 BEF_FACE_ATTRIBUTE_HAPPY = 3,                   //高兴
 BEF_FACE_ATTRIBUTE_SAD = 4,                     //伤心
 BEF_FACE_ATTRIBUTE_SURPRISE = 5,                //吃惊
 BEF_FACE_ATTRIBUTE_NEUTRAL = 6,                 //平静
 BEF_FACE_ATTRIBUTE_NUM_EXPRESSION = 7           //支持的表情个数
}bef_ai_face_attribute_expression_type;

/*
*@breif 单个人脸属性结构体
**/
typedef struct bef_ai_face_attribute_info {
 float age;                          // 预测的年龄值， 值范围【0，100】之间
 float boy_prob;                     // 预测为男性的概率值，值范围【0.0，1.0】之间
 float attractive;                   // 预测的颜值分数，范围【0，100】之间
 float happy_score;                  // 预测的微笑程度，范围【0，100】之间
 bef_ai_face_attribute_expression_type exp_type;            // 预测的表情类别
 float exp_probs[BEF_FACE_ATTRIBUTE_NUM_EXPRESSION];    // 预测的每个表情的概率，未加平滑处理
 bef_ai_face_attribute_racial_type racial_type;             // 预测的肤色类别
 float racial_probs[BEF_FACE_ATTRIBUTE_NUM_RACIAL];     // 预测的每个类别肤色的概率，未加平滑处理
} bef_ai_face_attribute_info;

人脸属性检测是以人脸106关键点作为输入，在106关键点的基础上，完成人脸属性的识别。

人脸属性检测接口分为单人脸输入和多人脸输入， 如果人脸检测结果中只有单个人脸，则调用单人脸输入的接口，接口定义如下：

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_detect(
	bef_effect_handle_t handle,
	const unsigned char *image,
	bef_ai_pixel_format pixel_format,
	int image_width,
	int image_height,
	int image_stride,
	const bef_ai_face_106 *ptr_base_info,
	unsigned long long config,
	bef_ai_face_attribute_info *ptr_face_attribute_info
);

参数说明

返回值

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

如果人脸检测结果中有多个人脸，则调用多人脸输入的接口，接口定义如下：

BEF_SDK_API bef_effect_result_t bef_effect_ai_face_attribute_detect_batch(
	bef_effect_handle_t handle,
	const unsigned char *image,
	bef_ai_pixel_format pixel_format,
	int image_width,
	int image_height,
	int image_stride,
	const bef_ai_face_106 *ptr_base_info,
	int face_count,
	unsigned long long config,
	bef_ai_face_attribute_result *ptr_face_attribute_result
);

参数说明

返回值

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

5. 销毁人脸属性检测句柄

BEF_SDK_API void bef_effect_ai_face_attribute_destroy(
	bef_effect_handle_t handle
);

参数说明

包内资源有 android_sdk.aar，此包为使用 Jni 将 c 接口 封装到 java 层的接口集合；包含 SDK 所需所有 检测模型、素材等资源。

Android 开发时可直接使用 aar 包，降低使用 sdk 的复杂度。

com.bef.effectsdk.OpenGLUtils                //一些常用 opengles
com.bytedance.labcv.effectsdk.RenderManager    //滤镜/美颜相关接口
com.bytedance.labcv.effectsdk.FaceDetect    //人脸检测相关接口
com.bytedance.labcv.effectsdk.BefFaceInfo    //人脸检测结果定义

com.bytedance.labcv.effectsdk.HandDetect    //人手检测相关接口
com.bytedance.labcv.effectsdk.BefHandInfo    //人手检测结果定义
com.bytedance.labcv.effectsdk.BefBytedEffecctConstants // sdk 常量

人脸106/240/280关键点检测

调用示例

// 初始化人脸106关键点检测句柄
ret = mFaceDetector.init(context, path,BEF_DETECT_SMALL_MODEL | BEF_DETECT_FULL, ResourceHelper.getLicensePath(LICENSE_NAME));

// 设置人脸280关键点模型
ret = mFaceDetector.initExtra(context, path, BytedEffectConstants.BEF_MOBILE_FACE_280_DETECT);
// 检测人脸关键点
BefFaceInfo faceInfo = mFaceDetector.detectFace(resizeInputBuffer,PixlFormat.RGBA8888,
       width, height, width * 4,
       rotation);

接口说明

人脸关键点检测相关的函数定义在com.bytedance.labcv.effectsdk.FaceDetect.java中。通常，人脸检测的执行流程如下。

1. 初始化人脸106关键点检测句柄

public int init(
	Context context, 
    String modelPath, 
    int config, 
    String license
)

参数说明

返回值

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

备注

config = 模型类型（必须设置,目前只有一种模式BytedEffectConstants.BEF_DETECT_SMALL_MODEL）

​ |检测模式（缺省值为BEF_DETECT_MODE_IMAGE,参考{@link BytedEffectConstants.DetectMode}）

​ |可检测的特征（必须设置, 参考{@link BytedEffectConstants.FaceAction}）

2. 设置240、280关键点检测模型

public int initExtra(
	Context context, 
    String extraModelpath, 
    int extraType
)

参数说明

返回值

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

备注

extraType 算法配置，支持以下四种

• Config-240，BEF_MOBILE_FACE_240_DETECT
• Config-280，BEF_MOBILE_FACE_280_DETECT
• Config-240 快速模式, BEF_MOBILE_FACE_240_DETECT | BEF_DETECT_FACE_240_DETECT_FASTMODE
• Config-280 快速式, BEF_MOBILE_FACE_280_DETECT | BEF_DETECT_FACE_240_DETECT_FASTMODE

我们在Demo中提供是的280关键点检测模型，因此extraType应该使用BEF_MOBILE_FACE_280_DETECT。

3. 设置人脸关键点检测参数

public int setDetectParam(
	int paramType , 
    int paramValue
)

参数说明

返回值

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

4. 设置人脸检测配置

public void setFaceDetectConfig(int mFaceDetectConfig)

参数说明

返回值

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

5. 检测人脸关键点

public BefFaceInfo detectFace(
	ByteBuffer buffer,
    PixlFormat pixel_format, 
    int image_width, 
    int image_height, 
    int image_stride,
    Rotation orientation
)

参数说明

返回值

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

6. 销毁人脸关键点检测句柄

public void release()

人脸属性检测

人脸属性检测相关的接口定义在com.bytedance.labcv.effectsdk.FaceDetect.java中，常用接口如下。

接口说明

1. 初始化人脸属性检测句柄

public int initAttri(
	Context context, 
    String faceAttriModelPath, 
    String faceAttrLicense
)

参数说明

返回值

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

2. 设置人脸属性检测参数

public void setAttriDetectConfig(int attriConfig)

参数说明

返回值

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

3. 检测人脸属性

同检测人脸关键点接口

public BefFaceInfo detectFace(
	ByteBuffer buffer, 
    PixlFormat pixel_format, 
    int image_width, 
    int image_height, 
    int image_stride, 
    RenderManager.Rotation orientation
)

参数说明

返回值

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

4. 销毁人脸属性检测句柄

public void release()

FAQ

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

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

bef_effect_ai 和SMASH_E_LOG 以及 EffectSDK

2.Android上使用detectFace接口识别一个由Bitmap转为ByteBuffer的数据，返回错误码-37（无效的图像数据），是哪里出了问题？

答：请确认buffer内存是通过使用ByteBuffer.allocateDirect()分配的，因为我们在JNI层是通过函数接口直接获取图像数据的native指针;如果使用ByteBuffer.allocate(),分配的是jvm堆内存，会导致JNI层获取native内存失败。

3.detectFace，返回错误码-107（无效的配置）

答：初始化的bef_effect_ai_face_detect_create的config参数跟bef_effect_ai_face_detect的config参数需要匹配。注意更改config时，两处保持一致

错误码

错误码请参考错误码表