基于OpenCV与LBPH的人脸识别门禁系统：从Haar检测到阈值调优实战

简介：基于Python与OpenCV的人脸识别门禁系统项目，依托LBPH局部二值模式直方图算法完成人脸特征提取与匹配，适合计算机视觉初学者及智能安防开发人员参考。资源覆盖完整实现链路：人脸样本采集、分类器训练、实时检测与识别，并设置70%相似度阈值作为放行依据。压缩包共49个文件，约987KB，包含Python源码、OpenCV预训练级联分类器XML、面部图像样本（pgm/png/bmp/jpg）及模型与说明文档，结构清晰便于对照学习。已有199人学习下载。通过源码可掌握cv2.face.LBPHFaceRecognizer_create、CascadeClassifier等关键API的实际用法，理解从训练到识别的完整流程；同时提供界面演示脚本与数据保存模块，可用于扩展考勤、门禁等场景，是一份兼具教学与实战价值的入门项目。

1. 这项目不是玩具：LBPH + 70% 阈值的门禁逻辑

基于 OpenCV 和 Python 的人脸识别门禁系统，听起来像课程设计，但这个项目的实际形态比演示稿完整得多。它用 LBPH（局部二值模式直方图）做人脸特征建模，配合 Haar 级联做检测，识别结果要过 70% 相似度这一硬指标才放行。很多人第一次跑通会卡在一个反直觉的地方：LBPH 返回的是距离值，不是百分比，距离越小越像。项目里的“70% 相似度”本质上是把这个距离换算成了置信度分数。这套技术栈不需要 GPU，不依赖深度学习框架，一个普通摄像头加一台 Win/Linux 机器就能跑。适合正在做课程设计的，适合想学 OpenCV 传统视觉落地路径的，也适合想低成本搭一套室内门禁原型的。往下拆解时我会按“检测 → 训练 → 识别 → 排错 → 加固”的顺序来，最后会给出一个让门禁系统更抗造的具体技巧。

2. 人脸检测先行：Haar 级联选型与 detectMultiScale 参数调优

2.1 三个 frontalface XML 怎么选

OpenCV 的 Haar 级联分类器在检测阶段就决定了你后面所有步骤的输入质量。项目压缩包里同时给了haarcascade_frontalface_default.xml、haarcascade_frontalface_alt.xml、haarcascade_frontalface_alt2.xml，外加一个haarcascade_eye.xml。很多新手不看文件名区别，随手拿 default 就用，结果检测框要么乱跳要么框不住侧脸。

这三个文件都是正面人脸检测器，但训练样本和特征选择策略不同，实际表现有明显差异：

我一般会优先用alt.xml做门禁主检测，因为它在大姿态变化和误检率之间比较平衡。eye.xml这一节先不用管，第 6 章我会把它用于活体防照片，那才是它的正确位置。

2.2 级联检测核心参数：detectMultiScale 四个关键值

Haar 检测的核心调用是detectMultiScale，这函数的参数直接影响门禁识别率。项目里不管face_pre_sys还是face_ui.py，底层都绕不开它。先给一段最常用的实时视频检测代码：

import cv2 cascade = cv2.CascadeClassifier('haarcascade_frontalface_alt.xml') cap = cv2.VideoCapture(0) while True: ret, frame = cap.read() if not ret: break gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) # scaleFactor 控制每层图像缩小比例，minNeighbors 控制最少保留的相邻检测框数 faces = cascade.detectMultiScale( gray, scaleFactor=1.1, minNeighbors=5, minSize=(60, 60), flags=cv2.CASCADE_SCALE_IMAGE ) for (x, y, w, h) in faces: cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2) cv2.imshow('detect', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()

这段代码的作用是先转灰度再检测，因为 Haar 特征本身基于灰度纹理信息，彩色图在级联分类器里没有额外收益，反而增加计算量，所以不要直接对 BGR 帧调用。scaleFactor=1.1意思是每轮检测把图像缩小 10%，数字越小检测越精细但越慢；minNeighbors=5表示一个候选区域至少要有 5 个重叠框才认定为真脸，太大容易漏检侧面，太小容易把背景纹理当人脸。minSize=(60, 60)过滤掉太小的候选框，对应门禁场景中摄像头距离人脸约 0.5 到 1 米的实际尺寸。如果检测框抖得厉害，优先把minNeighbors提到 6 或 7，而不是去改scaleFactor。

2.3 多人脸场景的处理顺序

门禁系统面对的不一定是单人场景，走廊里两个人并排走过来时，detectMultiScale会返回多个框。这时候不能每帧随便取第一个框，因为框的返回顺序不保证按面积从大到小。

# 取面积最大的框作为主识别目标，避免把远处路人当识别对象 if len(faces) > 0: faces = sorted(faces, key=lambda f: f[2] * f[3], reverse=True) (x, y, w, h) = faces[0]

这段逻辑对应项目里的face_pre_sys预处理思路：先排序后裁剪。如果你想把多个框都送去识别，LBPH 也能返回各自标签，但门禁动作应只绑定面积最大的主脸，否则同框出现一个注册用户和一个陌生人时，系统会不知道该不该开门。

3. 训练数据与 LBPH 模型：采集脚本、训练流程和阈值反测

3.1 样本采集：别让数据拖垮模型

LBPH 是传统特征方法，对样本数量和质量要求比深度学习低，但不代表随便拍几张就能用。压缩包里的face_data目录和face_date_save.py（注意这名字大概率是face_data_save.py的笔误）负责的就是数据采集环节。常见做法是把每个注册用户的照片存到单独子目录，文件名用“用户ID_序号”这种格式。

import cv2 import os cascade = cv2.CascadeClassifier('haarcascade_frontalface_alt.xml') cap = cv2.VideoCapture(0) user_id = input('输入用户ID，建议从 1 开始: ').strip() save_dir = f'face_data/user_{user_id}' os.makedirs(save_dir, exist_ok=True) count = 0 while count < 20: ret, frame = cap.read() if not ret: continue gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(100, 100)) for (x, y, w, h) in faces: # 稍微扩大裁剪区域，把额头和下颚边缘留出来，避免特征被切断 margin = 10 x1 = max(0, x - margin) y1 = max(0, y - margin) x2 = min(frame.shape[1], x + w + margin) y2 = min(frame.shape[0], y + h + margin) face = gray[y1:y2, x1:x2] face = cv2.resize(face, (200, 200)) cv2.imwrite(f'{save_dir}/{user_id}_{count}.jpg', face) count += 1 cv2.waitKey(300) # 每 300 毫秒存一张，期间人像可以有轻微角度变化

这段代码存的是灰度图，不是彩色图。原因后面讲训练时会说。margin=10是为了防止 Haar 检测框把人脸边缘裁得太狠，导致额头或下巴特征丢失。每张图间隔 300ms 是让采集对象自然产生头部角度和表情变化，而不是连拍 20 张同一姿态的静态图——那种数据训练出来的模型，换个体位就翻车。

采集时注意两点：一是光照要覆盖真实使用时段，早上逆光和晚上顶光照出来的模型差距很大；二是每个用户至少 15 到 20 张，太少的话 LBPH 的直方图统计不稳定，识别时距离值会随机漂移。项目里123Y-2目录很可能就是某个用户或某批采集数据，而zch这种短目录名多半是用户名的缩写，说明项目本身已经按“按用户分目录”的组织方式来管理数据。

3.2 训练模型：LBPH 构造参数与 train/write

数据采集完成后，真正训练的部分在face_predict.py或face_pre_sys里。LBPH 的原理是把人脸划分成小网格，在每个网格内计算局部二值模式直方图，再把所有网格的直方图拼接起来作为特征。所以它天然对光照变化有一定容忍度，这是选它而不是 EigenFace、FisherFace 的主要原因：后两者对光照敏感得多，门禁场景里光线不可控。

import cv2 import os import numpy as np def load_training_data(data_dir): images = [] labels = [] for user_name in os.listdir(data_dir): user_path = os.path.join(data_dir, user_name) if not os.path.isdir(user_path): continue # 从目录名 user_1 里解析出标签数字，标签必须从 1 开始连续 label = int(user_name.split('_')[1]) for img_name in os.listdir(user_path): if not img_name.endswith('.jpg'): continue img_path = os.path.join(user_path, img_name) img = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) images.append(img) labels.append(label) return images, np.array(labels) images, labels = load_training_data('face_data') # radius=1 表示每个像素只跟周围 8 个邻域比较，grid_x/grid_y 控制网格密度 trainer = cv2.face.LBPHFaceRecognizer_create(radius=1, neighbors=8, grid_x=8, grid_y=8) trainer.train(images, labels) trainer.save('G2/trainer.yml') print('模型已保存到 G2/trainer.yml')

LBPHFaceRecognizer_create的参数里，radius=1是 LBP 采样的邻域半径，neighbors=8是采样点数，这两个一般保持默认。grid_x=8, grid_y=8决定把图像切分成 8×8 的网格，网格越多特征越细致，但训练样本少时容易过拟合，门禁场景下 8×8 是稳妥选择。trainer.train(images, labels)接收两个参数：图像列表和标签数组，注意图片尺寸必须完全一致，否则 OpenCV 会抛异常——这就是采集脚本里统一 resize 到 200×200 的原因。

训练完成后，G2目录里会出现trainer.yml，这就是模型文件。项目文件清单里的G2大概率就是这个模型输出目录，而不是数据集目录。face_test.py和face_predict.py的区别在于：前者是单张图片的测试脚本，后者是集成到门禁主循环里的预测模块。

3.3 阈值反测：70% 相似度对应多少距离

这是整个项目最容易出问题的地方。LBPH 的predict返回的是样本到模型的距离值，距离越小代表越相似。OpenCV 官方文档并没有直接给出“相似度百分比”这个说法，但很多项目为了直观，会写一行映射代码：

label, distance = trainer.predict(face_resized) similarity = max(0, 100 - distance) # 把距离换算成相似度百分比

如果项目要求“达到 70% 以上相似度才算识别成功”，那么等价条件是distance <= 30。但这个 100 减去距离的映射只是常见习惯，不是 OpenCV 的数学定义，所以拿到一个陌生项目时不要直接信阈值，一定要自己反测一遍。

反测方法是：训练完后，另外采集几个已注册用户的新照片（不进训练集），分别跑predict，记录它们的距离值。正常情况同一用户的距离应该在 30 到 50 之间，不同用户基本在 80 往上。把门禁阈值设在“同用户最大距离加 10 到 15”的位置比较稳。如果你测出来同用户距离都到 60 了，那说明训练样本质量不行或采集时光照太单一，先别急着放宽阈值，回去补数据。

这个反测脚本很简单，写进face_test.py就行。先加载模型，再逐张读测试图，打印标签和距离，最后人工判断阈值是否合理。

4. 门禁识别主循环：predict 返回值、相似度换算与实时判定

4.1 识别主逻辑：检测→裁剪→预测→判阈值

门禁的主循环写在哪？项目里有两个入口：face_ui.py是带界面的主程序，face_predict.py是纯逻辑模块。UI 部分用logo1.png、logo2.png这些图拼了界面，本质逻辑还是下面这段。

import cv2 cascade = cv2.CascadeClassifier('haarcascade_frontalface_alt.xml') trainer = cv2.face.LBPHFaceRecognizer_create() trainer.read('G2/trainer.yml') cap = cv2.VideoCapture(0) # 连续 5 帧中至少有 4 帧判定为同一人才触发开门，避免单帧抖动 vote_window = [] while True: ret, frame = cap.read() if not ret: continue gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(80, 80)) for (x, y, w, h) in faces: face = gray[y:y + h, x:x + w] face = cv2.resize(face, (200, 200)) label, distance = trainer.predict(face) # 项目要求 70% 相似度才放行，对应 distance <= 30 if distance <= 30: vote_window.append(label) cv2.putText(frame, f'User {label} Access OK', (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 255, 0), 2) else: cv2.putText(frame, 'Access Denied', (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 0, 255), 2) if len(vote_window) >= 5: # 多数投票决定最终结果 final_label = max(set(vote_window), key=vote_window.count) if vote_window.count(final_label) >= 4: # 这里接开闸继电器或串口指令 print(f'Approve user {final_label}') vote_window.clear() cv2.imshow('face access', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()

predict返回两个值：label是模型判定的人脸标签，distance是特征距离。distance <= 30就是项目里“相似度不低于 70%”的落地写法。注意这里不要把label和数据库里的用户 ID 混淆，label 只是训练时设定的整数编号，真正对应到姓名，需要查master.txt——这个文件在项目里很可能是管理员名单或用户映射表，格式一般是“ID 姓名”逐行排列。

4.2 UI 与数据保存的联动逻辑

face_ui.py不只是一个显示窗口，它还串起了注册、训练、识别三个动作。常见设计是：点击“录入人脸”按钮，程序调第 3 章的采集脚本存图；采集完自动调train训练；训练完更新trainer.yml；之后主循环里的trainer.read每次都会重新加载最新模型。项目里的face_date_save.py应该就是负责把采集到的图片写入face_data目录的模块。

这里有个容易被忽略的细节：每次新增用户后都要重新训练整个模型，因为 LBPH 没有增量训练接口。如果用户数量多了（超过几十个），每次全量训练的耗时会上升，但门禁场景一般也就几个到十几个人，影响不大。真正要注意的是trainer.read('G2/trainer.yml')必须在每次新增样本后重新执行，否则新用户不会被识别出来。

4.3 相似度阈值写死的后果

项目原描述写的是“达到 70% 以上的相似度才可认为识别成功”，这听起来像写死了一个比例，但实际工程里阈值应该是可配置的。我会在master.txt里额外加一行配置项，让阈值可以从文件读取而不是改代码：

threshold_distance=30 admin_password=123456

这样调门禁灵敏度时不用动 Python 文件，也方便不同环境用不同阈值。比如在光线稳定的办公室，distance 阈值可以收到 25；在走廊这类光线变化大的区域，放宽到 35 更合理。master.txt在这个项目里承担的角色就是这种配置 + 名单映射，具体写法可以自己扩展，保持“ID 姓名”和“key=value”两种格式共存就行。

5. 常见问题避坑：从 cv2.face 报错到模型总认错人

5.1 模块导入报错

现象：运行face_predict.py时直接报ModuleNotFoundError: No module named 'cv2.face'。

原因：OpenCV 从 3.x 开始把face模块放进了扩展包，普通安装的opencv-python不带这个子模块，只有opencv-contrib-python才包含 LBPH、EigenFace、FisherFace 这些算法。

解决：先卸载再重装，避免版本冲突：

pip uninstall opencv-python opencv-contrib-python pip install opencv-contrib-python

装完验证一下：

python -c "import cv2; print(cv2.__version__); print(cv2.face.LBPHFaceRecognizer_create)"

如果打印出版本号和函数对象，就说明环境没问题。另外压缩包里出现了__pycache__目录以及face_date_save.cpython-35.pyc，说明项目是用 Python 3.5 写的。现在直接拿 Python 3.11 跑老项目很容易遇到 API 变动问题，建议用 Python 3.6 到 3.8 搭配 OpenCV 4.x，兼容性最好。

5.2 模型把所有人识别成同一个 ID

现象：新面孔测试时，predict返回的距离很小，label 总是某个特定用户，陌生人也能通过门禁。

原因：最常见的是标签从 0 开始，或者训练样本里混入了非人脸图片。LBPH 对标签 0 的处理比较特殊，如果你把第一个用户的 label 设为 0，某些 OpenCV 版本会把所有预测倾向到 0。另一个常见原因是face_data目录下存在空白背景图或裁剪失败的非人脸图，这些脏数据拉偏了直方图特征。

解决：标签强制从 1 开始，训练前先做一轮数据清洗，删掉所有检测框里没有人脸核心特征（眼睛、鼻子区域）的样本。检查方法很简单：把每张训练图拼成一张大图看一遍，一眼就能看出哪些是脏数据。

5.3 检测框抖动导致识别断断续续

现象：人脸明明没动，检测框却忽大忽小，识别结果在“通过”和“拒绝”之间横跳。

原因：detectMultiScale每次都是独立检测，单帧的 Haar 响应有随机性。minNeighbors设太低时，边缘被框住的概率也会增加，导致裁剪区域变化。

解决：前面第 4 章的代码里已经用了多帧投票，这里是第二个保险——把检测框做平滑。维护一个历史框列表，当前帧的框取最近 5 帧的平均位置和尺寸，再送去预测。不要每帧直接预测，不然“通过—拒绝”来回跳会让闸机反复动作。

# 历史框平滑：取最近 5 帧检测框的均值 import numpy as np history = [] if len(history) < 5: history.append([x, y, w, h]) else: history.pop(0) history.append([x, y, w, h]) arr = np.array(history, dtype=np.float32).mean(axis=0).astype(int) x, y, w, h = arr

5.4 距离值与相似度映射方向搞反

现象：distance返回 25，代码里写成if distance > 70: 通过，结果所有真人全被拒绝。

原因：把“距离小 = 相似度高”理解反了。LBPH 的 distance 是特征空间里的距离，不是百分比。distance 越小说明越接近训练样本，越大说明越不像。有些教程里会写成confidence = 100 - distance，那只是把距离映射到百分比刻度，本身不代表准确率。

解决：统一用 distance 做判定条件，不绕百分比那一层。第 3 章反测出来的同用户最大 distance 加余量，直接写进配置。如果项目描述里明确写了“70% 相似度”，就把阈值写成distance <= 30，但前提是你确认过自己训练数据的距离分布。

5.5 UI 界面中文乱码或按钮无响应

现象：face_ui.py跑起来后按钮上的中文显示成方块，或者点击按钮没反应。

原因：OpenCV 的cv2.putText不支持中文，默认字体没有中文字形。按钮无响应则多半是回调函数里调用了阻塞操作（比如训练模型），界面线程被卡住。

解决：界面按钮文字用英文或拼音，显示识别结果时把中文先写进一张透明画布，再用cv2.addWeighted叠加到画面上，绕开 putText 的字体限制。训练操作放进子线程，主线程保持刷帧，避免界面假死。

6. 进阶：让门禁更抗造的两个加固技巧

6.1 用眼睛级联做简单防照片

项目压缩包里的haarcascade_eye.xml不是摆设。照片打印出来的人脸能通过 frontal face 检测，但眼睛区域一般过不了 eye 级联的校验，因为照片里眼珠是死的，没有正常的瞳孔纹理。把两张级联串起来，先检测整脸，再在整脸区域内检测眼睛，能挡掉一部分纸质照片和手机屏幕翻拍。

eye_cascade = cv2.CascadeClassifier('haarcascade_eye.xml') # 在人脸坐标区域内检测眼睛 roi = gray[y:y + h, x:x + w] eyes = eye_cascade.detectMultiScale(roi, scaleFactor=1.1, minNeighbors=4, minSize=(20, 20)) if len(eyes) < 2: cv2.putText(frame, 'Liveness check failed', (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2) continue

这段逻辑不会挡住所有攻击，比如高清视频翻录可能依然有效，但足够把“拿照片怼摄像头”这种最廉价的绕过方式拦住。注意镜框反光会导致眼睛检测失败，对戴眼镜用户可以把minNeighbors降到 3，或者用haarcascade_eye_tree_eyeglasses.xml这种专门为眼镜设计的变体。

6.2 多帧投票 + 动态阈值

第 4 章代码里的投票窗口是固定值，实际部署时可以把它做成动态的：连续 10 帧中同一个 label 出现 8 次以上才触发开门，陌生人连续 10 帧都判拒绝才播报告警。这样既能防单帧抖动，也能防快速走过摄像头时误判。阈值距离可以分两级：distance <= 20是核心用户，直接放行；20 < distance <= 30是普通用户，需要额外输入master.txt里的口令；distance > 30一律拒绝。

从那以后我每次搭门禁系统，都会先跑一遍第 3 章的阈值反测，把每个已注册用户的距离分布画出来，确认同一用户最差距离和不同用户最优距离之间有明显间隔，再定阈值。这个习惯帮我避掉了至少三次“上线后被同一办公室同事拒之门外”的尴尬。希望这个项目和这套拆解思路帮到你。

本文还有配套的精品资源，点击获取