# laith-kalfood/gesture-led-control architecture

> Architecture diagram of the GitHub repository laith-kalfood/gesture-led-control, 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/laith-kalfood/gesture-led-control
- Repository: https://github.com/laith-kalfood/gesture-led-control

## Overview

A single Python script implements the runtime: it captures webcam frames, detects hands and gates control on a raised index finger, maps pinky–thumb distance to PWM brightness, and sends the value to an Arduino. It also overlays hand landmarks and the measured span for visual feedback. The README documents the Arduino/PyFirmata setup and intended gesture. There are no separate source modules or storage layers; relationships shown here are evidenced by the script, while external hardware and libraries are represented as actors/services.

Main entry points: [`KReader.py`](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py) (Frame capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Gesture controller"]
  node_capture["Frame capture<br/>[KReader.py]"]
  node_detect["Hand detection<br/>[KReader.py]"]
  node_gate["Index finger gate<br/>[KReader.py]"]
  node_measure["Finger distance<br/>[KReader.py]"]
  node_map["Brightness mapping<br/>[KReader.py]"]
  node_write["PWM output<br/>[KReader.py]"]
  node_overlay["Gesture overlay<br/>[KReader.py]"]
  node_display["Video display<br/>[KReader.py]"]
  node_shutdown["Shutdown<br/>[KReader.py]"]
end

subgraph group_external["External interfaces"]
  node_camera["Webcam"]
  node_opencv["OpenCV"]
  node_mediapipe["MediaPipe Hands"]
  node_pyfirmata["PyFirmata2"]
  node_arduino["Arduino PWM"]
end

node_user(("User gestures"))

node_user -->|"gestures in view"| node_camera
node_camera -->|"frames"| node_capture
node_capture -->|"reads frames"| node_opencv
node_capture -->|"passes RGB frame"| node_detect
node_detect -->|"processes frame"| node_mediapipe
node_detect -->|"landmarks"| node_gate
node_gate -->|"enables on index"| node_measure
node_measure -->|"distance"| node_map
node_map -->|"brightness value"| node_write
node_write -->|"writes pin"| node_pyfirmata
node_pyfirmata -->|"PWM signal"| node_arduino
node_detect -->|"draws landmarks"| node_overlay
node_measure -->|"draws finger span"| node_overlay
node_overlay -->|"annotated frame"| node_display
node_display -->|"shows video"| node_opencv
node_capture -->|"Q key exits loop"| node_shutdown
node_shutdown -->|"closes board"| node_arduino

click node_capture "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_detect "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_gate "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_measure "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_map "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_write "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_overlay "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_display "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py"
click node_shutdown "https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.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_capture,node_detect,node_gate,node_measure,node_map,node_write,node_overlay,node_display,node_shutdown,node_user toneBlue
class node_camera,node_opencv,node_mediapipe,node_pyfirmata,node_arduino toneAmber
```

## Components

### Gesture controller

- [Frame capture](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Hand detection](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Index finger gate](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Finger distance](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Brightness mapping](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [PWM output](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Gesture overlay](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Video display](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`
- [Shutdown](https://github.com/laith-kalfood/gesture-led-control/blob/main/KReader.py): `KReader.py`

### External interfaces

- **Webcam**
- **OpenCV**
- **MediaPipe Hands**
- **PyFirmata2**
- **Arduino PWM**

### Other components

- **User gestures**

## Connections

- User gestures → Webcam: gestures in view (evidence: `README.md`)
- Webcam → Frame capture: frames (evidence: `KReader.py`)
- Frame capture → OpenCV: reads frames (evidence: `KReader.py`)
- Frame capture → Hand detection: passes RGB frame (evidence: `KReader.py`)
- Hand detection → MediaPipe Hands: processes frame (evidence: `KReader.py`)
- Hand detection → Index finger gate: landmarks (evidence: `KReader.py`)
- Index finger gate → Finger distance: enables on index (evidence: `KReader.py`)
- Finger distance → Brightness mapping: distance (evidence: `KReader.py`)
- Brightness mapping → PWM output: brightness value (evidence: `KReader.py`)
- PWM output → PyFirmata2: writes pin (evidence: `KReader.py`)
- PyFirmata2 → Arduino PWM: PWM signal (evidence: `README.md`)
- Hand detection → Gesture overlay: draws landmarks (evidence: `KReader.py`)
- Finger distance → Gesture overlay: draws finger span (evidence: `KReader.py`)
- Gesture overlay → Video display: annotated frame (evidence: `KReader.py`)
- Video display → OpenCV: shows video (evidence: `KReader.py`)
- Frame capture → Shutdown: Q key exits loop (evidence: `KReader.py`)
- Shutdown → Arduino PWM: closes board (evidence: `KReader.py`)
