Merge branch 'main' into tutorial_be

microsoft · Jan 3, 2025 · a07e9e1 · a07e9e1
2 parents d2ffb64 + 5d94e18
commit a07e9e1
Show file tree

Hide file tree

Showing 45 changed files with 3,492 additions and 453 deletions.
diff --git a/.github/workflows/deploy.yaml b/.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
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -22,7 +22,7 @@ jobs:
         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 }}
@@ -51,7 +51,7 @@ jobs:
         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 }}

diff --git a/.github/workflows/style.yaml b/.github/workflows/style.yaml
@@ -24,7 +24,7 @@ jobs:
         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 }}
@@ -50,7 +50,7 @@ jobs:
         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 }}

diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -28,7 +28,7 @@ jobs:
         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 }}
@@ -48,7 +48,7 @@ jobs:
           pytest --cov --cov-report=xml
           python3 -m torchgeo --help
       - name: Report coverage
-        uses: codecov/codecov-action@v5.0.7
+        uses: codecov/codecov-action@v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
   minimum:
@@ -63,7 +63,7 @@ jobs:
         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 }}
@@ -82,7 +82,7 @@ jobs:
           pytest --cov --cov-report=xml
           python3 -m torchgeo --help
       - name: Report coverage
-        uses: codecov/codecov-action@v5.0.7
+        uses: codecov/codecov-action@v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
   datasets:
@@ -97,7 +97,7 @@ jobs:
         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 }}
@@ -114,7 +114,7 @@ jobs:
           pytest --cov --cov-report=xml
           python3 -m torchgeo --help
       - name: Report coverage
-        uses: codecov/codecov-action@v5.0.7
+        uses: codecov/codecov-action@v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 concurrency:

diff --git a/.github/workflows/tutorials.yaml b/.github/workflows/tutorials.yaml
@@ -26,7 +26,7 @@ jobs:
         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 }}

diff --git a/README.md b/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).
@@ -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

diff --git a/docs/conf.py b/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'),

diff --git a/docs/index.rst b/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
@@ -26,8 +35,8 @@ torchgeo
 
 .. toctree::
    :maxdepth: 1
-   :caption: Tutorials
 
+   :caption: Tutorials
    tutorials/getting_started
    tutorials/custom_raster_dataset
    tutorials/transforms
@@ -36,8 +45,6 @@ torchgeo
    tutorials/pretrained_weights
    tutorials/land_cover
 
-.. toctree::
-   :maxdepth: 1
    :caption: PyTorch Libraries
 
    PyTorch <https://pytorch.org/docs>

diff --git a/docs/tutorials/basic_usage.rst b/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
diff --git a/docs/tutorials/case_studies.rst b/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