如果您希望为 TerraTorch 做出贡献，请阅读贡献指南（见下方的“贡献”部分）。

概述

TerraTorch 是一个基于 PyTorch Lightning 和 TorchGeo 地理空间数据领域库的 PyTorch 领域库。

您也可以尝试我们的超参数优化/神经架构搜索工具：Iterate（https://github.com/terrastackai/iterate）

免责声明

TerraTorch 提供用于微调和使用预训练模型的工具。 TerraTorch 并不托管任何模型。TerraTorch 仅提供训练和推理框架。

用户责任：用户有责任自行核实其下载、微调或部署的任何模型的许可证是否允许其预期用途。 TerraTorch 的维护者不提供法律建议，也不对第三方模型的任何不当使用承担责任。

---

视频：TerraTorch 简介

---

TerraTorch 的主要目的是为地理空间基础模型提供一个灵活的微调框架，该框架可以在不同的抽象层次上进行交互。该库提供：

• 方便的建模工具：
  • 适用于图像分割、分类和像素级回归等微调任务的灵活训练器
  • 可以轻松组合不同任务的骨干网络和解码器的模型工厂
  • 即用型数据集和数据模块，只需指向您的数据即可，无需创建新的自定义类
  • 通过命令行和灵活的配置文件，或通过 Jupyter 笔记本启动微调任务
• 轻松访问：
  • 开源预训练的地理空间基础模型骨干：
    • Prithvi
    • TerraMind
    • SatMAE
    • ScaleMAE
    • Satlas（如在 TorchGeo 中实现）
    • DOFA（如在 TorchGeo 中实现）
    • SSL4EO-L 和 SSL4EO-S12 模型（如在 TorchGeo 中实现）
    • Clay
  • 在 timm（PyTorch 图像模型）中可用的骨干
  • 在 SMP（带有预训练骨干的 PyTorch 分割模型）和 mmsegmentation 包中可用的解码器
  • 微调后的模型，例如 granite-geospatial-biomass
  • 所有 GEO-Bench 数据集和数据模块
  • 所有 TorchGeo 数据集和数据模块

安装

pip

为了使用 pyproject.toml 文件，必须确保 pip>=21.8。如有必要，请使用 python -m pip install --upgrade pip 升级 pip。

对于稳定的点发布版本，使用 pip install terratorch==<version>。

[注释]: 如果您更倾向于获取主分支的最新版本，可以使用 pip install git+https://github.com/terrastackai/terratorch.git 来安装该库。 要获取 main 分支的最新版本，可以使用 pip install git+https://github.com/terrastackai/terratorch.git。

conda

TerraTorch 也在 conda-forge 上提供，您可以从那里使用 conda install -c conda-forge terratorch 进行安装。

pipx

或者，您也可以使用 pipx 通过 pipx install terratorch 进行安装，这会创建一个隔离的环境，并允许用户将应用程序作为常见的 CLI 工具运行，而无需安装依赖项或激活环境。

GDAL

TerraTorch 需要安装 GDAL，而这可能是一个相当复杂的过程。 如果您系统上尚未设置 GDAL，我们建议使用 conda 环境，并通过 conda install -c conda-forge gdal 进行安装。如果您是从 conda-forge 安装的，通常不会有问题。

作为开发者安装

要作为开发者安装（例如扩展该库）：

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

要安装对气象基础模型部分支持（开发中）的 TerraTorch，可以使用 pip install -e .[wxc]，目前该选项仅适用于 Python >= 3.11。

文档

要开始使用，请查看快速入门指南。 开发者请查看架构概述。 TerraTorch：地理空间基础模型工具包，发表于 arXiv

贡献

本项目欢迎贡献和建议。以下是参与或贡献的方式：

• 加入我们的 Discord
• 创建一个 Issue（用于报告 bug 或提出功能请求）
• 通过 PR 提交贡献
• 参加我们的 duoweekly 社区会议，会议时间分别为：周二下午4:30–5:00 中欧夏令时 和 周四下午2:30–3:00 中欧夏令时。

您可以在 这里 找到更详细的贡献指南。

如果您希望满足 GitHub 的 DCO 检查要求，必须按照以下方式提交您的更改：

git commit -s -m <message>

这将使用您的身份签名提交，从而满足检查要求。

致谢

Embed2Scale。 TerraTorch 中的嵌入工作流集成与维护是 Embed2Scale 项目的一部分， 该项目由欧盟“地平线欧洲”计划资助（资助协议编号：101131841），并得到 SERI 和 UKRI 的额外支持。

许可证

本项目主要采用 Apache License 2.0 许可证。

然而，部分文件包含采用 MIT License 许可的代码。这些文件已在 MIT_FILES.txt 中明确列出。

通过向本仓库贡献内容，您同意您的贡献将根据 Apache 2.0 许可证进行授权，除非另有说明。

更多详情请参阅 LICENSE 文件。

TerraTorch 快速上手指南

TerraTorch 是一个基于 PyTorch Lightning 和 TorchGeo 的地理空间领域库，专为**地理空间基础模型（Geospatial Foundation Models）**的微调和推理设计。它支持图像分割、分类和像素级回归任务，并集成了 Prithvi、SatMAE、Clay 等主流预训练骨干网络。

1. 环境准备

系统要求

• Python: 建议版本 >= 3.9（若需使用天气基础模型部分功能，需 Python >= 3.11）
• 操作系统: Linux, macOS, Windows (WSL 推荐)

前置依赖

TerraTorch 强依赖 GDAL 库处理地理空间数据。GDAL 的安装通常较为复杂，强烈建议使用 Conda 环境自动解决依赖。

• 推荐方案: 使用 conda 或 mamba 创建环境，可自动安装 GDAL。
• 备选方案: 若使用 pip 安装，需先在系统中手动编译安装 GDAL。

2. 安装步骤

方案 A：使用 Conda（推荐，自动解决 GDAL 依赖）

这是最稳妥的安装方式，特别适合没有配置过 GDAL 的用户。

# 创建新环境并安装 terratorch (conda-forge 源会自动处理 gdal 依赖)
conda install -c conda-forge terratorch

方案 B：使用 Pip

确保 pip 版本 >= 21.8。

# 升级 pip
python -m pip install --upgrade pip

# 安装最新稳定版
pip install terratorch

# 或者安装主分支最新版本
pip install git+https://github.com/terrastackai/terratorch.git

注意：若使用此方法，请确保系统已预先正确安装 GDAL，否则可能会报错。

方案 C：开发者安装

如果您需要修改源码或贡献代码：

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

3. 基本使用

TerraTorch 的核心优势在于通过配置文件或代码快速调用预训练模型进行微调。以下是一个最简单的使用流程示例。

步骤 1: 准备数据

TerraTorch 内置了对 TorchGeo 数据集的支持。您只需指向数据目录，无需编写自定义 Dataset 类。假设您有一个包含卫星影像和标签的目录结构。

步骤 2: 编写配置文件 (YAML)

创建一个名为 config.yaml 的文件，定义模型、数据和训练参数。以下是一个使用 Prithvi 骨干网络进行图像分割的简化示例：

model:
  backbone: prithvi_100M
  decoder: unet
  task: segmentation
  
data:
  datamodule: torchgeo
  data_root: ./path/to/your/data
  bands: [B02, B03, B04, B08, B11, B12] # Sentinel-2 波段示例
  
trainer:
  max_epochs: 10
  accelerator: gpu
  devices: 1

步骤 3: 启动训练

使用命令行工具直接启动训练任务：

terratorch fit --config config.yaml

步骤 4: 在 Python 中使用 (可选)

您也可以在 Jupyter Notebook 或 Python 脚本中直接调用：

from terratorch.models import model_factory
from terratorch.datamodules import TorchGeoDataModule

# 构建模型
model = model_factory.build_model(
    backbone="prithvi_100M",
    decoder="unet",
    task="segmentation",
    num_classes=10
)

# 加载数据
datamodule = TorchGeoDataModule(root="./path/to/your/data")

# 后续结合 PyTorch Lightning Trainer 进行训练
# from pytorch_lightning import Trainer
# trainer = Trainer()
# trainer.fit(model, datamodule)

提示: 更多详细的架构说明和高级用法，请访问官方文档 Architecture Overview。