# Gesture-controlled sphere

**Repository Path**: ling1212/gesture-controlled-sphere

## Basic Information

- **Project Name**: Gesture-controlled sphere
- **Description**: 手势控制球体
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 74
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 手势控制3D网络球体

这是一个基于Python的交互式3D可视化项目，结合了MediaPipe手势识别和OpenGL/Pygame 3D渲染技术，创建了一个由用户手势控制的动态3D网络球体系统。

## 文件结构

项目包含三个主要文件，各自负责不同的功能：

- **hands.py**：基础手势识别演示
  - 使用MediaPipe识别手部21个关键点
  - 可视化手部骨架和关键点
  - 显示左右手区分和深度信息
  - 适合初学者了解手势识别的基本原理

- **main.py**：绘画功能演示
  - 基于hands.py拓展的手势绘画功能
  - 使用食指指尖轨迹绘制星形图案
  - 握拳手势可擦除画布
  - 增强的手势识别算法和可视化效果

- **control_sphere.py**：完整的3D球体控制系统
  - 结合手势识别和3D渲染技术
  - 实现了旋转、缩放、锁定等高级交互功能
  - 多线程处理确保渲染和识别流畅运行
  - 提供了完整的用户界面和反馈系统

## 功能特点

- **实时手势识别**：使用MediaPipe识别四种关键手势
  - 手掌张开：控制旋转和缩放
  - OK手势（拇指和食指形成圈）：锁定当前缩放比例
  - 握拳：解除锁定或重置视角
  - 食指指向：预留的特殊功能接口

- **交互式3D可视化**：
  - 多彩小球在3D空间内运动和碰撞
  - 小球之间形成动态连接线
  - 基于物理的碰撞检测与反弹效果
  - 脉动灯光效果增强视觉体验

- **实时摄像头反馈**：
  - 在界面一角显示摄像头画面
  - 可视化手势识别结果
  - FPS计数器和缩放指示器

## 环境要求

- Python 3.7+
- 带摄像头的计算机
- 良好的照明条件（手势识别效果更佳）

## 安装步骤

1. 克隆或下载项目代码

2. 安装依赖库：
```bash
pip install numpy opencv-python mediapipe pygame PyOpenGL
```

3. 运行程序：
```bash
python control_sphere.py
```

## 使用说明

### 手势控制

- **手掌张开**：
  - 左右移动：水平旋转3D球体
  - 上下移动：垂直旋转3D球体
  - 靠近/远离摄像头：缩小/放大视图

- **OK手势**：
  - 保持1秒：锁定当前缩放比例
  - 白色圆圈标记会出现在进度条上，表示已锁定

- **握拳**：
  - 未锁定状态下：重置到默认视角
  - 锁定状态下持续2秒：解除缩放锁定

- **食指指向**：
  - 预留功能，暂未实现

### 键盘控制

- **ESC键**：退出程序
- **空格键**：切换自动旋转模式
- **V键**：循环切换预设视角

## 故障排除

- **摄像头未检测到**：
  - 检查摄像头是否正确连接
  - 确认其他程序未占用摄像头

- **手势识别不准确**：
  - 确保良好的光线条件
  - 将手掌保持在摄像头视野中心位置
  - 保持手势动作清晰、明确

- **帧率低**：
  - 降低程序中的球体数量（修改`num_balls`变量）
  - 关闭其他占用CPU/GPU的程序

## 技术细节

该项目结合了多种技术：
- MediaPipe手势识别
- Pygame窗口和事件处理
- OpenGL 3D渲染
- 多线程摄像头处理
- 物理模拟（碰撞检测与反弹）

## 许可证

[MIT许可证](LICENSE)