terratorch 1.2.12

Please read the contribution guidelines (see Contribution below) if you want to contribute to TerraTorch.

Overview

TerraTorch is a PyTorch domain library based on PyTorch Lightning and the TorchGeo domain library for geospatial data.

Please also try our HPO/NAS tool: Iterate

Disclaimer

TerraTorch provides tools for fine-tuning and using pretrained models. No models are hosted by TerraTorch. TerraTorch only provides the training and inference framework.

User responsibility: It is the sole responsibility of the user to verify that the license of any model they download, fine-tune, or deploy allows their intended use. The TerraTorch maintainers do not provide legal advice and are not liable for any misuse of third-party models.

Video: Introduction to TerraTorch

TerraTorch’s main purpose is to provide a flexible fine-tuning framework for Geospatial Foundation Models, which can be interacted with at different abstraction levels. The library provides:

• Convenient modelling tools:
  • Flexible trainers for Image Segmentation, Classification and Pixel Wise Regression fine-tuning tasks
  • Model factories that allow to easily combine backbones and decoders for different tasks
  • Ready-to-go datasets and datamodules that require only to point to your data with no need of creating new custom classes
  • Launching of fine-tuning tasks through CLI and flexible configuration files, or via jupyter notebooks
• Easy access to:
  • Open source pre-trained Geospatial Foundation Model backbones:
    • Prithvi
    • TerraMind
    • SatMAE
    • ScaleMAE
    • Satlas (as implemented in TorchGeo)
    • DOFA (as implemented in TorchGeo)
    • SSL4EO-L and SSL4EO-S12 models (as implemented in TorchGeo)
    • Clay
  • Backbones available in the timm (Pytorch image models)
  • Decoders available in SMP (Pytorch Segmentation models with pre-training backbones) and mmsegmentation packages
  • Fine-tuned models such as granite-geospatial-biomass
  • All GEO-Bench datasets and datamodules
  • All TorchGeo datasets and datamodules

Installation

Pip

In order to use the file pyproject.toml it is necessary to guarantee pip>=21.8. If necessary upgrade pip using python -m pip install --upgrade pip.

For a stable point-release, use pip install terratorch==<version>.

To get the most recent version of the branch main, install the library with pip install git+https://github.com/torchgeo/terratorch.git.

Conda

TerraTorch is also available on conda-forge, to install from there do conda install -c conda-forge terratorch.

Pipx

Alternatively, it is possible to install using pipx via pipx install terratorch, which creates an isolated environment and allows the user to run the application as a common CLI tool, with no need of installing dependencies or activating environments.

Gdal

TerraTorch requires gdal to be installed, which can be quite a complex process. If you don't have GDAL set up on your system, we recommend using a conda environment and installing it with conda install -c conda-forge gdal. If you are installing from conda-forge it probably won't be a problem.

Optional Dependencies

RF-DETR

RF-DETR integration is optional and depends on the upstream rfdetr package.

Install optional RF-DETR support with:

pip install terratorch[rfdetr]

For contributors using editable installs:

pip install -e .[test,rfdetr]

Deformable DETR

Some advanced object detection tests use the Deformable DETR variant, which requires compiling CUDA operators for MultiScaleDeformableAttention.

Note: Core DETR functionality works without this extension. Deformable DETR tests will be gracefully skipped if the operators are not compiled.

To enable Deformable DETR support, compile the CUDA operators:

git clone https://github.com/fundamentalvision/Deformable-DETR.git
cd Deformable-DETR/models/ops
sh make.sh

Requirements: Linux, CUDA ≥ 9.2, GCC ≥ 5.4

Install as a developer

To install as a developer (e.g. to extend the library):

git clone https://github.com/torchgeo/terratorch.git
cd terratorch
pip install -e .[test]

Optional Dependencies

TerraTorch supports several optional features that can be installed separately:

• VLLM support: pip install terratorch[vllm]
• Weather Foundation Models: pip install terratorch[wxc] (Python >= 3.11 only)
• PEFT (Parameter-Efficient Fine-Tuning): pip install terratorch[peft]
• Visualization tools: pip install terratorch[visualize]
• GeoBench v2: pip install terratorch[geobenchv2]
• Logging with Weights & Biases: pip install terratorch[logging]
• MMSegmentation support: pip install terratorch[mmseg]
• Surya support: pip install terratorch[surya]
• Tortilla file support: pip install terratorch[tortilla] - Required for loading datasets from tortilla files

You can install multiple optional dependencies at once: pip install terratorch[vllm,peft,logging]

Documentation

To get started, check out the quick start guide.

Developers, check out the architecture overview.

TerraTorch: The Geospatial Foundation Models Toolkit on arXiv

Contributing

This project welcomes contributions and suggestions. Ways to contribute or get involved:

• Join our Discord
• Create an Issue (for bugs or feature requests)
• Contribute via PR
• Join our duoweekly community calls taking place Tuesdays 4:30 PM - 5 PM CEST and Thursdays 2:30 PM - 3 PM CEST.

You can find more detailed contribution guidelines here.

If you want to meet the GitHub DCO checks, you need to do your commits as below:

git commit -s -m <message>

It will sign the commit with your ID and the check will be met.

Credits

Embed2Scale. The embedding workflow integration and maintenance in TerraTorch are carried out as part of the Embed2Scale project (Earth Observation & Weather Data Federation with AI Embeddings), funded by the EU’s Horizon Europe programme (Grant Agreement No. 101131841), with additional support from SERI and UKRI.

License

This project is primarily licensed under the Apache License 2.0.

However, some files contain code licensed under the MIT License. These files are explicitly listed in MIT_FILES.txt.

By contributing to this repository, you agree that your contributions will be licensed under the Apache 2.0 License unless otherwise stated.

For more details, see the LICENSE file.