# 人脸特征提取模块 API 文档

## 概述

`face_feature_extractor.py` 是一个独立的人脸特征提取模块，输入图像，输出质量评估合格的特征值。

### 主要功能
- ✅ 人脸检测和关键点检测
- ✅ 人脸对齐和预处理
- ✅ 多维度质量评估（亮度、清晰度、姿态、分辨率）
- ✅ 特征提取和标准化
- ✅ 质量过滤，只返回合格特征
- ✅ 支持单人和多人脸处理
- ✅ 可配置的质量阈值

## 快速开始

### 安装依赖
```bash
pip install opencv-python numpy onnxruntime
```

### 基础使用
```python
import cv2
from face_feature_extractor import extract_face_feature

# 读取图像
image = cv2.imread("person.jpg")

# 提取特征（自动质量过滤）
feature = extract_face_feature(image)

if feature is not None:
    print(f"特征维度: {feature.shape}")
    print(f"特征范数: {np.linalg.norm(feature):.6f}")
else:
    print("特征提取失败（质量检查未通过或未检测到人脸）")
```

## 核心 API

### FaceFeatureExtractor 类

#### 构造函数
```python
FaceFeatureExtractor(config: Optional[Dict] = None)
```

**参数:**
- `config`: 可选配置字典，如果为None则使用默认配置

**示例:**
```python
# 使用默认配置
extractor = FaceFeatureExtractor()

# 使用自定义配置
config = {
    "detection": {"score_threshold": 0.5},
    "quality": {"strict_mode": False}
}
extractor = FaceFeatureExtractor(config)
```

#### 主要方法

##### 1. extract_single_feature()
```python
extract_single_feature(image: np.ndarray) -> Optional[np.ndarray]
```
提取单个人脸特征（质量过滤后）

**参数:**
- `image`: 输入图像，BGR格式，numpy.ndarray

**返回:**
- `np.ndarray`: 质量合格的特征向量
- `None`: 未检测到人脸或质量不合格

**示例:**
```python
feature = extractor.extract_single_feature(image)
if feature is not None:
    print(f"成功提取特征: {feature.shape}")
```

##### 2. extract_multiple_features()
```python
extract_multiple_features(image: np.ndarray) -> List[np.ndarray]
```
提取多个人脸特征

**参数:**
- `image`: 输入图像，BGR格式

**返回:**
- `List[np.ndarray]`: 质量合格的特征向量列表

**示例:**
```python
features = extractor.extract_multiple_features(image)
print(f"检测到 {len(features)} 个质量合格的人脸")
```

##### 3. extract_features()
```python
extract_features(image: np.ndarray,
                 return_all_faces: bool = False,
                 quality_filter: bool = True) -> FeatureExtractionResult
```
详细特征提取（包含所有信息）

**参数:**
- `image`: 输入图像
- `return_all_faces`: 是否返回所有人脸（包括质量不合格的）
- `quality_filter`: 是否进行质量过滤

**返回:**
- `FeatureExtractionResult`: 包含人脸信息、质量评分、处理时间等

**示例:**
```python
result = extractor.extract_features(image, return_all_faces=True, quality_filter=False)
print(f"检测到 {len(result.faces)} 个人脸")
for face in result.faces:
    print(f"置信度: {face.confidence:.3f}")
    print(f"质量合格: {face.quality_scores['overall']['passed']}")
```

##### 4. get_statistics()
```python
get_statistics() -> Dict[str, Any]
```
获取模块统计信息

**返回:**
- `Dict`: 包含处理次数、成功率、平均处理时间等统计

## 便捷函数

### extract_face_feature()
```python
extract_face_feature(image: np.ndarray, config: Optional[Dict] = None) -> Optional[np.ndarray]
```
提取单个人脸特征的便捷函数

### extract_face_features()
```python
extract_face_features(image: np.ndarray, config: Optional[Dict] = None) -> List[np.ndarray]
```
提取多个人脸特征的便捷函数

## 配置选项

### 默认配置结构
```python
config = {
    "model_paths": {
        "detector": "./checkpoints/faceboxesv2-640x640.onnx",
        "landmk1": "./checkpoints/face_landmarker_pts5_net1.onnx",
        "landmk2": "./checkpoints/face_landmarker_pts5_net2.onnx",
        "recognizer": "./checkpoints/face_recognizer.onnx",
        "rotifier": "./checkpoints/model_gray_mobilenetv2_rotcls.onnx",
        "num_threads": 4
    },
    "detection": {
        "score_threshold": 0.35,    # 检测置信度阈值
        "iou_threshold": 0.45,      # NMS IoU阈值
        "max_faces": 1              # 最大处理人脸数
    },
    "quality": {
        "brightness": {
            "v0": 69.0, "v1": 70.0, "v2": 230.0, "v3": 231.0
        },
        "resolution": {
            "height": 112, "width": 112
        },
        "clarity": {
            "low_thrd": 0.10, "high_thrd": 0.20
        },
        "pose": {
            "yaw_thrd": 30.0, "pitch_thrd": 25.0,
            "var_onnx_path": "./checkpoints/fsanet-var.onnx",
            "conv_onnx_path": "./checkpoints/fsanet-conv.onnx"
        },
        "strict_mode": True          # 严格模式，所有质量检查都通过
    }
}
```

### 质量评估说明

模块会对每个人脸进行以下质量检查：

1. **亮度检查**: 确保人脸亮度在合理范围内
2. **分辨率检查**: 确保人脸分辨率足够高
3. **清晰度检查**: 确保图像清晰度良好
4. **姿态检查**: 确保人脸姿态正对摄像头

在严格模式下，只有所有检查都通过才会返回特征。

## 数据结构

### FaceInfo
```python
@dataclass
class FaceInfo:
    bbox: Tuple[float, float, float, float]     # 人脸边界框
    landmarks: List[Tuple[float, float]]        # 5个关键点
    confidence: float                           # 检测置信度
    quality_scores: Dict[str, Any]              # 质量评分
    feature: Optional[np.ndarray]               # 特征向量
```

### FeatureExtractionResult
```python
@dataclass
class FeatureExtractionResult:
    success: bool                    # 是否成功
    faces: List[FaceInfo]           # 检测到的人脸列表
    processing_time: float           # 处理时间
    error_message: Optional[str]    # 错误信息
```

## 使用示例

### 示例1: 单人注册
```python
import cv2
from face_feature_extractor import FaceFeatureExtractor

# 初始化
extractor = FaceFeatureExtractor()

# 读取图像
image = cv2.imread("user_photo.jpg")

# 提取特征
feature = extractor.extract_single_feature(image)

if feature is not None:
    # 保存特征到数据库
    save_feature_to_database(user_id="user123", feature=feature)
    print("用户注册成功")
else:
    print("注册失败，请使用质量更好的照片")
```

### 示例2: 人脸识别
```python
import cv2
import numpy as np
from face_feature_extractor import FaceFeatureExtractor

def recognize_user(image):
    extractor = FaceFeatureExtractor()

    # 提取待识别人脸特征
    unknown_feature = extractor.extract_single_feature(image)
    if unknown_feature is None:
        return None

    # 从数据库加载已知特征
    known_features = load_features_from_database()

    # 计算相似度
    best_match = None
    best_similarity = 0.0

    for user_id, known_feature in known_features.items():
        similarity = np.dot(unknown_feature, known_feature)
        if similarity > best_similarity and similarity > 0.7:
            best_similarity = similarity
            best_match = user_id

    return best_match, best_similarity

# 使用
image = cv2.imread("test_photo.jpg")
user_id, similarity = recognize_user(image)
if user_id:
    print(f"识别成功: {user_id}, 相似度: {similarity:.6f}")
else:
    print("识别失败")
```

### 示例3: 批量处理
```python
import os
import cv2
from face_feature_extractor import FaceFeatureExtractor

def batch_process_images(image_dir):
    extractor = FaceFeatureExtractor()
    results = {}

    for filename in os.listdir(image_dir):
        if filename.lower().endswith(('.jpg', '.jpeg', '.png')):
            image_path = os.path.join(image_dir, filename)
            image = cv2.imread(image_path)

            if image is not None:
                feature = extractor.extract_single_feature(image)
                if feature is not None:
                    results[filename] = feature
                    print(f"✓ {filename}: 特征提取成功")
                else:
                    print(f"✗ {filename}: 质量不合格")

    return results

# 使用
features = batch_process_images("./photos/")
print(f"成功处理 {len(features)} 张图像")
```

## 性能优化建议

1. **复用实例**: 对于批量处理，复用 `FaceFeatureExtractor` 实例
2. **调整线程数**: 根据硬件调整 `num_threads` 参数
3. **质量阈值**: 根据应用场景调整质量阈值
4. **图像预处理**: 确保输入图像质量良好

## 错误处理

### 常见错误及解决方案

1. **未检测到人脸**
   - 确保图像中包含清晰的人脸
   - 调整检测阈值 `score_threshold`

2. **质量检查未通过**
   - 使用更好的光照条件
   - 确保人脸姿态正对摄像头
   - 调整质量阈值或关闭严格模式

3. **模型加载失败**
   - 检查模型文件路径是否正确
   - 确保模型文件完整且未损坏

4. **处理速度慢**
   - 减少 `num_threads` 参数
   - 降低输入图像分辨率
   - 使用 GPU 版本的 ONNX Runtime

## 更新日志

### v1.0.0
- 初始版本发布
- 支持基础特征提取功能
- 集成质量评估系统
- 提供完整的 API 接口

## 技术支持

如有问题或建议，请查看：
- 测试代码: `test_feature_extractor.py`
- 使用示例: `feature_extractor_examples.py`
- 错误日志: 模块会输出详细的调试信息