# jfasoltholmes/freehand architecture

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

- Interactive diagram: https://gitdiagram.com/jfasoltholmes/freehand
- Repository: https://github.com/jfasoltholmes/freehand

## Overview

FreeHand maps webcam hand motion to a 3D-printed robotic hand. The main workflow captures frames, detects landmarks, extracts normalized finger distances, maps them through per-finger calibration, and streams angles to firmware for servo actuation. The README also describes landmark visualization and mechanical assembly; the repository includes hand-part models. Python vision and mapping are concentrated in `main.py`, while firmware parsing and servo control are in `firmware/src/main.cpp`. Wiring follows the sampled code; mechanical behavior is described in the README, not implemented here.

Main entry points: [`main.py`](https://github.com/jfasoltholmes/freehand/blob/main/main.py) (Frame capture), [`firmware/src/main.cpp`](https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp) (Firmware receiver), [`hand_landmarker.task`](https://github.com/jfasoltholmes/freehand/blob/main/hand_landmarker.task) (Hand model), [`handfiles`](https://github.com/jfasoltholmes/freehand/tree/main/handfiles) (Hand components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision"]
  node_capture["Frame capture<br/>[main.py]"]
  node_detector["Landmark detector<br/>[main.py]"]
  node_model["Hand model"]
  node_snapshot["Landmark snapshot<br/>[main.py]"]
  node_visualization["Landmark display<br/>[main.py]"]
end

subgraph group_mapping["Mapping and transport"]
  node_extraction["Finger distances<br/>[main.py]"]
  node_calibration["Angle calibration<br/>[main.py]"]
  node_serial["Serial sender<br/>[main.py]"]
end

subgraph group_embedded["Embedded actuation"]
  node_firmware["Firmware receiver<br/>[main.cpp]"]
  node_parser["Angle parser<br/>[main.cpp]"]
  node_servo_control["Servo control<br/>[main.cpp]"]
end

subgraph group_mechanical["Mechanical hand"]
  node_hand_parts["Hand components"]
end

node_user(("Hand motion"))
node_webcam["Webcam"]
node_connection["USB serial"]
node_servos["Five servos"]
node_robotic_hand["Robotic hand"]

node_user -->|"moves before"| node_webcam
node_webcam -->|"supplies frames"| node_capture
node_capture -->|"submits frames"| node_detector
node_model -->|"configures"| node_detector
node_detector -->|"callback stores"| node_snapshot
node_capture -->|"reads"| node_snapshot
node_capture -->|"draws landmarks"| node_visualization
node_snapshot -->|"provides landmarks"| node_extraction
node_extraction -->|"provides distances"| node_calibration
node_calibration -->|"provides angles"| node_serial
node_serial -->|"writes angles"| node_connection
node_connection -->|"delivers line"| node_firmware
node_firmware -->|"parses input"| node_parser
node_firmware -->|"constrains and writes"| node_servo_control
node_parser -->|"returns angles"| node_servo_control
node_servo_control -->|"sets positions"| node_servos
node_servos -->|"actuates"| node_robotic_hand
node_hand_parts -.->|"forms structure"| node_robotic_hand

click node_capture "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_detector "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_model "https://github.com/jfasoltholmes/freehand/blob/main/hand_landmarker.task"
click node_snapshot "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_visualization "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_extraction "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_calibration "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_serial "https://github.com/jfasoltholmes/freehand/blob/main/main.py"
click node_firmware "https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp"
click node_parser "https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp"
click node_servo_control "https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp"
click node_hand_parts "https://github.com/jfasoltholmes/freehand/tree/main/handfiles"

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_detector,node_model,node_snapshot,node_visualization toneBlue
class node_extraction,node_calibration,node_serial toneAmber
class node_firmware,node_parser,node_servo_control toneMint
class node_hand_parts toneRose
class node_user,node_webcam,node_connection,node_servos,node_robotic_hand toneIndigo
```

## Components

### Vision

- [Frame capture](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`
- [Landmark detector](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`
- [Hand model](https://github.com/jfasoltholmes/freehand/blob/main/hand_landmarker.task): `hand_landmarker.task`
- [Landmark snapshot](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`
- [Landmark display](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`

### Mapping and transport

- [Finger distances](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`
- [Angle calibration](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`
- [Serial sender](https://github.com/jfasoltholmes/freehand/blob/main/main.py): `main.py`

### Embedded actuation

- [Firmware receiver](https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Angle parser](https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Servo control](https://github.com/jfasoltholmes/freehand/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`

### Mechanical hand

- [Hand components](https://github.com/jfasoltholmes/freehand/tree/main/handfiles): `handfiles`

### Other components

- **Hand motion**
- **Webcam**
- **USB serial**
- **Five servos**
- **Robotic hand**

## Connections

- Hand motion → Webcam: moves before
- Webcam → Frame capture: supplies frames
- Frame capture → Landmark detector: submits frames
- Hand model → Landmark detector: configures
- Landmark detector → Landmark snapshot: callback stores
- Frame capture → Landmark snapshot: reads
- Frame capture → Landmark display: draws landmarks
- Landmark snapshot → Finger distances: provides landmarks
- Finger distances → Angle calibration: provides distances
- Angle calibration → Serial sender: provides angles
- Serial sender → USB serial: writes angles
- USB serial → Firmware receiver: delivers line
- Firmware receiver → Angle parser: parses input
- Firmware receiver → Servo control: constrains and writes
- Angle parser → Servo control: returns angles
- Servo control → Five servos: sets positions
- Five servos → Robotic hand: actuates
- Hand components → Robotic hand: forms structure