|
#ifndef INCLUDE_CVFACE_API_CV_FACE_EXTERNAL_H_
|
#define INCLUDE_CVFACE_API_CV_FACE_EXTERNAL_H_
|
|
|
#include "cv_common.h"
|
/// @defgroup cvface_common cvface common
|
/// @brief Common definitions for cvface
|
/// @{
|
|
/// @brief 人脸信息结构体
|
typedef struct cv_face_t {
|
cv_rect_t rect; ///< 代表面部的矩形区域
|
float score; ///< 置信度，用于筛除负例，与人脸照片质量无关，值越高表示置信度越高。
|
int points_count; ///< 人脸关键点数组的长度，如果没有计算关键点，则为0
|
float yaw; ///< 水平转角，真实度量的左负右正
|
float pitch; ///< 俯仰角，真实度量的上负下正
|
float roll; ///< 旋转角，真实度量的左负右正
|
float eye_dist; ///< 两眼间距
|
int ID; ///< faceID，用于表示在实时人脸跟踪中的相同人脸在不同帧多次出现，在人脸检测的结果中无实际意义
|
cv_pointf_t points_array[256]; ///< 人脸关键点的数组支持21点，106点，以及为将来预留的空间
|
} cv_face_t;
|
|
/// 人脸检测、跟踪配置选项
|
#define CV_FACE_DEFAULT_CONFIG 0x00000000 ///< 默认选项，不设置任何开关
|
#define CV_FACE_RESIZE_IMG_320W 0x00000002 ///< resize图像为长边320的图像
|
#define CV_FACE_RESIZE_IMG_640W 0x00000004 ///< resize图像为长边640的图像
|
#define CV_FACE_RESIZE_IMG_1280W 0x00000008 ///< resize图像为长边1280的图像
|
|
/// detect config flags, 0x----00-- ~ 0x----FF--
|
#define CV_DETECT_ENABLE_ALIGN_21 0x00000100 ///< 开启面部关键21点检测选项
|
#define CV_DETECT_ENABLE_ALIGN_106 0x00000200 ///< 开启面部关键106点检测选项
|
|
/// 该版本sdk未开启此功能(如：面部关键21点检测版本传入了面部关键106点检测参数)
|
#define CV_E_UNSURPPORTED (-1000)
|
/// 指定位置未找到license.lic文件
|
#define CV_E_MISSLICENSE (-1001)
|
/// cv_face_init_license_config 函数被重复调用
|
#define CV_E_MULTI_CALLS (-1002)
|
|
/// @brief 人脸朝向
|
typedef enum {
|
CV_FACE_UP = 0x0000001, ///< 人脸向上，即人脸朝向正常
|
CV_FACE_LEFT = 0x0000002, ///< 人脸向左，即人脸被逆时针旋转了90度
|
CV_FACE_DOWN = 0x0000004, ///< 人脸向下，即人脸被逆时针旋转了180度
|
CV_FACE_RIGHT = 0x0000008, ///< 人脸向右，即人脸被逆时针旋转了270度
|
CV_FACE_UNKNOWN = 0xf ///< 人脸朝向未知，API自动判断人脸朝向，耗时增加。face_track不支持此参数，等同于CV_FACE_UP
|
} cv_face_orientation;
|
|
/// @brief 输出当前SDK所支持的算法及内置模型信息
|
CV_SDK_API
|
void
|
cv_face_algorithm_info();
|
|
/// @brief 手动加载license文件，除IOS,Android平台外，都可以不主动调用此函数（但需要将license文件放在可执行程序同一目录，名称命名为license.lic）,该函数只能被成功调用一次
|
/// param[in] szLicense 授权文件中的字符串，license文件的全部内容
|
CV_SDK_API
|
cv_result_t
|
cv_face_init_license_config(const char* szLicense);
|
|
|
/// @defgroup cvface_detect cvface detect
|
/// @brief face position detection interfaces
|
///
|
/// This set of interfaces processing face position & 21 or 106 points landmark detection routines
|
///
|
/// @{
|
|
/// @brief 创建人脸检测句柄
|
/// @param[out] handle函数成功时被设置为有效的detector handle
|
/// @param[in] model_path 模型文件的绝对路径或相对路径，若不指定模型可为NULL
|
/// @param[in] config 配置选项，默认配置为CV_DETECT_ENABLE_ALIGN_21(21关键点检测)。支持106关键点检测CV_DETECT_ENABLE_ALIGN_106和自动缩放CV_FACE_RESIZE_IMG_XXXX。
|
/// @return 返回CV_OK 失败返回错误码
|
CV_SDK_API
|
cv_result_t
|
cv_face_create_detector(
|
cv_handle_t *handle,
|
const char *model_path,
|
unsigned int config
|
);
|
|
/// @brief 获取当前人脸检测的默认阀值
|
/// @param[in] handle 人脸检测句柄
|
/// @param[out] threshold 人脸检测的默认阀值
|
CV_SDK_API
|
cv_result_t cv_face_detect_get_threshold(
|
cv_handle_t detector_handle,
|
float *threshold
|
);
|
|
/// @brief 设置当前人脸检测的阀值，需要在调用cv_face_detect之前调用此函数，阈值需大于0，设置后调用cv_face_detect_get_threshold为新设置后的值)
|
/// @param[in] handle 人脸检测句柄
|
/// @param[in] threshold 人脸检测新阀值
|
CV_SDK_API
|
cv_result_t cv_face_detect_set_threshold(
|
cv_handle_t detector_handle,
|
float threshold
|
);
|
|
/// @brief 销毁已初始化的人脸检测句柄
|
/// @param[in] detector_handle 已初始化的人脸检测句柄
|
CV_SDK_API
|
void cv_face_destroy_detector(
|
cv_handle_t detector_handle
|
);
|
|
/// @brief 人脸检测
|
/// @param[in] detector_handle 已初始化的人脸检测句柄
|
/// @param[in] image 用于检测的图像数据
|
/// @param[in] piexl_format 用于检测的图像数据的像素格式
|
/// @param[in] image_width 用于检测的图像的宽度(以像素为单位)
|
/// @param[in] image_height 用于检测的图像的高度(以像素为单位)
|
/// @param[in] image_stride 用于检测的图像中每一行的跨度(以像素为单位) 图像跨度=图像宽度*图像维度
|
/// @param[in] orientation 图片中人脸的方向
|
/// @param[out] p_faces_array 检测到的人脸信息数组，api负责分配内存，需要调用cv_face_release_detector_result函数释放
|
/// @param[out] p_faces_count 检测到的人脸数量
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_face_detect(
|
cv_handle_t detector_handle,
|
const unsigned char *image,
|
cv_pixel_format pixel_format,
|
int image_width,
|
int image_height,
|
int image_stride,
|
cv_face_orientation orientation,
|
cv_face_t **p_faces_array,
|
int *p_faces_count
|
);
|
|
/// @brief 释放人脸检测返回结果时分配的空间
|
/// @param[in] faces_array 检测到的人脸信息数组
|
/// @param[in] faces_count 检测到的人脸数量
|
CV_SDK_API
|
void
|
cv_face_release_detector_result(
|
cv_face_t *faces_array,
|
int faces_count
|
);
|
|
|
/// @}
|
|
|
/// @defgroup cvface_track cvface track
|
/// @brief face tracking interfaces
|
///
|
/// This set of interfaces processing face tracking routines
|
///
|
/// @{
|
|
#define CV_FACE_TRACKING_TWO_THREAD 0x00110000 ///< 开启双线程人脸跟踪，建议低配置环境开启此选项。
|
|
/// @brief 创建实时人脸跟踪句柄。可以调用cv_face_track_set_detect_face_cnt_limit设置检测的最大人脸数目，默认为不限制人脸检测数量。
|
/// @param[out] handle函数成功时被设置为有效的tracker handle
|
/// @param[in] model_path 模型文件的绝对路径或相对路径，若不指定模型可为NULL
|
/// @param[in] config 默认配置为CV_DETECT_ENABLE_ALIGN_21(21关键点检测)。支持106关键点检测CV_DETECT_ENABLE_ALIGN_106、自动缩放CV_FACE_RESIZE_IMG_XXXX和双线程跟踪CV_FACE_TRACKING_TWO_THREAD。
|
/// @return 返回CV_OK 失败返回错误码
|
CV_SDK_API
|
cv_result_t
|
cv_face_create_tracker(
|
cv_handle_t *handle,
|
const char *model_path,
|
unsigned int config
|
);
|
|
/// @brief 销毁已初始化的实时人脸跟踪句柄
|
/// @param[in] tracker_handle 已初始化的实时人脸跟踪句柄
|
CV_SDK_API
|
void
|
cv_face_destroy_tracker(
|
cv_handle_t tracker_handle
|
);
|
|
/// @brief 对连续视频帧进行实时快速人脸跟踪
|
/// @param[in] tracker_handle 已初始化的实时人脸跟踪句柄
|
/// @param[in] image 用于检测的图像数据
|
/// @param[in] piexl_format 用于检测的图像数据的像素格式
|
/// @param[in] image_width 用于检测的图像的宽度(以像素为单位)
|
/// @param[in] image_height 用于检测的图像的高度(以像素为单位)
|
/// @param[in] image_stride 用于检测的图像中每一行的跨度(以像素为单位)，图像跨度=图像宽度*图像维度
|
/// @param[in] orientation 视频中人脸的方向
|
/// @param[out] p_faces_array 检测到的人脸信息数组，api负责分配内存，需要调用cv_facesdk_release_tracker_result函数释放
|
/// @param[out] p_faces_count 检测到的人脸数量
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_face_track(
|
cv_handle_t tracker_handle,
|
const unsigned char *image,
|
cv_pixel_format pixel_format,
|
int image_width,
|
int image_height,
|
int image_stride,
|
cv_face_orientation orientation,
|
cv_face_t **p_faces_array,
|
int *p_faces_count
|
);
|
|
/// @brief 重置人脸跟踪检测器
|
/// @param[in] tracker_handle 已初始化的实时人脸跟踪句柄
|
CV_SDK_API
|
void
|
cv_face_reset_tracker(
|
cv_handle_t tracker_handle
|
);
|
|
/// @brief 释放实时人脸跟踪返回结果时分配的空间
|
/// @param[in] faces_array 检测到的人脸信息数组
|
/// @param[in] faces_count 检测到的人脸数量
|
CV_SDK_API
|
void
|
cv_face_release_tracker_result(
|
cv_face_t *faces_array,
|
int faces_count
|
);
|
|
/// @brief 设置检测到的最大人脸数目N，持续track已检测到的N个人脸直到人脸数小于N再继续做detect,如果未调用则不对检测人脸数量做限制
|
/// @param[in] tracker_handle 已初始化的实时人脸跟踪句柄
|
/// @param[in] detect_face_cnt_limit 最大人脸数目N，-1表示不设上限
|
/// @param[out] val 如果为非空指针，则返回采用的新的值，注意，由于内部的限制， 实际采用的值并不一定等于detect_face_cnt_limit
|
/// @return 成功返回CV_OK，否则返回错误类型 (实际设置检测到的最大目标数目N可能小于detect_face_cnt_limit)
|
CV_SDK_API
|
cv_result_t
|
cv_face_track_set_detect_face_cnt_limit(
|
cv_handle_t tracker_handle,
|
int detect_face_cnt_limit,
|
int* val
|
);
|
|
/// @}
|
|
|
/// @defgroup cvface_verify cvface verify
|
/// @brief face verification interfaces
|
///
|
/// This set of interfaces processing face verification routines.
|
///
|
/// @{
|
|
/// @brief 创建人脸验证句柄
|
/// @param[out] handle函数成功时被设置为有效的verify handle
|
/// @param[in] model_path 模型库所在文件夹的绝对路径或相对路径(sdk中模型文件路径为sdk/models/verify.model")，不能为NULL
|
/// @return 返回CV_OK 失败返回错误码
|
CV_SDK_API
|
cv_result_t
|
cv_verify_create_handle(
|
cv_handle_t* handle,
|
const char *model_path
|
);
|
|
/// @brief 创建人脸验证句柄的副本，与旧的句柄共享内存，可用于多线程调用
|
/// @param[in] old_handle 旧的人脸验证句柄，新句柄释放后才能释放旧句柄
|
/// @param[out] new_handle 函数成功返回人脸验证句柄的副本
|
/// @return 成功返回CV_OK
|
CV_SDK_API
|
cv_result_t
|
cv_verify_duplicate_handle(
|
cv_handle_t old_handle,
|
cv_handle_t* new_handle
|
);
|
|
/// @brief 销毁已初始化的人脸验证句柄
|
/// @param[in] verify_handle 已初始化的人脸验证句柄
|
CV_SDK_API
|
void
|
cv_verify_destroy_handle(
|
cv_handle_t verify_handle
|
);
|
|
/// @brief 获取当前人脸验证使用的模型版本号
|
/// @param[in] verify_handle 人脸验证句柄
|
/// @return 版本号
|
CV_SDK_API
|
int
|
cv_verify_get_version(
|
cv_handle_t verify_handle
|
);
|
|
/// @brief 获取当前人脸验证使用的模型提取的feature长度，不包含cv_feature_header_t的长度
|
/// @param[in] verify_handle 人脸验证句柄
|
/// @return 特征长度
|
CV_SDK_API
|
int
|
cv_verify_get_feature_length(
|
cv_handle_t verify_handle
|
);
|
|
/// @brief 提取人脸特征，返回特征数据长度，可以把返回数组编码成字符串后存储起来以便以后使用
|
/// @param[in] verify_handle 已初始化的人脸验证句柄
|
/// @param[in] image 用于检测的图像数据
|
/// @param[in] piexl_format 用于检测的图像数据的像素格式
|
/// @param[in] image_width 用于检测的图像的宽度(以像素为单位)
|
/// @param[in] image_height 用于检测的图像的高度(以像素为单位)
|
/// @param[in] image_stride 用于检测的图像中每一行的跨度(以像素为单位)，图像跨度=图像宽度*图像维度
|
/// @param[in] face 输入待处理的人脸信息，需要包括关键点信息，即 face.points_array 不为NULL
|
/// @param[out] p_feature 人脸特征数据，需要调用cv_verify_release_feature函数释放
|
/// @param[out] feature_blob_size 特征的长度，包含cv_feature_header_t的长度，与cv_feature_header_t->len一致
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_get_feature(
|
cv_handle_t verify_handle,
|
const unsigned char *image,
|
cv_pixel_format pixel_format,
|
int image_width,
|
int image_height,
|
int image_stride,
|
const cv_face_t *face,
|
cv_feature_t **p_feature,
|
unsigned int *feature_blob_size
|
);
|
|
/// @brief 特征信息编码成字符串，编码后的字符串用于保存
|
/// @param[in] feature 输入的特征信息
|
/// @param[out] feature_str 输出的编码后的字符串,由用户分配和释放
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_serialize_feature(
|
const cv_feature_t *feature,
|
char *feature_str
|
);
|
|
|
/// @brief 解码字符串成特征信息
|
/// @param[in] feature_str 输入的待解码的字符串，api负责分配内存，需要调用cv_verify_release_feature释放
|
/// @return 返回解码后的feature, 需要用户使用 cv_common_feature_release() 释放
|
CV_SDK_API
|
cv_feature_t *
|
cv_verify_deserialize_feature(
|
const char *feature_str
|
);
|
|
/// @brief 人脸验证
|
/// @param[in] verify_handle 已初始化的人脸验证句柄
|
/// @param[in] feature1 第一张人脸特征信息
|
/// @param[in] feature2 第二张人脸特征信息
|
/// @param[out] score 人脸验证相似度得分，范围0-1，得分越接近1越相似
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_compare_feature(
|
cv_handle_t verify_handle,
|
const cv_feature_t *feature1,
|
const cv_feature_t *feature2,
|
float *score
|
);
|
|
/// @brief 释放提取人脸特征时分配的空间
|
/// @param[in] feature 提取到的人脸特征信息
|
CV_SDK_API
|
void
|
cv_verify_release_feature(
|
cv_feature_t *feature
|
);
|
|
/// @}
|
|
|
/// @defgroup cvface_search cvface search
|
/// @brief face searching interfaces
|
///
|
/// This set of interfaces processing face search routines.
|
///
|
/// @{
|
|
/// @defgroup cvface_database cvface database for search
|
/// @ingroup cvface_search
|
/// @brief face database CURD interfaces for face searching
|
/// @{
|
|
/// @brief 创建人脸数据库句柄
|
/// @handle[out] 成功时候设置为人脸数据库句柄
|
/// @return[in] 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_create_db(cv_handle_t *handle);
|
|
/// @brief 销毁已初始化的人脸数据库句柄
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
CV_SDK_API
|
void
|
cv_verify_destroy_db(
|
cv_handle_t db_handle
|
);
|
|
/// @brief 人脸数据库增加数据
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
/// @param[in] items 用于创建数据库的人脸特征信息数组
|
/// @param[in] item_count 特征信息数量
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_build_db(
|
cv_handle_t db_handle,
|
cv_feature_t* const *items,
|
unsigned int item_count
|
);
|
|
/// @brief 人脸数据库增加数据
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
/// @param[in] item 待加入的人脸特征信息
|
/// @param[out] idx 加入后的人脸数据库索引值
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_add_face(
|
cv_handle_t db_handle,
|
const cv_feature_t *item,
|
int *idx
|
);
|
|
/// @brief 人脸数据库删除数据
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
/// @param[in] idx 待删除的人脸数据库索引值(与加入时一致)
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_delete_face(
|
cv_handle_t db_handle,
|
int idx
|
);
|
|
/// @brief 将人脸数据库信息保存为数据库文件
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
/// @param[in] db_path 人脸数据库保存文件的路径
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_save_db(
|
cv_handle_t db_handle,
|
const char *db_path
|
);
|
|
/// @brief 加载人脸数据库文件
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
/// @param[in] db_path 人脸数据库保存文件的路径
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_load_db(
|
cv_handle_t db_handle,
|
const char *db_path
|
);
|
|
/// @}
|
|
/// @brief 搜索人脸数据库
|
/// @param[in] verify_handle 已初始化的人脸验证句柄
|
/// @param[in] db_handle 已初始化的人脸数据库句柄
|
/// @param[in] query 待搜索的人脸特征信息
|
/// @param[in] top_k 最大的人脸搜索数量
|
/// @param[out] top_idxs 搜索到的人脸数据库索引值数组(由用户分配和释放)
|
/// @param[out] top_scores 搜索到的人脸相似度得分数组(由用户分配和释放)，范围0-1，得分越接近1越相似
|
/// @param result_length 实际搜索到的人脸数量
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_search_face(
|
cv_handle_t verify_handle,
|
cv_handle_t db_handle,
|
const cv_feature_t *query,
|
unsigned int top_k,
|
int *top_idxs,
|
float *top_scores,
|
unsigned int *result_length
|
);
|
|
/// @brief 从一组特征数组中搜索人脸
|
/// @param[in] verify_handle 已初始化的人脸验证句柄
|
/// @param[in] list_feature 人脸特征信息数组
|
/// @param[in] list_count 人脸特征信息数量
|
/// @param[in] query 待搜索的人脸特征信息
|
/// @param[in] top_k 最大的人脸搜索数量
|
/// @param[out] top_idxs 搜索到的人脸数据库索引值数组(由用户分配和释放)
|
/// @param[out] top_scores 搜索到的人脸相似度得分数组(由用户分配和释放)，范围0-1，得分越接近1越相似
|
/// @param[out] result_length 实际搜索到的人脸数量
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_search_face_from_list(
|
cv_handle_t verify_handle,
|
cv_feature_t* const *list_feature,
|
int list_count,
|
const cv_feature_t *query,
|
unsigned int top_k,
|
int *top_idxs,
|
float *top_scores,
|
unsigned int *result_length
|
);
|
|
/// @}
|
|
|
/// @defgroup cvface_group cvface group
|
/// @brief face grouping interfaces
|
///
|
/// This set of interfaces processing face grouping routines.
|
///
|
/// @{
|
|
|
/// @brief 批量人脸分组
|
/// @param[in] verify_handle 已初始化的人脸验证句柄
|
/// @param[in] features 人脸特征信息数组
|
/// @param[in] feature_count 人脸特征信息数量
|
/// @param[out] p_groups_array 分组结果，index对应features的index，p_groups_array[0]表示index为0的feature对应的分组，内存由用户管理，p_groups_array大小与feature_count一致
|
/// @param[out] group_count 分组的组数，需用户初始化为0
|
/// @return 成功返回CV_OK，否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_verify_grouping(
|
cv_handle_t verify_handle,
|
const cv_feature_t * const *features,
|
unsigned int feature_count,
|
unsigned int *p_groups_array,
|
unsigned int *groups_count
|
);
|
|
/// @brief 初始化特征数组结果
|
/// @param[in] p_groups_array 特征分组结果存储地址
|
/// @param[in] feature_count 特征数组长度
|
CV_SDK_API
|
void
|
cv_verify_initialize_labels(
|
unsigned int *p_groups_array,
|
unsigned int feature_count
|
);
|
|
/// @}
|
|
|
/// @defgroup cvface_group cvface group
|
/// @brief face grouping interfaces
|
///
|
/// This set of interfaces processing face grouping routines.
|
///
|
/// @{
|
|
/// @brief 创建特征聚类句柄
|
/// @param[out] handle 输出已初始化的特征聚类句柄所在地址
|
/// @param[in] model 载入的模型路径
|
/// @return 成功返回CV_OK, 否则返回错误信息
|
CV_SDK_API
|
cv_result_t
|
cv_face_create_clustering(
|
cv_handle_t *clustering_handle,
|
const char* model_path
|
);
|
|
/// @brief 特征聚类（包含增量聚类）
|
/// @param[in] handle 已初始化的特征聚类句柄
|
/// @param[in] features 待聚类的特征数组
|
/// @param[out] labels 类别数组, 0表示需要重新聚类，1表示是单张人脸（当人脸数量大于等于2是才会单独分组），2表示噪音（模糊、侧脸、不是人脸等），3及其以上表示实际分类结果
|
/// @param[out] size 特征和类别的数量
|
/// @return 成功返回CV_OK, 否则返回错误类型
|
CV_SDK_API
|
cv_result_t
|
cv_face_clustering(
|
cv_handle_t clustering_handle,
|
const cv_feature_t * const *features,
|
unsigned int *labels,
|
int size
|
);
|
|
|
/// @brief 销毁已初始化的特征聚类句柄
|
/// @param[in] handle 已初始化的特征聚类句柄
|
CV_SDK_API
|
void
|
cv_face_clustering_destroy(
|
cv_handle_t clustering_handle
|
);
|
|
/// @}
|
|
|
#endif // INCLUDE_CVFACE_API_CV_FACE_H_
|
