How wanglibo1995/geoseg works
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.