# kommawar-tulasi/gesture-recognition-for-rubik-s-cube architecture

> Architecture diagram of the GitHub repository kommawar-tulasi/gesture-recognition-for-rubik-s-cube, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube
- Repository: https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube

## Overview

gesture-cube is a webcam-driven virtual Rubik’s cube, with a separate workflow for collecting labeled hand poses and training an SVM. At runtime, MediaPipe landmarks feed gesture recognition and hand tracking; the right hand aims, locks a tile, and drags a layer through the touchpad controller, while the left hand orbits or freezes the view. The app then updates and renders the puzzle, with keyboard controls as fallback. The README documents the end-to-end flow; sampled source confirms the feature schema, recognizer, controller, and rendering responsibilities, but not every runtime call site.

Main entry points: [`gesture_cube.py`](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py) (Hand Tracking), [`collect_gesture_data.py`](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/collect_gesture_data.py) (Sample Collector), [`gesture_svm.py`](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_svm.py) (Gesture Recognition), [`train_gesture_svm.py`](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/train_gesture_svm.py) (SVM Trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Gesture Data and Training"]
  node_collector["Sample Collector"]
  node_dataset["Labeled Samples"]
  node_trainer["SVM Trainer"]
  node_model["SVM Artifact"]
end

subgraph group_runtime["Hand Recognition"]
  node_landmarker["Landmark Detection<br/>[gesture_cube.py]"]
  node_features["Feature Extraction<br/>[gesture_svm.py]"]
  node_recognizer["Gesture Recognition<br/>[gesture_svm.py]"]
  node_handtracking["Hand Tracking<br/>[gesture_cube.py]"]
end

subgraph group_interaction["Cube Interaction"]
  node_touchpad["Touchpad Controller<br/>[gesture_cube.py]"]
  node_cube["Cube State and Moves<br/>[gesture_cube.py]"]
  node_orbit["Orbit Control<br/>[gesture_cube.py]"]
end

subgraph group_presentation["View and Controls"]
  node_renderer["Cube Renderer<br/>[gesture_cube.py]"]
  node_overlay["Status and Gesture UI<br/>[gesture_cube.py]"]
  node_keyboard["Keyboard Fallback<br/>[gesture_cube.py]"]
end

node_user(("User"))
node_webcam(("Webcam"))

node_user -->|"labels poses"| node_collector
node_webcam -->|"supplies video"| node_collector
node_collector -->|"saves samples"| node_dataset
node_dataset -->|"trains from"| node_trainer
node_trainer -->|"saves pipeline"| node_model
node_user -->|"gestures to"| node_webcam
node_webcam -->|"provides frames"| node_landmarker
node_landmarker -->|"provides landmarks"| node_features
node_features -->|"formats features"| node_recognizer
node_model -->|"loads model"| node_recognizer
node_recognizer -->|"provides gestures"| node_handtracking
node_handtracking -->|"provides hand input"| node_touchpad
node_touchpad -->|"turns selected layer"| node_cube
node_handtracking -->|"drives view orbit"| node_orbit
node_orbit -->|"sets view orientation"| node_renderer
node_cube -->|"renders puzzle state"| node_renderer
node_touchpad -->|"shows interaction status"| node_overlay
node_user -->|"uses fallback keys"| node_keyboard
node_keyboard -->|"issues move commands"| node_cube

click node_collector "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/collect_gesture_data.py"
click node_dataset "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/collect_gesture_data.py"
click node_trainer "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/train_gesture_svm.py"
click node_model "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/train_gesture_svm.py"
click node_landmarker "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_features "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_svm.py"
click node_recognizer "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_svm.py"
click node_handtracking "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_touchpad "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_cube "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_orbit "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_renderer "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_overlay "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"
click node_keyboard "https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collector,node_dataset,node_trainer,node_model,node_user toneBlue
class node_landmarker,node_features,node_recognizer,node_handtracking toneAmber
class node_touchpad,node_cube,node_orbit toneMint
class node_renderer,node_overlay,node_keyboard toneRose
class node_webcam toneIndigo
```

## Components

### Gesture Data and Training

- [Sample Collector](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/collect_gesture_data.py): `collect_gesture_data.py`
- [Labeled Samples](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/collect_gesture_data.py): `collect_gesture_data.py`
- [SVM Trainer](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/train_gesture_svm.py): `train_gesture_svm.py`
- [SVM Artifact](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/train_gesture_svm.py): `train_gesture_svm.py`

### Hand Recognition

- [Landmark Detection](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`
- [Feature Extraction](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_svm.py): `gesture_svm.py`
- [Gesture Recognition](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_svm.py): `gesture_svm.py`
- [Hand Tracking](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`

### Cube Interaction

- [Touchpad Controller](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`
- [Cube State and Moves](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`
- [Orbit Control](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`

### View and Controls

- [Cube Renderer](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`
- [Status and Gesture UI](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`
- [Keyboard Fallback](https://github.com/kommawar-tulasi/gesture-recognition-for-rubik-s-cube/blob/main/gesture_cube.py): `gesture_cube.py`

### Other components

- **User**
- **Webcam**

## Connections

- User → Sample Collector: labels poses (evidence: `README.md`)
- Webcam → Sample Collector: supplies video (evidence: `README.md`)
- Sample Collector → Labeled Samples: saves samples (evidence: `README.md`)
- Labeled Samples → SVM Trainer: trains from (evidence: `README.md`)
- SVM Trainer → SVM Artifact: saves pipeline (evidence: `train_gesture_svm.py`)
- User → Webcam: gestures to (evidence: `README.md`)
- Webcam → Landmark Detection: provides frames (evidence: `README.md`)
- Landmark Detection → Feature Extraction: provides landmarks (evidence: `README.md`)
- Feature Extraction → Gesture Recognition: formats features (evidence: `gesture_svm.py`)
- SVM Artifact → Gesture Recognition: loads model (evidence: `gesture_svm.py`)
- Gesture Recognition → Hand Tracking: provides gestures (evidence: `README.md`)
- Hand Tracking → Touchpad Controller: provides hand input (evidence: `README.md`)
- Touchpad Controller → Cube State and Moves: turns selected layer (evidence: `README.md`)
- Hand Tracking → Orbit Control: drives view orbit (evidence: `README.md`)
- Orbit Control → Cube Renderer: sets view orientation (evidence: `README.md`)
- Cube State and Moves → Cube Renderer: renders puzzle state (evidence: `README.md`)
- Touchpad Controller → Status and Gesture UI: shows interaction status (evidence: `gesture_cube.py`)
- User → Keyboard Fallback: uses fallback keys (evidence: `README.md`)
- Keyboard Fallback → Cube State and Moves: issues move commands (evidence: `README.md`)
