四川大学 C++ 暑期实训项目。使用 Qt Widgets + OpenCV 实现： 实时人脸检测（YuNet）、人脸注册与识别（SFace）、人员数据库管理（SQLite）、 识别日志与签到导出。
| 模块 | 功能 |
|---|---|
| 实时视频 | 摄像头采集（640x480，QTimer 每 30ms 取帧）、开始/停止、导入本地图片识别 |
| 人脸检测 | YuNet 模型，视频流中每张人脸画绿色矩形框 |
| 人脸识别 | SFace 128 维特征 + 余弦相似度，超过阈值显示姓名+得分，否则显示"陌生人" |
| 人员管理 | SQLite 数据库，表格增删改查；注册支持摄像头连拍 5 张或本地照片导入，平均特征入库 |
| 识别日志 | 时间、姓名、得分、抓拍缩略图；同一人 30 秒内不重复记录 |
| 签到模式 | 开启后识别成功自动记入当日签到（一天一次），可导出 CSV |
| 性能 | 检测每 2 帧执行一次（画面每帧刷新），状态栏实时显示 FPS；识别阈值滑块实时调节 |
- macOS + Xcode 命令行工具（
xcode-select --install） - Qt 5（Widgets / Sql 模块）+ Qt Creator
- OpenCV 4.x（Homebrew 安装）
- pkg-config（Homebrew 安装，qmake 靠它找到 OpenCV）
brew install opencv pkgconfApple Silicon（M 系列芯片）注意：Qt 官方的 5.14.2 安装包只有 x86_64 版本，没法链接 Homebrew 的 arm64 OpenCV。推荐直接用 Homebrew 的 Qt 5 （5.15，与 5.14 完全同代，本项目代码不使用任何 5.15 新增接口）：
brew install qt@5然后在 Qt Creator 里注册这个 Qt 版本（只需配置一次）：
- Qt Creator → 偏好设置（Preferences）→ Kits → Qt Versions → 添加，
选择
/opt/homebrew/opt/qt@5/bin/qmake - 切到 Kits 页 → 添加一个新 Kit，Qt 版本选上一步添加的 qt@5， 编译器选 Apple Clang
- 打开工程后在左侧 Projects 页勾选这个 Kit
Intel 芯片的 Mac 可以直接用官方 Qt 5.14.2 安装包（macOS clang 64-bit），
OpenCV 同样用 brew install opencv 即可，无需上述 Kit 配置。
bash scripts/download_models.sh会把 YuNet（人脸检测，约 230KB）和 SFace（特征提取，约 37MB）两个 ONNX
模型下载到 models/ 目录。GitHub 直连慢可以用：
MIRROR=https://gh-proxy.com/ bash scripts/download_models.sh
- 用 Qt Creator 打开
FaceRecognition.pro - 首次打开选择 Kit 后点 Configure Project
- 直接点运行（⌘R）
工程通过 pkg-config 自动定位 OpenCV 头文件与库（见 .pro 中
PKGCONFIG += opencv4），没有写死任何绝对路径；models/ 和 data/
目录通过 qmake 传入的工程路径定位，换机器重新 qmake 即可。
- 实时识别页：点"开始"打开摄像头；拖动阈值滑块可实时调整判定 松紧（默认 0.363）；勾选"签到模式"后识别成功自动签到， "导出今日签到"生成 CSV 文件。
- 人员管理页：点"注册人员"，输入姓名部门后，用摄像头按提示 连拍 5 张（正脸/左转/右转/抬头/低头各一张），或"导入照片"批量 选择本地照片；双击表格单元格可直接修改，"删除选中"删除人员及其特征。
- 识别日志页：查看识别记录（时间/姓名/得分/抓拍缩略图）。
运行数据（数据库 face.db、抓拍图 snapshots/）保存在工程的
data/ 目录下，已被 .gitignore 排除。
把项目打成不依赖开发环境、可以直接发给别人运行的程序，一条命令：
bash scripts/package_app.sh # 产出 build-release/FaceRecognition.app
bash scripts/package_app.sh --dmg # 追加生成 FaceRecognition.dmg 镜像脚本做的事：Release 编译 → 模型拷进 .app → macdeployqt 把 Qt
Frameworks 和 OpenCV 的 dylib 拷进 .app/Contents/Frameworks/ 并把
依赖路径改写为相对路径 → 补齐 macdeployqt 漏掉的库 → 自动验证
（otool -L 检查无 Homebrew 路径残留 + 拷到 /tmp 独立启动一次）。
macdeployqt 是 Qt 在 macOS 上的部署工具，与 Windows 下的 windeployqt
相对应：windeployqt 把 Qt 的 DLL 拷到 exe 旁边（Windows 从 exe 所在
目录找 DLL）；macdeployqt 把依赖拷进 .app 包内并用 install_name_tool
改写查找路径（macOS 按库里记录的路径找依赖）。两者目的相同——
把程序依赖的动态库收拢到发布包里，让没装开发环境的机器也能运行。
打包后的程序从 .app/Contents/Resources/models/ 读模型，运行数据写到
~/Library/Application Support/人脸识别签到系统/（.app 内部是只读的，
不能写数据库）；开发时仍用工程目录的 models/ 和 data/，两级查找
逻辑见 src/apppath.h。
1. 摄像头打不开 / 画面黑屏
第一次点"开始"时 macOS 会弹出摄像头授权框，必须点"允许"。如果当时
点了拒绝，去 系统设置 → 隐私与安全性 → 摄像头 里把本程序（从 Qt
Creator 启动时是 Qt Creator）打开，然后重启程序。工程的 Info.plist
已配置 NSCameraUsageDescription，缺少这个声明系统会直接拒绝访问。
2. 画面颜色发蓝/偏色
OpenCV 的 Mat 是 BGR 通道顺序，QImage 是 RGB，显示前必须
cv::cvtColor(..., COLOR_BGR2RGB) 转换（见 src/imageutils.h）。
如果出现整体偏蓝的人脸，就是漏了这一步。
3. qmake 报错 "opencv4 development package not found"
Qt Creator 从图形界面启动时继承不到终端的 PATH，找不到 Homebrew 的
pkg-config。本工程 .pro 已直接写入 Homebrew pkg-config 的完整路径做了
兜底；若仍报错，确认 brew install pkgconf opencv 已执行成功。
4. 启动时提示"模型缺失"
未运行下载脚本。在工程根目录执行 bash scripts/download_models.sh。
5. 导出的 CSV 用 Excel 打开中文乱码 不应出现——导出时已写入 UTF-8 BOM。如果用其他工具二次保存后乱码， 用"数据 → 从文本导入"并选择 UTF-8 编码。
6. 工程必须放在纯英文路径下
实测 Homebrew 的 qmake 处理不了含中文的工程路径：qmake 会报
Cannot find file: ....pro（文件明明存在）。这是 qmake 对命令行参数
的编码处理缺陷，与本工程无关。务必把工程放在不含中文、不含空格的
路径下（例如 ~/Desktop/FaceRecognition）再用 Qt Creator 打开。
FaceRecognition/
├── FaceRecognition.pro # qmake 工程文件
├── Info.plist # macOS 摄像头权限声明
├── src/
│ ├── main.cpp # 入口
│ ├── mainwindow.* # 主窗口：三页布局 + 视频流 + 识别调度
│ ├── faceengine.* # 算法封装：检测/特征/比对（UI 不碰 DNN）
│ ├── persondb.* # 数据库封装：全部 SQL 集中在这里
│ ├── registerdialog.* # 注册对话框：连拍/导入 + 平均特征
│ ├── imageutils.h # Mat -> QImage 转换
│ └── apppath.h # 模型/数据目录定位
├── models/ # ONNX 模型（脚本下载，不入库）
├── scripts/download_models.sh
└── docs/ # 测试清单、答辩要点