# siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay architecture

> Architecture diagram of the GitHub repository siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay
- Repository: https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay

## Overview

VEDHARPAN combines a webcam-based vision and telemetry backend with a desktop overlay hosting a Three.js 3D diorama. The backend captures and filters tracking data, places frames on a queue, and broadcasts them over WebSockets; the desktop app embeds the frontend. The frontend’s scene coordinates input, physics, effects, settings, and the mecha controller. The README describes vision-to-overlay integration as a roadmap item, and the excerpts do not show a frontend telemetry connection, so that relationship remains unverified.

Main entry points: [`frontend/js/scene.js`](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/scene.js) (Diorama scene), [`main.py`](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py) (Lifecycle controller), [`core/vision_pipeline.py`](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/core/vision_pipeline.py) (Vision pipeline), [`frontend/js/input_manager.js`](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/input_manager.js) (Input manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Vision and telemetry"]
  node_vision["Vision pipeline<br/>[vision_pipeline.py]"]
  node_frames["Telemetry queue<br/>[main.py]"]
  node_broker["WebSocket broker<br/>[main.py]"]
  node_app["Lifecycle controller<br/>[main.py]"]
end

subgraph group_desktop["Desktop presentation"]
  node_overlay["Transparent overlay<br/>[gui_overlay.py]"]
end

subgraph group_frontend["3D experience"]
  node_html["Frontend entry page<br/>[index.html]"]
  node_assets["3D assets"]
end

subgraph group_runtime["Scene systems"]
  node_scene["Diorama scene<br/>[scene.js]"]
  node_input["Input manager<br/>[input_manager.js]"]
  node_physics["Physics world<br/>[physics_world.js]"]
  node_effects["Visual effects<br/>[effects.js]"]
  node_mecha["Mecha controller"]
  node_settings["Settings manager<br/>[settings.js]"]
end

node_user(("Desktop user"))
node_camera(("Webcam"))

node_user -->|"provides video"| node_camera
node_camera -->|"captures frames"| node_vision
node_app -->|"starts pipeline"| node_vision
node_vision -->|"enqueues telemetry"| node_frames
node_app -->|"starts broker"| node_broker
node_broker -->|"reads frames"| node_frames
node_app -.->|"launches overlay"| node_overlay
node_overlay -->|"loads page"| node_html
node_html -->|"starts scene"| node_scene
node_scene -->|"loads models"| node_assets
node_scene -->|"creates input"| node_input
node_scene -->|"creates physics"| node_physics
node_scene -->|"creates effects"| node_effects
node_scene -->|"creates controller"| node_mecha
node_scene -->|"uses settings"| node_settings
node_user -->|"provides controls"| node_input
node_broker -.->|"sends tracking data"| node_input

click node_vision "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/core/vision_pipeline.py"
click node_frames "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py"
click node_broker "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py"
click node_app "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py"
click node_overlay "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/core/gui_overlay.py"
click node_html "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/index.html"
click node_scene "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/scene.js"
click node_assets "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/tree/main/frontend/assets"
click node_input "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/input_manager.js"
click node_physics "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/physics_world.js"
click node_effects "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/effects.js"
click node_mecha "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/mecha_controller.js"
click node_settings "https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/settings.js"

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_vision,node_frames,node_broker,node_app,node_user toneBlue
class node_overlay toneAmber
class node_html,node_assets toneMint
class node_scene,node_input,node_physics,node_effects,node_mecha,node_settings toneRose
class node_camera toneIndigo
```

## Components

### Vision and telemetry

- [Vision pipeline](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/core/vision_pipeline.py): `core/vision_pipeline.py`
- [Telemetry queue](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py): `main.py`
- [WebSocket broker](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py): `main.py`
- [Lifecycle controller](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/main.py): `main.py`

### Desktop presentation

- [Transparent overlay](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/core/gui_overlay.py): `core/gui_overlay.py`

### 3D experience

- [Frontend entry page](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/index.html): `frontend/index.html`
- [3D assets](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/tree/main/frontend/assets): `frontend/assets`

### Scene systems

- [Diorama scene](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/scene.js): `frontend/js/scene.js`
- [Input manager](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/input_manager.js): `frontend/js/input_manager.js`
- [Physics world](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/physics_world.js): `frontend/js/physics_world.js`
- [Visual effects](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/effects.js): `frontend/js/effects.js`
- [Mecha controller](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/mecha_controller.js): `frontend/js/mecha_controller.js`
- [Settings manager](https://github.com/siddeshkhandekar/vedharpan___real-time-3d-spatial-tracking-depth-overlay/blob/main/frontend/js/settings.js): `frontend/js/settings.js`

### Other components

- **Desktop user**
- **Webcam**

## Connections

- Desktop user → Webcam: provides video (evidence: `README.md`)
- Webcam → Vision pipeline: captures frames (evidence: `README.md`)
- Lifecycle controller → Vision pipeline: starts pipeline (evidence: `main.py`)
- Vision pipeline → Telemetry queue: enqueues telemetry (evidence: `core/vision_pipeline.py`)
- Lifecycle controller → WebSocket broker: starts broker (evidence: `main.py`)
- WebSocket broker → Telemetry queue: reads frames (evidence: `main.py`)
- Lifecycle controller → Transparent overlay: launches overlay (evidence: `main.py`)
- Transparent overlay → Frontend entry page: loads page (evidence: `core/gui_overlay.py`)
- Frontend entry page → Diorama scene: starts scene (evidence: `frontend/js/scene.js`)
- Diorama scene → 3D assets: loads models (evidence: `frontend/js/scene.js`)
- Diorama scene → Input manager: creates input (evidence: `frontend/js/scene.js`)
- Diorama scene → Physics world: creates physics (evidence: `frontend/js/scene.js`)
- Diorama scene → Visual effects: creates effects (evidence: `frontend/js/scene.js`)
- Diorama scene → Mecha controller: creates controller (evidence: `frontend/js/scene.js`)
- Diorama scene → Settings manager: uses settings (evidence: `frontend/js/scene.js`)
- Desktop user → Input manager: provides controls (evidence: `frontend/js/input_manager.js`)
- WebSocket broker → Input manager: sends tracking data
