# McpFace **Repository Path**: mythos-tech/mcp-face ## Basic Information - **Project Name**: McpFace - **Description**: 基于OpenFace的人脸识别系统，提供人脸检测、特征提取、人脸比对和实时视频流人脸识别功能。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-05-23 - **Last Updated**: 2025-05-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MCP Face Recognition 基于Spring Boot和OpenCV的人脸识别系统，提供人脸检测、特征提取、人脸比对和实时视频流人脸识别功能。 ## 项目介绍 MCP Face Recognition是一个完整的人脸识别解决方案，结合了Spring Boot后端和现代前端技术，使用OpenCV进行高效的人脸处理。系统支持静态图片分析和实时视频流处理，可用于身份验证、访问控制和用户管理等场景。 ## 功能特性 - **人脸检测**：检测图片中的人脸位置和数量 - **人脸特征提取**：提取人脸的特征向量，用于后续比对 - **人脸比对**：比较两张图片中的人脸是否为同一人 - **用户管理**：注册和管理用户，存储用户人脸特征 - **人脸登录**：通过人脸识别进行身份验证 - **实时视频流处理**：从摄像头捕获视频并实时检测人脸 - **质心优化算法**：通过质心计算减少视频流中的检测请求，提高性能 - **可视化界面**：直观展示检测和比对结果 ## 技术栈 - **后端**： - Spring Boot 3.1.5 - JavaCV/OpenCV (用于图像处理和人脸识别) - RESTful API - **前端**： - HTML5/CSS3/JavaScript - Bootstrap 5 (响应式UI) - Fetch API (异步请求) ## 系统要求 - JDK 17+ - Maven 3.6+ - 现代浏览器（支持HTML5和JavaScript） - 摄像头（用于视频流功能） ## 项目结构 ``` mcp-face/ ├── src/ │ ├── main/ │ │ ├── java/com/example/mcpface/ │ │ │ ├── controller/ # REST API控制器 │ │ │ ├── model/ # 数据模型 │ │ │ ├── service/ # 业务逻辑 │ │ │ └── util/ # 工具类 │ │ └── resources/ │ │ ├── static/ # 前端资源 │ │ │ ├── js/ # JavaScript文件 │ │ │ └── index.html # 主页面 │ │ └── application.yml # 应用配置 ├── models/ # 模型文件目录 ├── download_models.sh # 模型下载脚本 └── pom.xml # Maven配置 ``` ## 必需的模型文件 在运行项目之前，需要下载以下模型文件并放置在 `models` 目录下： 1. 人脸检测模型： - `res10_300x300_ssd_iter_140000.caffemodel`：SSD检测器模型 - `deploy.prototxt`：模型配置文件 2. 人脸识别模型： - `openface.nn4.small2.v1.t7`：OpenFace特征提取模型 可以使用提供的脚本自动下载模型： ```bash ./download_models.sh ``` ## 快速开始 1. 克隆项目： ```bash git clone https://github.com/yourusername/mcp-face.git cd mcp-face ``` 2. 下载模型文件： ```bash ./download_models.sh ``` 3. 构建项目： ```bash mvn clean package ``` 4. 运行项目： ```bash java -jar target/mcp-face-0.0.1-SNAPSHOT.jar ``` 5. 访问应用： 在浏览器中打开 `http://localhost:8080` ## 详细使用指南 ### 静态图片人脸检测 1. 在主页面选择"人脸检测"标签页 2. 点击"选择图片"按钮上传图片 3. 点击"检测人脸"按钮 4. 系统将显示检测结果，包括人脸位置和置信度 ### 人脸比对 1. 在主页面选择"人脸比对"标签页 2. 上传源图片和目标图片 3. 点击"比对人脸"按钮 4. 系统将显示比对结果，包括相似度和是否匹配 ### 用户注册 1. 在主页面选择"用户管理"标签页 2. 点击"注册"子标签页 3. 点击"启动摄像头"按钮 4. 调整位置确保人脸在画面中 5. 点击"拍照"按钮捕获人脸图像 6. 输入用户名和密码 7. 点击"注册"按钮完成注册 ### 人脸登录 1. 在主页面选择"用户管理"标签页 2. 点击"登录"子标签页 3. 点击"启动摄像头"按钮 4. 调整位置确保人脸在画面中 5. 点击"人脸登录"按钮 6. 系统将验证人脸并显示登录结果 ### 视频流人脸检测 1. 在主页面选择"视频流"标签页 2. 点击"开启摄像头"按钮 3. 点击"开启人脸检测"按钮 4. 系统将实时检测视频中的人脸 5. 可以通过"检测优化设置"面板调整参数 ## API 接口 ### 1. 人脸检测 **请求：** ```http POST /api/faces/detect Content-Type: multipart/form-data image=[图片文件] ``` **响应：** ```json { "faceDetected": true, "faceCount": 1, "faceLocations": [ { "x": 100, "y": 100, "width": 200, "height": 200, "confidence": 0.99 } ], "message": "成功检测到人脸" } ``` ### 2. 人脸比对 **请求：** ```http POST /api/faces/compare Content-Type: multipart/form-data sourceImage=[源图片文件] targetImage=[目标图片文件] ``` **响应：** ```json { "isMatch": true, "similarity": 0.95, "message": "人脸匹配", "sourceFaceCount": 1, "targetFaceCount": 1 } ``` ### 3. 视频帧人脸检测 **请求：** ```http POST /api/faces/detect-frame Content-Type: application/x-www-form-urlencoded image=[Base64编码的图像数据] ``` **响应：** 与人脸检测API相同 ### 4. 用户注册 **请求：** ```http POST /api/users/register Content-Type: multipart/form-data username=[用户名] password=[密码] faceImage=[人脸图像文件] ``` **响应：** ```json { "success": true, "message": "注册成功", "userId": 1 } ``` ### 5. 人脸登录 **请求：** ```http POST /api/users/login Content-Type: application/x-www-form-urlencoded faceImage=[Base64编码的人脸图像] ``` **响应：** ```json { "success": true, "message": "登录成功", "username": "user123" } ``` ## 配置说明 在 `application.yml` 中可以配置以下参数： ```yaml server: port: 8080 # 服务器端口 spring: application: name: mcp-face servlet: multipart: max-file-size: 10MB # 最大文件上传大小 max-request-size: 10MB # 自定义配置 face: detection: confidence-threshold: 0.7 # 人脸检测的置信度阈值 similarity-threshold: 0.8 # 人脸比对的相似度阈值 model-path: ${user.dir}/models # 模型文件路径 ``` ## 性能优化 系统实现了基于质心计算的视频流优化算法，可以显著减少对服务器的请求次数： 1. **质心计算**：计算每个检测到的人脸的质心位置 2. **距离比较**：比较连续帧之间人脸质心的距离 3. **智能跳过**：当质心距离小于阈值时，跳过服务器检测 可以通过UI中的"检测优化设置"面板调整以下参数： - **质心距离阈值**：决定多大的移动会触发新的检测（默认30像素） - **最大连续跳过次数**：防止长时间不更新（默认5次） - **启用/禁用优化**：完全控制优化功能 ## 故障排除 ### 常见问题 1. **无法检测到人脸** - 确保图像清晰且人脸正面朝向摄像头 - 检查光线条件，避免过暗或过亮 - 尝试调整`confidence-threshold`参数 2. **人脸比对不准确** - 确保两张图片中的人脸清晰可见 - 尝试调整`similarity-threshold`参数 - 检查模型文件是否正确加载 3. **视频流卡顿** - 降低视频分辨率 - 增加质心距离阈值减少检测频率 - 检查网络连接和服务器负载 4. **启动失败** - 确保模型文件已正确下载并放置在`models`目录 - 检查端口8080是否被占用 - 确保使用JDK 17或更高版本 ### 日志位置 应用日志默认输出到控制台，可以通过以下方式重定向到文件： ```bash java -jar target/mcp-face-0.0.1-SNAPSHOT.jar > app.log 2>&1 ``` ## 贡献指南 我们欢迎任何形式的贡献，包括但不限于： 1. 报告问题和建议 2. 提交代码改进 3. 改进文档 4. 添加新功能 贡献步骤： 1. Fork项目 2. 创建特性分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add some amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 创建Pull Request ## 未来计划 - [ ] 支持HTTPS安全连接 - [ ] 添加更多人脸属性分析（年龄、性别等） - [ ] 实现人脸表情识别 - [ ] 添加批量处理功能 - [ ] 支持更多视频源（如RTSP流） - [ ] 改进移动设备兼容性 ## 许可证 本项目采用MIT许可证 - 详情请参阅 [LICENSE](LICENSE) 文件 ## 联系方式 如有任何问题或建议，请通过以下方式联系我们： - 项目Issues: [GitHub Issues](https://github.com/yourusername/mcp-face/issues) - 电子邮件: your.email@example.com --- 感谢使用MCP Face Recognition！ ## API 接口 ### 1. 人脸检测 **请求：** ```http POST /api/faces/detect Content-Type: multipart/form-data image=[图片文件] ``` **响应：** ```json { "faceDetected": true, "faceCount": 1, "faceLocations": [ { "x": 100, "y": 100, "width": 200, "height": 200, "confidence": 0.99 } ], "message": "成功检测到人脸" } ``` ### 2. 人脸比对 **请求：** ```http POST /api/faces/compare Content-Type: multipart/form-data sourceImage=[源图片文件] targetImage=[目标图片文件] ``` **响应：** ```json { "isMatch": true, "similarity": 0.95, "message": "人脸匹配", "sourceFaceCount": 1, "targetFaceCount": 1 } ``` ## 配置说明 在 `application.yml` 中可以配置以下参数： ```yaml face: detection: confidence-threshold: 0.7 # 人脸检测的置信度阈值 similarity-threshold: 0.8 # 人脸比对的相似度阈值 model-path: ${user.dir}/models # 模型文件路径 ``` ## 注意事项 1. 确保已正确下载并放置所需的模型文件 2. 上传的图片大小限制为10MB 3. 仅支持常见的图片格式（JPEG、PNG等） 4. 建议上传清晰的正面人脸照片以获得最佳效果 ## 许可证 [添加许可证信息]