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