From 5b81d6ae95532831d4b384fec349724bca2fc5fc Mon Sep 17 00:00:00 2001 From: Tian jianyong <11429339@qq.com> Date: Thu, 18 Dec 2025 10:12:30 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20README=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 475 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 475 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3095414 --- /dev/null +++ b/README.md @@ -0,0 +1,475 @@ +# 康达机器人人脸识别系统 + +## 项目简介 + +这是一个基于 CompreFace 的智能人脸识别系统，为康达新材的接待机器人提供实时人脸检测、识别和访客管理功能。系统通过 WebSocket 与机器人主控程序通信，支持视频展示、二维码引导和流媒体推送等多种功能。 + +## 核心功能 + +### 1. 人脸识别 +- **实时检测**：基于 CompreFace API 进行高精度人脸检测 +- **身份识别**：自动识别员工和访客，支持相似度阈值配置 +- **防重复识别**：智能冷却机制，避免短时间内重复识别同一人 +- **质量评估**：使用 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_recognition: + recognition_cooldown: 20.0 # 识别冷却时间（秒） + +role_mapping: + stranger_threshold: 0.98 # 陌生人阈值 + +# 二维码配置 +qrcode: + image_path: "preview_qrcode_sota.jpg" + display_duration: 10 + +# 视频配置 +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.jpg # 二维码引导图片（新版） +├── 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 +- `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. 检查服务文件路径配置 +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.0.0 (2025-12-03) +- ✅ 完整的人脸检测和识别功能 +- ✅ WebSocket 双向通信 +- ✅ 二维码 SOTA 设计展示 +- ✅ 展厅讲解视频播放 +- ✅ 机器人状态叠加显示 +- ✅ FFmpeg 流媒体推送 +- ✅ 异步推流队列优化 +- ✅ 摄像头自动重连机制 +- ✅ 完善的日志系统 + +## 技术支持 + +如有问题，请联系开发团队或查看项目文档。 + +--- + +**泰奥理 © 2025**