# 康达机器人人脸识别系统

## 项目简介

这是一个基于 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 显示服务器

### 依赖安装
```bash
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 安装（用于推流）
```bash
sudo apt-get update
sudo apt-get install ffmpeg
```

### 配置文件

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

```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"
```

### 运行方式

#### 方式一：直接运行
```bash
python face_rec.py
```

#### 方式二：使用启动脚本
```bash
chmod +x start.sh
./start.sh
```

#### 方式三：系统服务（推荐生产环境）
```bash
# 复制服务文件
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**
```yaml
camera:
  device_id: 0  # 通常是第一个摄像头
```

**方式二：使用设备路径（推荐，更稳定）**
```bash
# 查看可用摄像头
ls /dev/v4l/by-id/

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

### WebSocket 消息格式

**发送识别结果**
```json
{
  "type": "face_recognition",
  "message": {
    "person_name": "张三",
    "person_role": "员工",
    "similarity": 0.99,
    "timestamp": "2025-12-18 10:30:00"
  }
}
```

**接收机器人状态**
```json
{
  "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 加速

## 维护和监控

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

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

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

### 性能监控
```bash
# 查看 CPU 和内存占用
top -p $(pgrep -f face_rec.py)

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

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

### 重启服务
```bash
# 重启服务
sudo systemctl restart face_rec

# 强制停止
sudo systemctl kill face_rec

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

## 开发和调试

### 调试模式
修改 `config.yaml`：
```yaml
logging:
  level: "DEBUG"
```

### 测试工具
```bash
# 测试摄像头
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**