# Gesture-controlled sphere

**Repository Path**: sxupgljd/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**: 1
- **Forks**: 87
- **Created**: 2025-03-20
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gesture-Controlled 3D Network Sphere

This is a Python-based interactive 3D visualization project that combines MediaPipe gesture recognition with OpenGL/Pygame 3D rendering technology to create a dynamic 3D network sphere system controlled by user gestures.

## File Structure

The project contains three main files, each responsible for different functionalities:

- **hands.py**: Basic gesture recognition demo
  - Uses MediaPipe to identify 21 key points on the hand
  - Visualizes hand skeleton and key points
  - Displays left/right hand distinction and depth information
  - Suitable for beginners to understand the basic principles of gesture recognition

- **main.py**: Drawing functionality demo
  - Extended gesture drawing functionality based on hands.py
  - Uses index fingertip trajectory to draw star patterns
  - Fist gesture can erase the canvas
  - Enhanced gesture recognition algorithms and visualization effects

- **control_sphere.py**: Complete 3D sphere control system
  - Combines gesture recognition and 3D rendering technology
  - Implements advanced interactive functions such as rotation, scaling, and locking
  - Multi-threaded processing ensures smooth rendering and recognition
  - Provides a complete user interface and feedback system

## Features

- **Real-time Gesture Recognition**: Uses MediaPipe to recognize four key gestures
  - Open palm: Controls rotation and scaling
  - OK gesture (thumb and index finger forming a circle): Locks current scale ratio
  - Fist: Releases lock or resets view
  - Pointing index finger: Reserved for special function interface

- **Interactive 3D Visualization**:
  - Colorful balls moving and colliding in 3D space
  - Dynamic connection lines forming between balls
  - Physics-based collision detection and rebound effects
  - Pulsating light effects enhance visual experience

- **Real-time Camera Feedback**:
  - Displays camera view in one corner of the interface
  - Visualizes gesture recognition results
  - FPS counter and scaling indicator

## Requirements

- Python 3.7+
- Computer with camera
- Good lighting conditions (for better gesture recognition)

## Installation

1. Clone or download the project code

2. Install dependencies:
```bash
pip install numpy opencv-python mediapipe pygame PyOpenGL
```

3. Run the program:
```bash
python control_sphere.py
```

## Usage Instructions

### Gesture Controls

- **Open Palm**:
  - Move left/right: Rotate the 3D sphere horizontally
  - Move up/down: Rotate the 3D sphere vertically
  - Move toward/away from camera: Decrease/increase view size

- **OK Gesture**:
  - Hold for 1 second: Lock current scale ratio
  - White circle marker appears on progress bar to indicate locked status

- **Fist**:
  - When unlocked: Reset to default view
  - When locked, hold for 2 seconds: Release scale lock

- **Index Finger Pointing**:
  - Reserved functionality, not yet implemented

### Keyboard Controls

- **ESC key**: Exit program
- **Spacebar**: Toggle auto-rotation mode
- **V key**: Cycle through preset views

## Troubleshooting

- **Camera Not Detected**:
  - Check if the camera is correctly connected
  - Confirm that other programs are not using the camera

- **Inaccurate Gesture Recognition**:
  - Ensure good lighting conditions
  - Keep your hand centered in the camera's field of view
  - Make clear, defined gesture movements

- **Low Frame Rate**:
  - Reduce the number of balls in the program (modify the `num_balls` variable)
  - Close other programs that use CPU/GPU resources

## Technical Details

This project combines multiple technologies:
- MediaPipe gesture recognition
- Pygame window and event handling
- OpenGL 3D rendering
- Multi-threaded camera processing
- Physics simulation (collision detection and rebound)

## License

[MIT License](LICENSE)