| Name | torchgeo JSON |
| Version |
0.6.0
JSON |
| download |
| home_page | None |
| Summary | TorchGeo: datasets, samplers, transforms, and pre-trained models for geospatial data |
| upload_time | 2024-09-01 10:35:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) Microsoft Corporation. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE |
| keywords |
pytorch
deep learning
machine learning
remote sensing
satellite imagery
earth observation
geospatial
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<img src="https://raw.githubusercontent.com/microsoft/torchgeo/main/logo/logo-color.svg" width="400" alt="TorchGeo logo"/>
TorchGeo is a [PyTorch](https://pytorch.org/) domain library, similar to [torchvision](https://pytorch.org/vision), providing datasets, samplers, transforms, and pre-trained models specific to geospatial data.
The goal of this library is to make it simple:
1. for machine learning experts to work with geospatial data, and
2. for remote sensing experts to explore machine learning solutions.
Community:
[](https://join.slack.com/t/torchgeo/shared_invite/zt-22rse667m-eqtCeNW0yI000Tl4B~2PIw)
[](https://www.osgeo.org/community/getting-started-osgeo/)
[](https://huggingface.co/torchgeo)
[](https://pytorch.org/ecosystem/join)
Packaging:
[](https://pypi.org/project/torchgeo/)
[](https://anaconda.org/conda-forge/torchgeo)
[](https://packages.spack.io/package.html?name=py-torchgeo)
Testing:
[](https://torchgeo.readthedocs.io/en/stable/)
[](https://github.com/microsoft/torchgeo/actions/workflows/style.yaml)
[](https://github.com/microsoft/torchgeo/actions/workflows/tests.yaml)
[](https://codecov.io/gh/microsoft/torchgeo)
## Installation
The recommended way to install TorchGeo is with [pip](https://pip.pypa.io/):
```console
$ 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).
## Documentation
You can find the documentation for TorchGeo on [ReadTheDocs](https://torchgeo.readthedocs.io). This includes API documentation, contributing instructions, and several [tutorials](https://torchgeo.readthedocs.io/en/stable/tutorials/getting_started.html). For more details, check out our [paper](https://arxiv.org/abs/2111.08872), [podcast episode](https://www.youtube.com/watch?v=ET8Hb_HqNJQ), [tutorial](https://www.youtube.com/watch?v=R_FhY8aq708), and [blog post](https://pytorch.org/blog/geospatial-deep-learning-with-torchgeo/).
<p float="left">
<a href="https://www.youtube.com/watch?v=ET8Hb_HqNJQ">
<img src="https://img.youtube.com/vi/ET8Hb_HqNJQ/0.jpg" style="width:49%;">
</a>
<a href="https://www.youtube.com/watch?v=R_FhY8aq708">
<img src="https://img.youtube.com/vi/R_FhY8aq708/0.jpg" style="width:49%;">
</a>
</p>
## Example Usage
The following sections give basic examples of what you can do with TorchGeo.
First we'll import various classes and functions used in the following sections:
```python
from lightning.pytorch import Trainer
from torch.utils.data import DataLoader
from torchgeo.datamodules import InriaAerialImageLabelingDataModule
from torchgeo.datasets import CDL, Landsat7, Landsat8, VHR10, stack_samples
from torchgeo.samplers import RandomGeoSampler
from torchgeo.trainers import SemanticSegmentationTask
```
### Geospatial datasets and samplers
Many remote sensing applications involve working with [_geospatial datasets_](https://torchgeo.readthedocs.io/en/stable/api/datasets.html#geospatial-datasets)—datasets with geographic metadata. These datasets can be challenging to work with due to the sheer variety of data. Geospatial imagery is often multispectral with a different number of spectral bands and spatial resolution for every satellite. In addition, each file may be in a different coordinate reference system (CRS), requiring the data to be reprojected into a matching CRS.
<img src="https://raw.githubusercontent.com/microsoft/torchgeo/main/images/geodataset.png" alt="Example application in which we combine Landsat and CDL and sample from both"/>
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"])
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)
dataset = landsat & cdl
```
This dataset can now be used with a PyTorch data loader. Unlike benchmark datasets, geospatial datasets often include very large images. For example, the CDL dataset consists of a single image covering the entire continental United States. In order to sample from these datasets using geospatial coordinates, TorchGeo defines a number of [_samplers_](https://torchgeo.readthedocs.io/en/stable/api/samplers.html). In this example, we'll use a random sampler that returns 256 x 256 pixel images and 10,000 samples per epoch. We also use a custom collation function to combine each sample dictionary into a mini-batch of samples.
```python
sampler = RandomGeoSampler(dataset, size=256, length=10000)
dataloader = DataLoader(dataset, batch_size=128, sampler=sampler, collate_fn=stack_samples)
```
This data loader can now be used in your normal training/evaluation pipeline.
```python
for batch in dataloader:
image = batch["image"]
mask = batch["mask"]
# train a model, or make predictions using a pre-trained model
```
Many applications involve intelligently composing datasets based on geospatial metadata like this. For example, users may want to:
- Combine datasets for multiple image sources and treat them as equivalent (e.g., Landsat 7 and 8)
- Combine datasets for disparate geospatial locations (e.g., Chesapeake NY and PA)
These combinations require that all queries are present in at least one dataset, and can be created using a `UnionDataset`. Similarly, users may want to:
- Combine image and target labels and sample from both simultaneously (e.g., Landsat and CDL)
- Combine datasets for multiple image sources for multimodal learning or data fusion (e.g., Landsat and Sentinel)
These combinations require that all queries are present in both datasets, and can be created using an `IntersectionDataset`. TorchGeo automatically composes these datasets for you when you use the intersection (`&`) and union (`|`) operators.
### Benchmark datasets
TorchGeo includes a number of [_benchmark datasets_](https://torchgeo.readthedocs.io/en/stable/api/datasets.html#non-geospatial-datasets)—datasets that include both input images and target labels. This includes datasets for tasks like image classification, regression, semantic segmentation, object detection, instance segmentation, change detection, and more.
If you've used [torchvision](https://pytorch.org/vision) before, these datasets should seem very familiar. In this example, we'll create a dataset for the Northwestern Polytechnical University (NWPU) very-high-resolution ten-class ([VHR-10](https://github.com/chaozhong2010/VHR-10_dataset_coco)) geospatial object detection dataset. This dataset can be automatically downloaded, checksummed, and extracted, just like with torchvision.
```python
from torch.utils.data import DataLoader
from torchgeo.datamodules.utils import collate_fn_detection
from torchgeo.datasets import VHR10
# Initialize the dataset
dataset = VHR10(root="...", download=True, checksum=True)
# Initialize the dataloader with the custom collate function
dataloader = DataLoader(
dataset,
batch_size=128,
shuffle=True,
num_workers=4,
collate_fn=collate_fn_detection,
)
# Training loop
for batch in dataloader:
images = batch["image"] # list of images
boxes = batch["boxes"] # list of boxes
labels = batch["labels"] # list of labels
masks = batch["masks"] # list of masks
# train a model, or make predictions using a pre-trained model
```
<img src="https://raw.githubusercontent.com/microsoft/torchgeo/main/images/vhr10.png" alt="Example predictions from a Mask R-CNN model trained on the VHR-10 dataset"/>
All TorchGeo datasets are compatible with PyTorch data loaders, making them easy to integrate into existing training workflows. The only difference between a benchmark dataset in TorchGeo and a similar dataset in torchvision is that each dataset returns a dictionary with keys for each PyTorch `Tensor`.
### Pre-trained Weights
Pre-trained weights have proven to be tremendously beneficial for transfer learning tasks in computer vision. Practitioners usually utilize models pre-trained on the ImageNet dataset, containing RGB images. However, remote sensing data often goes beyond RGB with additional multispectral channels that can vary across sensors. TorchGeo is the first library to support models pre-trained on different multispectral sensors, and adopts torchvision's [multi-weight API](https://pytorch.org/blog/introducing-torchvision-new-multi-weight-support-api/). A summary of currently available weights can be seen in the [docs](https://torchgeo.readthedocs.io/en/stable/api/models.html#pretrained-weights). To create a [timm](https://github.com/huggingface/pytorch-image-models) Resnet-18 model with weights that have been pretrained on Sentinel-2 imagery, you can do the following:
```python
import timm
from torchgeo.models import ResNet18_Weights
weights = ResNet18_Weights.SENTINEL2_ALL_MOCO
model = timm.create_model("resnet18", in_chans=weights.meta["in_chans"], num_classes=10)
model.load_state_dict(weights.get_state_dict(progress=True), strict=False)
```
These weights can also directly be used in TorchGeo Lightning modules that are shown in the following section via the `weights` argument. For a notebook example, see this [tutorial](https://torchgeo.readthedocs.io/en/stable/tutorials/pretrained_weights.html).
### Reproducibility with Lightning
In order to facilitate direct comparisons between results published in the literature and further reduce the boilerplate code needed to run experiments with datasets in TorchGeo, we have created Lightning [_datamodules_](https://torchgeo.readthedocs.io/en/stable/api/datamodules.html) with well-defined train-val-test splits and [_trainers_](https://torchgeo.readthedocs.io/en/stable/api/trainers.html) for various tasks like classification, regression, and semantic segmentation. These datamodules show how to incorporate augmentations from the kornia library, include preprocessing transforms (with pre-calculated channel statistics), and let users easily experiment with hyperparameters related to the data itself (as opposed to the modeling process). Training a semantic segmentation model on the [Inria Aerial Image Labeling](https://project.inria.fr/aerialimagelabeling/) dataset is as easy as a few imports and four lines of code.
```python
datamodule = InriaAerialImageLabelingDataModule(root="...", batch_size=64, num_workers=6)
task = SemanticSegmentationTask(
model="unet",
backbone="resnet50",
weights=True,
in_channels=3,
num_classes=2,
loss="ce",
ignore_index=None,
lr=0.1,
patience=6,
)
trainer = Trainer(default_root_dir="...")
trainer.fit(model=task, datamodule=datamodule)
```
<img src="https://raw.githubusercontent.com/microsoft/torchgeo/main/images/inria.png" alt="Building segmentations produced by a U-Net model trained on the Inria Aerial Image Labeling dataset"/>
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
# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeo
```
It supports command-line configuration or YAML/JSON config files. Valid options can be found from the help messages:
```console
# See valid stages
torchgeo --help
# See valid trainer options
torchgeo fit --help
# See valid model options
torchgeo fit --model.help ClassificationTask
# See valid data options
torchgeo fit --data.help EuroSAT100DataModule
```
Using the following config file:
```yaml
trainer:
max_epochs: 20
model:
class_path: ClassificationTask
init_args:
model: "resnet18"
in_channels: 13
num_classes: 10
data:
class_path: EuroSAT100DataModule
init_args:
batch_size: 8
dict_kwargs:
download: true
```
we can see the script in action:
```console
# Train and validate a model
torchgeo fit --config config.yaml
# Validate-only
torchgeo validate --config config.yaml
# Calculate and report test accuracy
torchgeo test --config config.yaml --ckpt_path=...
```
It can also be imported and used in a Python script if you need to extend it to add new features:
```python
from torchgeo.main import main
main(["fit", "--config", "config.yaml"])
```
See the [Lightning documentation](https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html) for more details.
## Citation
If you use this software in your work, please cite our [paper](https://dl.acm.org/doi/10.1145/3557915.3560953):
```bibtex
@inproceedings{Stewart_TorchGeo_Deep_Learning_2022,
address = {Seattle, Washington},
author = {Stewart, Adam J. and Robinson, Caleb and Corley, Isaac A. and Ortiz, Anthony and Lavista Ferres, Juan M. and Banerjee, Arindam},
booktitle = {Proceedings of the 30th International Conference on Advances in Geographic Information Systems},
doi = {10.1145/3557915.3560953},
month = nov,
pages = {1--12},
publisher = {Association for Computing Machinery},
series = {SIGSPATIAL '22},
title = {{TorchGeo}: Deep Learning With Geospatial Data},
url = {https://dl.acm.org/doi/10.1145/3557915.3560953},
year = {2022}
}
```
## Contributing
This project welcomes contributions and suggestions. If you would like to submit a pull request, see our [Contribution Guide](https://torchgeo.readthedocs.io/en/stable/user/contributing.html) for more information.
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
Raw data
{
"_id": null,
"home_page": null,
"name": "torchgeo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "\"Adam J. Stewart\" <ajstewart426@gmail.com>, Caleb Robinson <Caleb.Robinson@microsoft.com>, Isaac Corley <isaac.corley@my.utsa.edu>, Nils Lehmann <n.lehmann@tum.de>, Ashwin Nair <ashnair0007@gmail.com>",
"keywords": "pytorch, deep learning, machine learning, remote sensing, satellite imagery, earth observation, geospatial",
"author": null,
"author_email": "\"Adam J. Stewart\" <ajstewart426@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8d/3d/6afd8f2e13ba938b5f5cec342eb921b6c02858e9f9d9b5eae7d860345ceb/torchgeo-0.6.0.tar.gz",
"platform": null,
"description": "<img src=\"https://raw.githubusercontent.com/microsoft/torchgeo/main/logo/logo-color.svg\" width=\"400\" alt=\"TorchGeo logo\"/>\n\nTorchGeo is a [PyTorch](https://pytorch.org/) domain library, similar to [torchvision](https://pytorch.org/vision), providing datasets, samplers, transforms, and pre-trained models specific to geospatial data.\n\nThe goal of this library is to make it simple:\n\n1. for machine learning experts to work with geospatial data, and\n2. for remote sensing experts to explore machine learning solutions.\n\nCommunity:\n[](https://join.slack.com/t/torchgeo/shared_invite/zt-22rse667m-eqtCeNW0yI000Tl4B~2PIw)\n[](https://www.osgeo.org/community/getting-started-osgeo/)\n[](https://huggingface.co/torchgeo)\n[](https://pytorch.org/ecosystem/join)\n\nPackaging:\n[](https://pypi.org/project/torchgeo/)\n[](https://anaconda.org/conda-forge/torchgeo)\n[](https://packages.spack.io/package.html?name=py-torchgeo)\n\nTesting:\n[](https://torchgeo.readthedocs.io/en/stable/)\n[](https://github.com/microsoft/torchgeo/actions/workflows/style.yaml)\n[](https://github.com/microsoft/torchgeo/actions/workflows/tests.yaml)\n[](https://codecov.io/gh/microsoft/torchgeo)\n\n## Installation\n\nThe recommended way to install TorchGeo is with [pip](https://pip.pypa.io/):\n\n```console\n$ pip install torchgeo\n```\n\nFor [conda](https://docs.conda.io/) and [spack](https://spack.io/) installation instructions, see the [documentation](https://torchgeo.readthedocs.io/en/stable/user/installation.html).\n\n## Documentation\n\nYou can find the documentation for TorchGeo on [ReadTheDocs](https://torchgeo.readthedocs.io). This includes API documentation, contributing instructions, and several [tutorials](https://torchgeo.readthedocs.io/en/stable/tutorials/getting_started.html). For more details, check out our [paper](https://arxiv.org/abs/2111.08872), [podcast episode](https://www.youtube.com/watch?v=ET8Hb_HqNJQ), [tutorial](https://www.youtube.com/watch?v=R_FhY8aq708), and [blog post](https://pytorch.org/blog/geospatial-deep-learning-with-torchgeo/).\n\n<p float=\"left\">\n <a href=\"https://www.youtube.com/watch?v=ET8Hb_HqNJQ\">\n <img src=\"https://img.youtube.com/vi/ET8Hb_HqNJQ/0.jpg\" style=\"width:49%;\">\n </a>\n <a href=\"https://www.youtube.com/watch?v=R_FhY8aq708\">\n <img src=\"https://img.youtube.com/vi/R_FhY8aq708/0.jpg\" style=\"width:49%;\">\n </a>\n</p>\n\n## Example Usage\n\nThe following sections give basic examples of what you can do with TorchGeo.\n\nFirst we'll import various classes and functions used in the following sections:\n\n```python\nfrom lightning.pytorch import Trainer\nfrom torch.utils.data import DataLoader\n\nfrom torchgeo.datamodules import InriaAerialImageLabelingDataModule\nfrom torchgeo.datasets import CDL, Landsat7, Landsat8, VHR10, stack_samples\nfrom torchgeo.samplers import RandomGeoSampler\nfrom torchgeo.trainers import SemanticSegmentationTask\n```\n\n### Geospatial datasets and samplers\n\nMany remote sensing applications involve working with [_geospatial datasets_](https://torchgeo.readthedocs.io/en/stable/api/datasets.html#geospatial-datasets)\u2014datasets with geographic metadata. These datasets can be challenging to work with due to the sheer variety of data. Geospatial imagery is often multispectral with a different number of spectral bands and spatial resolution for every satellite. In addition, each file may be in a different coordinate reference system (CRS), requiring the data to be reprojected into a matching CRS.\n\n<img src=\"https://raw.githubusercontent.com/microsoft/torchgeo/main/images/geodataset.png\" alt=\"Example application in which we combine Landsat and CDL and sample from both\"/>\n\nIn 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.\n\n```python\nlandsat7 = Landsat7(root=\"...\", bands=[\"B1\", ..., \"B7\"])\nlandsat8 = Landsat8(root=\"...\", bands=[\"B2\", ..., \"B8\"])\nlandsat = landsat7 | landsat8\n```\n\nNext, 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.\n\n```python\ncdl = CDL(root=\"...\", download=True, checksum=True)\ndataset = landsat & cdl\n```\n\nThis dataset can now be used with a PyTorch data loader. Unlike benchmark datasets, geospatial datasets often include very large images. For example, the CDL dataset consists of a single image covering the entire continental United States. In order to sample from these datasets using geospatial coordinates, TorchGeo defines a number of [_samplers_](https://torchgeo.readthedocs.io/en/stable/api/samplers.html). In this example, we'll use a random sampler that returns 256 x 256 pixel images and 10,000 samples per epoch. We also use a custom collation function to combine each sample dictionary into a mini-batch of samples.\n\n```python\nsampler = RandomGeoSampler(dataset, size=256, length=10000)\ndataloader = DataLoader(dataset, batch_size=128, sampler=sampler, collate_fn=stack_samples)\n```\n\nThis data loader can now be used in your normal training/evaluation pipeline.\n\n```python\nfor batch in dataloader:\n image = batch[\"image\"]\n mask = batch[\"mask\"]\n\n # train a model, or make predictions using a pre-trained model\n```\n\nMany applications involve intelligently composing datasets based on geospatial metadata like this. For example, users may want to:\n\n- Combine datasets for multiple image sources and treat them as equivalent (e.g., Landsat 7 and 8)\n- Combine datasets for disparate geospatial locations (e.g., Chesapeake NY and PA)\n\nThese combinations require that all queries are present in at least one dataset, and can be created using a `UnionDataset`. Similarly, users may want to:\n\n- Combine image and target labels and sample from both simultaneously (e.g., Landsat and CDL)\n- Combine datasets for multiple image sources for multimodal learning or data fusion (e.g., Landsat and Sentinel)\n\nThese combinations require that all queries are present in both datasets, and can be created using an `IntersectionDataset`. TorchGeo automatically composes these datasets for you when you use the intersection (`&`) and union (`|`) operators.\n\n### Benchmark datasets\n\nTorchGeo includes a number of [_benchmark datasets_](https://torchgeo.readthedocs.io/en/stable/api/datasets.html#non-geospatial-datasets)\u2014datasets that include both input images and target labels. This includes datasets for tasks like image classification, regression, semantic segmentation, object detection, instance segmentation, change detection, and more.\n\nIf you've used [torchvision](https://pytorch.org/vision) before, these datasets should seem very familiar. In this example, we'll create a dataset for the Northwestern Polytechnical University (NWPU) very-high-resolution ten-class ([VHR-10](https://github.com/chaozhong2010/VHR-10_dataset_coco)) geospatial object detection dataset. This dataset can be automatically downloaded, checksummed, and extracted, just like with torchvision.\n\n```python\nfrom torch.utils.data import DataLoader\n\nfrom torchgeo.datamodules.utils import collate_fn_detection\nfrom torchgeo.datasets import VHR10\n\n# Initialize the dataset\ndataset = VHR10(root=\"...\", download=True, checksum=True)\n\n# Initialize the dataloader with the custom collate function\ndataloader = DataLoader(\n dataset,\n batch_size=128,\n shuffle=True,\n num_workers=4,\n collate_fn=collate_fn_detection,\n)\n\n# Training loop\nfor batch in dataloader:\n images = batch[\"image\"] # list of images\n boxes = batch[\"boxes\"] # list of boxes\n labels = batch[\"labels\"] # list of labels\n masks = batch[\"masks\"] # list of masks\n\n # train a model, or make predictions using a pre-trained model\n```\n\n<img src=\"https://raw.githubusercontent.com/microsoft/torchgeo/main/images/vhr10.png\" alt=\"Example predictions from a Mask R-CNN model trained on the VHR-10 dataset\"/>\n\nAll TorchGeo datasets are compatible with PyTorch data loaders, making them easy to integrate into existing training workflows. The only difference between a benchmark dataset in TorchGeo and a similar dataset in torchvision is that each dataset returns a dictionary with keys for each PyTorch `Tensor`.\n\n### Pre-trained Weights\n\nPre-trained weights have proven to be tremendously beneficial for transfer learning tasks in computer vision. Practitioners usually utilize models pre-trained on the ImageNet dataset, containing RGB images. However, remote sensing data often goes beyond RGB with additional multispectral channels that can vary across sensors. TorchGeo is the first library to support models pre-trained on different multispectral sensors, and adopts torchvision's [multi-weight API](https://pytorch.org/blog/introducing-torchvision-new-multi-weight-support-api/). A summary of currently available weights can be seen in the [docs](https://torchgeo.readthedocs.io/en/stable/api/models.html#pretrained-weights). To create a [timm](https://github.com/huggingface/pytorch-image-models) Resnet-18 model with weights that have been pretrained on Sentinel-2 imagery, you can do the following:\n\n```python\nimport timm\nfrom torchgeo.models import ResNet18_Weights\n\nweights = ResNet18_Weights.SENTINEL2_ALL_MOCO\nmodel = timm.create_model(\"resnet18\", in_chans=weights.meta[\"in_chans\"], num_classes=10)\nmodel.load_state_dict(weights.get_state_dict(progress=True), strict=False)\n```\n\nThese weights can also directly be used in TorchGeo Lightning modules that are shown in the following section via the `weights` argument. For a notebook example, see this [tutorial](https://torchgeo.readthedocs.io/en/stable/tutorials/pretrained_weights.html).\n\n### Reproducibility with Lightning\n\nIn order to facilitate direct comparisons between results published in the literature and further reduce the boilerplate code needed to run experiments with datasets in TorchGeo, we have created Lightning [_datamodules_](https://torchgeo.readthedocs.io/en/stable/api/datamodules.html) with well-defined train-val-test splits and [_trainers_](https://torchgeo.readthedocs.io/en/stable/api/trainers.html) for various tasks like classification, regression, and semantic segmentation. These datamodules show how to incorporate augmentations from the kornia library, include preprocessing transforms (with pre-calculated channel statistics), and let users easily experiment with hyperparameters related to the data itself (as opposed to the modeling process). Training a semantic segmentation model on the [Inria Aerial Image Labeling](https://project.inria.fr/aerialimagelabeling/) dataset is as easy as a few imports and four lines of code.\n\n```python\ndatamodule = InriaAerialImageLabelingDataModule(root=\"...\", batch_size=64, num_workers=6)\ntask = SemanticSegmentationTask(\n model=\"unet\",\n backbone=\"resnet50\",\n weights=True,\n in_channels=3,\n num_classes=2,\n loss=\"ce\",\n ignore_index=None,\n lr=0.1,\n patience=6,\n)\ntrainer = Trainer(default_root_dir=\"...\")\n\ntrainer.fit(model=task, datamodule=datamodule)\n```\n\n<img src=\"https://raw.githubusercontent.com/microsoft/torchgeo/main/images/inria.png\" alt=\"Building segmentations produced by a U-Net model trained on the Inria Aerial Image Labeling dataset\"/>\n\nTorchGeo 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:\n\n```console\n# If torchgeo has been installed\ntorchgeo\n# If torchgeo has been installed, or if it has been cloned to the current directory\npython3 -m torchgeo\n```\n\nIt supports command-line configuration or YAML/JSON config files. Valid options can be found from the help messages:\n\n```console\n# See valid stages\ntorchgeo --help\n# See valid trainer options\ntorchgeo fit --help\n# See valid model options\ntorchgeo fit --model.help ClassificationTask\n# See valid data options\ntorchgeo fit --data.help EuroSAT100DataModule\n```\n\nUsing the following config file:\n\n```yaml\ntrainer:\n max_epochs: 20\nmodel:\n class_path: ClassificationTask\n init_args:\n model: \"resnet18\"\n in_channels: 13\n num_classes: 10\ndata:\n class_path: EuroSAT100DataModule\n init_args:\n batch_size: 8\n dict_kwargs:\n download: true\n```\n\nwe can see the script in action:\n\n```console\n# Train and validate a model\ntorchgeo fit --config config.yaml\n# Validate-only\ntorchgeo validate --config config.yaml\n# Calculate and report test accuracy\ntorchgeo test --config config.yaml --ckpt_path=...\n```\n\nIt can also be imported and used in a Python script if you need to extend it to add new features:\n\n```python\nfrom torchgeo.main import main\n\nmain([\"fit\", \"--config\", \"config.yaml\"])\n```\n\nSee the [Lightning documentation](https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html) for more details.\n\n## Citation\n\nIf you use this software in your work, please cite our [paper](https://dl.acm.org/doi/10.1145/3557915.3560953):\n\n```bibtex\n@inproceedings{Stewart_TorchGeo_Deep_Learning_2022,\n address = {Seattle, Washington},\n author = {Stewart, Adam J. and Robinson, Caleb and Corley, Isaac A. and Ortiz, Anthony and Lavista Ferres, Juan M. and Banerjee, Arindam},\n booktitle = {Proceedings of the 30th International Conference on Advances in Geographic Information Systems},\n doi = {10.1145/3557915.3560953},\n month = nov,\n pages = {1--12},\n publisher = {Association for Computing Machinery},\n series = {SIGSPATIAL '22},\n title = {{TorchGeo}: Deep Learning With Geospatial Data},\n url = {https://dl.acm.org/doi/10.1145/3557915.3560953},\n year = {2022}\n}\n```\n\n## Contributing\n\nThis project welcomes contributions and suggestions. If you would like to submit a pull request, see our [Contribution Guide](https://torchgeo.readthedocs.io/en/stable/user/contributing.html) for more information.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) Microsoft Corporation. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE ",
"summary": "TorchGeo: datasets, samplers, transforms, and pre-trained models for geospatial data",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://torchgeo.readthedocs.io",
"Homepage": "https://github.com/microsoft/torchgeo"
},
"split_keywords": [
"pytorch",
" deep learning",
" machine learning",
" remote sensing",
" satellite imagery",
" earth observation",
" geospatial"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6b916346e153ba04c9e916e5081eff5f5f0d27865ece50f01baffb344317252",
"md5": "c9f361ab8af2375f4c486682d5f317da",
"sha256": "41e9c0a8b56a28f9b81717fe02e7d33c13d65ba8e6de67a44d0800b3396e2227"
},
"downloads": -1,
"filename": "torchgeo-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9f361ab8af2375f4c486682d5f317da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 454155,
"upload_time": "2024-09-01T10:35:44",
"upload_time_iso_8601": "2024-09-01T10:35:44.822164Z",
"url": "https://files.pythonhosted.org/packages/d6/b9/16346e153ba04c9e916e5081eff5f5f0d27865ece50f01baffb344317252/torchgeo-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d3d6afd8f2e13ba938b5f5cec342eb921b6c02858e9f9d9b5eae7d860345ceb",
"md5": "ab23b10e6f54fb0596136f46a6c5e765",
"sha256": "c5b073b3c9ac06cd68e45620bab3a78fb7637fa3563aae4f75f4781ba57aee5a"
},
"downloads": -1,
"filename": "torchgeo-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "ab23b10e6f54fb0596136f46a6c5e765",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 291279,
"upload_time": "2024-09-01T10:35:46",
"upload_time_iso_8601": "2024-09-01T10:35:46.929877Z",
"url": "https://files.pythonhosted.org/packages/8d/3d/6afd8f2e13ba938b5f5cec342eb921b6c02858e9f9d9b5eae7d860345ceb/torchgeo-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-01 10:35:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "microsoft",
"github_project": "torchgeo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "torchgeo"
}
