1316 lines
36 KiB
Markdown
1316 lines
36 KiB
Markdown
# 课前拍照打卡系统总流程与接口规范
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档用于说明课前拍照打卡系统的整体实现流程、模块拆分、模块内部职责、模块之间的接口规范、数据结构、错误码、数据库读写约定和后续扩展方向。
|
||
|
||
当前阶段系统按单机板端方案设计，优先实现两个基础能力：
|
||
|
||
1. 大图人头数统计：输入课堂大图，检测人头或人脸位置，输出人数统计结果。
|
||
2. 单张人脸匹配：输入单张清晰人脸，和本地已注册人脸库匹配，输出识别结果。
|
||
|
||
完整课堂大图多人脸识别打卡属于后续扩展功能。当前文档会预留接口，但不会把第一阶段目标复杂化。
|
||
|
||
## 2. 设计原则
|
||
|
||
1. 单机优先：程序、模型、配置、数据库都部署在 IMX6ULL_ALPHA 板端。
|
||
2. 先命令行，后界面：第一阶段使用命令行运行，方便调试、答辩和移植。
|
||
3. 模块解耦：摄像头、模型推理、后处理、数据库、业务流程分离。
|
||
4. 模型可替换：接口层不绑定具体模型，ncnn 和 TFLite 通过适配层切换。
|
||
5. 数据可追溯：每次检测、匹配都保存输入图片路径、结果、阈值、模型版本和时间。
|
||
6. 板端友好：避免重复加载模型，避免保存过多大文件，避免不必要的内存拷贝。
|
||
|
||
## 3. 默认技术决策
|
||
|
||
当前先采用以下默认方案，后续如果实测性能不满足，再做调整。
|
||
|
||
| 项目 | 默认方案 | 原因 |
|
||
| --- | --- | --- |
|
||
| 开发语言 | C++17 | 适合嵌入式 Linux，便于调用 OpenCV、SQLite、ncnn |
|
||
| 构建系统 | CMake | 方便 PC 编译和交叉编译 |
|
||
| 图像处理 | OpenCV | 摄像头采集、图片读写、resize、画框方便 |
|
||
| 推理框架 | ncnn 优先，TFLite 预留 | ncnn 对 ARM CPU 友好，部署文件简单 |
|
||
| 本地数据库 | SQLite | 单机部署简单，不需要数据库服务 |
|
||
| 配置格式 | JSON | 结构清晰，便于维护 |
|
||
| 第一阶段运行方式 | 命令行工具 | 降低 UI 干扰，先跑通核心功能 |
|
||
| 时间格式 | 本地时间字符串 `YYYY-MM-DD HH:MM:SS` | 便于查看数据库记录 |
|
||
| 图片路径 | 相对项目运行目录保存 | 方便板端迁移 |
|
||
|
||
## 4. 系统总体架构
|
||
|
||
```text
|
||
+-----------------------------+
|
||
| attendance_app |
|
||
| command line entry point |
|
||
+--------------+--------------+
|
||
|
|
||
v
|
||
+-----------------------------+
|
||
| AppContext |
|
||
| config / db / model paths |
|
||
+--+-----------+-----------+--+
|
||
| | |
|
||
+-----------+ | +----------------+
|
||
v v v
|
||
+---------------+ +---------------+ +----------------+
|
||
| CameraCapture | | HeadCounter | | FaceMatchFlow |
|
||
| V4L2/OpenCV | | large image | | register/match |
|
||
+-------+-------+ +-------+-------+ +--------+-------+
|
||
| | |
|
||
v v v
|
||
+---------------+ +---------------+ +----------------+
|
||
| ImageUtils | | HeadDetector | | FaceDetector |
|
||
| read/save | | model infer | | single face |
|
||
| draw/resize | +-------+-------+ +--------+-------+
|
||
+---------------+ | |
|
||
v v
|
||
+---------------+ +----------------+
|
||
| Postprocess | | FaceAligner |
|
||
| decode / NMS | | crop / align |
|
||
+-------+-------+ +--------+-------+
|
||
| |
|
||
v v
|
||
+---------------+ +----------------+
|
||
| AttendanceDB |<-----------| FeatureExtract |
|
||
| SQLite write | | embedding |
|
||
+---------------+ +--------+-------+
|
||
|
|
||
v
|
||
+----------------+
|
||
| FaceMatcher |
|
||
| cosine search |
|
||
+----------------+
|
||
```
|
||
|
||
## 5. 程序运行模式
|
||
|
||
主程序 `attendance_app` 负责解析命令行参数，并根据 `--mode` 调用不同业务流程。
|
||
|
||
| 模式 | 功能 | 当前阶段 |
|
||
| --- | --- | --- |
|
||
| `capture` | 摄像头拍照并保存图片 | 可选实现 |
|
||
| `head_count` | 大图人头数统计 | 必须实现 |
|
||
| `register_face` | 注册学生人脸特征 | 必须实现 |
|
||
| `face_match` | 单张人脸匹配 | 必须实现 |
|
||
| `init_db` | 初始化数据库 | 必须实现 |
|
||
| `full_attendance` | 大图多人脸识别打卡 | 后续扩展 |
|
||
|
||
### 5.1 命令行规范
|
||
|
||
```bash
|
||
./attendance_app --mode init_db
|
||
./attendance_app --mode capture --output data/images/capture_001.jpg
|
||
./attendance_app --mode head_count --image data/images/classroom.jpg
|
||
./attendance_app --mode register_face --student-no 20240001 --name zhangsan --class-name class01 --image data/faces/zhangsan.jpg
|
||
./attendance_app --mode face_match --image data/images/test_face.jpg
|
||
```
|
||
|
||
### 5.2 通用命令行参数
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `--mode` | 是 | 运行模式 |
|
||
| `--config` | 否 | 主配置文件路径，默认 `config/app_config.json` |
|
||
| `--image` | 部分模式必填 | 输入图片路径 |
|
||
| `--output` | 否 | 输出图片路径 |
|
||
| `--save-result-image` | 否 | 是否保存带框结果图 |
|
||
| `--verbose` | 否 | 输出详细日志 |
|
||
|
||
## 6. 总流程设计
|
||
|
||
## 6.1 程序启动流程
|
||
|
||
所有模式共用启动流程。
|
||
|
||
```text
|
||
main()
|
||
-> parse command line
|
||
-> load app_config.json
|
||
-> load camera_config.json
|
||
-> load model_config.json
|
||
-> create AppContext
|
||
-> init log module
|
||
-> ensure data directories exist
|
||
-> open SQLite database
|
||
-> dispatch by mode
|
||
```
|
||
|
||
### 6.1.1 启动阶段检查项
|
||
|
||
| 检查项 | 失败处理 |
|
||
| --- | --- |
|
||
| 配置文件存在且可解析 | 返回 `CONFIG_ERROR` |
|
||
| 数据目录可写 | 返回 `FILE_IO_ERROR` |
|
||
| 数据库可打开 | 返回 `DATABASE_ERROR` |
|
||
| 模型文件存在 | 进入对应模式时返回 `MODEL_LOAD_ERROR` |
|
||
| 输入图片存在 | 返回 `INVALID_ARGUMENT` 或 `FILE_IO_ERROR` |
|
||
|
||
## 6.2 大图人头数统计流程
|
||
|
||
### 6.2.1 流程说明
|
||
|
||
```text
|
||
输入图片路径或摄像头采集
|
||
-> 读取原图 cv::Mat
|
||
-> 检查图片是否为空
|
||
-> resize / letterbox 到模型输入尺寸
|
||
-> 模型推理
|
||
-> 解码模型输出
|
||
-> 置信度过滤
|
||
-> NMS 去重
|
||
-> 坐标映射回原图
|
||
-> 统计有效目标数量
|
||
-> 绘制检测框
|
||
-> 保存结果图片
|
||
-> 写入 head_count_records
|
||
-> 输出 JSON 或终端结果
|
||
```
|
||
|
||
### 6.2.2 顺序调用关系
|
||
|
||
```text
|
||
HeadCountFlow
|
||
-> ImageUtils::ReadImage()
|
||
-> HeadCounter::Count()
|
||
-> HeadDetector::Detect()
|
||
-> HeadPreprocessor::Preprocess()
|
||
-> ModelEngine::Forward()
|
||
-> DetectPostprocess::Decode()
|
||
-> DetectPostprocess::Nms()
|
||
-> ImageUtils::DrawDetections()
|
||
-> AttendanceDB::InsertHeadCountRecord()
|
||
```
|
||
|
||
### 6.2.3 输入
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `image_path` | string | 待检测课堂大图 |
|
||
| `save_result_image` | bool | 是否保存带框图片 |
|
||
| `result_image_path` | string | 结果图片路径，可为空 |
|
||
| `confidence_threshold` | float | 检测置信度阈值 |
|
||
| `nms_threshold` | float | NMS 阈值 |
|
||
|
||
### 6.2.4 输出
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `head_count` | int | 最终统计人数 |
|
||
| `detections` | array | 检测框列表 |
|
||
| `result_image_path` | string | 带框图片路径 |
|
||
| `elapsed_ms` | int | 处理耗时 |
|
||
| `record_id` | int64 | 数据库记录 ID |
|
||
|
||
## 6.3 单张人脸注册流程
|
||
|
||
### 6.3.1 流程说明
|
||
|
||
```text
|
||
输入学生信息和人脸图片
|
||
-> 检查 student_no 是否已存在
|
||
-> 读取图片
|
||
-> 人脸检测
|
||
-> 如果多张人脸，选择最大人脸
|
||
-> 人脸关键点定位
|
||
-> 人脸对齐为固定尺寸
|
||
-> 特征提取
|
||
-> 特征向量 L2 归一化
|
||
-> 保存学生信息
|
||
-> 保存人脸图片和特征向量
|
||
-> 输出注册结果
|
||
```
|
||
|
||
### 6.3.2 顺序调用关系
|
||
|
||
```text
|
||
FaceRegisterFlow
|
||
-> FaceRepository::FindStudentByNo()
|
||
-> ImageUtils::ReadImage()
|
||
-> FaceDetector::Detect()
|
||
-> FaceAligner::Align()
|
||
-> FaceFeatureExtractor::Extract()
|
||
-> FaceMatcher::Normalize()
|
||
-> FaceRepository::InsertStudent()
|
||
-> FaceRepository::InsertFaceTemplate()
|
||
```
|
||
|
||
### 6.3.3 输入
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `student_no` | string | 学号，唯一 |
|
||
| `name` | string | 姓名 |
|
||
| `class_name` | string | 班级 |
|
||
| `image_path` | string | 注册人脸图片 |
|
||
| `overwrite` | bool | 学号已存在时是否覆盖 |
|
||
|
||
### 6.3.4 输出
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `student_id` | int64 | 数据库学生 ID |
|
||
| `template_id` | int64 | 人脸模板 ID |
|
||
| `face_image_path` | string | 保存的人脸图片路径 |
|
||
| `feature_dim` | int | 特征维度 |
|
||
| `message` | string | 注册说明 |
|
||
|
||
## 6.4 单张人脸匹配流程
|
||
|
||
### 6.4.1 流程说明
|
||
|
||
```text
|
||
输入测试人脸图片
|
||
-> 读取图片
|
||
-> 人脸检测
|
||
-> 如果多张人脸，选择最大人脸
|
||
-> 人脸对齐
|
||
-> 特征提取
|
||
-> 特征向量归一化
|
||
-> 从数据库读取所有注册特征
|
||
-> 逐个计算余弦相似度
|
||
-> 选择最高分
|
||
-> 根据阈值判断 matched / unknown
|
||
-> 写入 face_match_records
|
||
-> 输出匹配结果
|
||
```
|
||
|
||
### 6.4.2 顺序调用关系
|
||
|
||
```text
|
||
FaceMatchFlow
|
||
-> ImageUtils::ReadImage()
|
||
-> FaceDetector::Detect()
|
||
-> FaceAligner::Align()
|
||
-> FaceFeatureExtractor::Extract()
|
||
-> FaceRepository::LoadAllTemplates()
|
||
-> FaceMatcher::Match()
|
||
-> FaceRepository::InsertFaceMatchRecord()
|
||
```
|
||
|
||
### 6.4.3 输入
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `image_path` | string | 待匹配人脸图片 |
|
||
| `threshold` | float | 匹配阈值 |
|
||
| `save_aligned_face` | bool | 是否保存对齐后人脸 |
|
||
|
||
### 6.4.4 输出
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `matched` | bool | 是否匹配成功 |
|
||
| `student_id` | int64 | 匹配到的学生 ID |
|
||
| `student_no` | string | 学号 |
|
||
| `name` | string | 姓名 |
|
||
| `score` | float | 最高相似度 |
|
||
| `threshold` | float | 使用阈值 |
|
||
| `status` | string | `matched`、`unknown`、`failed` |
|
||
| `record_id` | int64 | 识别记录 ID |
|
||
|
||
## 6.5 后续完整打卡流程
|
||
|
||
完整流程在第一阶段之后实现。
|
||
|
||
```text
|
||
课堂大图拍照
|
||
-> 大图人脸检测
|
||
-> 裁剪每个人脸
|
||
-> 对每个人脸做对齐和特征提取
|
||
-> 对每个人脸做数据库匹配
|
||
-> 同一学生结果去重
|
||
-> 生成一次课堂 session
|
||
-> 保存每个学生的到课状态
|
||
-> 保存未知人脸和低置信度人脸
|
||
```
|
||
|
||
为避免第一阶段过度复杂，当前仅预留 `full_attendance` 模式和数据库扩展方向。
|
||
|
||
## 7. 模块详细设计
|
||
|
||
## 7.1 App 模块
|
||
|
||
### 7.1.1 职责
|
||
|
||
| 文件 | 职责 |
|
||
| --- | --- |
|
||
| `include/app/app_config.h` | 配置结构定义 |
|
||
| `src/app/app_config.cpp` | JSON 配置读取、默认值填充 |
|
||
| `include/app/app_context.h` | 全局运行上下文 |
|
||
| `src/app/app_context.cpp` | 初始化目录、数据库、公共资源 |
|
||
| `src/main.cpp` | 命令行入口和模式分发 |
|
||
|
||
### 7.1.2 AppContext 内容
|
||
|
||
```cpp
|
||
struct AppContext {
|
||
AppConfig app_config;
|
||
CameraConfig camera_config;
|
||
ModelConfig model_config;
|
||
std::shared_ptr<AttendanceDB> db;
|
||
std::shared_ptr<Logger> logger;
|
||
};
|
||
```
|
||
|
||
### 7.1.3 约束
|
||
|
||
1. `AppContext` 只保存公共依赖，不直接实现业务逻辑。
|
||
2. 模型对象由具体业务模块懒加载或在流程开始时加载。
|
||
3. 数据库连接在程序启动时打开，程序退出时关闭。
|
||
|
||
## 7.2 Config 模块
|
||
|
||
### 7.2.1 app_config.json
|
||
|
||
```json
|
||
{
|
||
"data_root": "data",
|
||
"database_path": "data/database/attendance.db",
|
||
"log_path": "data/logs/attendance.log",
|
||
"save_result_image": true,
|
||
"timezone": "Asia/Shanghai"
|
||
}
|
||
```
|
||
|
||
### 7.2.2 camera_config.json
|
||
|
||
```json
|
||
{
|
||
"device": "/dev/video0",
|
||
"width": 1280,
|
||
"height": 720,
|
||
"fps": 15,
|
||
"format": "MJPEG",
|
||
"warmup_frames": 5
|
||
}
|
||
```
|
||
|
||
### 7.2.3 model_config.json
|
||
|
||
```json
|
||
{
|
||
"engine": "ncnn",
|
||
"head_detect": {
|
||
"param": "models/head_detect/head_detect.param",
|
||
"bin": "models/head_detect/head_detect.bin",
|
||
"input_width": 416,
|
||
"input_height": 416,
|
||
"confidence_threshold": 0.4,
|
||
"nms_threshold": 0.45,
|
||
"model_version": "head_detect_v1"
|
||
},
|
||
"face_detect": {
|
||
"param": "models/face_recognition/face_detect.param",
|
||
"bin": "models/face_recognition/face_detect.bin",
|
||
"input_width": 320,
|
||
"input_height": 320,
|
||
"confidence_threshold": 0.6,
|
||
"nms_threshold": 0.4,
|
||
"model_version": "face_detect_v1"
|
||
},
|
||
"face_feature": {
|
||
"param": "models/face_recognition/face_feature.param",
|
||
"bin": "models/face_recognition/face_feature.bin",
|
||
"input_width": 112,
|
||
"input_height": 112,
|
||
"feature_dim": 128,
|
||
"match_threshold": 0.75,
|
||
"model_version": "face_feature_v1"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2.4 配置读取规则
|
||
|
||
1. 配置缺失时使用默认值，但模型路径、数据库路径不能缺失。
|
||
2. 命令行参数优先级高于配置文件。
|
||
3. 阈值必须在 `[0, 1]` 范围内，否则返回 `CONFIG_ERROR`。
|
||
4. 文件路径统一使用 `/`，在 Windows 调试时由 C++ 标准库兼容处理。
|
||
|
||
## 7.3 Camera 模块
|
||
|
||
### 7.3.1 职责
|
||
|
||
1. 打开摄像头设备。
|
||
2. 设置分辨率、帧率、格式。
|
||
3. 采集一帧图片。
|
||
4. 保存拍照图片。
|
||
5. 出错时返回明确错误码。
|
||
|
||
### 7.3.2 接口定义
|
||
|
||
```cpp
|
||
struct CameraConfig {
|
||
std::string device;
|
||
int width;
|
||
int height;
|
||
int fps;
|
||
std::string format;
|
||
int warmup_frames;
|
||
};
|
||
|
||
struct CaptureResult {
|
||
cv::Mat image;
|
||
std::string saved_path;
|
||
int width;
|
||
int height;
|
||
std::string captured_at;
|
||
};
|
||
|
||
class CameraCapture {
|
||
public:
|
||
Status Open(const CameraConfig& config);
|
||
Result<CaptureResult> CaptureOne(const std::string& save_path);
|
||
void Close();
|
||
};
|
||
```
|
||
|
||
### 7.3.3 实现约定
|
||
|
||
1. PC 调试阶段可使用 OpenCV `VideoCapture`。
|
||
2. 板端如果 OpenCV 摄像头采集不稳定，再切换为 V4L2 实现。
|
||
3. 摄像头打开后先丢弃 `warmup_frames` 帧，降低曝光不稳定影响。
|
||
4. 保存图片默认使用 JPEG，质量参数建议 `85`。
|
||
|
||
## 7.4 ImageUtils 模块
|
||
|
||
### 7.4.1 职责
|
||
|
||
1. 图片读取和保存。
|
||
2. 图片尺寸检查。
|
||
3. resize 和 letterbox。
|
||
4. 检测框绘制。
|
||
5. 图片路径生成。
|
||
|
||
### 7.4.2 接口定义
|
||
|
||
```cpp
|
||
struct LetterboxInfo {
|
||
float scale;
|
||
int pad_x;
|
||
int pad_y;
|
||
int resized_width;
|
||
int resized_height;
|
||
};
|
||
|
||
Result<cv::Mat> ReadImage(const std::string& path);
|
||
Status SaveImage(const std::string& path, const cv::Mat& image);
|
||
Result<cv::Mat> ResizeWithLetterbox(
|
||
const cv::Mat& image,
|
||
int target_width,
|
||
int target_height,
|
||
LetterboxInfo* info
|
||
);
|
||
cv::Rect MapBoxToOriginal(
|
||
const cv::Rect2f& model_box,
|
||
const LetterboxInfo& info,
|
||
int original_width,
|
||
int original_height
|
||
);
|
||
void DrawDetections(cv::Mat* image, const std::vector<Detection>& detections);
|
||
```
|
||
|
||
### 7.4.3 图片坐标约定
|
||
|
||
1. 原点在左上角。
|
||
2. `x` 向右增大，`y` 向下增大。
|
||
3. 检测框格式默认使用 `x, y, width, height`。
|
||
4. 数据库存储整数坐标，模型内部可使用浮点坐标。
|
||
|
||
## 7.5 ModelEngine 模块
|
||
|
||
### 7.5.1 职责
|
||
|
||
为 ncnn 或 TFLite 提供统一推理接口，让业务模块不直接依赖具体推理框架。
|
||
|
||
### 7.5.2 接口定义
|
||
|
||
```cpp
|
||
struct Tensor {
|
||
std::vector<int> shape;
|
||
std::vector<float> data;
|
||
};
|
||
|
||
struct ModelInput {
|
||
std::string name;
|
||
Tensor tensor;
|
||
};
|
||
|
||
struct ModelOutput {
|
||
std::string name;
|
||
Tensor tensor;
|
||
};
|
||
|
||
class ModelEngine {
|
||
public:
|
||
virtual ~ModelEngine() = default;
|
||
virtual Status Load(const ModelLoadOptions& options) = 0;
|
||
virtual Result<std::vector<ModelOutput>> Forward(
|
||
const std::vector<ModelInput>& inputs
|
||
) = 0;
|
||
};
|
||
```
|
||
|
||
### 7.5.3 第一阶段简化方案
|
||
|
||
如果时间紧，可以先不抽象 `ModelEngine`，直接在 `HeadDetector`、`FaceDetector`、`FaceFeatureExtractor` 中调用 ncnn。
|
||
但头文件接口仍然建议保持稳定，避免后续切换模型时影响业务流程。
|
||
|
||
## 7.6 HeadCount 模块
|
||
|
||
### 7.6.1 文件职责
|
||
|
||
| 文件 | 职责 |
|
||
| --- | --- |
|
||
| `include/head_count/head_detector.h` | 人头检测模型接口 |
|
||
| `src/head_count/head_detector.cpp` | 模型加载、预处理、推理 |
|
||
| `include/head_count/detect_postprocess.h` | 检测后处理接口 |
|
||
| `src/head_count/detect_postprocess.cpp` | 输出解码、阈值过滤、NMS |
|
||
| `include/head_count/head_counter.h` | 人头统计业务接口 |
|
||
| `src/head_count/head_counter.cpp` | 串联检测、统计、保存结果 |
|
||
|
||
### 7.6.2 核心数据结构
|
||
|
||
```cpp
|
||
struct Detection {
|
||
int class_id;
|
||
std::string class_name;
|
||
float score;
|
||
float x;
|
||
float y;
|
||
float width;
|
||
float height;
|
||
};
|
||
|
||
struct HeadCountRequest {
|
||
std::string image_path;
|
||
bool save_result_image;
|
||
std::string result_image_path;
|
||
float confidence_threshold;
|
||
float nms_threshold;
|
||
};
|
||
|
||
struct HeadCountResult {
|
||
int head_count;
|
||
std::vector<Detection> detections;
|
||
std::string image_path;
|
||
std::string result_image_path;
|
||
int elapsed_ms;
|
||
int64_t record_id;
|
||
};
|
||
```
|
||
|
||
### 7.6.3 HeadDetector 接口
|
||
|
||
```cpp
|
||
class HeadDetector {
|
||
public:
|
||
Status Load(const HeadDetectConfig& config);
|
||
Result<std::vector<Detection>> Detect(const cv::Mat& image);
|
||
};
|
||
```
|
||
|
||
### 7.6.4 HeadCounter 接口
|
||
|
||
```cpp
|
||
class HeadCounter {
|
||
public:
|
||
HeadCounter(HeadDetector* detector, AttendanceDB* db);
|
||
Result<HeadCountResult> Count(const HeadCountRequest& request);
|
||
};
|
||
```
|
||
|
||
### 7.6.5 后处理规则
|
||
|
||
1. 先按置信度过滤。
|
||
2. 再按类别过滤，只保留 `head` 或 `face` 类别。
|
||
3. 执行 NMS。
|
||
4. 将检测框映射回原图。
|
||
5. 裁剪超出图片边界的坐标。
|
||
6. 最终 `head_count = detections.size()`。
|
||
|
||
### 7.6.6 NMS 接口
|
||
|
||
```cpp
|
||
std::vector<Detection> Nms(
|
||
const std::vector<Detection>& input,
|
||
float iou_threshold
|
||
);
|
||
```
|
||
|
||
## 7.7 FaceMatch 模块
|
||
|
||
### 7.7.1 文件职责
|
||
|
||
| 文件 | 职责 |
|
||
| --- | --- |
|
||
| `include/face_match/face_detector.h` | 单张图片人脸检测接口 |
|
||
| `src/face_match/face_detector.cpp` | 人脸检测模型推理 |
|
||
| `include/face_match/face_aligner.h` | 人脸对齐接口 |
|
||
| `src/face_match/face_aligner.cpp` | 关键点对齐和裁剪 |
|
||
| `include/face_match/face_feature_extractor.h` | 特征提取接口 |
|
||
| `src/face_match/face_feature_extractor.cpp` | 人脸特征模型推理 |
|
||
| `include/face_match/face_matcher.h` | 特征匹配接口 |
|
||
| `src/face_match/face_matcher.cpp` | 余弦相似度匹配 |
|
||
|
||
### 7.7.2 核心数据结构
|
||
|
||
```cpp
|
||
struct FaceLandmarks {
|
||
cv::Point2f left_eye;
|
||
cv::Point2f right_eye;
|
||
cv::Point2f nose;
|
||
cv::Point2f left_mouth;
|
||
cv::Point2f right_mouth;
|
||
};
|
||
|
||
struct FaceDetection {
|
||
float score;
|
||
cv::Rect2f box;
|
||
FaceLandmarks landmarks;
|
||
};
|
||
|
||
struct FaceFeature {
|
||
std::vector<float> values;
|
||
int dim;
|
||
std::string model_version;
|
||
};
|
||
|
||
struct Student {
|
||
int64_t id;
|
||
std::string student_no;
|
||
std::string name;
|
||
std::string class_name;
|
||
};
|
||
|
||
struct FaceTemplate {
|
||
int64_t id;
|
||
Student student;
|
||
FaceFeature feature;
|
||
std::string face_image_path;
|
||
};
|
||
```
|
||
|
||
### 7.7.3 FaceDetector 接口
|
||
|
||
```cpp
|
||
class FaceDetector {
|
||
public:
|
||
Status Load(const FaceDetectConfig& config);
|
||
Result<std::vector<FaceDetection>> Detect(const cv::Mat& image);
|
||
};
|
||
```
|
||
|
||
### 7.7.4 FaceAligner 接口
|
||
|
||
```cpp
|
||
class FaceAligner {
|
||
public:
|
||
Result<cv::Mat> Align(
|
||
const cv::Mat& image,
|
||
const FaceDetection& face,
|
||
int output_width,
|
||
int output_height
|
||
);
|
||
};
|
||
```
|
||
|
||
### 7.7.5 FaceFeatureExtractor 接口
|
||
|
||
```cpp
|
||
class FaceFeatureExtractor {
|
||
public:
|
||
Status Load(const FaceFeatureConfig& config);
|
||
Result<FaceFeature> Extract(const cv::Mat& aligned_face);
|
||
};
|
||
```
|
||
|
||
### 7.7.6 FaceMatcher 接口
|
||
|
||
```cpp
|
||
struct FaceMatchCandidate {
|
||
int64_t student_id;
|
||
std::string student_no;
|
||
std::string name;
|
||
float score;
|
||
};
|
||
|
||
struct FaceMatchRequest {
|
||
std::string image_path;
|
||
float threshold;
|
||
bool save_aligned_face;
|
||
};
|
||
|
||
struct FaceMatchResult {
|
||
bool matched;
|
||
std::string status;
|
||
FaceMatchCandidate best;
|
||
float threshold;
|
||
std::string input_image_path;
|
||
std::string aligned_face_path;
|
||
int elapsed_ms;
|
||
int64_t record_id;
|
||
};
|
||
|
||
class FaceMatcher {
|
||
public:
|
||
static void Normalize(FaceFeature* feature);
|
||
static float CosineSimilarity(
|
||
const std::vector<float>& a,
|
||
const std::vector<float>& b
|
||
);
|
||
Result<FaceMatchResult> Match(
|
||
const FaceFeature& query,
|
||
const std::vector<FaceTemplate>& templates,
|
||
float threshold
|
||
);
|
||
};
|
||
```
|
||
|
||
### 7.7.7 多人脸处理规则
|
||
|
||
单张人脸匹配功能原则上要求输入图片只有一个人脸。若检测到多张人脸，第一阶段默认选择面积最大的人脸。
|
||
|
||
后续可以增加策略：
|
||
|
||
1. 选择置信度最高的人脸。
|
||
2. 选择离图片中心最近的人脸。
|
||
3. 返回错误，要求重新拍摄。
|
||
|
||
当前推荐：注册和单张匹配都选择面积最大人脸，并在日志中记录检测到的人脸数量。
|
||
|
||
## 7.8 Database 模块
|
||
|
||
### 7.8.1 文件职责
|
||
|
||
| 文件 | 职责 |
|
||
| --- | --- |
|
||
| `include/database/attendance_db.h` | 数据库连接和表初始化 |
|
||
| `src/database/attendance_db.cpp` | SQLite 执行 SQL、事务封装 |
|
||
| `include/database/face_repository.h` | 学生、人脸模板、识别记录的数据访问 |
|
||
| `src/database/face_repository.cpp` | 业务数据读写实现 |
|
||
|
||
### 7.8.2 AttendanceDB 接口
|
||
|
||
```cpp
|
||
class AttendanceDB {
|
||
public:
|
||
Status Open(const std::string& db_path);
|
||
Status InitSchema();
|
||
Status Execute(const std::string& sql);
|
||
sqlite3* RawHandle();
|
||
void Close();
|
||
};
|
||
```
|
||
|
||
### 7.8.3 FaceRepository 接口
|
||
|
||
```cpp
|
||
class FaceRepository {
|
||
public:
|
||
explicit FaceRepository(AttendanceDB* db);
|
||
|
||
Result<int64_t> InsertStudent(const Student& student);
|
||
Result<Student> FindStudentByNo(const std::string& student_no);
|
||
Result<int64_t> InsertFaceTemplate(
|
||
int64_t student_id,
|
||
const std::string& image_path,
|
||
const FaceFeature& feature
|
||
);
|
||
Result<std::vector<FaceTemplate>> LoadAllTemplates();
|
||
Result<int64_t> InsertFaceMatchRecord(const FaceMatchResult& result);
|
||
Result<int64_t> InsertHeadCountRecord(const HeadCountResult& result);
|
||
};
|
||
```
|
||
|
||
### 7.8.4 事务约定
|
||
|
||
1. 注册学生时，`students` 和 `face_templates` 必须在同一事务内写入。
|
||
2. 写入检测记录时，如果结果图片保存失败，不写数据库记录。
|
||
3. 数据库写失败时，业务流程返回失败，但不删除原始输入图片。
|
||
4. 特征向量以 float32 二进制 BLOB 保存。
|
||
|
||
## 8. 通用接口规范
|
||
|
||
## 8.1 命名空间
|
||
|
||
所有业务代码建议放入统一命名空间：
|
||
|
||
```cpp
|
||
namespace attendance {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
## 8.2 返回值规范
|
||
|
||
推荐使用 `Status` 和 `Result<T>` 统一表达成功、失败和错误信息。
|
||
|
||
```cpp
|
||
enum class StatusCode {
|
||
OK = 0,
|
||
INVALID_ARGUMENT,
|
||
CONFIG_ERROR,
|
||
FILE_IO_ERROR,
|
||
CAMERA_ERROR,
|
||
MODEL_LOAD_ERROR,
|
||
MODEL_INFER_ERROR,
|
||
IMAGE_PROCESS_ERROR,
|
||
FACE_NOT_FOUND,
|
||
MULTIPLE_FACES_FOUND,
|
||
FEATURE_ERROR,
|
||
DATABASE_ERROR,
|
||
NOT_FOUND,
|
||
UNKNOWN_ERROR
|
||
};
|
||
|
||
struct Status {
|
||
StatusCode code;
|
||
std::string message;
|
||
|
||
bool ok() const {
|
||
return code == StatusCode::OK;
|
||
}
|
||
};
|
||
|
||
template <typename T>
|
||
struct Result {
|
||
Status status;
|
||
T value;
|
||
|
||
bool ok() const {
|
||
return status.ok();
|
||
}
|
||
};
|
||
```
|
||
|
||
### 8.2.1 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
| --- | --- |
|
||
| `OK` | 成功 |
|
||
| `INVALID_ARGUMENT` | 命令行参数或函数入参不合法 |
|
||
| `CONFIG_ERROR` | 配置文件缺失、格式错误、字段非法 |
|
||
| `FILE_IO_ERROR` | 图片、模型、目录读写失败 |
|
||
| `CAMERA_ERROR` | 摄像头打开或采集失败 |
|
||
| `MODEL_LOAD_ERROR` | 模型文件加载失败 |
|
||
| `MODEL_INFER_ERROR` | 模型推理失败 |
|
||
| `IMAGE_PROCESS_ERROR` | 图片 resize、转换、裁剪失败 |
|
||
| `FACE_NOT_FOUND` | 未检测到人脸 |
|
||
| `MULTIPLE_FACES_FOUND` | 检测到多张人脸且当前策略不允许 |
|
||
| `FEATURE_ERROR` | 特征维度错误或特征提取失败 |
|
||
| `DATABASE_ERROR` | SQLite 执行失败 |
|
||
| `NOT_FOUND` | 数据不存在 |
|
||
| `UNKNOWN_ERROR` | 未分类错误 |
|
||
|
||
## 8.3 日志规范
|
||
|
||
日志格式：
|
||
|
||
```text
|
||
[2026-06-04 09:00:00] [INFO] [HeadCounter] image=data/images/classroom.jpg head_count=36 elapsed_ms=2530
|
||
```
|
||
|
||
日志级别：
|
||
|
||
| 级别 | 使用场景 |
|
||
| --- | --- |
|
||
| `DEBUG` | 模型输入尺寸、检测框数量、阈值等调试信息 |
|
||
| `INFO` | 主要流程开始和结束 |
|
||
| `WARN` | 非致命问题，例如检测到多张人脸但选择最大人脸 |
|
||
| `ERROR` | 流程失败，例如模型加载失败、数据库写失败 |
|
||
|
||
## 8.4 JSON 输出规范
|
||
|
||
命令行工具建议支持 `--json` 参数，便于后续 UI 或脚本调用。
|
||
|
||
### 8.4.1 head_count 输出
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"mode": "head_count",
|
||
"image_path": "data/images/classroom.jpg",
|
||
"result_image_path": "data/results/classroom_detected.jpg",
|
||
"head_count": 36,
|
||
"detections": [
|
||
{
|
||
"class_id": 0,
|
||
"class_name": "head",
|
||
"score": 0.91,
|
||
"x": 120,
|
||
"y": 85,
|
||
"width": 32,
|
||
"height": 36
|
||
}
|
||
],
|
||
"elapsed_ms": 2530,
|
||
"record_id": 1
|
||
}
|
||
```
|
||
|
||
### 8.4.2 face_match 输出
|
||
|
||
```json
|
||
{
|
||
"status": "matched",
|
||
"mode": "face_match",
|
||
"input_image_path": "data/images/test_face.jpg",
|
||
"matched": true,
|
||
"student_id": 1,
|
||
"student_no": "20240001",
|
||
"name": "zhangsan",
|
||
"score": 0.82,
|
||
"threshold": 0.75,
|
||
"elapsed_ms": 840,
|
||
"record_id": 12
|
||
}
|
||
```
|
||
|
||
### 8.4.3 失败输出
|
||
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"code": "FACE_NOT_FOUND",
|
||
"message": "no face detected in image",
|
||
"mode": "face_match"
|
||
}
|
||
```
|
||
|
||
## 9. 数据库设计
|
||
|
||
## 9.1 students
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS students (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
student_no TEXT NOT NULL UNIQUE,
|
||
name TEXT NOT NULL,
|
||
class_name TEXT,
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT
|
||
);
|
||
```
|
||
|
||
## 9.2 face_templates
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS face_templates (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
student_id INTEGER NOT NULL,
|
||
face_image_path TEXT NOT NULL,
|
||
feature BLOB NOT NULL,
|
||
feature_dim INTEGER NOT NULL,
|
||
model_version TEXT NOT NULL,
|
||
created_at TEXT NOT NULL,
|
||
FOREIGN KEY(student_id) REFERENCES students(id)
|
||
);
|
||
```
|
||
|
||
## 9.3 head_count_records
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS head_count_records (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
image_path TEXT NOT NULL,
|
||
result_image_path TEXT,
|
||
head_count INTEGER NOT NULL,
|
||
detections_json TEXT NOT NULL,
|
||
confidence_threshold REAL NOT NULL,
|
||
nms_threshold REAL NOT NULL,
|
||
model_version TEXT NOT NULL,
|
||
elapsed_ms INTEGER,
|
||
created_at TEXT NOT NULL
|
||
);
|
||
```
|
||
|
||
## 9.4 face_match_records
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS face_match_records (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
input_image_path TEXT NOT NULL,
|
||
aligned_face_path TEXT,
|
||
matched_student_id INTEGER,
|
||
score REAL,
|
||
threshold REAL NOT NULL,
|
||
status TEXT NOT NULL,
|
||
model_version TEXT NOT NULL,
|
||
elapsed_ms INTEGER,
|
||
created_at TEXT NOT NULL,
|
||
FOREIGN KEY(matched_student_id) REFERENCES students(id)
|
||
);
|
||
```
|
||
|
||
## 9.5 后续扩展表
|
||
|
||
完整课堂打卡时建议增加：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS attendance_sessions (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
class_name TEXT,
|
||
course_name TEXT,
|
||
image_path TEXT NOT NULL,
|
||
result_image_path TEXT,
|
||
expected_count INTEGER,
|
||
detected_count INTEGER,
|
||
recognized_count INTEGER,
|
||
unknown_count INTEGER,
|
||
created_at TEXT NOT NULL
|
||
);
|
||
|
||
CREATE TABLE IF NOT EXISTS attendance_records (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
session_id INTEGER NOT NULL,
|
||
student_id INTEGER,
|
||
face_image_path TEXT,
|
||
bbox_json TEXT,
|
||
score REAL,
|
||
status TEXT NOT NULL,
|
||
created_at TEXT NOT NULL,
|
||
FOREIGN KEY(session_id) REFERENCES attendance_sessions(id),
|
||
FOREIGN KEY(student_id) REFERENCES students(id)
|
||
);
|
||
```
|
||
|
||
## 10. 文件和目录规范
|
||
|
||
## 10.1 目录用途
|
||
|
||
| 目录 | 用途 |
|
||
| --- | --- |
|
||
| `config/` | 配置文件 |
|
||
| `models/head_detect/` | 大图人头检测模型 |
|
||
| `models/face_recognition/` | 人脸检测和特征模型 |
|
||
| `data/images/` | 原始图片 |
|
||
| `data/faces/` | 注册人脸、对齐人脸、裁剪人脸 |
|
||
| `data/results/` | 带框结果图 |
|
||
| `data/database/` | SQLite 数据库 |
|
||
| `data/logs/` | 日志文件 |
|
||
| `include/` | 头文件 |
|
||
| `src/` | 源码 |
|
||
| `tools/` | 独立工具程序 |
|
||
| `tests/` | 单元测试 |
|
||
| `docs/` | 设计文档 |
|
||
|
||
## 10.2 文件命名
|
||
|
||
拍照图片：
|
||
|
||
```text
|
||
data/images/capture_YYYYMMDD_HHMMSS.jpg
|
||
```
|
||
|
||
人头统计结果图：
|
||
|
||
```text
|
||
data/results/head_count_YYYYMMDD_HHMMSS.jpg
|
||
```
|
||
|
||
注册人脸图：
|
||
|
||
```text
|
||
data/faces/register_{student_no}_YYYYMMDD_HHMMSS.jpg
|
||
```
|
||
|
||
单张匹配对齐图：
|
||
|
||
```text
|
||
data/faces/match_aligned_YYYYMMDD_HHMMSS.jpg
|
||
```
|
||
|
||
## 11. 模块间数据流
|
||
|
||
## 11.1 head_count 数据流
|
||
|
||
| 阶段 | 输入 | 输出 |
|
||
| --- | --- | --- |
|
||
| 图片读取 | `image_path` | `cv::Mat original` |
|
||
| 预处理 | `original` | `model_input`, `LetterboxInfo` |
|
||
| 推理 | `model_input` | raw tensors |
|
||
| 后处理 | raw tensors, `LetterboxInfo` | `vector<Detection>` |
|
||
| 统计 | `vector<Detection>` | `head_count` |
|
||
| 画图 | `original`, detections | result image |
|
||
| 入库 | result object | record ID |
|
||
|
||
## 11.2 face_match 数据流
|
||
|
||
| 阶段 | 输入 | 输出 |
|
||
| --- | --- | --- |
|
||
| 图片读取 | `image_path` | `cv::Mat image` |
|
||
| 人脸检测 | `image` | `vector<FaceDetection>` |
|
||
| 人脸选择 | detections | `FaceDetection selected` |
|
||
| 对齐 | image, selected | `cv::Mat aligned_face` |
|
||
| 特征提取 | aligned_face | `FaceFeature query` |
|
||
| 模板读取 | database | `vector<FaceTemplate>` |
|
||
| 匹配 | query, templates | `FaceMatchResult` |
|
||
| 入库 | result | record ID |
|
||
|
||
## 12. 性能和资源约束
|
||
|
||
IMX6ULL_ALPHA 板端性能有限，代码实现时需要遵守以下约束：
|
||
|
||
1. 模型只加载一次，不能每张图片重新加载。
|
||
2. 尽量使用较小输入尺寸，例如 `320x320`、`416x416`。
|
||
3. 大图检测优先使用 letterbox，不直接拉伸变形。
|
||
4. 数据库特征模板加载后可以缓存，注册新人后再刷新缓存。
|
||
5. 图片保存默认 JPEG，避免保存 BMP/PNG 大文件。
|
||
6. 日志不要频繁写大量检测框细节，调试时再打开 `DEBUG`。
|
||
7. 避免在循环中频繁创建大 `cv::Mat`，可复用缓冲区。
|
||
8. 第一阶段采用单线程顺序流程，确保稳定后再考虑多线程。
|
||
|
||
## 13. 测试计划
|
||
|
||
## 13.1 单元测试
|
||
|
||
| 测试文件 | 测试内容 |
|
||
| --- | --- |
|
||
| `tests/test_head_postprocess.cpp` | NMS、坐标映射、置信度过滤 |
|
||
| `tests/test_face_similarity.cpp` | 余弦相似度、特征归一化 |
|
||
| `tests/test_config.cpp` | 配置读取和默认值 |
|
||
| `tests/test_database.cpp` | 数据库初始化、插入、查询 |
|
||
|
||
## 13.2 PC 端集成测试
|
||
|
||
1. 使用本地图片测试 `head_count`。
|
||
2. 注册 5 名学生。
|
||
3. 用同一学生不同图片测试 `face_match`。
|
||
4. 用未注册人员图片测试 `unknown`。
|
||
5. 删除模型文件，确认返回 `MODEL_LOAD_ERROR`。
|
||
6. 输入不存在图片，确认返回 `FILE_IO_ERROR`。
|
||
|
||
## 13.3 板端测试
|
||
|
||
1. 摄像头能正常拍照并保存。
|
||
2. `head_count` 能在板端完成一次推理。
|
||
3. `face_match` 能在板端完成一次推理。
|
||
4. 连续运行 20 次不崩溃。
|
||
5. 断电重启后数据库仍可读取。
|
||
6. 存储空间不足时能返回明确错误。
|
||
|
||
## 14. 第一阶段验收标准
|
||
|
||
## 14.1 大图人头数统计
|
||
|
||
1. 能读取本地课堂大图。
|
||
2. 能输出检测到的人头数量。
|
||
3. 能保存带框结果图。
|
||
4. 能将检测记录写入 SQLite。
|
||
5. 命令行能输出文本结果和 JSON 结果。
|
||
|
||
## 14.2 单张人脸匹配
|
||
|
||
1. 能注册至少 5 名学生。
|
||
2. 能保存学生信息和特征向量。
|
||
3. 能识别已注册学生。
|
||
4. 能将未注册人员识别为 `unknown`。
|
||
5. 能保存识别记录。
|
||
|
||
## 15. 待确认决策项
|
||
|
||
以下问题建议在开始编码核心模型模块前确认。
|
||
|
||
| 编号 | 决策项 | 推荐默认值 | 影响 |
|
||
| --- | --- | --- | --- |
|
||
| D1 | 推理框架选 ncnn 还是 TFLite | ncnn | 影响模型转换和 C++ 调用方式 |
|
||
| D2 | 大图统计检测对象是人头还是人脸 | 人头优先，脸部可备选 | 人头对低头、侧脸更稳；人脸方便后续识别 |
|
||
| D3 | 摄像头类型 | 先 USB 摄像头 | OpenCV 采集更容易调试 |
|
||
| D4 | 人脸特征维度 | 按模型确定，优先 128 或 512 | 影响数据库 BLOB 大小和匹配速度 |
|
||
| D5 | 注册时一人保存几个模板 | 第一阶段 1 个 | 多模板准确率更高，但管理更复杂 |
|
||
| D6 | 多人脸输入单张匹配时如何处理 | 选择最大人脸 | 简单可演示，但可能误选背景人脸 |
|
||
| D7 | 匹配阈值 | 初始 0.75 | 需要通过测试集调参 |
|
||
| D8 | 是否加入 LCD/Web 界面 | 第一阶段不加 | 先保证算法和数据链路稳定 |
|
||
| D9 | 是否做完整大图多人脸识别 | 第二阶段做 | 第一阶段先验证两个基础能力 |
|
||
|
||
## 16. 建议实施顺序
|
||
|
||
1. 建立基础 CMake 工程。
|
||
2. 实现 `Status`、`Result<T>`、日志、时间工具。
|
||
3. 实现配置读取。
|
||
4. 实现 SQLite 初始化和基础表结构。
|
||
5. 实现图片读写、画框、letterbox、坐标映射。
|
||
6. 实现 `head_count` 的后处理和假数据测试。
|
||
7. 接入真实人头检测模型。
|
||
8. 实现人脸特征相似度和数据库模板读写。
|
||
9. 接入人脸检测、人脸对齐、特征提取模型。
|
||
10. 打通 `register_face`。
|
||
11. 打通 `face_match`。
|
||
12. 在 PC 端完整测试。
|
||
13. 交叉编译部署到 IMX6ULL_ALPHA。
|
||
14. 根据板端耗时和准确率调整模型和阈值。
|
||
|
||
## 17. 后续扩展接口预留
|
||
|
||
完整课堂打卡可以新增以下业务接口。
|
||
|
||
```cpp
|
||
struct AttendanceSessionRequest {
|
||
std::string image_path;
|
||
std::string class_name;
|
||
std::string course_name;
|
||
bool save_result_image;
|
||
};
|
||
|
||
struct AttendanceRecord {
|
||
int64_t student_id;
|
||
std::string student_no;
|
||
std::string name;
|
||
Detection face_box;
|
||
float score;
|
||
std::string status;
|
||
std::string face_image_path;
|
||
};
|
||
|
||
struct AttendanceSessionResult {
|
||
int64_t session_id;
|
||
int detected_count;
|
||
int recognized_count;
|
||
int unknown_count;
|
||
std::vector<AttendanceRecord> records;
|
||
std::string image_path;
|
||
std::string result_image_path;
|
||
};
|
||
|
||
class AttendanceFlow {
|
||
public:
|
||
Result<AttendanceSessionResult> Run(
|
||
const AttendanceSessionRequest& request
|
||
);
|
||
};
|
||
```
|
||
|
||
后续完整打卡流程可以复用第一阶段已经实现的：
|
||
|
||
1. 图片读取和保存。
|
||
2. 人脸或人头检测。
|
||
3. 人脸对齐。
|
||
4. 特征提取。
|
||
5. 特征匹配。
|
||
6. SQLite 入库。
|
||
|
||
## 18. 风险点和规避方案
|
||
|
||
| 风险 | 表现 | 规避方案 |
|
||
| --- | --- | --- |
|
||
| 板端推理慢 | 一张图处理十几秒以上 | 降低输入尺寸、换更小模型、只做演示级检测 |
|
||
| 后排人脸太小 | 漏检严重 | 使用更高分辨率拍照、调整摄像头位置、使用人头检测模型 |
|
||
| 光照差 | 检测和识别不稳定 | 固定摄像头曝光，增加补光，加入模糊/亮度检查 |
|
||
| 阈值不合适 | 误识别或大量 unknown | 用真实班级图片调参 |
|
||
| 数据库特征模型版本混乱 | 新旧特征不可比 | `face_templates` 必须保存 `model_version` |
|
||
| 中文路径或姓名乱码 | 数据显示异常 | 源码和数据库统一 UTF-8 |
|
||
| 摄像头驱动不稳定 | 拍照失败 | 先用 USB 摄像头，必要时改 V4L2 |
|
||
|
||
## 19. 当前推荐结论
|
||
|
||
第一阶段按以下路线推进最稳：
|
||
|
||
1. 使用 C++17 + OpenCV + SQLite + ncnn。
|
||
2. 先实现命令行程序，不做界面。
|
||
3. 大图人头数统计和单张人脸匹配分开实现。
|
||
4. 人头统计先只输出人数，不做人脸身份识别。
|
||
5. 单张人脸匹配先要求输入清晰单人脸。
|
||
6. 所有结果都保存到 SQLite，便于答辩展示和后续扩展。
|
||
|