简介：在Ubuntu系统下，基于Qt与OpenCV的人脸识别项目资料，面向计算机相关专业学生及开发者。资源包含完整可运行的工程代码，覆盖人脸检测、视频识别、图片输入等核心功能，并配有界面设计文件、头文件及说明文档，可作为毕业设计、课程设计或人脸识别入门的学习参考。压缩包内共23个文件，包括7个C++源文件、6个界面UI文件、6个头文件，以及工程配置和README等，整体大小约21KB，结构紧凑，便于阅读和二次修改。目前已有75人学习浏览，项目经导师指导并获答辩高分认可，代码通过测试，功能稳定。对于希望快速掌握Qt与OpenCV集成开发、理解人脸识别流程的读者，这份资料提供了从界面搭建到算法调用的完整范例，能够有效节省前期资料搜集与调试时间。
1. 基于Qt和OpenCV人脸识别程序在Ubuntu下，最该先解决的不是算法
拿到一个写着“详细文档+全部资料+高分项目.zip”的压缩包，解压后往往是几个 .cpp、.ui、一堆 xml 和一段写得很满的 word 说明。但双击运行不了，报错不是“cannot find -lopencv_face”，就是“QV4L2Capture: ioctl failed”。这个标题对应的是非常典型的课程设计：用 Qt 做界面，OpenCV 调摄像头，做人脸检测与识别，最终交付文档。真正的难点不在人脸识别算法本身，而在 Ubuntu 系统下把摄像头权限、OpenCV 的 contrib 模块、Qt 的界面刷新线程这三件事接起来。适合正在做课设、或者想拿一个能现场演示的 Qt 项目去求职的开发者。我会按环境、原理、代码再到发布的顺序，把能跑通的那条路讲清楚。
2. 摄像头到人脸框：OpenCV调用相机的原理与Qt线程模型
OpenCV 的 VideoCapture 不是直接操作硬件的库，它在 Linux 上通过 V4L2 或 GStreamer 跟内核驱动打交道。理解这一点，很多“摄像头打开失败”就能自己排查。
2.1 OpenCV 调用相机原理：V4L2 与 VideoCapture 参数
执行cv::VideoCapture cap(0, cv::CAP_V4L2)时，OpenCV 会去打开/dev/video0，用 ioctl 查询设备能力，请求设置像素格式，再用 mmap 映射驱动里的缓存。之后每次cap.read(frame)都从驱动缓冲区把图像复制回用户态。因此权限、设备占用、格式不支持都会在打开或读帧阶段暴露。下面是一段最小可运行的打开代码。
#include <opencv2/opencv.hpp> #include <iostream> int main() { // 显式指定 V4L2 后端，避免默认后端选错 cv::VideoCapture cap(0, cv::CAP_V4L2); if (!cap.isOpened()) { std::cerr << "camera open failed" << std::endl; return -1; } cap.set(cv::CAP_PROP_FOURCC, cv::VideoWriter::fourcc('M', 'J', 'P', 'G')); cap.set(cv::CAP_PROP_FRAME_WIDTH, 1280); cap.set(cv::CAP_PROP_FRAME_HEIGHT, 720); cap.set(cv::CAP_PROP_FPS, 30); cv::Mat frame; cap.read(frame); if (frame.empty()) { std::cerr << "empty frame" << std::endl; return -1; } return 0; }显式指定CAP_V4L2可以避免 OpenCV 自动后端选到错误的 GStreamer 管线；fourcc要在宽高之前设置，部分 UVC 摄像机会在改分辨率后重置格式。cap.set只是下发请求，最终是否生效要看cap.get(cv::CAP_PROP_FRAME_WIDTH)返回的值。read是阻塞调用，默认会等待下一帧，所以直接把它放进 Qt 界面主线程会卡住拖拽、按钮点击这些交互。
摄像头常用参数与优先级
| 参数 | 典型值 | 说明 |
|---|---|---|
| CAP_PROP_FOURCC | MJPG | 优先使用硬件编码，可提高分辨率帧率 |
| CAP_PROP_FRAME_WIDTH | 1280 | 请求宽度，需同时检查实际值 |
| CAP_PROP_FRAME_HEIGHT | 720 | 请求高度，比例要匹配 |
| CAP_PROP_FPS | 30 | 帧率请求，不保证精确 |
| CAP_PROP_BUFFERSIZE | 1 | 设置最小缓冲可降低延迟 |
CAP_PROP_BUFFERSIZE不是所有驱动都支持，设置失败时 OpenCV 不会报错，只知道get返回 0。如果测到画面延迟明显，建议先把它设为 1，再做后续图像处理。
2.2 人脸检测与人脸识别算法选型：Haar、LBPH 还是深度学习模型
先理清“检测”和“识别”是两步。检测是在画面中找到人脸框，识别是把框内图像与注册的人脸比对。OpenCV 内置的 Haar 级联用 AdaBoost 训练得到，模型文件小、CPU 推理快，适合正脸和光线均匀的室内场景；LBPH 识别器训练快，几十个人的小库也能跑，正好匹配课设的数据量。如果追求侧脸、遮挡下的效果，用 OpenCV DNN 模块加载 YuNet 检测模型更合适，但模型文件有十几 MB，部署时容易丢。下面是常见方案的横向对比。
| 方案 | 检测/识别 | 模型形态 | CPU 开销 | 适用场景 |
|---|---|---|---|---|
| Haar cascade | 检测 | 自带 xml | 低 | 正脸、环境可控 |
| LBPH | 识别 | 自训练 yml | 低 | 小规模人脸库 |
| DNN YuNet | 检测 | onnx | 中 | 侧脸、遮挡改善 |
| FaceNet/ArcFace | 识别 | 大型模型 | 高 | 大规模高精度 |
我一般会让项目先以 Haar + LBPH 掉通：haarcascade_frontalface_default.xml 直接在 OpenCV 安装目录里，训练 LBPH 不需要 GPU，写文档时公式也容易讲清楚。detectMultiScale的两个参数决定演示效果：scaleFactor从 1.1 到 1.2 之间调，越小越慢但越容易召回；minNeighbors默认 5，误检多就调到 8，漏检多就降到 3。参数要结合演示环境光线再调整，不能照抄默认值。
2.3 Qt 的 QTimer 里读帧，用 QImage 把 cv::Mat 送给 QLabel
常见做法不是给摄像头单独开一个无限 while 循环，而是用 QTimer 每 30ms 触发一次读帧和检测。这样不破坏 Qt 事件循环，按钮依然响应。核心代码片段如下。
QTimer timer; connect(&timer, &QTimer::timeout, this, [this]() { cv::Mat frame; if (!cap.read(frame)) return; std::vector<cv::Rect> faces; cv::Mat gray; cv::cvtColor(frame, gray, cv::COLOR_BGR2GRAY); cascade.detectMultiScale(gray, faces, 1.1, 5); for (const auto &r : faces) { cv::rectangle(frame, r, cv::Scalar(0, 255, 0), 2); } cv::cvtColor(frame, frame, cv::COLOR_BGR2RGB); QImage img(frame.data, frame.cols, frame.rows, frame.step, QImage::Format_RGB888); videoLabel->setPixmap(QPixmap::fromImage(img.copy())); }); timer.start(33);这里必须调用img.copy()，否则 QImage 不会共享 cv::Mat 的引用计数，下一帧cap.read会重写同一块内存，界面出现花屏或残影。frame.step用于处理 BGR 转 RGB 后每行字节数不等于 width*3 的情况，漏了它会在宽高不是 4 的倍数时出现斜条纹。人脸框画在彩色图上，而检测在灰度图上做，两个图不要互相覆盖。
理解完线程模型，下一步就是环境安装。
3. Ubuntu 上把 Qt和OpenCV装到能编译：版本、CMake 和摄像头权限
这一章如果不是全新机器，也可以先看现有版本再决定是否卸载重装。重点是把 opencv_face 这个容易缺的模块提前识别出来。
3.1 用系统包安装 Qt 和 OpenCV，判断是否需要自编译
Ubuntu 仓库的 libopencv-dev 通常不带 contrib 模块，也就是没有 opencv2/face.hpp。LBPH 就用不了。先用一条命令判断：
ls /usr/include/opencv4/opencv2/face.hpp如果这个文件不存在，说明系统包不完整。接下来安装基础环境：
sudo apt update sudo apt install -y build-essential cmake git pkg-config sudo apt install -y qtbase5-dev qttools5-dev-tools qtchooser sudo apt install -y libopencv-dev libopencv-videoio-dev安装后验证版本：
qmake -v pkg-config --modversion opencv4在 Ubuntu 20.04 上 OpenCV 一般是 4.2，Ubuntu 22.04 是 4.5。对课程设计来说版本不是越新越好，系统包和 Qt 5 配合最省事。缺少face.hpp时，有两个方向：源码编译 OpenCV with contrib，时间大概二十分钟；或者放弃 LBPH，改用特征点匹配和 SVM 做识别。前者需要准备编译依赖，工程量偏大，但如果你要把“详细文档”写成带 opencv_face 源码编译记录，反而更能体现工作量。
3.2 CMakeLists.txt 模板：AUTOMOC 与 Qt/OpenCV 链接顺序
用 Qt + OpenCV 的 C++ 工程，CMake 是最好的构建方式。最关键的是把CMAKE_AUTOMOC打开，否则包含Q_OBJECT的类会报虚表或信号槽未定义错误。一个最小模板如下。
cmake_minimum_required(VERSION 3.16) project(FaceRecognitionQt LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) find_package(Qt5 COMPONENTS Widgets REQUIRED) find_package(OpenCV REQUIRED) add_executable(facerec main.cpp mainwindow.cpp mainwindow.h ) target_include_directories(facerec PRIVATE ${OpenCV_INCLUDE_DIRS}) target_link_libraries(facerec PRIVATE Qt5::Widgets ${OpenCV_LIBS} )find_package(OpenCV REQUIRED)在 Ubuntu 上默认找的是 libopencv-dev 安装的 cmake 配置，它会给出 OpenCV_LIBS 变量。不写成OpenCV::opencv_core这种形式是为了兼容系统包版本；源码编译的 OpenCV 也支持，但变量形式更通用。如果在 Ubuntu 22.04 上找不到 Qt5，先确认安装的是 qtbase5-dev 而不是 Qt6，Qt5 的 CMake 配置在/usr/lib/x86_64-linux-gnu/cmake/Qt5。
3.3 摄像头打不开？权限、设备节点与 V4L2 格式排查
开发机上摄像头不存在，往往不是代码问题。先看设备节点：
ls -l /dev/video* sudo usermod -aG video $USER重新登录后权限生效。如果是 VMware 或 VirtualBox 虚拟机，还要检查 USB 摄像头是否已经连接到客户机，连接后v4l2-ctl --list-devices才有输出。常用排查表如下。
| 现象 | 原因 | 处理 |
|---|---|---|
| isOpened() 返回 false | 无设备节点或节点权限不足 | usermod -aG video，重登 |
| read() 一直返回 false | 摄像头被其他进程占用 | lsof /dev/video0 |
| 画面窄且拉伸 | 设置了不支持的宽高比例 | 用 v4l2-ctl --list-formats-ext 查支持规格 |
| 色彩发绿交错 | FOURCC 没有设置 | 显式设置 MJPG，再设宽高 |
如果两步都排除，接下来用v4l2-ctl --list-formats-ext -d /dev/video0查看摄像头实际支持的格式。很多普通摄像头在 1280x720 下只支持 MJPG，如果 VideoCapture 默认走 YUYV，就无法打开高分模式。解决办法是在cap.open后立刻设置CAP_PROP_FOURCC为MJPG，然后设置分辨率。全部环境就绪后，再进入界面与识别代码。
4. 从空白窗口到可演示的人脸识别：Qt界面、图像处理与考勤记录实现
直接写纯代码创建的界面，省去 .ui 文件的路径问题。识别流程放在 QTimer 回调里，与第 2 章一致。这一章给出能直接编译的骨架。
4.1 最小界面定义：QLabel 显示画面，按钮切换摄像头开关
在MainWindow头文件里声明要用的成员：
class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent = nullptr); private slots: void openCamera(); void closeCamera(); void onTimeout(); private: cv::VideoCapture cap; cv::CascadeClassifier cascade; cv::Ptr<cv::face::LBPHFaceRecognizer> recognizer; QTimer timer; QLabel *videoLabel; QPushButton *openBtn; };构造函数里创建 central widget、一个 QLabel 和一个 QPushButton，再把 clicked 连接到 openCamera/slot。用代码创建界面的好处是发布时少带一个 .ui 文件，但布局代码会多一些。控件和信号的关系如下表。
| 控件 | 成员 | 信号 | 槽 |
|---|---|---|---|
| 打开按钮 | openBtn | clicked() | openCamera() |
| 关闭按钮 | closeBtn | clicked() | closeCamera() |
| 视频标签 | videoLabel | 无 | 由 timer 更新 |
实际演示时，最好把两个按钮并排放，关闭后第一时间释放摄像头，避免下次打开失败。
4.2 detectMultiScale 的参数调优与画框技巧
完整的人脸检测部分，在灰度图上做 histogram equalization 能减少侧光影响。代码：
cv::Mat frame, gray, eq; cap.read(frame); cv::cvtColor(frame, gray, cv::COLOR_BGR2GRAY); cv::equalizeHist(gray, eq); std::vector<cv::Rect> faces; cascade.detectMultiScale(eq, faces, 1.1, 5, cv::CASCADE_SCALE_IMAGE, cv::Size(80, 80)); for (const auto &r : faces) { cv::rectangle(frame, r, cv::Scalar(0, 255, 0), 2); }注意minSize设置为 80x80，能过滤很多背景纹理误检；如果你要检测 3 米外的小脸，这个值要调低。scaleFactor从 1.1 改到 1.05 会显著增加计算量，但小脸召回率会好一点。画框颜色用cv::Scalar(0, 255, 0)是 BGR 空间下的绿色，如果想用 Qt 的红色习惯，要写成(0, 0, 255)。
4.3 LBPH 人脸识别：训练数据目录、标签映射与置信度阈值
先按“每个人的照片一个目录”整理训练集，然后用下面的代码遍历目录、读取灰度图并 resize 到统一尺寸。这一步很关键，因为 LBPH 对输入大小不敏感，但不统一会让训练容易过拟合。
#include <filesystem> std::vector<cv::Mat> images; std::vector<int> labels; int label = 0; for (const auto &entry : std::filesystem::directory_iterator("train")) { if (!entry.is_directory()) continue; for (const auto &file : std::filesystem::directory_iterator(entry.path())) { cv::Mat img = cv::imread(file.path().string(), cv::IMREAD_GRAYSCALE); cv::resize(img, img, cv::Size(100, 100)); images.push_back(img); labels.push_back(label); } label++; } auto recognizer = cv::face::LBPHFaceRecognizer::create(); recognizer->train(images, labels); recognizer->save("face_model.yml");代码中用std::filesystem需要 C++17，所以第 3 章的 CMake 里写了 C++17。训练完成后，predict会把 confidence 返回：LBPH 的置信度是距离，值越小越像。课程项目中通常设 80 为阈值，小于 80 显示对应人员，大于等于 80 显示 unknown。这个值要在实际摄像头上试拍几张再定，室内光线差时 80 可能过严。
4.4 识别结果记录到 CSV，并同步到 QTableWidget
在每次识别到已知人脸时，把时间、标签、置信度追加到本地文件，这是答辩时的直观展示点。写文件适合用 QFile 和 QTextStream。
void MainWindow::saveRecord(int label, double confidence) { QFile f("records.csv"); if (!f.open(QIODevice::Append | QIODevice::Text)) return; QTextStream out(&f); out << QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss") << "," << label << "," << QString::number(confidence, 'f', 2) << "\n"; f.close(); }同步 QTableWidget 就是 insertRow 和 setItem，不再展开。要注意的是，识别成功与否需要做“去重”：同一个 ID 在 5 秒内重复出现在画面里，只记录第一次，否则演示时记录表会被刷屏。可以保存一个QHash<int, QDateTime> lastSeen，在 saveRecord 里判断时间差。至此，项目骨架已经能展示“摄像头打开-画框-显示名字-记录表格”完整流程。
5. 从能跑到高分：Qt+OpenCV人脸识别程序的模型路径、发布包与自测技巧
许多项目源码在 Qt Creator 里跑得好好的，评审机器上却打不开摄像头或找不到模型文件。最后一章集中解决这三个最丢分的问题。
5.1 模型文件路径不要依赖当前目录，而是绑定可执行文件位置
Haar 模型文件和 LBPH 训练结果通常放在项目根目录，但双击运行时当前目录是启动目录，不在项目目录。修复方式是用QCoreApplication::applicationDirPath()拼接。
QString modelDir = QCoreApplication::applicationDirPath() + "/models"; cascade.load(modelDir.toStdString() + "/haarcascade_frontalface_default.xml"); recognizer->read(modelDir.toStdString() + "/face_model.yml");发布时把models目录和可执行文件放在同一级。如果程序放在/usr/local/bin，这个目录可能是只读的，课程设计场景下建议直接放可写目录。
5.2 用 ldd 和 patchelf 生成可拷贝的发布包
Qt 和 OpenCV 都是动态库，只拷可执行文件必然报错。先确认依赖：
ldd facerec | grep -E "opencv|Qt5"把列出的 so 文件复制到lib/目录后，用 patchelf 写死运行路径。
mkdir -p lib plugins/platforms cp /usr/lib/x86_64-linux-gnu/libopencv_core.so.4.5* lib/ cp /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5* lib/ patchelf --set-rpath '$ORIGIN/lib' facerec再创建qt.conf，让 Qt 知道去哪里找插件。
[Paths] Plugins = plugins将编译出的plugins/platforms/libqxcb.so拷贝到对应目录。目标电脑上如果还提示 xcb 库缺失，需要用ldd plugins/platforms/libqxcb.so补齐 xcb 相关的系统库。
5.3 识别演示前的两分钟自测
启动程序后先确认三件事：摄像头指示灯是否亮起；人脸框是否贴合人脸；切换到已登记人脸时名字是否在 1 秒内出现。然后用命令观察内存与 CPU。
while true; do ps -C facerec -o pid,rss,%cpu,etime --no-headers sleep 2 done如果 RSS 持续上涨，优先检查 QImage 是否每次 copy 新的内存；如果 CPU 一直 100%，把timer.setInterval(33)调整为 50，或将检测放到cv::UMat中。另一个常见问题是画面像素格式偏绿，此时应回头确认摄像头是否真的进入了 MJPG 格式，而不是靠cap.get(CAP_PROP_FOURCC)检查。最后可以在records.csv同目录输出 run.log，把模型加载失败和摄像头打开失败两个分支写清楚，这份日志会让项目的可信度明显提升。
本文还有配套的精品资源，点击获取
