# xiaocar-hand-detection

**Repository Path**: yr_binary/xiaocar-hand-detection

## Basic Information

- **Project Name**: xiaocar-hand-detection
- **Description**: 基于YOLO11的手部关键点检测与角度计算系统，支持右手正面识别、手指角度计算和手掌张开度分析
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-10-15
- **Last Updated**: 2025-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚗 XiaoCar 手部检测与角度计算系统

基于YOLO11的智能手部关键点检测与角度计算系统，专门用于右手正面识别、手指角度计算和手掌张开度分析。

## 🌟 项目特色

- **🎯 精准识别**：专门针对右手正面进行优化识别
- **📐 角度计算**：实时计算手指间角度和手掌张开度
- **🖥️ 中文界面**：完全本地化的中文用户界面
- **⚡ 实时处理**：支持摄像头实时检测和图像/视频处理
- **🔧 易于使用**：简单的命令行界面和详细的使用说明

## 📁 项目结构

```
xiaocar/
├── hand/                           # 手部检测模块
│   ├── hand_angle_detection.py     # 主程序：手部检测与角度计算
│   ├── train_hand_keypoints.py     # 训练脚本
│   ├── models/                     # 模型文件目录
│   │   ├── yolo11n-hand-kpts-gpu/  # 手部关键点检测模型
│   │   └── yolo11n-pose.pt         # 预训练姿态模型
│   ├── hand-keypoints.yaml         # 数据集配置文件
│   ├── requirements.txt            # 依赖包列表
│   └── README.md                   # 手部模块详细说明
├── runs/                           # 其他实验代码
└── README.md                       # 项目主说明文档
```

## 🚀 快速开始

### 环境要求

- Python 3.8+
- CUDA 11.0+ (GPU加速，可选)
- 摄像头设备

### 安装依赖

```bash
cd hand
pip install -r requirements.txt
```

### 运行程序

#### 1. 摄像头实时检测（推荐）
```bash
python hand_angle_detection.py
```

#### 2. 处理单张图像
```bash
python hand_angle_detection.py --image path/to/image.jpg --save
```

#### 3. 处理视频文件
```bash
python hand_angle_detection.py --video path/to/video.mp4 --save
```

#### 4. 查看所有参数
```bash
python hand_angle_detection.py --help
```

## 🎮 使用说明

### 检测状态说明

- **✅ 检测到: 右手正面** - 绿色显示，正常工作状态
- **⚠️ 检测到右手，但非正面** - 橙色警告，请调整手势
- **❌ 未检测到右手** - 红色提示，请将右手放在摄像头前

### 输出信息

程序会实时显示：
- 右手张开度百分比
- 四个手指间的角度值（拇指-食指、食指-中指、中指-无名指、无名指-小指）
- 手部关键点可视化
- 手指骨骼连接线

### 操作控制

- 按 `q` 键退出程序
- 使用 `--save` 参数保存检测结果

## 🔧 技术特点

### 核心算法

1. **右手识别算法**：基于手部关键点的几何特征判断
2. **正面检测算法**：通过指尖可见性和手掌法向量计算
3. **角度计算算法**：使用向量夹角公式计算手指间角度
4. **张开度评估**：综合多个角度指标评估手掌张开程度

### 技术栈

- **深度学习框架**：Ultralytics YOLO11
- **计算机视觉**：OpenCV
- **数值计算**：NumPy
- **GPU加速**：PyTorch CUDA

## 📊 性能指标

- **检测精度**：>95% (右手正面)
- **处理速度**：30+ FPS (GPU) / 10+ FPS (CPU)
- **角度精度**：±2°
- **响应延迟**：<50ms

## 🛠️ 开发说明

### 模型训练

如需重新训练模型：

```bash
python train_hand_keypoints.py --data hand-keypoints.yaml --epochs 100
```

### 自定义配置

可以修改以下文件进行自定义：
- `hand-keypoints.yaml`：数据集配置
- `hand_angle_detection.py`：检测参数调整

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 更新日志

### v1.0.0 (2025-01-15)
- ✨ 实现右手正面检测功能
- ✨ 添加手指角度计算
- ✨ 完整中文界面本地化
- ✨ 支持实时摄像头检测
- ✨ 支持图像和视频处理

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 👥 作者

- **开发者**: zp (yr_binary)
- **项目地址**: https://gitee.com/yr_binary/xiaocar-hand-detection

## 🙏 致谢

- Ultralytics YOLO 团队提供的优秀框架
- OpenCV 社区的技术支持
- 所有为开源项目做出贡献的开发者们

---

如有问题或建议，欢迎提交 Issue 或联系开发者！