# gedeananda/python-handtrack architecture

> Architecture diagram of the GitHub repository gedeananda/python-handtrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gedeananda/python-handtrack
- Repository: https://github.com/gedeananda/python-handtrack

## Overview

Retrolens is a webcam-based hand-tracking filter app. Its main workflow captures a frame, detects hand landmarks, uses gestures to select a filter and define a four-point portal, processes the portal region, then displays the result. The README also documents eleven filters, including Galaxy background replacement; the segmentation model is optional at runtime. The implementation is concentrated in `main.py`, so several distinct responsibilities share that path. Relationships below are supported by the excerpted source or README.

Main entry points: [`main.py`](https://github.com/gedeananda/python-handtrack/blob/main/main.py) (Frame Loop), [`hand_landmarker.task`](https://github.com/gedeananda/python-handtrack/blob/main/hand_landmarker.task) (Hand Model), [`selfie_segmenter.tflite`](https://github.com/gedeananda/python-handtrack/blob/main/selfie_segmenter.tflite) (Segmentation Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Capture and Perception"]
  node_frame_loop["Frame Loop<br/>[main.py]"]
  node_hand_detection["Hand Detection<br/>[main.py]"]
  node_hand_model["Hand Model"]
  node_segmentation["Person Segmentation<br/>[main.py]"]
  node_segment_model["Segmentation Model"]
end

subgraph group_interaction["Gesture and Portal"]
  node_gesture_filter["Gesture Filter Switch<br/>[main.py]"]
  node_portal_geometry["Portal Geometry<br/>[main.py]"]
  node_filter_state["Active Filter<br/>[main.py]"]
end

subgraph group_rendering["Filter Rendering"]
  node_galaxy_background["Galaxy Background<br/>[main.py]"]
  node_filter_engine["Filter Engine<br/>[main.py]"]
  node_portal_composite["Portal Composite<br/>[main.py]"]
  node_camera_display["Camera Display<br/>[main.py]"]
end

node_user(("User"))
node_webcam(("Webcam"))
node_screen(("Display"))

node_webcam -->|"provides frames"| node_frame_loop
node_frame_loop -->|"submits frames"| node_hand_detection
node_hand_detection -->|"loads model"| node_hand_model
node_hand_detection -->|"returns landmarks"| node_gesture_filter
node_hand_detection -->|"returns landmarks"| node_portal_geometry
node_frame_loop -->|"requests mask"| node_segmentation
node_segmentation -->|"loads model"| node_segment_model
node_gesture_filter -->|"advances filter"| node_filter_state
node_portal_geometry -->|"supplies region"| node_filter_engine
node_filter_state -->|"selects filter"| node_filter_engine
node_segmentation -->|"supplies mask"| node_filter_engine
node_galaxy_background -->|"supplies background"| node_filter_engine
node_frame_loop -->|"creates background"| node_galaxy_background
node_filter_engine -->|"returns filtered region"| node_portal_composite
node_portal_geometry -->|"supplies polygon"| node_portal_composite
node_frame_loop -->|"sends frame"| node_camera_display
node_portal_composite -->|"updates frame"| node_camera_display
node_user -->|"makes gestures"| node_gesture_filter
node_user -->|"presses q"| node_camera_display
node_camera_display -->|"shows frame"| node_screen

click node_frame_loop "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_hand_detection "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_hand_model "https://github.com/gedeananda/python-handtrack/blob/main/hand_landmarker.task"
click node_segmentation "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_segment_model "https://github.com/gedeananda/python-handtrack/blob/main/selfie_segmenter.tflite"
click node_gesture_filter "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_portal_geometry "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_filter_state "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_galaxy_background "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_filter_engine "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_portal_composite "https://github.com/gedeananda/python-handtrack/blob/main/main.py"
click node_camera_display "https://github.com/gedeananda/python-handtrack/blob/main/main.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_frame_loop,node_hand_detection,node_hand_model,node_segmentation,node_segment_model,node_user toneBlue
class node_gesture_filter,node_portal_geometry,node_filter_state toneAmber
class node_galaxy_background,node_filter_engine,node_portal_composite,node_camera_display toneMint
class node_webcam,node_screen toneIndigo
```

## Components

### Capture and Perception

- [Frame Loop](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Hand Detection](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Hand Model](https://github.com/gedeananda/python-handtrack/blob/main/hand_landmarker.task): `hand_landmarker.task`
- [Person Segmentation](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Segmentation Model](https://github.com/gedeananda/python-handtrack/blob/main/selfie_segmenter.tflite): `selfie_segmenter.tflite`

### Gesture and Portal

- [Gesture Filter Switch](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Portal Geometry](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Active Filter](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`

### Filter Rendering

- [Galaxy Background](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Filter Engine](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Portal Composite](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`
- [Camera Display](https://github.com/gedeananda/python-handtrack/blob/main/main.py): `main.py`

### Other components

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

## Connections

- Webcam → Frame Loop: provides frames (evidence: `main.py`)
- Frame Loop → Hand Detection: submits frames (evidence: `main.py`)
- Hand Detection → Hand Model: loads model (evidence: `main.py`)
- Hand Detection → Gesture Filter Switch: returns landmarks (evidence: `main.py`)
- Hand Detection → Portal Geometry: returns landmarks (evidence: `main.py`)
- Frame Loop → Person Segmentation: requests mask (evidence: `main.py`)
- Person Segmentation → Segmentation Model: loads model (evidence: `main.py`)
- Gesture Filter Switch → Active Filter: advances filter (evidence: `main.py`)
- Portal Geometry → Filter Engine: supplies region (evidence: `main.py`)
- Active Filter → Filter Engine: selects filter (evidence: `main.py`)
- Person Segmentation → Filter Engine: supplies mask (evidence: `main.py`)
- Galaxy Background → Filter Engine: supplies background (evidence: `main.py`)
- Frame Loop → Galaxy Background: creates background (evidence: `main.py`)
- Filter Engine → Portal Composite: returns filtered region (evidence: `main.py`)
- Portal Geometry → Portal Composite: supplies polygon (evidence: `main.py`)
- Frame Loop → Camera Display: sends frame (evidence: `main.py`)
- Portal Composite → Camera Display: updates frame (evidence: `main.py`)
- User → Gesture Filter Switch: makes gestures (evidence: `README.md`)
- User → Camera Display: presses q (evidence: `main.py`)
- Camera Display → Display: shows frame (evidence: `main.py`)
