Face_reg_app/FaceFeatureExtractorAPI

人脸特征提取模块 API 文档

概述

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

主要功能

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

快速开始

安装依赖

pip install opencv-python numpy onnxruntime

基础使用

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 类

构造函数

FaceFeatureExtractor(config: Optional[Dict] = None)

参数:

• config: 可选配置字典，如果为None则使用默认配置

示例:

# 使用默认配置
extractor = FaceFeatureExtractor()

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

主要方法

1. extract_single_feature()

extract_single_feature(image: np.ndarray) -> Optional[np.ndarray]

提取单个人脸特征（质量过滤后）

参数:

• image: 输入图像，BGR格式，numpy.ndarray

返回:

• np.ndarray: 质量合格的特征向量
• None: 未检测到人脸或质量不合格

示例:

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

2. extract_multiple_features()

extract_multiple_features(image: np.ndarray) -> List[np.ndarray]

提取多个人脸特征

参数:

• image: 输入图像，BGR格式

返回:

• List[np.ndarray]: 质量合格的特征向量列表

示例:

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

3. extract_features()

extract_features(image: np.ndarray,
                 return_all_faces: bool = False,
                 quality_filter: bool = True) -> FeatureExtractionResult

详细特征提取（包含所有信息）

参数:

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

返回:

• FeatureExtractionResult: 包含人脸信息、质量评分、处理时间等

示例:

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()

get_statistics() -> Dict[str, Any]

获取模块统计信息

返回:

• Dict: 包含处理次数、成功率、平均处理时间等统计

便捷函数

extract_face_feature()

extract_face_feature(image: np.ndarray, config: Optional[Dict] = None) -> Optional[np.ndarray]

提取单个人脸特征的便捷函数

extract_face_features()

extract_face_features(image: np.ndarray, config: Optional[Dict] = None) -> List[np.ndarray]

提取多个人脸特征的便捷函数

配置选项

默认配置结构

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

@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

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

使用示例

示例1: 单人注册

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: 人脸识别

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: 批量处理

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
• 错误日志: 模块会输出详细的调试信息