# wanglibo1995/geoseg architecture

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

- Interactive diagram: https://gitdiagram.com/wanglibo1995/geoseg
- Repository: https://github.com/wanglibo1995/geoseg

## Overview

##### Project Type and Purpose
- This is an open-source, config-driven semantic segmentation toolbox (GeoSeg) for remote-sensing imagery.
- It provides unified training, testing, and inference pipelines built on PyTorch, PyTorch Lightning, and timm, and supports multiple datasets (Vaihingen, Potsdam, UAVid, LoveDA, etc.) and segmentation architectures (transformers, CNNs, PyramidMamba).

##### High-Level Architectural Components
a. Configuration Layer
- Directory: config/
- Holds per-dataset, per-model Python config files (e.g. config/vaihingen/dcswin.py).
- Drives dataset parameters, model hyperparameters, training schedule, data paths.
b. Data Preparation Layer
- tools/ and scripts under GeoSeg/tools (patch splitting, mask conversion, metrics).
- Standalone CLI utilities for raw → processed data conversion (patching, format conversion).
c. Core Library (geoseg/)
- geoseg/datasets: Dataset classes (VaihingenDataset, PotsdamDataset, etc.) and transforms.
- geoseg/models: Plug-in network modules (UNetFormer, DCSwin, PyramidMamba, etc.).
- geoseg/losses: Loss functions (Dice, Focal, Lovasz, joint losses).
- geoseg/__init__.py: Package entry-point.
d. Training Engine
- train_supervision.py: CLI entry for training.
- Builds a PyTorch Lightning DataModule and LightningModule by reading a config.
- Uses timm to instantiate backbones, wraps models, losses, optimizers, schedulers under Lightning.
- Outputs checkpoints (model_weights/) and logs (lightning_logs/).
e. Testing / Inference Engine
- Scripts: vaihingen_test.py, potsdam_test.py, loveda_test.py, inference_uavid.py, inference_huge_image.py.
- Load a checkpoint via config, run test loop (with optional TTA), produce predicted masks under fig_results/.
f. External Frameworks
- PyTorch / torchvision / torchaudio
- PyTorch Lightning (Trainer orchestration)
- timm (pretrained backbones)
- Optional: causal-conv1d, mamba-ssm

##### Relationships and Data Flow
1. User invokes a CLI script (train_supervision or a test script) with a config path.
2. Config parser loads dataset paths, model architecture params, training hyperparameters.
3. Data Preparation tools (if preprocessing step) produce patched and formatted datasets.
4. During training:
- DataModule (geoseg/datasets) wraps processed data into DataLoaders.
- Model factory (geoseg/models) + Loss factory (geoseg/losses) instantiate network and criterion.
- Lightning Trainer handles epoch loop, optimizer, scheduler, multi-GPU coordination.
5. Checkpoints and logs are written.
6. For inference: a test script uses similar pipeline but runs evaluation/inference only, writing mask outputs.

##### Architectural Patterns and Principles
- Modular plugin system: add new datasets, models, or losses by dropping files under geoseg/.
- Config-driven pipeline: all runtime choices (models, data paths, hyperparameters) live in config/*.
- Separation of concerns:
- Data preparation (tools/)
- Core library (geoseg/)
- Orchestration (train_supervision.py, *_test.py)
- Use of PyTorch Lightning for boilerplate reduction (training loop, checkpointing, logging).

##### Detail Level
- Plugin directories (models/, losses/) as extensibility points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["config/"]:::data
    end
    click Config "https://github.com/wanglibo1995/geoseg/tree/main/config/"

    %% Data Preparation Tools
    subgraph "Data Preparation Tools"
        Tools["tools/ CLI Utilities"]:::data
        VPS["Vaihingen Patch Split"]:::data
        click VPS "https://github.com/wanglibo1995/geoseg/blob/main/tools/vaihingen_patch_split.py"
        PPS["Potsdam Patch Split"]:::data
        click PPS "https://github.com/wanglibo1995/geoseg/blob/main/tools/potsdam_patch_split.py"
        UVPS["UAVid Patch Split"]:::data
        click UVPS "https://github.com/wanglibo1995/geoseg/blob/main/tools/uavid_patch_split.py"
        LMC["LoveDA Mask Convert"]:::data
        click LMC "https://github.com/wanglibo1995/geoseg/blob/main/tools/loveda_mask_convert.py"
        MET["Metric Computation"]:::data
        click MET "https://github.com/wanglibo1995/geoseg/blob/main/tools/metric.py"
    end

    %% Data Storage
    Raw["Raw Data"]:::data
    Processed["Processed Data"]:::data

    %% Core Library
    subgraph "Core Library"
        Entry["geoseg/__init__.py"]:::core
        click Entry "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/__init__.py"
        subgraph "Datasets"
            VD["VaihingenDataset"]:::core
            click VD "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/datasets/vaihingen_dataset.py"
            PD["PotsdamDataset"]:::core
            click PD "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/datasets/potsdam_dataset.py"
            UD["UAVidDataset"]:::core
            click UD "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/datasets/uavid_dataset.py"
            LD["LoveDADataset"]:::core
            click LD "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/datasets/loveda_dataset.py"
            TF["Transforms"]:::core
            click TF "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/datasets/transform.py"
        end
        subgraph "Models"
            DCS["DCSwin"]:::core
            click DCS "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/DCSwin.py"
            UNF["UNetFormer"]:::core
            click UNF "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/UNetFormer.py"
            FTU["FTUNetFormer"]:::core
            click FTU "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/FTUNetFormer.py"
            PM["PyramidMamba"]:::core
            click PM "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/PyramidMamba.py"
            A2F["A2FPN"]:::core
            click A2F "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/A2FPN.py"
            ABC["ABCNet"]:::core
            click ABC "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/ABCNet.py"
            BAN["BANet"]:::core
            click BAN "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/BANet.py"
            MAN["MANet"]:::core
            click MAN "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/models/MANet.py"
        end
        subgraph "Losses"
            Dice["dice.py"]:::core
            click Dice "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/losses/dice.py"
            Focal["focal.py"]:::core
            click Focal "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/losses/focal.py"
            Lovasz["lovasz.py"]:::core
            click Lovasz "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/losses/lovasz.py"
            Joint["joint_loss.py"]:::core
            click Joint "https://github.com/wanglibo1995/geoseg/blob/main/geoseg/losses/joint_loss.py"
        end
    end

    %% Orchestration Scripts
    subgraph "Training Engine"
        Train["train_supervision.py"]:::orch
        click Train "https://github.com/wanglibo1995/geoseg/blob/main/train_supervision.py"
    end

    subgraph "Testing / Inference Engine"
        VT["vaihingen_test.py"]:::orch
        click VT "https://github.com/wanglibo1995/geoseg/blob/main/vaihingen_test.py"
        PT["potsdam_test.py"]:::orch
        click PT "https://github.com/wanglibo1995/geoseg/blob/main/potsdam_test.py"
        LT["loveda_test.py"]:::orch
        click LT "https://github.com/wanglibo1995/geoseg/blob/main/loveda_test.py"
        UI["inference_uavid.py"]:::orch
        click UI "https://github.com/wanglibo1995/geoseg/blob/main/inference_uavid.py"
        HI["inference_huge_image.py"]:::orch
        click HI "https://github.com/wanglibo1995/geoseg/blob/main/inference_huge_image.py"
    end

    %% Outputs
    Weights["model_weights/"]:::data
    Logs["lightning_logs/"]:::data
    Results["fig_results/"]:::data

    %% External Frameworks
    subgraph "External Frameworks"
        PTorch["PyTorch / torchvision"]:::ext
        PLight["PyTorch Lightning"]:::ext
        Timm["timm"]:::ext
    end

    %% Data Flow
    Raw -->|preprocess| VPS --> Tools
    Raw -->|preprocess| PPS --> Tools
    Raw -->|preprocess| UVPS --> Tools
    Raw -->|convert masks| LMC --> Tools
    Tools -->|compute metrics| MET
    Tools --> Processed

    Config --> Train
    Processed -->|instantiate DataLoader| Train
    Config -->|load params| Entry
    Train -->|uses| Entry
    Entry --> VD
    Entry --> PD
    Entry --> UD
    Entry --> LD
    Entry --> TF
    Entry --> DCS
    Entry --> UNF
    Entry --> FTU
    Entry --> PM
    Entry --> A2F
    Entry --> ABC
    Entry --> BAN
    Entry --> MAN
    Entry --> Dice
    Entry --> Focal
    Entry --> Lovasz
    Entry --> Joint
    Train -->|train loop| PLight
    PLight --> PTorch
    PLight --> Timm
    Train --> Weights
    Train --> Logs

    Weights --> VT
    Config --> VT
    VT -->|load model| Entry
    VT -->|apply TTA| Entry
    VT --> Results
    PT --> Results
    LT --> Results
    UI --> Results
    HI --> Results

    %% Styles
    classDef core fill:#D0E6FF,stroke:#004080,color:#004080;
    classDef orch fill:#DFF2D8,stroke:#2E7D32,color:#2E7D32;
    classDef data fill:#FFDDBD,stroke:#E65100,color:#E65100;
    classDef ext fill:#E0E0E0,stroke:#555,color:#555;
```
