康达机器人人脸识别系统

项目简介

这是一个基于 CompreFace 的智能人脸识别系统，为康达新材的接待机器人提供实时人脸检测、识别和访客管理功能。系统通过 WebSocket 与机器人主控程序通信，支持视频展示、二维码引导和流媒体推送等多种功能。

核心功能

1. 人脸识别

• 实时检测：基于 CompreFace API 进行高精度人脸检测
• 正脸检测：使用姿态检测技术，获取人脸的yaw（偏航角）、pitch（俯仰角）、roll（翻滚角）数据，只识别正面人脸，有效过滤侧脸、抬头或低头
• 角度过滤：通过REST API直接调用CompreFace的pose插件，设置±20°的角度阈值，确保只检测正脸
• 身份识别：自动识别员工和访客，支持相似度阈值配置
• 防重复识别：智能冷却机制，避免短时间内重复识别同一人
• 质量评估：使用 Laplacian 方差评估图像清晰度

2. 访客引导

• 二维码展示：陌生访客自动弹出访客预约流程二维码
• SOTA 设计：采用现代化 UI 设计，左侧二维码 + 右侧步骤说明
• 自动关闭：可配置显示时长（默认 10 秒）

3. 展厅讲解

• 视频播放：当机器人角色为"展厅讲解员"时自动播放展厅视频
• 状态叠加：在视频上实时显示机器人状态（思考、倾听、讲话）
• 循环播放：支持视频循环播放配置

4. WebSocket 通信

• 双向通信：与机器人主控程序实时交互
• 状态同步：获取机器人说话、思考、倾听状态
• 自动重连：连接断开时自动重连，保证系统稳定性

5. 流媒体推送

• RTMP/RTSP 推流：支持将识别画面推送到流媒体服务器
• 异步推流：独立线程处理推流，不影响主流程性能
• 自动重试：推流失败自动重试，带冷却机制

6. 摄像头管理

• 自动重连：摄像头断开时自动尝试重新连接
• 故障恢复：连续失败达到阈值时触发完整重新初始化

技术架构

技术栈

• Python 3.x
• OpenCV：图像处理和摄像头控制
• CompreFace：人脸检测和识别服务
• WebSocket：实时通信
• Pillow (PIL)：中文字体渲染和图像合成
• FFmpeg：流媒体推送
• asyncio：异步事件循环

系统架构

┌─────────────────────────────────────────────────────────┐
│                    人脸识别系统主程序                      │
│                    (face_rec.py)                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  摄像头模块   │  │  识别模块     │  │  显示模块     │  │
│  │              │  │              │  │              │  │
│  │ - 视频采集   │  │ - 人脸检测   │  │ - 信息叠加   │  │
│  │ - 自动重连   │  │ - 身份识别   │  │ - 二维码显示 │  │
│  │ - 质量评估   │  │ - 角色判定   │  │ - 视频播放   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ WebSocket    │  │  推流模块     │  │  日志模块     │  │
│  │              │  │              │  │              │  │
│  │ - 状态同步   │  │ - FFmpeg推流 │  │ - 日志记录   │  │
│  │ - 消息通信   │  │ - 异步队列   │  │ - 日志轮转   │  │
│  │ - 自动重连   │  │ - 错误恢复   │  │              │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
    ┌─────────────┐      ┌──────────┐       ┌──────────┐
    │ CompreFace  │      │ 机器人主控│       │ 流媒体   │
    │   服务      │      │  程序     │       │  服务器  │
    └─────────────┘      └──────────┘       └──────────┘

安装部署

环境要求

• Python 3.7+
• Linux 系统（推荐 Ubuntu 20.04+）
• 摄像头设备
• X11 显示服务器

依赖安装

pip install opencv-python
pip install websockets
pip install pyyaml
pip install numpy
pip install Pillow
pip install compreface-sdk
pip install screeninfo
pip install psutil  # 可选，用于进程管理

FFmpeg 安装（用于推流）

sudo apt-get update
sudo apt-get install ffmpeg

配置文件

编辑 config.yaml 配置系统参数：

# CompreFace API 配置
compreface:
  host: "http://10.0.0.202"
  port: "8000"
  recognition_api_key: "your_recognition_key"
  detection_api_key: "your_detection_key"

# WebSocket 配置
websocket:
  url: "ws://127.0.0.1:3344"
  status_interval: 0.2

# 摄像头配置
camera:
  device_id: 0  # 或使用设备路径
  width: 1280
  height: 720
  fps: 30

# 人脸检测配置
face_detection:
  frame_interval: 10  # 检测帧间隔(每N帧检测一次)
  quality_threshold: 10  # 图像质量阈值(Laplacian方差)
  min_face_size: 80  # 最小人脸尺寸(像素)
  face_present_duration: 2.0  # 持续出现时长(秒)才触发识别
  max_yaw: 20.0  # 最大允许的偏航角(度)，超过此角度视为侧脸
  max_pitch: 20.0  # 最大允许的俯仰角(度)，超过此角度视为抬头或低头

# 人脸识别配置
face_recognition:
  recognition_cooldown: 20.0  # 识别冷却时间（秒）

role_mapping:
  stranger_threshold: 0.98  # 陌生人阈值

# 二维码配置
qrcode:
  image_path: "preview_qrcode_sota.jpg"
  display_duration: 30

# 视频配置
video:
  path: "exhibition.mp4"
  loop: true

# 推流配置（可选）
stream:
  enabled: false  # 是否启用推流
  rtmp_url: "rtsp://127.0.0.1/live/video"

运行方式

方式一：直接运行

python face_rec.py

方式二：使用启动脚本

chmod +x start.sh
./start.sh

方式三：系统服务（推荐生产环境）

# 复制服务文件
sudo cp face_rec.service /etc/systemd/system/

# 重载服务
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start face_rec

# 设置开机自启
sudo systemctl enable face_rec

# 查看服务状态
sudo systemctl status face_rec

# 查看日志
sudo journalctl -u face_rec -f

核心模块说明

1. FaceRecognitionSystem 类

系统主类，包含以下核心方法：

初始化相关

• __init__(): 初始化系统，加载配置
• _init_camera(): 初始化摄像头
• _init_compreface(): 初始化 CompreFace 服务
• _init_ffmpeg_stream(): 初始化推流

人脸识别

• detect_faces(): 检测人脸
• recognize_face(): 识别人脸
• assess_frame_quality(): 评估图像质量
• determine_role(): 判定人员角色
• should_recognize(): 判断是否需要识别

显示相关

• _show_qrcode(): 显示二维码
• _show_video(): 显示展厅视频
• draw_info_on_frame(): 在画面上绘制信息
• _draw_robot_status_on_video(): 在视频上绘制机器人状态
• _build_qrcode_instruction_canvas(): 构建二维码指引画布

WebSocket 通信

• connect_websocket(): 连接 WebSocket
• send_websocket_message(): 发送消息
• handle_websocket_messages(): 处理接收消息
• query_robot_status(): 查询机器人状态

推流相关

• _start_stream_thread(): 启动推流线程
• _stream_worker(): 推流工作线程
• _push_frame_to_stream(): 推送帧到流媒体
• _force_cleanup_ffmpeg(): 清理 FFmpeg 资源

主流程

• process_video_stream(): 处理视频流主循环
• run(): 系统运行入口

2. 工作流程

启动系统
    ↓
初始化配置、日志、CompreFace、摄像头
    ↓
连接 WebSocket（后台任务）
    ↓
启动推流（如果启用）
    ↓
┌─────────────────────────────────────┐
│         主循环（异步）                │
│                                     │
│  1. 读取摄像头帧                     │
│  2. 检查机器人角色，控制视频播放      │
│  3. 更新视频帧（如果正在播放）        │
│  4. 检查二维码超时                   │
│  5. 每 N 帧进行人脸检测              │
│  6. 检测到人脸 → 持续出现 2 秒       │
│  7. 触发人脸识别                     │
│  8. 判定角色（员工/访客/陌生人）      │
│  9. 发送识别结果到机器人             │
│ 10. 陌生人 → 显示二维码              │
│ 11. 绘制识别信息到画面               │
│ 12. 推送画面到流媒体（如果启用）      │
│ 13. 显示画面                         │
│                                     │
│  按 'q' 退出                         │
└─────────────────────────────────────┘
    ↓
清理资源（摄像头、推流、窗口）
    ↓
退出系统

文件说明

kanda-robot-facial-recognition/
├── face_rec.py                    # 主程序
├── config.yaml                    # 配置文件
├── start.sh                       # 启动脚本
├── face_rec.service               # systemd 服务文件
├── preview_qrcode_sota.png        # 二维码引导图片（新版）
├── qrcode.jpg                     # 二维码图片（旧版）
├── exhibition.mp4                 # 展厅讲解视频
├── preview_qrcode.py              # 二维码预览生成工具
├── face_recognition.log           # 运行日志
├── 001保存摄像头流.py              # 工具：保存摄像头视频流
├── 002查看摄像头id.py              # 工具：查看摄像头设备 ID
├── 003查看GUI后端.py               # 工具：查看 GUI 后端
└── README.md                      # 本文档

配置说明

人脸识别参数

• frame_interval: 检测帧间隔，建议 5-15
• quality_threshold: 图像质量阈值，建议 10-50
• min_face_size: 最小人脸尺寸（像素），建议 60-100
• face_present_duration: 持续出现时长（秒），建议 1.5-3.0
• max_yaw: 最大允许的偏航角（度），超过此角度视为侧脸，推荐 20°
• max_pitch: 最大允许的俯仰角（度），超过此角度视为抬头或低头，推荐 20°
• stranger_threshold: 陌生人阈值，建议 0.95-0.99
• recognition_cooldown: 识别冷却时间（秒），建议 15-30

摄像头设备 ID

方式一：使用数字 ID

camera:
  device_id: 0  # 通常是第一个摄像头

方式二：使用设备路径（推荐，更稳定）

# 查看可用摄像头
ls /dev/v4l/by-id/

# 使用设备路径
camera:
  device_id: "/dev/v4l/by-id/usb-xxx-video-index0"

WebSocket 消息格式

发送识别结果

{
  "type": "face_recognition",
  "message": {
    "person_name": "张三",
    "person_role": "员工",
    "similarity": 0.99,
    "timestamp": "2025-12-18 10:30:00"
  }
}

接收机器人状态

{
  "type": "status",
  "message": {
    "is_speaking": false,
    "is_thinking": true,
    "listening": false,
    "role_name": "展厅讲解员"
  }
}

常见问题

Q1: 摄像头无法打开

A:

1. 检查摄像头是否被其他程序占用
2. 确认设备 ID 是否正确：ls /dev/video*
3. 检查用户权限：sudo usermod -a -G video $USER
4. 重启系统

Q2: 无法显示中文

A:

1. 确认系统已安装中文字体
2. 修改 config.yaml 中的 font_path 配置
3. 常见字体路径：
   • Ubuntu: /usr/share/fonts/truetype/wqy/wqy-microhei.ttc
   • CentOS: /usr/share/fonts/wqy-microhei/wqy-microhei.ttc

Q3: WebSocket 连接失败

A:

1. 确认机器人主控程序已启动
2. 检查 WebSocket URL 配置
3. 查看防火墙设置
4. 系统会自动重连，检查日志确认状态

Q4: 推流失败

A:

1. 确认 FFmpeg 已安装：ffmpeg -version
2. 检查流媒体服务器是否运行
3. 验证 RTMP/RTSP URL 格式
4. 查看日志中的 FFmpeg 错误信息

Q5: 识别准确率低

A:

1. 提高 quality_threshold 确保图像清晰
2. 调整 stranger_threshold 阈值
3. 确保光线充足
4. 在 CompreFace 中添加更多训练照片

Q6: 侧脸也被识别了

A:

1. 调整 max_yaw 和 max_pitch 参数，降低角度阈值
2. 默认设置为 ±30 度，可改为 ±20 度提高严格程度
3. 检查 CompreFace 服务是否支持 pose 插件
4. 查看日志中的角度检查信息进行调试

Q7: 系统服务无法启动

A:

1. 检查服务文件路径配置
2. 确认 Python 环境和依赖
3. 查看日志：sudo journalctl -u face_rec -n 50
4. 检查 DISPLAY 和 XAUTHORITY 环境变量

性能优化建议

1. 降低检测频率：增大 frame_interval 值
2. 降低分辨率：适当降低摄像头分辨率
3. 关闭推流：生产环境不需要时关闭推流功能
4. 调整日志级别：生产环境使用 INFO 或 WARNING
5. 使用 GPU：如有 GPU，配置 OpenCV 使用 CUDA 加速

维护和监控

日志查看

# 查看应用日志
tail -f face_recognition.log

# 查看系统服务日志
sudo journalctl -u face_rec -f

# 查看启动脚本日志
tail -f /home/unitree/robot_face_rec/logs/face_rec/*.log

性能监控

# 查看 CPU 和内存占用
top -p $(pgrep -f face_rec.py)

# 查看 GPU 使用（如果使用 NVIDIA GPU）
nvidia-smi

# 查看进程状态
ps aux | grep face_rec

重启服务

# 重启服务
sudo systemctl restart face_rec

# 强制停止
sudo systemctl kill face_rec

# 完全重启（包括清理资源）
sudo systemctl stop face_rec
sleep 2
sudo systemctl start face_rec

开发和调试

调试模式

修改 config.yaml：

logging:
  level: "DEBUG"

测试工具

# 测试摄像头
python 001保存摄像头流.py

# 查看摄像头 ID
python 002查看摄像头id.py

# 预览二维码设计
python preview_qrcode.py

更新日志

v1.1.0 (2025-12-18)

• ✅ 新增正脸检测功能，基于CompreFace姿态检测技术过滤侧脸
• ✅ 添加人脸角度阈值配置（max_yaw: 20°, max_pitch: 20°）
• ✅ 使用REST API直接调用CompreFace，绕过SDK限制获取pose数据
• ✅ 优化人脸识别准确性，适用于门禁场景，只识别正面人脸
• ✅ 二维码显示时间延长至30秒，方便访客操作
• ✅ 二维码指引界面改为全屏显示，提升用户体验
• ✅ 修复PIL兼容性问题，解决圆角矩形渲染错误

v1.0.0 (2025-12-03)

• ✅ 完整的人脸检测和识别功能
• ✅ WebSocket 双向通信
• ✅ 二维码 SOTA 设计展示
• ✅ 展厅讲解视频播放
• ✅ 机器人状态叠加显示
• ✅ FFmpeg 流媒体推送
• ✅ 异步推流队列优化
• ✅ 摄像头自动重连机制
• ✅ 完善的日志系统

技术支持

如有问题，请联系开发团队或查看项目文档。

---

泰奥理 © 2025