# 质量评估器

## **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 SeetaRect**<br>

|名称 | 类型 | 说明|
|---|---|---|
|x|int32_t |人脸区域左上角横坐标|
|y| int32_t | 人脸区域左上角纵坐标|
|width| int32_t | 人脸区域宽度|
|height| int32_t | 人脸区域高度|

### **2.3 struct SeetaPointF**<br>

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

### 2.4 enum QualityLevel

|名称 | 类型 | 说明|
|---|---|---|
|LOW| |表示人脸质量为低|
|MEDIUM| |表示人脸质量为中|
|HIGH| |表示人脸质量为高|

### 2.5 class QualityResult

|名称 | 类型 | 说明|
|---|---|---|
|level|QualityLevel|人脸质量等级|
|score|float|人脸质量分数|

## 3 class QualityOfBrightness
非深度的人脸亮度评估器。

### 3.1 构造函数

#### QualityOfBrightness
人脸亮度评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|void|| ||

#### QualityOfBrightness
人脸亮度评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|v0|float| |分级参数一|
|v1|float| |分级参数二|
|v2|float| |分级参数三|
|v3|float| |分级参数四|
说明：说明：分类依据为[0, v0) and [v3, ~) => LOW；[v0, v1) and [v2, v3) =>
MEDIUM；[v1, v2) => HIGH。

### 3.2 成员函数

#### check
检测人脸亮度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|face|const SeetaRect&| |人脸位置|
|points|const SeetaPointF*| |人脸5个特征点数组|
|N|const int32_t| |人脸特征点数组长度|
|返回值|QualityResult| |人脸亮度检测结果|

##  4 class QualityOfClarity
非深度学习的人脸清晰度评估器。

### 4.1 构造函数

#### QualityOfClarity
人脸清晰度评估器构造函数

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|void|| ||

#### QualityOfClarity
人脸清晰度评估器构造函数

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|low|float| |分级参数一|
|high|float| |分级参数二|
说明：分类依据为[0, low)=> LOW; [low, high)=> MEDIUM; [high, ~)=> HIGH。

### 4.2 成员函数

#### check
检测人脸清晰度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|face|const SeetaRect&| |人脸位置|
|points|const SeetaPointF*| |人脸5个特征点数组|
|N|const int32_t| |人脸特征点数组长度|
|返回值|QualityResult| |人脸清晰度检测结果|

## 5 class QualityOfLBN
深度学习的人脸清晰度评估器。

### 5.1 Enum SeetaDevice

模型运行的计算设备。

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

### 5.2 struct SeetaModelSetting

构造评估器需要传入的结构体参数。

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

### 5.3 构造函数
人脸清晰度评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|setting|const SeetaModelSetting&| |对象构造结构体参数|

### 5.4 成员函数

#### Detect
检测人脸清晰度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|points|const SeetaPointF*| |人脸68个特征点数组|
|light|int*| |亮度返回结果，暂不推荐使用该返回结果|
|blur|int*| |模糊度返回结果|
|noise|int*| |是否有噪声返回结果，暂不推荐使用该返回结果|
|返回值|void| ||
说明：blur 结果返回 0 说明人脸是清晰的，blur 为 1 说明人脸是模糊的。

#### set
设置相关属性值。其中<br>

**PROPERTY_NUMBER_THREADS**: 
表示计算线程数，默认为 4。<br>
**PROPERTY_ARM_CPU_MODE**：针对于移动端，表示设置的 cpu 计算模式。0 表示
大核计算模式，1 表示小核计算模式，2 表示平衡模式，为默认模式。<br>
**PROPERTY_BLUR_THRESH**：表示人脸模糊阈值，默认值大小为 0.80。

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

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

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

## 6 class QualityOfPose
非深度学习的人脸姿态评估器。

### 6.1 构造函数

#### QualityOfPose
人脸姿态评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|void|| ||

### 6.2 成员函数

#### check
检测人脸姿态。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|face|const SeetaRect&| |人脸位置|
|points|const SeetaPointF*| |人脸5个特征点数组|
|N|const int32_t| |人脸特征点数组长度|
|返回值|QualityResult| |人脸姿态检测结果|

## 7 class QualityOfPoseEx
深度学习的人脸姿态评估器。

### 7.1 Enum SeetaDevice

模型运行的计算设备。

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

### 7.2 struct SeetaModelSetting

构造评估器需要传入的结构体参数。

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

### 7.3 构造函数

#### QualityOfPoseEx
人脸姿态评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|setting|const SeetaModelSetting&| |对象结构体参数|

### 7.4 成员函数

#### check
检测人脸姿态。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|face|const SeetaRect&| |人脸位置|
|points|const SeetaPointF*| |人脸5个特征点数组|
|N|const int32_t| |人脸特征点数组长度|
|返回值|QualityResult| |人脸姿态检测结果|


#### set
设置相关属性值。其中<br>
**YAW_HIGH_THRESHOLD**: 
yaw方向的分级参数一。<br>
**YAW_LOW_THRESHOLD**: 
yaw方向的分级参数二。<br>
**PITCH_HIGH_THRESHOLD**：
pitch方向的分级参数一。<br>
**PITCH_LOW_THRESHOLD**：
pitch方向的分级参数二。<br>
**ROLL_HIGH_THRESHOLD**：
roll方向的分级参数一。<br>
**ROLL_LOW_THRESHOLD**：
roll方向的分级参数二。<br>

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

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

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

## 8 class QualityOfResolution
非深度学习的人脸尺寸评估器。

### 8.1 构造函数

#### QualityOfResolution
人脸尺寸评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|void|| ||

#### QualityOfResolution
人脸尺寸评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|low|float| |分级参数一|
|high|float| |分级参数二|

### 8.2 成员函数

#### check
评估人脸尺寸。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|face|const SeetaRect&| |人脸位置|
|points|const SeetaPointF*| |人脸5个特征点数组|
|N|const int32_t| |人脸特征点数组长度|
|返回值|QualityResult| |人脸尺寸评估结果|

## 9 class QualityOfIntegrity
非深度学习的人脸完整度评估器，评估人脸靠近图像边缘的程度。

### 9.1 构造函数

#### QualityOfIntegrity
人脸完整评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|void|| ||

#### QualityOfIntegrity
人脸尺寸评估器构造函数。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|low|float| |分级参数一|
|high|float| |分级参数二|

说明：low和high主要来控制人脸位置靠近图像边缘的接受程度。

### 9.2 成员函数

#### check
评估人脸完整度。

|参数 | 类型 |缺省值|说明|
|---|---|---|---|
|image|const SeetaImageData&| |原始图像数据|
|face|const SeetaRect&| |人脸位置|
|points|const SeetaPointF*| |人脸5个特征点数组|
|N|const int32_t| |人脸特征点数组长度|
|返回值|QualityResult| |人脸完整度评估结果|