# earthobservation/adaf architecture

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

- Interactive diagram: https://gitdiagram.com/earthobservation/adaf
- Repository: https://github.com/earthobservation/adaf

## Overview

##### Project type and purpose
- ADAF is a desktop/data-science tool (Python library + Jupyter interface) for automatic detection of archaeological features in airborne LiDAR (ALS) data.
- It uses RVT (Relief Visualisation Toolbox) for preprocessing, AiTLAS for CNN-based inference, and presents results in Jupyter or via a small widget interface.

##### File structure
Top-level folders:
- adaf/         ← Core Python package (inference, utils, visualization, widget, I/O pipelines)
- inference/    ← Example notebooks and scripts showing segmentation/object-detection workflows
- installation/ ← Installable wheels for GDAL and AiTLAS
- Notebooks & scripts at root for training and evaluation
- _wheels/      ← Bundled wheel files for offline install
- run_adaf.bat  ← Entry-point script

##### Pull insights from the README
- ML models live in adaf/ml_models (external tar files ~5 GB), loaded at runtime.
- Dependencies: Python 3.8, GDAL, PyTorch (GPU optional), AiTLAS.
- Usage via Jupyter Notebook (ADAF_main.ipynb) or CLI scripts.

1. User Interfaces
- Jupyter Notebook (ADAF_main.ipynb)
- adaf_widget (if using the interactive widget)
- Optional CLI/Batch script (run_adaf.bat)
2. Core Processing Pipeline (adaf package)
- Data Loader & RVT preprocessing (grid_tools, create_patches)
- Inference Engine (adaf_inference → loads AiTLAS models)
- Post-processing & Visualization (adaf_vis, create_visualisations)
3. Model Storage
- adaf/ml_models directory (TAR files for segmentation & detection)
4. External Dependencies
- GDAL (geospatial I/O)
- AiTLAS framework
- PyTorch / CUDA
- Anaconda / Python runtime
b. Relationships & data flow
- User invokes Notebook or run_adaf.bat → calls into adaf_widget or adaf_inference
- Raw ALS data → GDAL reader → RVT preprocessing modules → patch generation
- Patches → Inference Engine → AiTLAS models (segmentation & object detection)
- Predictions → Post-processing → Visual outputs & metrics → Notebook / widget display
- Optionally: save results to disk (GeoTIFFs, shapefiles)
c. Architectural patterns & design principles
- Pipeline pattern: staged processing (preprocess → infer → postprocess)
- Modular separation: utils, I/O, inference, visualization in distinct modules
- Pluggable ML back-end: AiTLAS models are external, loaded dynamically
d. Key technologies & libraries
- Python 3.8
- GDAL (installed via wheel)
- PyTorch (CPU/GPU)
- AiTLAS (installed via wheel)
- Jupyter Notebook & ipykernel for interactive use

##### Every essential element
- Don’t forget the installation step: show “installation/_wheels → pip install → environment” as a side flow.
- Optional GPU path in the inference engine.
- Example notebooks in the “inference/” folder as variations on the core pipeline (segmentation vs. object-detection).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        NotebookMain["Jupyter Notebook<br/>(ADAF_main.ipynb)"]:::ui
        Notebook1["ADAF_notebook.ipynb"]:::ui
        Notebook2["ADAF_trainning_samples.ipynb"]:::ui
        WidgetNB["ADAF_widget.ipynb"]:::ui
        CLI["CLI/Batch Script<br/>(run_adaf.bat)"]:::ui
    end

    %% Core Pipeline
    subgraph "Core Pipeline (adaf package)"
        subgraph Preprocessing
            GridTools["Grid Tools<br/>(adaf/grid_tools.py)"]:::pipeline
            CreatePatches["Create Patches<br/>(adaf/create_patches.py)"]:::pipeline
        end
        Inference["Inference Engine<br/>(adaf/adaf_inference.py)"]:::pipeline
        Utils["Utilities<br/>(adaf/adaf_utils.py)"]:::pipeline
        subgraph "Post-Process & Visualization"
            Vis["Visualization<br/>(adaf/adaf_vis.py)"]:::pipeline
            CreateVis["Create Visualisations<br/>(adaf/create_visualisations.py)"]:::pipeline
        end
        WidgetComp["Interactive Widget<br/>(adaf/adaf_widget.py)"]:::pipeline
    end

    %% Example Workflows
    subgraph "Example Workflows"
        SegNotebook["Segmentation Predictions<br/>(inference/make_predictions_segmentation.ipynb)"]:::ui
        ObjNotebook["Object Detection Predictions<br/>(inference/make_predictions_object_detection.ipynb)"]:::ui
        TrainSeg["Train & Evaluate Segmentation<br/>(inference/train_and_evaluate_segmentation.ipynb)"]:::ui
        InfUtils["Inference Utils<br/>(inference/utils.py)"]:::pipeline
    end

    %% Storage
    MLModels["ML Models Storage<br/>(adaf/media)"]:::storage
    Results["Results (GeoTIFF/Shapefiles)"]:::storage

    %% External Dependencies
    subgraph "External Dependencies"
        GDAL["GDAL (Geo I/O)"]:::external
        PyTorch["PyTorch / CUDA"]:::external
        AiTLAS["AiTLAS Framework"]:::external
        Conda["Conda / Python 3.8"]:::external
        GDALWheel1["_wheels/GDAL-3.4.3-cp38-cp38-win_amd64.whl"]:::external
        AiTLASWheel1["_wheels/aitlas-0.0.1-py3-none-any.whl"]:::external
        GDALWheel2["installation/GDAL-3.4.3-cp38-cp38-win_amd64.whl"]:::external
        AiTLASWheel2["installation/aitlas-0.0.1-py3-none-any.whl"]:::external
    end

    %% Connections - Entry Points
    NotebookMain -->|runs| WidgetComp
    NotebookMain -->|calls| Inference
    Notebook1 -->|calls| Inference
    Notebook2 -->|calls| Inference
    WidgetNB -->|calls| WidgetComp
    CLI -->|executes| WidgetComp
    CLI -->|executes| Inference

    %% Preprocessing Flow
    GDAL -->|"reads raw ALS data"| GridTools
    GridTools -->|grid output| CreatePatches
    CreatePatches -->|"patch tiles"| Inference

    %% Runtime Environment
    Conda -->|"provides runtime"| GridTools
    Conda -->|"provides runtime"| Inference
    Conda -->|"manages env"| GDAL
    Conda -->|"manages env"| PyTorch
    Conda -->|"manages env"| AiTLAS

    %% Inference and Models
    Inference -->|"loads models from"| MLModels
    Inference -->|"uses AiTLAS"| AiTLAS
    PyTorch -->|"executes models"| Inference

    %% Post-processing & Visualization
    Inference -->|"prediction masks"| Vis
    Vis -->|"generated visuals"| WidgetComp
    Vis -->|"generated visuals"| NotebookMain
    Vis -->|"GeoTIFFs/shapefiles"| Results

    %% Example Workflows Integration
    SegNotebook -->|"uses pipeline"| Inference
    ObjNotebook -->|"uses pipeline"| Inference
    TrainSeg -->|"uses pipeline"| Inference
    InfUtils -->|"supports"| Inference

    %% Installation Wheels to Dependencies
    GDALWheel1 -->|"installation source"| GDAL
    GDALWheel2 -->|"installation source"| GDAL
    AiTLASWheel1 -->|"installation source"| AiTLAS
    AiTLASWheel2 -->|"installation source"| AiTLAS

    %% Click Events
    click NotebookMain "https://github.com/earthobservation/adaf/blob/main/ADAF_main.ipynb"
    click Notebook1 "https://github.com/earthobservation/adaf/blob/main/ADAF_notebook.ipynb"
    click Notebook2 "https://github.com/earthobservation/adaf/blob/main/ADAF_trainning_samples.ipynb"
    click WidgetNB "https://github.com/earthobservation/adaf/blob/main/ADAF_widget.ipynb"
    click CLI "https://github.com/earthobservation/adaf/blob/main/run_adaf.bat"
    click GridTools "https://github.com/earthobservation/adaf/blob/main/adaf/grid_tools.py"
    click CreatePatches "https://github.com/earthobservation/adaf/blob/main/adaf/create_patches.py"
    click Inference "https://github.com/earthobservation/adaf/blob/main/adaf/adaf_inference.py"
    click Utils "https://github.com/earthobservation/adaf/blob/main/adaf/adaf_utils.py"
    click Vis "https://github.com/earthobservation/adaf/blob/main/adaf/adaf_vis.py"
    click CreateVis "https://github.com/earthobservation/adaf/blob/main/adaf/create_visualisations.py"
    click WidgetComp "https://github.com/earthobservation/adaf/blob/main/adaf/adaf_widget.py"
    click SegNotebook "https://github.com/earthobservation/adaf/blob/main/inference/make_predictions_segmentation.ipynb"
    click ObjNotebook "https://github.com/earthobservation/adaf/blob/main/inference/make_predictions_object_detection.ipynb"
    click TrainSeg "https://github.com/earthobservation/adaf/blob/main/inference/train_and_evaluate_segmentation.ipynb"
    click InfUtils "https://github.com/earthobservation/adaf/blob/main/inference/utils.py"
    click MLModels "https://github.com/earthobservation/adaf/tree/main/adaf/media"
    click GDALWheel1 "https://github.com/earthobservation/adaf/blob/main/_wheels/GDAL-3.4.3-cp38-cp38-win_amd64.whl"
    click AiTLASWheel1 "https://github.com/earthobservation/adaf/blob/main/_wheels/aitlas-0.0.1-py3-none-any.whl"
    click GDALWheel2 "https://github.com/earthobservation/adaf/blob/main/installation/GDAL-3.4.3-cp38-cp38-win_amd64.whl"
    click AiTLASWheel2 "https://github.com/earthobservation/adaf/blob/main/installation/aitlas-0.0.1-py3-none-any.whl"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef pipeline fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#383d41;
```
