# bhumishah265/single_pass_3d architecture

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

- Interactive diagram: https://gitdiagram.com/bhumishah265/single_pass_3d
- Repository: https://github.com/bhumishah265/single_pass_3d

## Overview

AeroSynth 3D turns a drone flight video, optionally paired with telemetry, into validated photogrammetry deliverables and a browser-inspectable 3D scene. The main workflow runs from upload or CLI invocation through frame processing, SfM, dense reconstruction, surface generation, georeferencing and analysis, then artifact validation and job/output viewing. The README documents key stages and exports; sampled excerpts confirm API job dispatch, frame extraction, masking, telemetry parsing, runtime validation and Studio model loading. Other stage wiring is represented only where README documentation supports it.

Main entry points: [`app/pipeline.py`](https://github.com/bhumishah265/single_pass_3d/blob/main/app/pipeline.py) (Pipeline coordinator), [`app/api/routes.py`](https://github.com/bhumishah265/single_pass_3d/blob/main/app/api/routes.py) (FastAPI routes), [`app/pipeline_runtime.py`](https://github.com/bhumishah265/single_pass_3d/blob/main/app/pipeline_runtime.py) (Artifact gate), [`frontend/app.js`](https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/app.js) (Web control room)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_web["Web control room<br/>[app.js]"]
  node_studio["3D Studio<br/>[studio.js]"]
  node_viewer["Browser scene<br/>[studio.js]"]
end

subgraph group_orchestration["Run orchestration"]
  node_cli["CLI and server<br/>[main.py]"]
  node_api["FastAPI routes<br/>[routes.py]"]
  node_jobstate[("Job state<br/>[routes.py]")]
  node_runtime["Artifact gate"]
  node_pipeline["Pipeline coordinator<br/>[pipeline.py]"]
end

subgraph group_reconstruction["Reconstruction stages"]
  node_video["Video extraction<br/>[extractor.py]"]
  node_quality["Quality filtering<br/>[quality.py]"]
  node_keyframes["Keyframe selection<br/>[frame_selector.py]"]
  node_masks["Dynamic masking<br/>[dynamic_objects.py]"]
  node_sfm["Structure from motion<br/>[colmap.py]"]
  node_mvs["Dense MVS<br/>[openmvs.py]"]
  node_mesh["Surface mesh<br/>[meshing.py]"]
  node_complete["Inferred complete surface"]
end

subgraph group_deliverables["Analysis and outputs"]
  node_telemetry["Telemetry parsing<br/>[gps.py]"]
  node_georef["Georeferencing<br/>[georeference.py]"]
  node_measure["Measurements<br/>[measurements.py]"]
  node_confidence["Confidence analysis<br/>[confidence.py]"]
  node_semantic["Semantic annotation<br/>[semantic.py]"]
  node_outputs[("Reconstruction artifacts")]
end

node_operator(("Operator"))

node_operator -->|"operates"| node_web
node_operator -->|"runs"| node_cli
node_web -->|"requests jobs"| node_api
node_api -->|"reads and writes"| node_jobstate
node_api -->|"dispatches run"| node_runtime
node_cli -->|"starts run"| node_runtime
node_runtime -->|"runs"| node_pipeline
node_pipeline -->|"extracts frames"| node_video
node_pipeline -->|"filters frames"| node_quality
node_pipeline -->|"selects frames"| node_keyframes
node_pipeline -.->|"generates masks"| node_masks
node_pipeline -->|"maps keyframes"| node_sfm
node_pipeline -->|"reconstructs dense"| node_mvs
node_pipeline -->|"builds surface"| node_mesh
node_pipeline -.->|"exports inferred model"| node_complete
node_pipeline -.->|"parses telemetry"| node_telemetry
node_pipeline -.->|"georeferences scene"| node_georef
node_pipeline -->|"measures scene"| node_measure
node_pipeline -->|"evaluates quality"| node_confidence
node_pipeline -.->|"annotates points"| node_semantic
node_runtime -->|"validates and writes"| node_outputs
node_api -->|"serves deliverables"| node_outputs
node_web -->|"loads jobs"| node_api
node_studio -->|"loads job data"| node_api
node_studio -->|"renders models"| node_viewer
node_outputs -->|"provides model files"| node_viewer

click node_cli "https://github.com/bhumishah265/single_pass_3d/blob/main/app/main.py"
click node_web "https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/app.js"
click node_studio "https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/studio.js"
click node_api "https://github.com/bhumishah265/single_pass_3d/blob/main/app/api/routes.py"
click node_jobstate "https://github.com/bhumishah265/single_pass_3d/blob/main/app/api/routes.py"
click node_runtime "https://github.com/bhumishah265/single_pass_3d/blob/main/app/pipeline_runtime.py"
click node_pipeline "https://github.com/bhumishah265/single_pass_3d/blob/main/app/pipeline.py"
click node_video "https://github.com/bhumishah265/single_pass_3d/blob/main/app/video/extractor.py"
click node_quality "https://github.com/bhumishah265/single_pass_3d/blob/main/app/preprocessing/quality.py"
click node_keyframes "https://github.com/bhumishah265/single_pass_3d/blob/main/app/video/frame_selector.py"
click node_masks "https://github.com/bhumishah265/single_pass_3d/blob/main/app/preprocessing/dynamic_objects.py"
click node_sfm "https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/colmap.py"
click node_mvs "https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/openmvs.py"
click node_mesh "https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/meshing.py"
click node_complete "https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/estimated_surface.py"
click node_telemetry "https://github.com/bhumishah265/single_pass_3d/blob/main/app/geospatial/gps.py"
click node_georef "https://github.com/bhumishah265/single_pass_3d/blob/main/app/geospatial/georeference.py"
click node_measure "https://github.com/bhumishah265/single_pass_3d/blob/main/app/analysis/measurements.py"
click node_confidence "https://github.com/bhumishah265/single_pass_3d/blob/main/app/analysis/confidence.py"
click node_semantic "https://github.com/bhumishah265/single_pass_3d/blob/main/app/analysis/semantic.py"
click node_outputs "https://github.com/bhumishah265/single_pass_3d/tree/main/data/output"
click node_viewer "https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/studio.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_web,node_studio,node_viewer toneBlue
class node_cli,node_api,node_jobstate,node_runtime,node_pipeline toneAmber
class node_video,node_quality,node_keyframes,node_masks,node_sfm,node_mvs,node_mesh,node_complete toneMint
class node_telemetry,node_georef,node_measure,node_confidence,node_semantic,node_outputs toneRose
class node_operator toneIndigo
```

## Components

### User interface

- [Web control room](https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/app.js): `frontend/app.js`
- [3D Studio](https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/studio.js): `frontend/studio.js`
- [Browser scene](https://github.com/bhumishah265/single_pass_3d/blob/main/frontend/studio.js): `frontend/studio.js`

### Run orchestration

- [CLI and server](https://github.com/bhumishah265/single_pass_3d/blob/main/app/main.py): `app/main.py`
- [FastAPI routes](https://github.com/bhumishah265/single_pass_3d/blob/main/app/api/routes.py): `app/api/routes.py`
- [Job state](https://github.com/bhumishah265/single_pass_3d/blob/main/app/api/routes.py): `app/api/routes.py`
- [Artifact gate](https://github.com/bhumishah265/single_pass_3d/blob/main/app/pipeline_runtime.py): `app/pipeline_runtime.py`
- [Pipeline coordinator](https://github.com/bhumishah265/single_pass_3d/blob/main/app/pipeline.py): `app/pipeline.py`

### Reconstruction stages

- [Video extraction](https://github.com/bhumishah265/single_pass_3d/blob/main/app/video/extractor.py): `app/video/extractor.py`
- [Quality filtering](https://github.com/bhumishah265/single_pass_3d/blob/main/app/preprocessing/quality.py): `app/preprocessing/quality.py`
- [Keyframe selection](https://github.com/bhumishah265/single_pass_3d/blob/main/app/video/frame_selector.py): `app/video/frame_selector.py`
- [Dynamic masking](https://github.com/bhumishah265/single_pass_3d/blob/main/app/preprocessing/dynamic_objects.py): `app/preprocessing/dynamic_objects.py`
- [Structure from motion](https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/colmap.py): `app/reconstruction/colmap.py`
- [Dense MVS](https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/openmvs.py): `app/reconstruction/openmvs.py`
- [Surface mesh](https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/meshing.py): `app/reconstruction/meshing.py`
- [Inferred complete surface](https://github.com/bhumishah265/single_pass_3d/blob/main/app/reconstruction/estimated_surface.py): `app/reconstruction/estimated_surface.py`

### Analysis and outputs

- [Telemetry parsing](https://github.com/bhumishah265/single_pass_3d/blob/main/app/geospatial/gps.py): `app/geospatial/gps.py`
- [Georeferencing](https://github.com/bhumishah265/single_pass_3d/blob/main/app/geospatial/georeference.py): `app/geospatial/georeference.py`
- [Measurements](https://github.com/bhumishah265/single_pass_3d/blob/main/app/analysis/measurements.py): `app/analysis/measurements.py`
- [Confidence analysis](https://github.com/bhumishah265/single_pass_3d/blob/main/app/analysis/confidence.py): `app/analysis/confidence.py`
- [Semantic annotation](https://github.com/bhumishah265/single_pass_3d/blob/main/app/analysis/semantic.py): `app/analysis/semantic.py`
- [Reconstruction artifacts](https://github.com/bhumishah265/single_pass_3d/tree/main/data/output): `data/output`

### Other components

- **Operator**

## Connections

- Operator → Web control room: operates
- Operator → CLI and server: runs
- Web control room → FastAPI routes: requests jobs
- FastAPI routes → Job state: reads and writes
- FastAPI routes → Artifact gate: dispatches run
- CLI and server → Artifact gate: starts run
- Artifact gate → Pipeline coordinator: runs
- Pipeline coordinator → Video extraction: extracts frames
- Pipeline coordinator → Quality filtering: filters frames
- Pipeline coordinator → Keyframe selection: selects frames
- Pipeline coordinator → Dynamic masking: generates masks
- Pipeline coordinator → Structure from motion: maps keyframes
- Pipeline coordinator → Dense MVS: reconstructs dense
- Pipeline coordinator → Surface mesh: builds surface
- Pipeline coordinator → Inferred complete surface: exports inferred model
- Pipeline coordinator → Telemetry parsing: parses telemetry
- Pipeline coordinator → Georeferencing: georeferences scene
- Pipeline coordinator → Measurements: measures scene
- Pipeline coordinator → Confidence analysis: evaluates quality
- Pipeline coordinator → Semantic annotation: annotates points
- Artifact gate → Reconstruction artifacts: validates and writes
- FastAPI routes → Reconstruction artifacts: serves deliverables
- Web control room → FastAPI routes: loads jobs
- 3D Studio → FastAPI routes: loads job data
- 3D Studio → Browser scene: renders models
- Reconstruction artifacts → Browser scene: provides model files