diff --git a/docs/index.rst b/docs/index.rst index 561a496d67a..02ba03a8cc5 100644 --- 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 @@ -24,23 +33,6 @@ torchgeo api/trainers api/transforms -.. toctree:: - :maxdepth: 1 - :caption: Tutorials - - tutorials/getting_started - tutorials/pytorch - tutorials/geospatial - tutorials/torchgeo - tutorials/contribute_non_geo_dataset - tutorials/custom_raster_dataset - tutorials/contribute_datamodule - tutorials/transforms - tutorials/indices - tutorials/trainers - tutorials/pretrained_weights - tutorials/earth_surface_water - .. toctree:: :maxdepth: 1 :caption: PyTorch Libraries diff --git a/docs/tutorials/basic_usage.rst b/docs/tutorials/basic_usage.rst new file mode 100644 index 00000000000..10fcb97b42d --- /dev/null +++ b/docs/tutorials/basic_usage.rst @@ -0,0 +1,18 @@ +Basic Usage +=========== + +The following tutorials introduce the basic concepts and components of TorchGeo: + +* `Transforms `_: Preprocessing and data augmentation transforms for geospatial data +* `Indices `_: Spectral indices +* `Pretrained Weights `_: Models and pretrained weights +* `Lightning Trainers `_: PyTorch Lightning data modules and trainers + +.. toctree:: + :hidden: + :maxdepth: 1 + + transforms + indices + pretrained_weights + trainers diff --git a/docs/tutorials/case_studies.rst b/docs/tutorials/case_studies.rst new file mode 100644 index 00000000000..aee09a94265 --- /dev/null +++ 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 `_: 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 diff --git a/docs/tutorials/contribute_non_geo_dataset.ipynb b/docs/tutorials/contribute_non_geo_dataset.ipynb index 655deb1c8d7..4a702222daf 100644 --- a/docs/tutorials/contribute_non_geo_dataset.ipynb +++ b/docs/tutorials/contribute_non_geo_dataset.ipynb @@ -259,7 +259,11 @@ "# Create dummy data for all splits and filenames\n", "for split in splits:\n", " for filename in image_file_names:\n", - " create_input_image(split, filename)\n", + " create_input_image(\n", + " os.path.join(root_dir, 'image', split, filename),\n", + " (IMG_SIZE, IMG_SIZE),\n", + " range(2**16),\n", + " )\n", " create_target_images(split, filename.replace('_', '_target_'))\n", "\n", "# Zip directory\n", diff --git a/docs/tutorials/customization.rst b/docs/tutorials/customization.rst new file mode 100644 index 00000000000..07b0870607b --- /dev/null +++ b/docs/tutorials/customization.rst @@ -0,0 +1,20 @@ +Customization +============= + +Is TorchGeo missing a dataset or model you need? Would you like to modify the default augmentations for a data module or extend a builtin trainer? + +The following tutorials will teach you how to customize TorchGeo to meet your needs: + +* `Custom Non-Geospatial Datasets `_: How to create and contribute a new NonGeoDataset +* `Custom Raster Datasets `_: How to create a new RasterDataset +* `Custom Data Module `_: How to create and contribute a new DataModule + +TorchGeo is a community-driven open source library. If there is a feature missing that you would like to add, please open a pull request to add it. See the ref:`contributing` guidelines to get started. + +.. toctree:: + :hidden: + :maxdepth: 1 + + contribute_non_geo_dataset + custom_raster_dataset + contribute_datamodule diff --git a/docs/tutorials/getting_started.ipynb b/docs/tutorials/getting_started.ipynb deleted file mode 100644 index 9bdb0eed11c..00000000000 --- a/docs/tutorials/getting_started.ipynb +++ /dev/null @@ -1,324 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "35303546", - "metadata": {}, - "source": [ - "Copyright (c) Microsoft Corporation. All rights reserved.\n", - "\n", - "Licensed under the MIT License." - ] - }, - { - "cell_type": "markdown", - "id": "9478ed9a", - "metadata": { - "id": "NdrXRgjU7Zih" - }, - "source": [ - "# Getting Started\n", - "\n", - "In this tutorial, we demonstrate some of the basic features of TorchGeo and show how easy it is to use if you're already familiar with other PyTorch domain libraries like torchvision.\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." - ] - }, - { - "cell_type": "markdown", - "id": "34f10e9f", - "metadata": { - "id": "lCqHTGRYBZcz" - }, - "source": [ - "## Setup\n", - "\n", - "First, we install TorchGeo." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "019092f0", - "metadata": {}, - "outputs": [], - "source": [ - "%pip install torchgeo planetary_computer" - ] - }, - { - "cell_type": "markdown", - "id": "4db9f791", - "metadata": { - "id": "dV0NLHfGBMWl" - }, - "source": [ - "## Imports\n", - "\n", - "Next, we import TorchGeo and any other libraries we need." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "3d92b0f1", - "metadata": { - "id": "entire-albania" - }, - "outputs": [], - "source": [ - "import os\n", - "import tempfile\n", - "\n", - "import planetary_computer\n", - "from torch.utils.data import DataLoader\n", - "\n", - "from torchgeo.datasets import NAIP, ChesapeakeDE, stack_samples\n", - "from torchgeo.datasets.utils import download_url\n", - "from torchgeo.samplers import RandomGeoSampler" - ] - }, - { - "cell_type": "markdown", - "id": "7f26e4b8", - "metadata": { - "id": "5rLknZxrBEMz" - }, - "source": [ - "## Datasets\n", - "\n", - "For this tutorial, we'll be using imagery from the [National Agriculture Imagery Program (NAIP)](https://catalog.data.gov/dataset/national-agriculture-imagery-program-naip) and labels from the [Chesapeake Bay High-Resolution Land Cover Project](https://www.chesapeakeconservancy.org/conservation-innovation-center/high-resolution-data/land-cover-data-project/). First, we manually download a few NAIP tiles and create a PyTorch Dataset." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "4a39af46", - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 232, - "referenced_widgets": [ - "d00a2177bf4b4b8191bfc8796f0e749f", - "17d6b81aec50455989276b595457cc7f", - "06ccd130058b432dbfa025c102eaeb27", - "6bc5b9872b574cb5aa6ebd1d44e7a71f", - "f7746f028f874a85b6101185fc9a8efc", - "f7ef78d6f87a4a2685788e395525fa7c", - "5b2450e316e64b4ba432c78b63275124", - "d3bbd6112f144c77bc68e5f2a7a355ff", - "a0300b1252cd4da5a798b55c15f8f5fd", - "793c2851b6464b398f7b4d2f2f509722", - "8dd61c8479d74c95a55de147e04446b3", - "b57d15e6c32b4fff8994ae67320972f6", - "9a34f8907a264232adf6b0d0543461dd", - "e680eda3c84c440083e2959f04431bea", - "a073e33fd9ae4125822fc17971233770", - "87faaa32454a42939d3bd405e726228c", - "b3d4c9c99bec4e69a199e45920d52ce4", - "a215f3310ea543d1a8991f57ec824872", - "569f60397fd6440d825e8afb83b4e1ae", - "b7f604d2ba4e4328a451725973fa755f", - "737fa148dfae49a18cc0eabbe05f2d0f", - "0b6613adbcc74165a9d9f74988af366e", - "b25f274c737d4212b3ffeedb2372ba22", - "ef0fc75ff5044171be942a6b3ba0c2da", - "612d84013a6e4890a48eb229f6431233", - "9a689285370646ab800155432ea042a5", - "014ed48a23234e8b81dd7ac4dbf95817", - "93c536a27b024728a00486b1f68b4dde", - "8a8538a91a74439b81e3f7c6516763e3", - "caf540562b484594bab8d6210dd7c2c1", - "99cd2e65fb104380953745f2e0a93fac", - "c5b818707bb64c5a865236a46399cea2", - "54f5db9555c44efa9370cbb7ab58e142", - "1d83b20dbb9c4c6a9d5c100fe4770ba4", - "c51b2400ca9442a9a9e0712d5778cd9a", - "bd2e44a8eb1a4c19a32da5a1edd647d1", - "0f9feea4b8344a7f8054c9417150825e", - "31acb7a1ca8940078e1aacd72e547f47", - "0d0ca8d64d3e4c2f88d87342808dd677", - "54402c5f8df34b83b95c94104b26e2c6", - "910b98584fa74bb5ad308fe770f5b40e", - "b2dce834ee044d69858389178b493a2b", - "237f2e31bcfe476baafae8d922877e07", - "43ac7d95481b4ea3866feef6ace2f043" - ] - }, - "id": "e3138ac3", - "outputId": "11589c46-eee6-455d-839b-390f2934d834" - }, - "outputs": [], - "source": [ - "naip_root = os.path.join(tempfile.gettempdir(), 'naip')\n", - "naip_url = (\n", - " 'https://naipeuwest.blob.core.windows.net/naip/v002/de/2018/de_060cm_2018/38075/'\n", - ")\n", - "tiles = [\n", - " 'm_3807511_ne_18_060_20181104.tif',\n", - " 'm_3807511_se_18_060_20181104.tif',\n", - " 'm_3807512_nw_18_060_20180815.tif',\n", - " 'm_3807512_sw_18_060_20180815.tif',\n", - "]\n", - "for tile in tiles:\n", - " url = planetary_computer.sign(naip_url + tile)\n", - " download_url(url, naip_root, filename=tile)\n", - "\n", - "naip = NAIP(naip_root)" - ] - }, - { - "cell_type": "markdown", - "id": "e25bad40", - "metadata": { - "id": "HQVji2B22Qfu" - }, - "source": [ - "Next, we tell TorchGeo to automatically download the corresponding Chesapeake labels." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "689bb2b0", - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "2Ah34KAw2biY", - "outputId": "03b7bdf0-78c1-4a13-ac56-59de740d7f59" - }, - "outputs": [], - "source": [ - "chesapeake_root = os.path.join(tempfile.gettempdir(), 'chesapeake')\n", - "os.makedirs(chesapeake_root, exist_ok=True)\n", - "chesapeake = ChesapeakeDE(chesapeake_root, crs=naip.crs, res=naip.res, download=True)" - ] - }, - { - "cell_type": "markdown", - "id": "56f2d78b", - "metadata": { - "id": "OWUhlfpD22IX" - }, - "source": [ - "Finally, we create an IntersectionDataset so that we can automatically sample from both GeoDatasets simultaneously." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "daefbc4d", - "metadata": { - "id": "WXxy8F8l2-aC" - }, - "outputs": [], - "source": [ - "dataset = naip & chesapeake" - ] - }, - { - "cell_type": "markdown", - "id": "ded44652", - "metadata": { - "id": "yF_R54Yf3EUd" - }, - "source": [ - "## Sampler\n", - "\n", - "Unlike typical PyTorch Datasets, TorchGeo GeoDatasets are indexed using lat/long/time bounding boxes. This requires us to use a custom GeoSampler instead of the default sampler/batch_sampler that comes with PyTorch." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "b8a0d99c", - "metadata": { - "id": "RLczuU293itT" - }, - "outputs": [], - "source": [ - "sampler = RandomGeoSampler(dataset, size=1000, length=10)" - ] - }, - { - "cell_type": "markdown", - "id": "5b8c1c52", - "metadata": { - "id": "OWa-mmYd8S6K" - }, - "source": [ - "## DataLoader\n", - "\n", - "Now that we have a Dataset and Sampler, we can combine these into a single DataLoader." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "96faa142", - "metadata": { - "id": "jfx-9ZmU8ZTc" - }, - "outputs": [], - "source": [ - "dataloader = DataLoader(dataset, sampler=sampler, collate_fn=stack_samples)" - ] - }, - { - "cell_type": "markdown", - "id": "64ae63f7", - "metadata": { - "id": "HZIfqqW58oZe" - }, - "source": [ - "## Training\n", - "\n", - "Other than that, the rest of the training pipeline is the same as it is for torchvision." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8a2b44f8", - "metadata": { - "id": "7sGmNvBy8uIg" - }, - "outputs": [], - "source": [ - "for sample in dataloader:\n", - " image = sample['image']\n", - " target = sample['mask']" - ] - } - ], - "metadata": { - "colab": { - "collapsed_sections": [], - "name": "getting_started.ipynb", - "provenance": [] - }, - "execution": { - "timeout": 1200 - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst new file mode 100644 index 00000000000..8049a95a20f --- /dev/null +++ b/docs/tutorials/getting_started.rst @@ -0,0 +1,18 @@ +Getting Started +=============== + +New to deep learning or remote sensing? First time using PyTorch or TorchGeo? You've come to the right place. + +The following tutorials will teach you enough to get started: + +* `Introduction to PyTorch `_: A brief overview of deep learning with PyTorch +* `Introduction to Geospatial Data `_: A brief overview of the challenges of working with geospatial data +* `Introduction to TorchGeo `_: A brief overview of the design of TorchGeo + +.. toctree:: + :hidden: + :maxdepth: 1 + + pytorch + geospatial + torchgeo diff --git a/docs/user/contributing.rst b/docs/user/contributing.rst index ae3cdd41045..033fcecdea2 100644 --- a/docs/user/contributing.rst +++ b/docs/user/contributing.rst @@ -1,3 +1,5 @@ +.. _contributing: + Contributing ============