# klischa/astra2 architecture

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

- Interactive diagram: https://gitdiagram.com/klischa/astra2
- Repository: https://github.com/klischa/astra2

## Overview

#### Purpose and entry points
AstraScanner2 is a Windows C++17 desktop application for RGB-D 3D scanning, point-cloud processing, mesh reconstruction, multi-scan registration, and file export. The executable is assembled by CMake at `CMakeLists.txt`; application startup is `src/main.cpp`, which creates the Qt UI shell in `src/gui/MainWindow.cpp`.

#### UI orchestration layer
Qt6 UI is intentionally thin: binders assemble tab/menu/status widgets while controllers own user workflows, state transitions, and asynchronous orchestration. `src/gui/MainWindow.cpp` connects the shell to `src/controllers/ProjectUiController.cpp`, `src/controllers/CaptureSessionController.cpp`, and `src/controllers/ProcessingController.cpp`. `src/controllers/ViewerCoordinator.cpp` coordinates main and processing visualizations and switches cloud/mesh displays.

#### Capture and scan-session pipeline
A scan session starts through `CaptureSessionController`, which manages a worker/thread boundary around `src/capture/CaptureWorker.cpp`. The worker acquires RGB/depth frames through `src/capture/AstraCamera.cpp`, using OpenNI2 for an Orbbec Astra Pro when available or synthetic emulation otherwise; depth is converted to point-cloud data via `src/capture/DepthCloudConverter.h`. `src/controllers/ScanWorkflow.cpp` and `src/controllers/TurntableController.cpp` coordinate manual and timed turntable scan flows.

#### Pose and coverage tracking
Captured frames feed one of two pose-estimation paths. Marker tracking is defined behind `src/marker_tracker/IMarkerDetector.h`; `src/marker_tracker/MarkerTracker.cpp` selects CCTag/circular detection and uses `src/marker_tracker/MarkerMap.cpp` to derive object pose from known markers. Neural tracking uses the bundled ONNX model at `models/pose_regressor.onnx`, executed by `src/tracking/NeuralTracker.cpp` and coordinated/validated in `src/tracking/NeuralTrackingPipeline.cpp`. `src/tracking/SurfelCoverageTracker.cpp` evaluates scan coverage/quality. Neural inference can use ONNX Runtime CUDA execution, with guard logic in `src/tracking/NeuralTrackingGuards.cpp`.

#### Processing and reconstruction services
`ProcessingController` delegates computational work to services rather than UI code. `src/services/CloudFiltersService.cpp` performs cloud cleanup; the compatibility/filter facade is `src/filters/PointCloudFilters.cpp`. CUDA-specific implementations and wrappers are isolated in `src/filters/PointCloudFiltersCUDA.cu` and `src/filters/PointCloudFiltersCUDA_wrapper.cpp`, with CPU PCL fallback. `src/services/RegistrationService.cpp` performs ICP-based scan alignment/merging. `src/services/ReconstructionService.cpp` produces Poisson meshes, and `src/services/MeshProcessingService.cpp` handles smoothing, decimation, and hole filling.

#### Persistence and output boundary
`src/project/ProjectManager.cpp` owns project lifecycle and durable metadata/cloud state, separating workspace persistence from processing. `src/export/ExportManager.cpp` is the outward format boundary for PLY, PCD, STL, and OBJ. Application-wide operational settings, including capture/filter/tracking parameters, are centralized in `src/settings/SettingsManager.cpp`; marker-disk configuration is supplied at `data/marker_disk_config.json`.

#### Runtime and infrastructure
The native runtime combines Qt6, PCL, VTK/OpenGL visualization, OpenCV, CCTag, Eigen, and ONNX Runtime, declared and linked via `CMakeLists.txt` and `vcpkg.json`. CUDA is optional and targets NVIDIA GPUs; OpenNI2 is optional hardware infrastructure for Astra Pro. Deployment must include Qt plugins, vcpkg/OpenNI2/ONNX DLLs, model assets, and `data/`, as configured by the build system.

Main entry points: [`src/controllers/ProcessingController.cpp`](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ProcessingController.cpp) (Processing controller), [`src/gui/MainWindow.cpp`](https://github.com/klischa/astra2/blob/klischa-patch/src/gui/MainWindow.cpp) (Qt UI shell), [`src/controllers/CaptureSessionController.cpp`](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/CaptureSessionController.cpp) (Capture session controller), [`src/tracking/NeuralTrackingPipeline.cpp`](https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/NeuralTrackingPipeline.cpp) (Neural tracking pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_build["CMake build<br/>build manifest<br/>[CMakeLists.txt]"]
  node_main["Application startup<br/>C++ entry point<br/>[main.cpp]"]
end

subgraph group_ui["UI &amp; Workflows"]
  node_main_window["Qt UI shell<br/>Qt window<br/>[MainWindow.cpp]"]
  node_project_ui["Project UI controller<br/>workflow controller"]
  node_capture_controller["Capture session controller<br/>workflow controller"]
  node_processing_controller["Processing controller<br/>workflow controller"]
  node_viewer["Viewer coordinator<br/>visualization coordinator"]
end

subgraph group_capture["Capture &amp; Tracking"]
  node_scan_workflow["Scan &amp; turntable workflows<br/>scan workflow<br/>[ScanWorkflow.cpp]"]
  node_capture_worker["Capture worker<br/>threaded worker<br/>[CaptureWorker.cpp]"]
  node_astra_camera["Astra camera<br/>camera adapter<br/>[AstraCamera.cpp]"]
  node_depth_converter["Depth-to-cloud converter<br/>cloud conversion"]
  node_marker_tracker["Marker pose tracking<br/>pose estimator<br/>[MarkerTracker.cpp]"]
  node_neural_pipeline["Neural tracking pipeline<br/>pose pipeline"]
  node_neural_tracker["Neural tracker<br/>ONNX inference<br/>[NeuralTracker.cpp]"]
  node_coverage["Surfel coverage tracker<br/>quality tracker"]
end

subgraph group_processing["Processing"]
  node_filters["Cloud filtering<br/>processing service"]
  node_registration["Registration service<br/>ICP alignment"]
  node_reconstruction["Reconstruction service<br/>Poisson meshing"]
  node_mesh_processing["Mesh processing<br/>mesh service"]
end

subgraph group_data["Persistence &amp; Output"]
  node_project_manager[("Project manager<br/>workspace persistence<br/>[ProjectManager.cpp]")]
  node_export_manager["Export manager<br/>format boundary<br/>[ExportManager.cpp]"]
  node_settings["Settings manager<br/>application settings"]
end

node_build -->|"builds"| node_main
node_main -->|"creates"| node_main_window
node_main_window -->|"binds"| node_project_ui
node_main_window -->|"binds"| node_capture_controller
node_main_window -->|"binds"| node_processing_controller
node_main_window -->|"binds"| node_viewer
node_project_ui -->|"manages projects"| node_project_manager
node_capture_controller -->|"dispatches"| node_capture_worker
node_capture_controller -->|"drives"| node_scan_workflow
node_capture_worker -->|"acquires frames"| node_astra_camera
node_astra_camera -->|"supplies depth"| node_depth_converter
node_depth_converter -->|"cloud frames"| node_marker_tracker
node_depth_converter -->|"cloud frames"| node_neural_pipeline
node_neural_pipeline -->|"runs inference"| node_neural_tracker
node_marker_tracker -->|"pose updates"| node_coverage
node_neural_pipeline -->|"pose updates"| node_coverage
node_capture_controller -->|"stores captures"| node_project_manager
node_processing_controller -->|"cleans clouds"| node_filters
node_processing_controller -->|"aligns scans"| node_registration
node_processing_controller -->|"reconstructs mesh"| node_reconstruction
node_reconstruction -->|"produces mesh"| node_mesh_processing
node_processing_controller -->|"reads and persists assets"| node_project_manager
node_processing_controller -->|"exports results"| node_export_manager
node_processing_controller -->|"updates displays"| node_viewer
node_settings -.->|"capture parameters"| node_capture_controller
node_settings -.->|"processing parameters"| node_processing_controller
node_settings -.->|"tracking parameters"| node_neural_pipeline

click node_build "https://github.com/klischa/astra2/blob/klischa-patch/CMakeLists.txt"
click node_main "https://github.com/klischa/astra2/blob/klischa-patch/src/main.cpp"
click node_main_window "https://github.com/klischa/astra2/blob/klischa-patch/src/gui/MainWindow.cpp"
click node_project_ui "https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ProjectUiController.cpp"
click node_capture_controller "https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/CaptureSessionController.cpp"
click node_processing_controller "https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ProcessingController.cpp"
click node_viewer "https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ViewerCoordinator.cpp"
click node_scan_workflow "https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ScanWorkflow.cpp"
click node_capture_worker "https://github.com/klischa/astra2/blob/klischa-patch/src/capture/CaptureWorker.cpp"
click node_astra_camera "https://github.com/klischa/astra2/blob/klischa-patch/src/capture/AstraCamera.cpp"
click node_depth_converter "https://github.com/klischa/astra2/blob/klischa-patch/src/capture/DepthCloudConverter.h"
click node_marker_tracker "https://github.com/klischa/astra2/blob/klischa-patch/src/marker_tracker/MarkerTracker.cpp"
click node_neural_pipeline "https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/NeuralTrackingPipeline.cpp"
click node_neural_tracker "https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/NeuralTracker.cpp"
click node_coverage "https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/SurfelCoverageTracker.cpp"
click node_filters "https://github.com/klischa/astra2/blob/klischa-patch/src/services/CloudFiltersService.cpp"
click node_registration "https://github.com/klischa/astra2/blob/klischa-patch/src/services/RegistrationService.cpp"
click node_reconstruction "https://github.com/klischa/astra2/blob/klischa-patch/src/services/ReconstructionService.cpp"
click node_mesh_processing "https://github.com/klischa/astra2/blob/klischa-patch/src/services/MeshProcessingService.cpp"
click node_project_manager "https://github.com/klischa/astra2/blob/klischa-patch/src/project/ProjectManager.cpp"
click node_export_manager "https://github.com/klischa/astra2/blob/klischa-patch/src/export/ExportManager.cpp"
click node_settings "https://github.com/klischa/astra2/blob/klischa-patch/src/settings/SettingsManager.cpp"

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_build,node_main toneBlue
class node_main_window,node_project_ui,node_capture_controller,node_processing_controller,node_viewer toneAmber
class node_scan_workflow,node_capture_worker,node_astra_camera,node_depth_converter,node_marker_tracker,node_neural_pipeline,node_neural_tracker,node_coverage toneMint
class node_filters,node_registration,node_reconstruction,node_mesh_processing toneRose
class node_project_manager,node_export_manager,node_settings toneIndigo
```

## Components

### Application

- [CMake build](https://github.com/klischa/astra2/blob/klischa-patch/CMakeLists.txt): build manifest · Assembles the executable and declares native dependencies. · `CMakeLists.txt`
- [Application startup](https://github.com/klischa/astra2/blob/klischa-patch/src/main.cpp): C++ entry point · `src/main.cpp`

### UI & Workflows

- [Qt UI shell](https://github.com/klischa/astra2/blob/klischa-patch/src/gui/MainWindow.cpp): Qt window · Thin widget, menu, tab, and status binder layer. · `src/gui/MainWindow.cpp`
- [Project UI controller](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ProjectUiController.cpp): workflow controller · `src/controllers/ProjectUiController.cpp`
- [Capture session controller](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/CaptureSessionController.cpp): workflow controller · Owns asynchronous capture-session orchestration. · `src/controllers/CaptureSessionController.cpp`
- [Processing controller](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ProcessingController.cpp): workflow controller · `src/controllers/ProcessingController.cpp`
- [Viewer coordinator](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ViewerCoordinator.cpp): visualization coordinator · Coordinates main and processing cloud/mesh displays. · `src/controllers/ViewerCoordinator.cpp`

### Capture & Tracking

- [Scan & turntable workflows](https://github.com/klischa/astra2/blob/klischa-patch/src/controllers/ScanWorkflow.cpp): scan workflow · Coordinates manual and timed turntable scans. · `src/controllers/ScanWorkflow.cpp`
- [Capture worker](https://github.com/klischa/astra2/blob/klischa-patch/src/capture/CaptureWorker.cpp): threaded worker · Runs acquisition outside the UI thread. · `src/capture/CaptureWorker.cpp`
- [Astra camera](https://github.com/klischa/astra2/blob/klischa-patch/src/capture/AstraCamera.cpp): camera adapter · Uses OpenNI2 hardware when available or synthetic emulation. · `src/capture/AstraCamera.cpp`
- [Depth-to-cloud converter](https://github.com/klischa/astra2/blob/klischa-patch/src/capture/DepthCloudConverter.h): cloud conversion · `src/capture/DepthCloudConverter.h`
- [Marker pose tracking](https://github.com/klischa/astra2/blob/klischa-patch/src/marker_tracker/MarkerTracker.cpp): pose estimator · Selects circular/CCTag detection and derives pose from known markers. · `src/marker_tracker/MarkerTracker.cpp`
- [Neural tracking pipeline](https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/NeuralTrackingPipeline.cpp): pose pipeline · Coordinates and validates ONNX pose inference. · `src/tracking/NeuralTrackingPipeline.cpp`
- [Neural tracker](https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/NeuralTracker.cpp): ONNX inference · `src/tracking/NeuralTracker.cpp`
- [Surfel coverage tracker](https://github.com/klischa/astra2/blob/klischa-patch/src/tracking/SurfelCoverageTracker.cpp): quality tracker · `src/tracking/SurfelCoverageTracker.cpp`

### Processing

- [Cloud filtering](https://github.com/klischa/astra2/blob/klischa-patch/src/services/CloudFiltersService.cpp): processing service · Uses CUDA filters when available, with CPU PCL fallback. · `src/services/CloudFiltersService.cpp`
- [Registration service](https://github.com/klischa/astra2/blob/klischa-patch/src/services/RegistrationService.cpp): ICP alignment · Aligns and merges scans. · `src/services/RegistrationService.cpp`
- [Reconstruction service](https://github.com/klischa/astra2/blob/klischa-patch/src/services/ReconstructionService.cpp): Poisson meshing · `src/services/ReconstructionService.cpp`
- [Mesh processing](https://github.com/klischa/astra2/blob/klischa-patch/src/services/MeshProcessingService.cpp): mesh service · Smooths, decimates, and fills holes. · `src/services/MeshProcessingService.cpp`

### Persistence & Output

- [Project manager](https://github.com/klischa/astra2/blob/klischa-patch/src/project/ProjectManager.cpp): workspace persistence · Owns project lifecycle and durable metadata/cloud state. · `src/project/ProjectManager.cpp`
- [Export manager](https://github.com/klischa/astra2/blob/klischa-patch/src/export/ExportManager.cpp): format boundary · Exports PLY, PCD, STL, and OBJ. · `src/export/ExportManager.cpp`
- [Settings manager](https://github.com/klischa/astra2/blob/klischa-patch/src/settings/SettingsManager.cpp): application settings · Centralizes capture, filter, and tracking parameters. · `src/settings/SettingsManager.cpp`

## Connections

- CMake build → Application startup: builds
- Application startup → Qt UI shell: creates
- Qt UI shell → Project UI controller: binds
- Qt UI shell → Capture session controller: binds
- Qt UI shell → Processing controller: binds
- Qt UI shell → Viewer coordinator: binds
- Project UI controller → Project manager: manages projects
- Capture session controller → Capture worker: dispatches
- Capture session controller → Scan & turntable workflows: drives
- Capture worker → Astra camera: acquires frames
- Astra camera → Depth-to-cloud converter: supplies depth
- Depth-to-cloud converter → Marker pose tracking: cloud frames
- Depth-to-cloud converter → Neural tracking pipeline: cloud frames
- Neural tracking pipeline → Neural tracker: runs inference
- Marker pose tracking → Surfel coverage tracker: pose updates
- Neural tracking pipeline → Surfel coverage tracker: pose updates
- Capture session controller → Project manager: stores captures
- Processing controller → Cloud filtering: cleans clouds
- Processing controller → Registration service: aligns scans
- Processing controller → Reconstruction service: reconstructs mesh
- Reconstruction service → Mesh processing: produces mesh
- Processing controller → Project manager: reads and persists assets
- Processing controller → Export manager: exports results
- Processing controller → Viewer coordinator: updates displays
- Settings manager → Capture session controller: capture parameters
- Settings manager → Processing controller: processing parameters
- Settings manager → Neural tracking pipeline: tracking parameters