Merge branch 'main' into mdas

.github/workflows/deploy.yaml

@@ -21,7 +21,7 @@ jobs:
       - name: Build project
         run: python3 -m build
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4.4.3
+        uses: actions/upload-artifact@v4.5.0
         with:
           name: pypi-dist
           path: dist/
@@ -42,4 +42,4 @@ jobs:
           name: pypi-dist
           path: dist/
       - name: Publish to PyPI
-        uses: pypa/[email protected].2
+        uses: pypa/[email protected].3

.github/workflows/release.yaml

@@ -17,15 +17,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.12'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-integration
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
       - name: Install pip dependencies
         if: steps.cache.outputs.cache-hit != 'true'
         run: |
@@ -45,15 +46,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.12'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-tutorials
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}-tutorials
       - name: Install pip dependencies
         if: steps.cache.outputs.cache-hit != 'true'
         run: |

.github/workflows/style.yaml

@@ -19,15 +19,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.12'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('requirements/required.txt') }}-${{ hashFiles('requirements/datasets.txt') }}-${{ hashFiles('requirements/style.txt') }}-${{ hashFiles('requirements/tests.txt') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('requirements/required.txt', 'requirements/datasets.txt', 'requirements/style.txt', 'requirements/tests.txt') }}
       - name: Install pip dependencies
         if: steps.cache.outputs.cache-hit != 'true'
         run: |
@@ -44,15 +45,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.12'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('requirements/style.txt') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('requirements/style.txt') }}
       - name: Install pip dependencies
         if: steps.cache.outputs.cache-hit != 'true'
         run: |

.github/workflows/tests.yaml

@@ -23,15 +23,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: ${{ matrix.python-version }}
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('requirements/required.txt') }}-${{ hashFiles('requirements/datasets.txt') }}-${{ hashFiles('requirements/tests.txt') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('requirements/required.txt', 'requirements/datasets.txt', 'requirements/tests.txt') }}
         if: ${{ runner.os != 'macOS' }}
       - name: Setup headless display for pyvista
         uses: pyvista/setup-headless-display-action@v3
@@ -47,7 +48,7 @@ jobs:
           pytest --cov --cov-report=xml
           python3 -m torchgeo --help
       - name: Report coverage
-        uses: codecov/codecov-action@v5.0.2
+        uses: codecov/codecov-action@v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
   minimum:
@@ -57,15 +58,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.10'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('requirements/min-reqs.old') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('requirements/min-reqs.old') }}
       - name: Setup headless display for pyvista
         uses: pyvista/setup-headless-display-action@v3
       - name: Install pip dependencies
@@ -80,7 +82,7 @@ jobs:
           pytest --cov --cov-report=xml
           python3 -m torchgeo --help
       - name: Report coverage
-        uses: codecov/codecov-action@v5.0.2
+        uses: codecov/codecov-action@v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
   datasets:
@@ -90,15 +92,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.12'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('requirements/required.txt') }}-${{ hashFiles('requirements/tests.txt') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('requirements/required.txt', 'requirements/tests.txt') }}
       - name: Install pip dependencies
         if: steps.cache.outputs.cache-hit != 'true'
         run: |
@@ -111,7 +114,7 @@ jobs:
           pytest --cov --cov-report=xml
           python3 -m torchgeo --help
       - name: Report coverage
-        uses: codecov/codecov-action@v5.0.2
+        uses: codecov/codecov-action@v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 concurrency:

.github/workflows/tutorials.yaml

@@ -21,15 +21,16 @@ jobs:
       - name: Clone repo
         uses: actions/[email protected]
       - name: Set up python
+        id: setup-python
         uses: actions/[email protected]
         with:
           python-version: '3.12'
       - name: Cache dependencies
-        uses: actions/cache@v4.1.2
+        uses: actions/cache@v4.2.0
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ env.pythonLocation }}-${{ hashFiles('requirements/required.txt') }}-${{ hashFiles('requirements/docs.txt') }}-${{ hashFiles('requirements/tests.txt') }}-tutorials
+          key: ${{ runner.os }}-${{ runner.arch }}-Python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('requirements/required.txt', 'requirements/docs.txt', 'requirements/tests.txt') }}-tutorials
       - name: Install pip dependencies
         if: steps.cache.outputs.cache-hit != 'true'
         run: |

README.md

@@ -28,8 +28,8 @@ Testing:
 
 The recommended way to install TorchGeo is with [pip](https://pip.pypa.io/):
 
-```console
-$ pip install torchgeo
+```sh
+pip install torchgeo
 ```
 
 For [conda](https://docs.conda.io/) and [spack](https://spack.io/) installation instructions, see the [documentation](https://torchgeo.readthedocs.io/en/stable/user/installation.html).
@@ -72,15 +72,15 @@ Many remote sensing applications involve working with [_geospatial datasets_](ht
 In this example, we show how easy it is to work with geospatial data and to sample small image patches from a combination of [Landsat](https://www.usgs.gov/landsat-missions) and [Cropland Data Layer (CDL)](https://data.nal.usda.gov/dataset/cropscape-cropland-data-layer) data using TorchGeo. First, we assume that the user has Landsat 7 and 8 imagery downloaded. Since Landsat 8 has more spectral bands than Landsat 7, we'll only use the bands that both satellites have in common. We'll create a single dataset including all images from both Landsat 7 and 8 data by taking the union between these two datasets.
 
 ```python
-landsat7 = Landsat7(root="...", bands=["B1", ..., "B7"])
-landsat8 = Landsat8(root="...", bands=["B2", ..., "B8"])
+landsat7 = Landsat7(paths="...", bands=["B1", ..., "B7"])
+landsat8 = Landsat8(paths="...", bands=["B2", ..., "B8"])
 landsat = landsat7 | landsat8
 ```
 
 Next, we take the intersection between this dataset and the CDL dataset. We want to take the intersection instead of the union to ensure that we only sample from regions that have both Landsat and CDL data. Note that we can automatically download and checksum CDL data. Also note that each of these datasets may contain files in different coordinate reference systems (CRS) or resolutions, but TorchGeo automatically ensures that a matching CRS and resolution is used.
 
 ```python
-cdl = CDL(root="...", download=True, checksum=True)
+cdl = CDL(paths="...", download=True, checksum=True)
 dataset = landsat & cdl
 ```
 
@@ -192,7 +192,7 @@ trainer.fit(model=task, datamodule=datamodule)
 
 TorchGeo also supports command-line interface training using [LightningCLI](https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html). It can be invoked in two ways:
 
-```console
+```sh
 # If torchgeo has been installed
 torchgeo
 # If torchgeo has been installed, or if it has been cloned to the current directory
@@ -201,7 +201,7 @@ python3 -m torchgeo
 
 It supports command-line configuration or YAML/JSON config files. Valid options can be found from the help messages:
 
-```console
+```sh
 # See valid stages
 torchgeo --help
 # See valid trainer options
@@ -233,7 +233,7 @@ data:
 
 we can see the script in action:
 
-```console
+```sh
 # Train and validate a model
 torchgeo fit --config config.yaml
 # Validate-only

docs/api/datamodules.rst

@@ -124,6 +124,11 @@ GID-15
 
 .. autoclass:: GID15DataModule
 
+HySpecNet-11k
+^^^^^^^^^^^^^
+
+.. autoclass:: HySpecNet11kDataModule
+
 Inria Aerial Image Labeling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -213,6 +218,11 @@ SustainBench Crop Yield
 
 .. autoclass:: SustainBenchCropYieldDataModule
 
+TreeSatAI
+^^^^^^^^^
+
+.. autoclass:: TreeSatAIDataModule
+
 Tropical Cyclone
 ^^^^^^^^^^^^^^^^
 

docs/api/datasets.rst

@@ -312,6 +312,11 @@ GID-15
 
 .. autoclass:: GID15
 
+HySpecNet-11k
+^^^^^^^^^^^^^
+
+.. autoclass:: HySpecNet11k
+
 IDTReeS
 ^^^^^^^
 
@@ -474,6 +479,11 @@ SustainBench Crop Yield
 
 .. autoclass:: SustainBenchCropYield
 
+TreeSatAI
+^^^^^^^^^
+
+.. autoclass:: TreeSatAI
+
 Tropical Cyclone
 ^^^^^^^^^^^^^^^^
 

docs/api/datasets/non_geo_datasets.csv

@@ -21,6 +21,7 @@ Dataset,Task,Source,License,# Samples,# Classes,Size (px),Resolution (m),Bands
 `Forest Damage`_,OD,Drone imagery,"CDLA-Permissive-1.0","1,543",4,"1,500x1,500",,RGB
 `GeoNRW`_,S,Aerial,"CC-BY-4.0","7,783",11,"1,000x1,000",1,"RGB, DEM"
 `GID-15`_,S,Gaofen-2,-,150,15,"6,800x7,200",3,RGB
+`HySpecNet-11k`_,-,EnMAP,CC0-1.0,11k,-,128,30,HSI
 `IDTReeS`_,"OD,C",Aerial,"CC-BY-4.0",591,33,200x200,0.1--1,RGB
 `Inria Aerial Image Labeling`_,S,Aerial,-,360,2,"5,000x5,000",0.3,RGB
 `LandCover.ai`_,S,Aerial,"CC-BY-NC-SA-4.0","10,674",5,512x512,0.25--0.5,RGB
@@ -53,6 +54,7 @@ Dataset,Task,Source,License,# Samples,# Classes,Size (px),Resolution (m),Bands
 `SSL4EO-L Benchmark`_,S,Lansat & CDL,"CC0-1.0",25K,134,264x264,30,MSI
 `SSL4EO-L Benchmark`_,S,Lansat & NLCD,"CC0-1.0",25K,17,264x264,30,MSI
 `SustainBench Crop Yield`_,R,MODIS,"CC-BY-SA-4.0",11k,-,32x32,-,MSI
+`TreeSatAI`_,"C, R, S","Aerial, Sentinel-1/2",CC-BY-4.0,50K,"12, 15, 20","6, 20, 304","0.2, 10","CIR, MSI, SAR"
 `Tropical Cyclone`_,R,GOES 8--16,"CC-BY-4.0","108,110",-,256x256,4K--8K,MSI
 `UC Merced`_,C,USGS National Map,"public domain","2,100",21,256x256,0.3,RGB
 `USAVars`_,R,NAIP Aerial,"CC-BY-4.0",100K,-,-,4,"RGB, NIR"

docs/conf.py

@@ -59,6 +59,8 @@
     ('py:class', 'fiona.model.Feature'),
     ('py:class', 'kornia.augmentation._2d.intensity.base.IntensityAugmentationBase2D'),
     ('py:class', 'kornia.augmentation.base._AugmentationBase'),
+    ('py:class', 'lightning.pytorch.utilities.types.LRSchedulerConfig'),
+    ('py:class', 'lightning.pytorch.utilities.types.OptimizerConfig'),
     ('py:class', 'lightning.pytorch.utilities.types.OptimizerLRSchedulerConfig'),
     ('py:class', 'segmentation_models_pytorch.base.model.SegmentationModel'),
     ('py:class', 'timm.models.resnet.ResNet'),

docs/index.rst

@@ -12,6 +12,15 @@ torchgeo
    user/glossary
    user/alternatives
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/getting_started
+   tutorials/basic_usage
+   tutorials/case_studies
+   tutorials/customization
+
 .. toctree::
    :maxdepth: 2
    :caption: Package Reference
@@ -24,17 +33,6 @@ torchgeo
    api/trainers
    api/transforms
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Tutorials
-
-   tutorials/getting_started
-   tutorials/custom_raster_dataset
-   tutorials/transforms
-   tutorials/indices
-   tutorials/trainers
-   tutorials/pretrained_weights
-
 .. toctree::
    :maxdepth: 1
    :caption: PyTorch Libraries

docs/tutorials/basic_usage.rst

@@ -0,0 +1,20 @@
+Basic Usage
+===========
+
+The following tutorials introduce the basic concepts and components of TorchGeo:
+
+* `Transforms <transforms.ipynb>`_: Preprocessing and data augmentation transforms for geospatial data
+* `Spectral Indices <indices.ipynb>`_: Visualizing and appending spectral indices
+* `Pretrained Weights <pretrained_weights.ipynb>`_: Models and pretrained weights
+* `Lightning Trainers <trainers.ipynb>`_: PyTorch Lightning data modules and trainers
+* `Command-Line Interface <cli.ipynb>`_: TorchGeo's command-line interface
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   transforms
+   indices
+   pretrained_weights
+   trainers
+   cli

docs/tutorials/case_studies.rst

@@ -0,0 +1,14 @@
+Case Studies
+============
+
+The following case studies present end-to-end workflows for common use cases of geospatial machine learning:
+
+* `Earth Surface Water <earth_surface_water.ipynb>`_: A workflow for mapping surface water, including lakes and rivers
+
+Do you have a use case that is missing from this list? Please open a pull request to add tutorials for your own use cases.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   earth_surface_water