torchgeo
v0.6.2
Torchgeo ist eine Pytorch-Domänenbibliothek, ähnlich wie Torchvision und bereitgestellt Datensätze, Sampler, Transformationen und vorgebrachte Modelle, die für Geospatial-Daten spezifisch sind.
Das Ziel dieser Bibliothek ist es, sie einfach zu machen:
Gemeinschaft:
Verpackung:
Testen:
Die empfohlene Möglichkeit zur Installation von Torchgeo ist mit PIP:
pip install torchgeoFür Conda- und Spack -Installationsanweisungen finden Sie in der Dokumentation.
Sie finden die Dokumentation für Torchgeo auf Redethedocs. Dies beinhaltet API -Dokumentation, Beitragsanweisungen und mehrere Tutorials. Weitere Informationen finden Sie in unserem Artikel, Podcast -Episode, Tutorial und Blog -Beitrag.
Die folgenden Abschnitte geben grundlegende Beispiele dafür, was Sie mit Torchgeo tun können.
Zuerst importieren wir verschiedene Klassen und Funktionen, die in den folgenden Abschnitten verwendet werden:
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 SemanticSegmentationTaskViele Fernerkundungsanwendungen beinhalten die Arbeit mit Geospatial -Datensätzen - Datensätze mit geografischen Metadaten. Diese Datensätze können aufgrund der bloßen Vielfalt der Daten eine Herausforderung sein, mit ihnen zu arbeiten. Geospatial -Bilder sind oft multispektral mit einer anderen Anzahl von Spektralbändern und einer räumlichen Auflösung für jeden Satelliten. Darüber hinaus kann jede Datei in einem anderen Koordinatenreferenzsystem (CRS) vorhanden sein, wodurch die Daten in eine passende CRS revidiert werden sollen.
In diesem Beispiel zeigen wir, wie einfach es ist, mit Geospatial -Daten zu arbeiten und kleine Bild Patches aus einer Kombination aus Landsat- und Cropland Data Layer -Daten (CDL) unter Verwendung von Torchgeo zu probieren. Zunächst gehen wir davon aus, dass der Benutzer Landsat 7 und 8 Bilder heruntergeladen hat. Da Landsat 8 mehr Spektralbänder als Landsat 7 hat, werden wir nur die Bands verwenden, die beide Satelliten gemeinsam haben. Wir erstellen einen einzelnen Datensatz mit allen Bildern sowohl aus Landsat 7 als auch 8 Daten, indem wir die Vereinigung zwischen diesen beiden Datensätzen nehmen.
landsat7 = Landsat7 ( paths = "..." , bands = [ "B1" , ..., "B7" ])
landsat8 = Landsat8 ( paths = "..." , bands = [ "B2" , ..., "B8" ])
landsat = landsat7 | landsat8Als nächstes nehmen wir den Schnittpunkt zwischen diesem Datensatz und dem CDL -Datensatz. Wir möchten die Kreuzung anstelle der Union nehmen, um sicherzustellen, dass wir nur aus Regionen probieren, in denen sowohl Landsat- als auch CDL -Daten vorhanden sind. Beachten Sie, dass wir CDL -Daten automatisch herunterladen und prüfler. Beachten Sie auch, dass jeder dieser Datensätze Dateien in verschiedenen Koordinatenreferenzsystemen (CRS) oder Auflösungen enthalten kann, aber Torchgeo stellt automatisch sicher, dass eine passende CRS und Auflösung verwendet wird.
cdl = CDL ( paths = "..." , download = True , checksum = True )
dataset = landsat & cdlDieser Datensatz kann jetzt mit einem Pytorch -Datenloader verwendet werden. Im Gegensatz zu Benchmark -Datensätzen enthalten Geospatial -Datensätze häufig sehr große Bilder. Zum Beispiel besteht der CDL -Datensatz aus einem einzigen Bild, das die gesamten kontinentalen Vereinigten Staaten abdeckt. Um aus diesen Datensätzen mithilfe von Geospatial -Koordinaten zu probieren, definiert Torchgeo eine Reihe von Probenstichen . In diesem Beispiel verwenden wir einen zufälligen Sampler, der 256 x 256 Pixelbilder und 10.000 Proben pro Epoche zurückgibt. Wir verwenden auch eine benutzerdefinierte Kollationsfunktion, um jedes Proben-Wörterbuch zu einer Mini-Proben-Proben zu kombinieren.
sampler = RandomGeoSampler ( dataset , size = 256 , length = 10000 )
dataloader = DataLoader ( dataset , batch_size = 128 , sampler = sampler , collate_fn = stack_samples )Dieser Datenloader kann jetzt in Ihrer normalen Trainings-/Bewertungspipeline verwendet werden.
for batch in dataloader :
image = batch [ "image" ]
mask = batch [ "mask" ]
# train a model, or make predictions using a pre-trained modelViele Anwendungen beinhalten intelligent komponierende Datensätze, die auf solchen geospatialen Metadaten basieren. Zum Beispiel möchten Benutzer möglicherweise:
Diese Kombinationen erfordern, dass alle Abfragen in mindestens einem Datensatz vorhanden sind und mit einem UnionDataset erstellt werden können. In ähnlicher Weise möchten Benutzer möglicherweise:
Diese Kombinationen erfordern, dass alle Abfragen in beiden Datensätzen vorhanden sind und mit einem IntersectionDataset erstellt werden können. Torchgeo komponiert diese Datensätze automatisch für Sie, wenn Sie die Operatoren der Kreuzung ( & ) und der Gewerkschaft ( | ) verwenden.
Torchgeo enthält eine Reihe von Benchmark -Datensätzen - Datensätze, die sowohl Eingabebilder als auch Zielbezeichnungen enthalten. Dies umfasst Datensätze für Aufgaben wie Bildklassifizierung, Regression, semantische Segmentierung, Objekterkennung, Instanzsegmentierung, Änderungserkennung und mehr.
Wenn Sie schon einmal Torchvision verwendet haben, sollten diese Datensätze sehr vertraut erscheinen. In diesem Beispiel erstellen wir einen Datensatz für die nordwestliche Polytechnical University (NWPU) mit sehr hoher Auflösung von zehnklassen (VHR-10) Geospatial Object Detection-Datensatz. Dieser Datensatz kann automatisch heruntergeladen, überprüft und extrahiert werden, genau wie bei Torchvision.
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 Alle Torchgeo -Datensätze sind mit Pytorch -Datenladern kompatibel, wodurch sie einfach in die vorhandenen Trainingsworkflows integriert werden können. Der einzige Unterschied zwischen einem Benchmark -Datensatz in Torchgeo und einem ähnlichen Datensatz in Torchvision besteht darin, dass jeder Datensatz ein Wörterbuch mit Tasten für jeden Pytorch Tensor zurückgibt.
Vorausgebildete Gewichte haben sich als äußerst vorteilhaft für Übertragungslernaufgaben in Computer Vision erwiesen. Praktiker verwenden normalerweise Modelle, die auf dem Bildnetz-Datensatz vorgebracht sind und RGB-Bilder enthalten. Die Fernerkundungsdaten gehen jedoch häufig über RGB hinaus mit zusätzlichen multispektralen Kanälen, die zwischen Sensoren variieren können. Torchgeo ist die erste Bibliothek, die Modelle unterstützt, die auf verschiedenen multispektralen Sensoren ausgebildet ist, und nimmt die Multi-Gewicht-API von Torchvision an. Eine Zusammenfassung der derzeit verfügbaren Gewichte ist in den Dokumenten zu sehen. Um ein Timm Resnet-18-Modell mit Gewichten zu erstellen, die auf Sentinel-2-Bildern vorgebracht wurden, können Sie Folgendes tun:
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 ) Diese Gewichte können auch direkt in Torchgeo -Blitzmodulen verwendet werden, die im folgenden Abschnitt über das Argument weights angezeigt werden. Ein Notizbuch -Beispiel finden Sie in diesem Tutorial.
Um direkte Vergleiche zwischen den in der Literatur veröffentlichten Ergebnissen zu erleichtern und den Boilerplate-Code weiter zu reduzieren, das zum Ausführen von Experimenten mit Datensätzen in Torchgeo erforderlich ist, haben wir Blitzdatenamodulen mit gut definierter Zug-Val-Test-Splits und Trainer für verschiedene Aufgaben wie Klassifizierung, Regression und semantische Segmentierung erstellt. Diese Datamodules zeigen, wie Sie Augmentationen aus der Kornia-Bibliothek einbeziehen, Vorverarbeitungstransformationen (mit vorbereiteten Kanalstatistiken) umfassen und die Benutzer leicht mit Hyperparametern in Bezug auf die Daten selbst (im Gegensatz zum Modellierungsprozess) experimentieren können. Training Ein semantisches Segmentierungsmodell auf dem INRIA -Luftbildkennzeichnungsdatensatz ist so einfach wie einige Importe und vier Codezeilen.
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 )Torchgeo unterstützt auch das Befehls-Linien-Schnittstellentraining mit LightningCli. Es kann auf zwei Arten aufgerufen werden:
# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeoEs unterstützt die Befehlszeilenkonfiguration oder YAML/JSON-Konfigurationsdateien. In den Hilfemeldungen finden Sie gültige Optionen:
# 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 EuroSAT100DataModuleVerwenden der folgenden Konfigurationsdatei:
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 : trueWir können das Skript in Aktion sehen:
# 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=...Es kann auch in einem Python -Skript importiert und verwendet werden, wenn Sie es erweitern müssen, um neue Funktionen hinzuzufügen:
from torchgeo . main import main
main ([ "fit" , "--config" , "config.yaml" ])Weitere Informationen finden Sie in der Blitzdokumentation.
Wenn Sie diese Software in Ihrer Arbeit verwenden, zitieren Sie bitte unser Papier:
@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 }
}Dieses Projekt begrüßt Beiträge und Vorschläge. Wenn Sie eine Pull -Anfrage einreichen möchten, finden Sie in unserem Beitragsanleitung weitere Informationen.
Dieses Projekt hat den Microsoft Open Source -Verhaltenscode übernommen. Weitere Informationen finden Sie im FAQ oder wenden Sie sich an [email protected] mit zusätzlichen Fragen oder Kommentaren.
