How ibm/terratorch works
Project Type & Purpose
• TerraTorch is an open-source Python domain library (not a monolithic application) built on top of PyTorch Lightning and TorchGeo.
• Its goal is to provide a flexible fine-tuning framework for geospatial foundation models (Prithvi, TerraMind, SatMAE, etc.), offering ready-to-use datasets, datamodules, model factories, tasks, and a CLI.
File Structure & Architectural Patterns
• Top-level packaging:
• terratorch/ – the core library
– __main__.py, cli_tools.py, validate_config.py (entrypoints & utilities)
– datamodules/, datasets/ (Lightning-style DataModules & PyTorch Datasets)
– models/ (backbones, decoders, heads, factories)
– tasks/ (training/inference tasks, loss handlers, optimizer factories)
– registry/ (central registries for backbones, decoders, datamodules)
– samplers/, utils/ (supporting utilities)
• examples/, docs/, tests/, integrationtests/ (usage samples, docs, CI tests)
• Architectural pattern:
• Layered design separating
– Interface layer (CLI, notebooks, YAML configs)
– Orchestration layer (Tasks that glue DataModules, Models, and Lightning Trainer)
– Model layer (Model factories assemble backbones → necks → heads/decoders)
– Data layer (DataModules wrap datasets and transforms)
• Factory & Registry pattern for plug-and-play components
• Lightning plugin pattern: tasks implement step(), configure_optimizers() and hand off to LightningTrainer
Key Components & Their Relationships
a. Interface Components
• CLI (terratorch CLI via __main__.py & cli_tools.py)
• Config files (YAML) loaded by validate_config.py
• Notebooks / Python API that call the same internals
b. Orchestration Layer
• Task classes (terratorch.tasks.*) define prepare_data(), train/validation steps, inference loops
• These take as input: a DataModule instance + a Model (from factory) + optimizer/loss
• Hand off to PyTorch Lightning’s Trainer
c. Data Layer
• Datasets (terratorch.datasets.*) implement raw geospatial data loading & transforms
• Datamodules (terratorch.datamodules.*) wrap Datasets into train/val/test DataLoaders
d. Model Layer
• Backbones (terratorch.models.backbones.*) – pre-trained foundation model encoders
• Decoders/Heads (terratorch.models.decoders.*, heads/) – task-specific output modules
• Model Factories (encoder_decoder_factory.py, full_model_factory.py, smp_model_factory.py, etc.) use registries to pair backbones + decoders + heads
e. Registry & Utilities
• registry/ ensures decoupling: registering new backbones, decoders, datasets without editing core
• cli_tools & validate_config ensure correct wiring of components from YAML to Python objects
f. External Dependencies
• PyTorch & PyTorch Lightning (training runtime)
• TorchGeo (geospatial foundation models & datasets)
• Hugging Face Hub (model weights)
• SMP / mmsegmentation / timm (backbone & decoder providers)
• GDAL (geospatial I/O)
Architectural Patterns & Design Principles
• Separation of Concerns: interface vs orchestration vs data vs model
• Factories & Registries to enable plug-in extensibility
• Lightning plugin pattern (Tasks delegate actual training loops)
• Declarative configuration (YAML → Python objects via validate_config/cli_tools)
Essential Elements to Capture
• Interfaces: CLI & Configs → loaders (validate_config.py, cli_tools.py)
• Orchestration: Task classes + Lightning Trainer
• Data Flow: DataModule → Dataset → on-disk geospatial files via GDAL
• Model Construction: Registry → Factory → Backbone + Decoder + Head → PyTorch model
• External Integrations: TorchGeo, timm, SMP, Hugging Face, PyTorch Lightning