# cupidbity/spiderlily architecture

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

- Interactive diagram: https://gitdiagram.com/cupidbity/spiderlily
- Repository: https://github.com/cupidbity/spiderlily

## Overview

#### Purpose
Spiderlily is an interactive audiovisual artwork driven by webcam hand gestures. It provides two independent runtimes: a browser-based 3D visualiser and the original TouchDesigner performance project.

#### Entry Points
- Browser runtime: `spiderlily-web/index.html`, served over HTTP(S) so camera access and MediaPipe tracking work.
- TouchDesigner runtime: `InteractiveFlower.43.toe`, opened and run inside TouchDesigner.
- Runtime-specific operation details are documented in `README.md` and `spiderlily-web/README.md`.

#### Web Visualisation Pipeline
`spiderlily-web/index.html` is a self-contained application with no build pipeline. It loads Three.js and MediaPipe from CDNs, requests webcam input, derives hand gesture state, and renders the flower scene plus a camera/tracking HUD. Browser controls support camera orbit/zoom, HUD visibility, and a debug auto-bloom mode.

#### Gesture-to-Plant Control Boundary
Both implementations share the same interaction model: the left hand controls plant growth and the right hand controls flower blooming; pinch/spread state is the primary continuous gesture signal. Webcam permissions, browser camera APIs, and MediaPipe hand tracking are external boundaries for the web path. `spiderlily-web/index.html` owns the translation from tracking output to visual parameters.

#### TouchDesigner Composition
`InteractiveFlower.43.toe` contains the original editable TouchDesigner network and is the primary composition/rendering entry point for that runtime. It depends on reusable MediaPipe-oriented TouchDesigner components under `toxes/`, notably `toxes/hand_tracking.tox`, `toxes/face_tracking.tox`, and `toxes/pose_tracking.tox`. The project is intended for live webcam-driven playback or performance rather than a compiled deployment.

#### Tracking Assets and External Dependency
The repository includes task-specific tracking/tox assets such as `toxes/hand_tracking.tox`, `toxes/object_tracking.tox`, and `toxes/image_classification.tox`. The TouchDesigner route additionally requires a separately downloaded `MediaPipe.tox` engine placed beside them; this is not committed due to its size. Thus the key infrastructure split is browser CDN dependencies for the web experience versus TouchDesigner plus local tox/plugin dependencies for the original piece.

Main entry points: [`InteractiveFlower.43.toe`](https://github.com/cupidbity/spiderlily/blob/main/InteractiveFlower.43.toe) (Interactive flower project), [`spiderlily-web/index.html`](https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html) (Flower scene), [`toxes/hand_tracking.tox`](https://github.com/cupidbity/spiderlily/blob/main/toxes/hand_tracking.tox) (Hand tracking component), [`README.md`](https://github.com/cupidbity/spiderlily/blob/main/README.md) (Runtime documentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser runtime"]
  node_web_entry["Web app entry<br/>HTML application<br/>[index.html]"]
  node_web_gesture["Gesture translation<br/>interaction layer<br/>[index.html]"]
  node_web_scene["Flower scene<br/>Three.js scene<br/>[index.html]"]
  node_web_hud["Camera and tracking HUD<br/>UI overlay<br/>[index.html]"]
  node_web_controls["Viewer controls<br/>browser controls<br/>[index.html]"]
end

subgraph group_td["TouchDesigner runtime"]
  node_td_project["Interactive flower project<br/>TouchDesigner composition"]
  node_td_webcam(("Live webcam input<br/>capture source"))
  node_td_hand["Hand tracking component<br/>TouchDesigner tox<br/>[hand_tracking.tox]"]
  node_td_face["Face tracking component<br/>TouchDesigner tox<br/>[face_tracking.tox]"]
  node_td_pose["Pose tracking component<br/>TouchDesigner tox<br/>[pose_tracking.tox]"]
  node_td_assets["Other tracking assets<br/>TouchDesigner tox assets"]
end

subgraph group_external["External dependencies"]
  node_web_camera(("Webcam input<br/>browser API"))
  node_web_tracking{{"Hand tracking<br/>MediaPipe CDN"}}
  node_three{{"Three.js CDN<br/>rendering library"}}
  node_td_mediapipe{{"MediaPipe engine<br/>local TouchDesigner tox"}}
end

node_docs["Runtime documentation<br/>README files<br/>[README.md]"]

node_web_camera -->|"camera frames"| node_web_entry
node_web_entry -->|"submits frames"| node_web_tracking
node_web_tracking -->|"hand landmarks"| node_web_gesture
node_web_gesture -->|"growth and bloom parameters"| node_web_scene
node_three -->|"rendering"| node_web_scene
node_web_scene -->|"tracking display"| node_web_hud
node_web_controls -->|"camera and debug settings"| node_web_scene
node_td_webcam -->|"live video"| node_td_project
node_td_project -->|"uses"| node_td_hand
node_td_project -.->|"uses"| node_td_face
node_td_project -.->|"uses"| node_td_pose
node_td_project -.->|"can use"| node_td_assets
node_td_mediapipe -->|"tracking engine"| node_td_hand
node_td_hand -->|"hand gesture data"| node_td_project
node_docs -.->|"web operation"| node_web_entry
node_docs -.->|"performance operation"| node_td_project

click node_web_entry "https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html"
click node_web_gesture "https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html"
click node_web_scene "https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html"
click node_web_hud "https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html"
click node_web_controls "https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html"
click node_td_project "https://github.com/cupidbity/spiderlily/blob/main/InteractiveFlower.43.toe"
click node_td_hand "https://github.com/cupidbity/spiderlily/blob/main/toxes/hand_tracking.tox"
click node_td_face "https://github.com/cupidbity/spiderlily/blob/main/toxes/face_tracking.tox"
click node_td_pose "https://github.com/cupidbity/spiderlily/blob/main/toxes/pose_tracking.tox"
click node_td_assets "https://github.com/cupidbity/spiderlily/blob/main/toxes/object_tracking.tox"
click node_docs "https://github.com/cupidbity/spiderlily/blob/main/README.md"

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_web_entry,node_web_gesture,node_web_scene,node_web_hud,node_web_controls toneBlue
class node_td_project,node_td_webcam,node_td_hand,node_td_face,node_td_pose,node_td_assets toneAmber
class node_web_camera,node_web_tracking,node_three,node_td_mediapipe toneMint
class node_docs toneNeutral
```

## Components

### Browser runtime

- [Web app entry](https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html): HTML application · Self-contained browser visualiser. · `spiderlily-web/index.html`
- [Gesture translation](https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html): interaction layer · Maps left growth and right bloom gestures to visual parameters. · `spiderlily-web/index.html`
- [Flower scene](https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html): Three.js scene · Renders the reactive 3D plant. · `spiderlily-web/index.html`
- [Camera and tracking HUD](https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html): UI overlay · `spiderlily-web/index.html`
- [Viewer controls](https://github.com/cupidbity/spiderlily/blob/main/spiderlily-web/index.html): browser controls · Orbit, zoom, HUD, and auto-bloom controls. · `spiderlily-web/index.html`

### TouchDesigner runtime

- [Interactive flower project](https://github.com/cupidbity/spiderlily/blob/main/InteractiveFlower.43.toe): TouchDesigner composition · Primary editable performance and rendering network. · `InteractiveFlower.43.toe`
- **Live webcam input**: capture source
- [Hand tracking component](https://github.com/cupidbity/spiderlily/blob/main/toxes/hand_tracking.tox): TouchDesigner tox · `toxes/hand_tracking.tox`
- [Face tracking component](https://github.com/cupidbity/spiderlily/blob/main/toxes/face_tracking.tox): TouchDesigner tox · `toxes/face_tracking.tox`
- [Pose tracking component](https://github.com/cupidbity/spiderlily/blob/main/toxes/pose_tracking.tox): TouchDesigner tox · `toxes/pose_tracking.tox`
- [Other tracking assets](https://github.com/cupidbity/spiderlily/blob/main/toxes/object_tracking.tox): TouchDesigner tox assets · Includes object tracking and image classification components. · `toxes/object_tracking.tox`

### External dependencies

- **Webcam input**: browser API
- **Hand tracking**: MediaPipe CDN · Produces hand landmarks and gesture state.
- **Three.js CDN**: rendering library
- **MediaPipe engine**: local TouchDesigner tox · Separately downloaded dependency placed beside repository toxes.

### Other components

- [Runtime documentation](https://github.com/cupidbity/spiderlily/blob/main/README.md): README files · Documents web serving and TouchDesigner operation. · `README.md`

## Connections

- Webcam input → Web app entry: camera frames
- Web app entry → Hand tracking: submits frames
- Hand tracking → Gesture translation: hand landmarks
- Gesture translation → Flower scene: growth and bloom parameters
- Three.js CDN → Flower scene: rendering
- Flower scene → Camera and tracking HUD: tracking display
- Viewer controls → Flower scene: camera and debug settings
- Live webcam input → Interactive flower project: live video
- Interactive flower project → Hand tracking component: uses
- Interactive flower project → Face tracking component: uses
- Interactive flower project → Pose tracking component: uses
- Interactive flower project → Other tracking assets: can use
- MediaPipe engine → Hand tracking component: tracking engine
- Hand tracking component → Interactive flower project: hand gesture data
- Runtime documentation → Web app entry: web operation
- Runtime documentation → Interactive flower project: performance operation