# 人脸识别器

## **1. 接口简介** <br>

人脸识别器要求输入原始图像数据和人脸特征点（或者裁剪好的人脸数据），对输入的人脸提取特征值数组，根据提取的特征值数组对人脸进行相似度比较。<br>

## **2. 类型说明**<br>

### **2.1 struct SeetaImageData**<br>

|名称 | 类型 | 说明|
|---|---|---|
|data|unit8_t* |图像数据|
|width | int32_t | 图像的宽度|
|height | int32_t | 图像的高度|
|channels | int32_t | 图像的通道数|
说明：存储彩色（三通道）或灰度（单通道）图像，像素连续存储，行优先，采用 BGR888 格式存放彩色图像，单字节灰度值存放灰度图像。

### **2.2 struct SeetaPointF**<br>

|名称 | 类型 | 说明|
|---|---|---|
|x|double|人脸特征点横坐标|
|y|double|人脸特征点纵坐标|

## 3 class FaceRecognizer
人脸识别器。

### 3.1 Enum SeetaDevice

模型运行的计算设备。

|名称 |说明|
|---|---|
|SEETA_DEVICE_AUTO|自动检测，会优先使用 GPU|
|SEETA_DEVICE_CPU|使用CPU计算|
|SEETA_DEVICE_GPU|使用GPU计算|

### 3.2 struct SeetaModelSetting

构造人脸识别器需要传入的结构体参数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|model|const char**| |识别器模型|
|id|int| |GPU id|
|device|SeetaDevice|AUTO |计算设备(CPU 或者 GPU)|

### 3.3 构造函数
#### FaceRecognizer

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|setting|const SeetaModelSetting&| |识别器结构参数|

### 3.4 成员函数

#### GetCropFaceWidth
获取裁剪人脸的宽度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |返回的人脸宽度|

#### GetCropFaceHeight
获取裁剪的人脸高度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |返回的人脸高度|

#### GetCropFaceChannels
获取裁剪的人脸数据通道数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |返回的人脸数据通道数|

#### CropFace
裁剪人脸。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|points|const SeetaPointF*| |人脸特征点数组|
|face|SeetaImageData&| |返回的裁剪人脸|
|返回值|bool| |true表示人脸裁剪成功|

#### CropFace
裁剪人脸。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|points|const SeetaPointF*| |人脸特征点数组|
|返回值|seeta::ImageData| |返回的裁剪人脸|

#### GetCropFaceWidthV2
获取裁剪人脸的宽度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |返回的人脸宽度|

#### GetCropFaceHeightV2
获取裁剪的人脸高度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |返回的人脸高度|

#### GetCropFaceChannelsV2
获取裁剪的人脸数据通道数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |返回的人脸数据通道数|

#### CropFaceV2
裁剪人脸。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|points|const SeetaPointF*| |人脸特征点数组|
|face|SeetaImageData&| |返回的裁剪人脸|
|返回值|bool| |true表示人脸裁剪成功|

#### CropFaceV2
裁剪人脸。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|points|const SeetaPointF*| |人脸特征点数组|
|返回值|seeta::ImageData| |返回的裁剪人脸|

#### GetExtractFeatureSize
获取特征值数组的长度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|返回值|int| |特征值数组的长度|

#### ExtractCroppedFace
输入裁剪后的人脸图像，提取人脸的特征值数组。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|face|const SeetaImageData&| |裁剪后的人脸图像数据|
|features|float*| |返回的人脸特征值数组|
|返回值|bool| |true表示提取特征成功|

#### Extract
输入原始图像数据和人脸特征点数组，提取人脸的特征值数组。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始的人脸图像数据|
|points|const SeetaPointF*| |人脸的特征点数组|
|features|float*| |返回的人脸特征值数组|
|返回值|bool| |true表示提取特征成功|

#### CalculateSimilarity
比较两人脸的特征值数据，获取人脸的相似度值。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|features1|const float*| |特征数组一|
|features2|const float*| |特征数组二|
|返回值|float| |相似度值|

#### set
设置相关属性值。其中<br>
**PROPERTY_NUMBER_THREADS**: 
表示计算线程数，默认为 4.

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|property|Property||属性类别|
|value|double||设置的属性值|
|返回值|void| | | |

#### get
获取相关属性值。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|property|Property||属性类别|
|返回值|double||对应的属性值|