# zuka98/egpis architecture

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

- Interactive diagram: https://gitdiagram.com/zuka98/egpis
- Repository: https://github.com/zuka98/egpis

## Overview

##### Project type and purpose
- This is a research-oriented algorithmic pipeline for Enhanced GPIS (Gaussian Process Implicit Surfaces) learning, as described in the README and accompanying paper. It is not a web or mobile app but a scientific computing toolkit that:
- downloads and organizes datasets
- configures parameters
- runs a reconstruction pipeline (GP regression + local/global focus learning)
- analyses and visualizes results

##### File structure
- Top-level scripts:
- download_datasets.sh – grabs raw data
- init.sh – creates folders, unpacks data
- src/ directory (the core pipeline):
- main.py – entry point, ties everything together
- Parameters.py – defines experiment configurations
- GPRegressionModel.py – encapsulates Gaussian Process training & prediction
- Reconstruction.py – uses GPRegressionModel to build implicit surfaces
- reconstruct.py – higher-level orchestration of reconstruction experiments
- analyse_results.py – computes metrics, generates plots, tables
- helpers.py – I/O routines, utility functions
- requirements.txt – external dependencies (NumPy, SciPy, Matplotlib, GP library, etc.)

##### README insights
- Describes project goal: enhanced GPIS learning with local/global focus
- Provides usage steps: download, init, then python3 src/main.py
- References datasets and paper citation

##### Main components
a. Shell Script Layer
- download_datasets.sh → Data Storage
- init.sh → Directory & folder setup
b. Data Layer
- Raw Dataset Files (local disk)
- Organized Folders (created by init.sh)
c. Configuration Layer
- Parameters.py → Experiment settings, hyperparameters
d. Core Algorithm Layer
- Data Loader (helpers.py)
- GPRegressionModel.py → Training & inference engine
- Reconstruction.py → Surface reconstruction logic (combines global + local focus)
- reconstruct.py → Batch orchestration of multiple runs
e. Orchestration Layer
- main.py → CLI: reads Parameters, invokes reconstruct or Reconstruction, then analyse_results
f. Analysis & Visualization Layer
- analyse_results.py → Metrics computation, plots, saving output
g. External Services / Libraries
- Python interpreter
- NumPy, SciPy, Matplotlib
- GP library (GPflow, GPy, scikit-learn’s GaussianProcess)

##### Relationships and data flows
- download_datasets.sh → populates “data/” folder
- init.sh → creates folder structure under workspace
- main.py reads in parameters, calls helpers to load data
- Data Loader → supplies training/test points to GPRegressionModel
- GPRegressionModel → returns implicit surface predictions
- Reconstruction → stitches predictions into final mesh or field
- reconstruct.py (if batch mode) loops over seeds/parameters
- analyse_results.py consumes reconstructed outputs → generates charts/tables

##### Architectural patterns & design principles
- Modular design: each Python module has a single responsibility
- Pipeline / DAG pattern: data flows in stages from loading → modeling → reconstruction → analysis
- Config-driven: behaviour controlled via Parameters.py rather than hard-coding
- Reusability: helpers.py and clear function boundaries

##### Technologies & frameworks to annotate
- Python 3.x runtime
- Key libraries: NumPy, SciPy, Matplotlib, GP library
- Bash for orchestration (download, init)
- Directory structure (data/, results/, logs/)

##### Elements to ensure clarity
- Version information (Python 3.x, library versions) in a corner

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Shell Script Layer
    subgraph "Shell Script Layer"
        direction TB
        DL["download_datasets.sh\n(grabs raw data)"]:::bash
        IU["init.sh\n(setup directories)"]:::bash
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RAW["Raw Dataset Files\n(local disk)"]:::data
        ORG["Organized Folders\n(created by init.sh)"]:::data
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        CFG["Parameters.py\n(experiment settings)"]:::config
    end

    %% Core Algorithm Layer
    subgraph "Core Algorithm Layer"
        direction TB
        HL["helpers.py\n(data loader & utilities)"]:::core
        GP["GPRegressionModel.py\n(training & prediction)"]:::core
        RC["Reconstruction.py\n(surface reconstruction)"]:::core
        BR["reconstruct.py\n(batch orchestration)"]:::core
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        MAIN["main.py\n(pipeline controller CLI)"]:::orchestration
    end

    %% Analysis & Visualization Layer
    subgraph "Analysis & Visualization Layer"
        direction TB
        AR["analyse_results.py\n(metrics & plots)"]:::analysis
    end

    %% External Libraries
    subgraph "External Services / Libraries"
        direction TB
        PY["Python 3.x"]:::external
        NUM["NumPy, SciPy"]:::external
        MPL["Matplotlib"]:::external
        GP_LIB["GP library"]:::external
    end

    %% Connections
    DL -->|"downloads data"| RAW
    IU -->|"sets up folders"| ORG
    RAW -->|"provides raw input"| HL
    ORG -->|"structured data"| HL

    MAIN -->|"reads parameters"| CFG
    MAIN -->|"invokes batch"| BR
    MAIN -->|"runs analysis"| AR

    HL -->|"PointCloud data"| GP
    GP -->|"predicted field"| RC
    RC -->|"surface mesh"| AR

    BR -.->|"loops over seeds"| RC

    PY --> MAIN
    NUM --> GP
    MPL --> AR
    GP_LIB --> GP

    %% Click Events
    click DL "https://github.com/zuka98/egpis/blob/main/download_datasets.sh"
    click IU "https://github.com/zuka98/egpis/blob/main/init.sh"
    click CFG "https://github.com/zuka98/egpis/blob/main/src/Parameters.py"
    click HL "https://github.com/zuka98/egpis/blob/main/src/helpers.py"
    click GP "https://github.com/zuka98/egpis/blob/main/src/GPRegressionModel.py"
    click RC "https://github.com/zuka98/egpis/blob/main/src/Reconstruction.py"
    click BR "https://github.com/zuka98/egpis/blob/main/src/reconstruct.py"
    click MAIN "https://github.com/zuka98/egpis/blob/main/src/main.py"
    click AR "https://github.com/zuka98/egpis/blob/main/src/analyse_results.py"

    %% Styles
    classDef bash fill:#f9e79f,stroke:#b7950b,color:#000
    classDef data fill:#ebedef,stroke:#95a5a6,color:#000
    classDef config fill:#85c1e9,stroke:#21618c,color:#000
    classDef core fill:#82e0aa,stroke:#196f3d,color:#000
    classDef orchestration fill:#f5cba7,stroke:#af601a,color:#000
    classDef analysis fill:#d7bde2,stroke:#6c3483,color:#000
    classDef external fill:#d5dbdb,stroke:#566573,color:#000
```
