TorchGeo

Common errors

• ModuleNotFoundError: No module named 'torchgeo.datasets.utils'

  cause The `utils` submodule within `torchgeo.datasets` (or other modules) may have been refactored, moved, or its contents integrated directly into other classes/functions.
  fix Check the official TorchGeo documentation or GitHub repository for the correct import path for the specific utility you are trying to use. The functionality might now be directly available on a class or in a different submodule.

• UserWarning: `torchgeo` is being used with an unsupported `lightning` version. This might lead to unexpected behavior.

  cause The installed version of PyTorch Lightning is not officially tested or supported by the current TorchGeo version, leading to potential incompatibilities.
  fix Verify the required `lightning` version in TorchGeo's `pyproject.toml` or `setup.py`. Downgrade or upgrade your `lightning` installation to a compatible version, e.g., `pip install 'lightning<2.5'` if 2.5.x is causing issues with your TorchGeo version.

• TypeError: __init__ missing 1 required positional argument: 'root'

  cause Many `torchgeo.datasets` classes, especially those loading data from disk, require a `root` directory path as a mandatory argument during initialization. This error occurs if `root` is omitted or incorrectly passed.
  fix When initializing a dataset, always provide the `root` argument pointing to the directory where the dataset should be stored or is located, e.g., `dataset = EuroSAT(root='./data', download=True)`.

• RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cpu and cuda:0!

  cause This is a common PyTorch error indicating that tensors involved in an operation are on different devices (CPU vs. GPU), which can happen if not all data or models are explicitly moved to CUDA.
  fix Ensure all relevant tensors and models are moved to the same device (e.g., CUDA) before operations. Use `.to(device)` where `device = 'cuda' if torch.cuda.is_available() else 'cpu'`. For DataLoaders, custom collate functions or transform steps might be needed to ensure output tensors are on the desired device.

Warnings

• breaking TorchGeo 0.8.0 introduced a complete rewrite of `GeoDataset` and `GeoSampler` internals. Code relying on direct manipulation or specific internal structures of these base classes might break.
  Fix: Review the official documentation for `GeoDataset` and `GeoSampler` usage patterns and update your code to align with the new API. Specifically, pay attention to how samples are structured and accessed.
• gotcha TorchGeo versions 0.9.0 and later require Python 3.12 or newer. Users on older Python versions will encounter installation errors.
  Fix: Ensure your Python environment is 3.12 or higher. Upgrade Python or create a new virtual environment with the correct version.
• gotcha There have been reported incompatibilities with specific versions of the `lightning` library (e.g., 2.5.5 was not supported in v0.7.2). Using an unsupported `lightning` version can lead to errors or unexpected behavior during training.
  Fix: Consult TorchGeo's `pyproject.toml` or `setup.py` on GitHub for the exact `lightning` version constraints. If you encounter issues, try pinning `lightning` to a known compatible version, e.g., `pip install 'lightning<2.5'` if 2.5.x had issues.
• gotcha Specific versions of `rasterio` (e.g., 1.4.0, 1.4.1) have caused issues in earlier TorchGeo versions, leading to potential crashes or incorrect data loading when processing raster data.
  Fix: Check the `rasterio` version listed in TorchGeo's dependency requirements. If you encounter `rasterio`-related errors, try updating TorchGeo to the latest version or explicitly installing a compatible `rasterio` version, for example, `pip install 'rasterio>=1.3.1,!=1.4.0,!=1.4.1'`.

Install

• pip install torchgeo Stable release
• pip install 'torchgeo[all]' With all optional dependencies

Imports

• EuroSAT

  from torchgeo.datasets import EuroSAT

• RasterDataset

  from torchgeo.datasets import RasterDataset

• RandomGeoSampler

  from torchgeo.samplers import RandomGeoSampler

• AugmentationSequential

  from torchgeo.transforms import AugmentationSequential

• ResNet18_Weights

  from torchgeo.models import ResNet18_Weights

Quickstart

This quickstart demonstrates how to load the EuroSAT dataset, apply basic transformations using `AugmentationSequential`, set up a `RandomBatchGeoSampler` for extracting image patches, and load data in batches using a standard PyTorch `DataLoader`. Note that `EuroSAT` will download the dataset to the specified root directory if it's not already present.

import torch
from torchgeo.datasets import EuroSAT
from torchgeo.transforms import AugmentationSequential, RandomGrayscale
from torchgeo.samplers import RandomBatchGeoSampler
from torch.utils.data import DataLoader
import tempfile
import os

# Initialize transforms
transforms = AugmentationSequential(
    RandomGrayscale(p=0.5),
    data_keys=["image"]
)

# Use a temporary directory for the dataset to avoid polluting the user's system
with tempfile.TemporaryDirectory() as tmpdir:
    # Initialize EuroSAT dataset (will download if not present)
    dataset = EuroSAT(root=tmpdir, split="train", transforms=transforms, download=True)

    # Initialize a sampler to get patches
    sampler = RandomBatchGeoSampler(dataset, patch_size=(64, 64), batch_size=4, length=10)

    # Create a DataLoader
    dataloader = DataLoader(dataset, sampler=sampler, num_workers=0)

    # Iterate through one batch and print shapes
    for batch in dataloader:
        image = batch["image"]
        label = batch["label"]
        print(f"Batch image shape: {image.shape}, label shape: {label.shape}")
        break # Just one batch for quickstart