# stable-x/geomaster architecture

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

- Interactive diagram: https://gitdiagram.com/stable-x/geomaster
- Repository: https://github.com/stable-x/geomaster

## Overview

##### Main Components
- Data Input & Preparation:
– Represent the input data (images, sparse files) as the starting point. The README clarifies the structure (data_001/images, data_001/sparse) and the gm-prepare-data command that converts raw data into a format suitable for processing.
- Mesh Reconstruction Pipeline:
– This component includes commands like gm-recon that work on prepared data to create an initial mesh (e.g., visual_hull.ply). In the file tree, various scripts under geomaster/scripts (e.g., prepare_data.py, process_data.py) support these operations.
- Mesh Enhancement/Refinement Pipeline:
– Highlight the gm-refine command and the associated scripts (refine_mesh.py, render_mesh.py, render_meshes.py) that enhance geometric details.
- Mesh Post-Processing:
– Capture the functionality for making the mesh watertight (gm-process-mesh) and for culling invisible parts (gm-cull-mesh), with corresponding scripts (cull_mesh.py).
- Pipeline Systems Framework:
– Under geomaster/systems, you have pipeline modules like mesh_pipeline.py, sap_pipeline.py, and tsdf_fusion_pipeline.py. Represent these as organized “processing engines” that configure and sequence the steps.
- Model Definitions & Utilities:
– The geomaster/models directory defines data structures (mesh.py, sap.py), while the utils subdirectory (camera_utils.py, mesh_utils.py, etc.) provides helper functions. These support the core pipelines.

##### Relationships and Interactions
– Starting from raw data input, flow into the data preparation module.
– Then, pass to the Mesh Reconstruction Pipeline which outputs a coarse mesh.
– The coarse mesh is fed to the Mesh Refinement Pipeline for high-resolution enhancement.
– Optionally, the refined mesh can be processed further (e.g., to become watertight or cleaned via culling).
- That each pipeline module (found under geomaster/systems) orchestrates several internal steps that rely on scripts and utility functions.

##### Architectural Patterns and Design Principles
- Modular and Pipeline-Based Design:
– Each component (data preparation, reconstruction, refinement, post-processing) is implemented as distinct pipelines, making the system extensible.
- Separation of Concerns:
– Using dedicated directories (models, scripts, systems, utils) reflects clear separation of business logic, data structures, orchestration, and utilities.
- Integration with External Libraries:

##### Relevant Technologies and Frameworks
- Python Packaging:
– With pyproject.toml, requirements.txt, and setup.py, show that GeoMaster is designed as a Python package.
- External Dependencies:
– Show connections/links that indicate the installation and usage of PyTorch, nvdiffrast, Real-ESRGAN, and gaustudio.
- Command-Line User Interface:
– Emphasize that users interact with the system via command line commands (gm-prepare-data, gm-recon, gm-refine, gm-process-mesh, gm-cull-mesh).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level: CLI Commands
    CLI["CLI Commands (gm-prepare-data, gm-recon, gm-refine, gm-process-mesh, gm-cull-mesh)"]:::cli

    %% Input Data Subgraph
    subgraph "Input Data"
        RAW1["Images"]:::raw
        RAW2["Sparse"]:::raw
    end

    %% Data Preparation
    DP["Data Preparation (gm-prepare-data)"]:::pipeline

    %% Mesh Reconstruction Pipeline Subgraph
    subgraph "Mesh Reconstruction Pipeline"
        MR1["Reconstruction Script"]:::pipeline
        MR2["Pipeline Engine"]:::pipeline
    end

    %% Mesh Refinement Pipeline Subgraph
    subgraph "Mesh Refinement Pipeline"
        REF1["Refinement Script"]:::pipeline
        REF2["Rendering Script 1"]:::pipeline
        REF3["Rendering Script 2"]:::pipeline
    end

    %% Mesh Post-Processing Subgraph
    subgraph "Mesh Post-Processing"
        MP1["Mesh Culling"]:::pipeline
        MP2["Mesh Processing"]:::pipeline
    end

    %% Pipeline Systems Framework Subgraph
    subgraph "Pipeline Systems Framework"
        PS1["Mesh Pipeline Module"]:::system
        PS2["SAP Pipeline Module"]:::system
        PS3["TSDF Fusion Pipeline Module"]:::system
    end

    %% Models & Utilities Subgraph
    subgraph "Models & Utilities"
        MU1["Mesh Model"]:::utility
        MU2["SAP Model"]:::utility
        MU3["Camera Utils"]:::utility
        MU4["Mesh Utils"]:::utility
        MU5["Func Utils"]:::utility
        MU6["NCC Utils"]:::utility
        MU7["Remesh Utils"]:::utility
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        ED1["PyTorch"]:::external
        ED2["nvdiffrast"]:::external
        ED3["Real-ESRGAN"]:::external
        ED4["gaustudio"]:::external
    end

    %% Python Packaging Subgraph
    subgraph "Python Packaging"
        PP1["pyproject.toml"]:::packaging
        PP2["requirements.txt"]:::packaging
        PP3["setup.py"]:::packaging
    end

    %% Connections: Vertical Data Flow
    CLI --> RAW1
    CLI --> RAW2
    RAW1 --> DP
    RAW2 --> DP
    DP --> MR1
    MR2 --> REF1
    REF3 --> MP1

    %% Internal connections within subgraphs are defined by order.
    MR1 --- MR2
    REF1 --- REF2
    REF2 --- REF3
    MP1 --- MP2

    %% Connect Pipelines to Pipeline Systems Framework
    MP2 --> PS1
    MR2 --> PS1
    REF3 --> PS1

    %% Connect Pipeline Systems Framework to Models & Utilities
    PS3 --> MU1
    PS3 --> MU2
    PS3 --> MU3
    PS3 --> MU4
    PS3 --> MU5
    PS3 --> MU6
    PS3 --> MU7

    %% External Dependencies integrated with pipelines (dotted arrows)
    ED1 --- PS1
    ED2 --- PS1
    ED3 --- REF1
    ED4 --- REF1

    %% Class Definitions for Coloring
    classDef cli fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef raw fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef pipeline fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef system fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef utility fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#f0b27a,stroke:#e67e22,stroke-width:2px;
    classDef packaging fill:#d6eaf8,stroke:#5dade2,stroke-width:2px;

    %% Click Events for Component Mapping
    click RAW1 "https://github.com/stable-x/geomaster/tree/master/examples/glt/images"
    click RAW2 "https://github.com/stable-x/geomaster/tree/master/examples/glt/sparse"
    click DP "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/prepare_data.py"
    click MR1 "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/process_data.py"
    click MR2 "https://github.com/stable-x/geomaster/blob/master/geomaster/systems/mesh_pipeline.py"
    click REF1 "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/refine_mesh.py"
    click REF2 "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/render_mesh.py"
    click REF3 "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/render_meshes.py"
    click MP1 "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/cull_mesh.py"
    click MP2 "https://github.com/stable-x/geomaster/blob/master/geomaster/scripts/process_mesh.py"
    click PS1 "https://github.com/stable-x/geomaster/blob/master/geomaster/systems/mesh_pipeline.py"
    click PS2 "https://github.com/stable-x/geomaster/blob/master/geomaster/systems/sap_pipeline.py"
    click PS3 "https://github.com/stable-x/geomaster/blob/master/geomaster/systems/tsdf_fusion_pipeline.py"
    click MU1 "https://github.com/stable-x/geomaster/blob/master/geomaster/models/mesh.py"
    click MU2 "https://github.com/stable-x/geomaster/blob/master/geomaster/models/sap.py"
    click MU3 "https://github.com/stable-x/geomaster/blob/master/geomaster/utils/camera_utils.py"
    click MU4 "https://github.com/stable-x/geomaster/blob/master/geomaster/utils/mesh_utils.py"
    click MU5 "https://github.com/stable-x/geomaster/blob/master/geomaster/utils/func.py"
    click MU6 "https://github.com/stable-x/geomaster/blob/master/geomaster/utils/ncc_utils.py"
    click MU7 "https://github.com/stable-x/geomaster/blob/master/geomaster/utils/remesh_utils.py"
```
