#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_