Update tutorial for transforms and pretrained weights (#2454)

* update tutorial for transforms * update tutorial for pretrained_weights * fix tutorial of transforms * solve Adam's reviews * Change to original author * Change to original author, add more readings * Code formatting --------- Co-authored-by: Adam J. Stewart <[email protected]>
microsoft · Dec 8, 2024 · 6109fea · 6109fea
1 parent 53254d2
commit 6109fea
Show file tree

Hide file tree

Showing 2 changed files with 65 additions and 18 deletions.
diff --git a/docs/tutorials/pretrained_weights.ipynb b/docs/tutorials/pretrained_weights.ipynb
@@ -1,14 +1,15 @@
 {
  "cells": [
   {
-   "cell_type": "markdown",
+   "cell_type": "code",
+   "execution_count": null,
    "metadata": {
     "id": "p63J-QmUrMN-"
    },
+   "outputs": [],
    "source": [
-    "Copyright (c) Microsoft Corporation. All rights reserved.\n",
-    "\n",
-    "Licensed under the MIT License."
+    "# Copyright (c) Microsoft Corporation. All rights reserved.\n",
+    "# Licensed under the MIT License."
    ]
   },
   {
@@ -19,6 +20,8 @@
    "source": [
     "# Pretrained Weights\n",
     "\n",
+    "_Written by: Nils Lehmann_\n",
+    "\n",
     "In this tutorial, we demonstrate some available pretrained weights in TorchGeo. The implementation follows torchvisions' recently introduced [Multi-Weight API](https://pytorch.org/blog/introducing-torchvision-new-multi-weight-support-api/). We will use the [EuroSAT](https://torchgeo.readthedocs.io/en/stable/api/datasets.html#eurosat) dataset throughout this tutorial. Specifically, a subset containing only 100 images.\n",
     "\n",
     "It's recommended to run this notebook on Google Colab if you don't have your own GPU. Click the \"Open in Colab\" button above to get started."
@@ -147,9 +150,11 @@
    "source": [
     "## Weights\n",
     "\n",
-    "Available pretrained weights are listed on the model documentation [page](https://torchgeo.readthedocs.io/en/stable/api/models.html). While some weights only accept RGB channel input, some weights have been pretrained on Sentinel 2 imagery with 13 input channels and can hence prove useful for transfer learning tasks involving Sentinel 2 data.\n",
+    "Pretrained weights for `torchgeo.models` are available and sorted by satellite or sensor type: sensor-agnostic, Landsat, NAIP, Sentinel-1, and Sentinel-2. Refer to the [model documentation](https://torchgeo.readthedocs.io/en/stable/api/models.html#pretrained-weights) for a complete list of weights. Choose from the provided pre-trained weights based on your specific use case.\n",
+    "\n",
+    "While some weights only accept RGB channel input, some weights have been pretrained on Sentinel-2 imagery with 13 input channels and can hence prove useful for transfer learning tasks involving Sentinel-2 data.\n",
     "\n",
-    "To access these weights you can do the following:"
+    "To use these weights, you can load them as follows:"
    ]
   },
   {
@@ -169,7 +174,16 @@
     "id": "EIpnXuXgrMOM"
    },
    "source": [
-    "This set of weights is a torchvision `WeightEnum` and holds information such as the download url link or additional meta data. TorchGeo takes care of the downloading and initialization of models with a desired set of weights. Given that EuroSAT is a classification dataset, we can use a `ClassificationTask` object that holds the model and optimizer object as well as the training logic."
+    "This set of weights is a torchvision `WeightEnum` and holds information such as the download url link or additional meta data. TorchGeo takes care of the downloading and initialization of models with a desired set of weights. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`torchgeo.trainers` provides specialized task classes that simplify training workflows for common geospatial tasks. Depending on your objective, you can select the appropriate trainer class, such as `ClassificationTask` for classification, `SemanticSegmentationTask` for semantic segmentation, or other task-specific trainers. Check the [trainers documentation](https://torchgeo.readthedocs.io/en/stable/api/trainers.html) for more information.\n",
+    "\n",
+    "Given that EuroSAT is a classification dataset, we can use a `ClassificationTask` object that holds the model and optimizer as well as the training logic."
    ]
   },
   {
@@ -495,7 +509,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.13.0"
   },
   "vscode": {
    "interpreter": {
@@ -504,5 +518,5 @@
   }
  },
  "nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 4
 }
diff --git a/docs/tutorials/transforms.ipynb b/docs/tutorials/transforms.ipynb
@@ -1,14 +1,15 @@
 {
  "cells": [
   {
-   "cell_type": "markdown",
+   "cell_type": "code",
+   "execution_count": null,
    "metadata": {
     "id": "DYndcZst_kdr"
    },
+   "outputs": [],
    "source": [
-    "Copyright (c) Microsoft Corporation. All rights reserved.\n",
-    "\n",
-    "Licensed under the MIT License."
+    "# Copyright (c) Microsoft Corporation. All rights reserved.\n",
+    "# Licensed under the MIT License."
    ]
   },
   {
@@ -20,6 +21,13 @@
     "# Transforms"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "_Written by: Isaac A. Corley_"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -408,7 +416,7 @@
     "id": "p28C8cTGE3dP"
    },
    "source": [
-    "Transforms are able to operate across batches of samples and singular samples. This allows them to be used inside the dataset itself or externally, chained together with other transform operations using `nn.Sequential`. "
+    "`torchgeo.transforms` work seamlessly with both singular samples and batches of data. They can be applied within datasets or externally and combined with other transforms using `nn.Sequential`. Built for multispectral imagery, they are fully compatible with `torchvision.transforms` and `kornia.augmentation`."
    ]
   },
   {
@@ -429,13 +437,24 @@
     "print(x.dtype, x.min(), x.max())"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Appending Indices\n",
+    "\n",
+    "`torchgeo.transforms` support appending indices to a specified channel dimension.\n",
+    "\n",
+    "For detailed usage of all available transforms, refer to the [transforms documentation](https://torchgeo.readthedocs.io/en/stable/api/transforms.html)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
     "id": "KRjb-u0EEmDf"
    },
    "source": [
-    "Indices can also be computed on batches of images and appended as an additional band to the specified channel dimension. Notice how the number of channels increases from 13 -> 14."
+    "The following example shows how indices can be computed on batches of images and appended as an additional band to the specified channel dimension. Notice how the number of channels increases from 13 -> 14."
    ]
   },
   {
@@ -500,7 +519,9 @@
     "id": "w4ZbjxPyHoiB"
    },
    "source": [
-    "It's even possible to chain indices along with augmentations from Kornia for a single callable during training."
+    "It's even possible to chain indices along with augmentations from Kornia for a single callable during training.\n",
+    "\n",
+    "When using Kornia with a dictionary input, you must explicitly set `data_keys=None` during the creation of the augmentation pipeline."
    ]
   },
   {
@@ -689,6 +710,18 @@
     "print(f\"Class Label: {dataset.classes[sample['label']]}\")\n",
     "image.resize((256, 256), resample=Image.BILINEAR)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Additional Reading\n",
+    "\n",
+    "To learn more about preprocessing and data augmentation transforms, the following external resources may be helpful:\n",
+    "\n",
+    "* [Kornia augmentations](https://kornia.readthedocs.io/en/latest/augmentation.html)\n",
+    "* [torchvision transforms](https://pytorch.org/vision/main/transforms.html)"
+   ]
   }
  ],
  "metadata": {
@@ -717,9 +750,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.13.0"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 4
 }