torchgeo
v0.6.2
Torchgeo est une bibliothèque de domaines Pytorch, similaire à TorchVision, fournissant des ensembles de données, des échantillonneurs, des transformations et des modèles pré-formés spécifiques aux données géospatiales.
Le but de cette bibliothèque est de simplifier les choses:
Communauté:
Conditionnement:
Essai:
La façon recommandée d'installer Torchgeo est avec PIP:
pip install torchgeoPour les instructions d'installation de Conda et de Spack, consultez la documentation.
Vous pouvez trouver la documentation de Torchgeo sur ReadTheDocs. Cela comprend la documentation de l'API, les instructions contributives et plusieurs tutoriels. Pour plus de détails, consultez notre article, notre épisode de podcast, notre bourse et notre article de blog.
Les sections suivantes donnent des exemples de base de ce que vous pouvez faire avec Torchgeo.
Nous allons d'abord importer différentes classes et fonctions utilisées dans les sections suivantes:
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 SemanticSegmentationTaskDe nombreuses applications de télédétection impliquent de travailler avec des ensembles de données géospatiaux - des ensembles de données avec des métadonnées géographiques. Ces ensembles de données peuvent être difficiles à travailler en raison de la variété des données. L'imagerie géospatiale est souvent multispectrale avec un nombre différent de bandes spectrales et une résolution spatiale pour chaque satellite. De plus, chaque fichier peut être dans un système de référence de coordonnées (CRS) différent, ce qui nécessite que les données soient reprojetées dans un CRS correspondant.
Dans cet exemple, nous montrons à quel point il est facile de travailler avec les données géospatiales et d'échantillonner de petites patchs d'image à partir d'une combinaison de données Landsat et Croplands Data Layer (CDL) utilisant Torchgeo. Tout d'abord, nous supposons que l'utilisateur a téléchargé l'imagerie Landsat 7 et 8. Étant donné que Landsat 8 a plus de bandes spectrales que Landsat 7, nous n'utiliserons que les bandes que les deux satellites ont en commun. Nous allons créer un ensemble de données unique, y compris toutes les images des données Landsat 7 et 8 en prenant le syndicat entre ces deux ensembles de données.
landsat7 = Landsat7 ( paths = "..." , bands = [ "B1" , ..., "B7" ])
landsat8 = Landsat8 ( paths = "..." , bands = [ "B2" , ..., "B8" ])
landsat = landsat7 | landsat8Ensuite, nous prenons l'intersection entre cet ensemble de données et l'ensemble de données CDL. Nous voulons prendre l'intersection au lieu de l'Union pour nous assurer que nous échantillons uniquement dans des régions qui ont des données Landsat et CDL. Notez que nous pouvons télécharger et contrôler automatiquement les données CDL. Notez également que chacun de ces ensembles de données peut contenir des fichiers dans différents systèmes de référence de coordonnées (CRS) ou résolutions, mais Torchgeo garantit automatiquement qu'un CR et une résolution correspondants sont utilisés.
cdl = CDL ( paths = "..." , download = True , checksum = True )
dataset = landsat & cdlCet ensemble de données peut désormais être utilisé avec un chargeur de données Pytorch. Contrairement aux ensembles de données de référence, les ensembles de données géospatiaux incluent souvent de très grandes images. Par exemple, l'ensemble de données CDL se compose d'une seule image couvrant l'ensemble des États-Unis continentaux. Afin d'échantillonner ces ensembles de données en utilisant des coordonnées géospatiales, Torchgeo définit un certain nombre d' échantillons . Dans cet exemple, nous utiliserons un échantillonneur aléatoire qui renvoie 256 images de 256 pixels et 10 000 échantillons par époque. Nous utilisons également une fonction de collation personnalisée pour combiner chaque dictionnaire d'échantillons dans un mini-lot d'échantillons.
sampler = RandomGeoSampler ( dataset , size = 256 , length = 10000 )
dataloader = DataLoader ( dataset , batch_size = 128 , sampler = sampler , collate_fn = stack_samples )Ce chargeur de données peut désormais être utilisé dans votre pipeline de formation / évaluation normal.
for batch in dataloader :
image = batch [ "image" ]
mask = batch [ "mask" ]
# train a model, or make predictions using a pre-trained modelDe nombreuses applications impliquent une composition intelligente de ensembles de données basés sur des métadonnées géospatiales comme celle-ci. Par exemple, les utilisateurs peuvent vouloir:
Ces combinaisons nécessitent que toutes les requêtes soient présentes dans au moins un ensemble de données et peuvent être créées à l'aide d'un UnionDataset . De même, les utilisateurs peuvent vouloir:
Ces combinaisons nécessitent que toutes les requêtes soient présentes dans les deux ensembles de données et peuvent être créées à l'aide d'un IntersectionDataset . Torchgeo compose automatiquement ces ensembles de données pour vous lorsque vous utilisez les opérateurs d'intersection ( & ) et d'union ( | ).
Torchgeo comprend un certain nombre d' ensembles de données de référence —Datasets qui incluent à la fois des images d'entrée et des étiquettes cibles. Cela comprend des ensembles de données pour des tâches telles que la classification d'images, la régression, la segmentation sémantique, la détection d'objets, la segmentation des instances, la détection des changements, etc.
Si vous avez déjà utilisé TorchVision, ces ensembles de données devraient sembler très familiers. Dans cet exemple, nous allons créer un ensemble de données pour la Northwestern Polytechnical University (NWPU) très haute résolution à dix classe (VHR-10) ensemble de données de détection d'objets géospatiaux. Cet ensemble de données peut être automatiquement téléchargé, vérifié et extrait, tout comme avec 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 Tous les ensembles de données Torchgeo sont compatibles avec les chargeurs de données Pytorch, ce qui les rend faciles à intégrer dans les flux de travail de formation existants. La seule différence entre un ensemble de données de référence dans Torchgeo et un ensemble de données similaire dans TorchVision est que chaque ensemble de données renvoie un dictionnaire avec des clés pour chaque Tensor de pytorch.
Les poids pré-formés se sont révélés extrêmement bénéfiques pour les tâches d'apprentissage du transfert dans la vision par ordinateur. Les praticiens utilisent généralement des modèles pré-formés sur l'ensemble de données ImageNet, contenant des images RVB. Cependant, les données de télédétection vont souvent au-delà du RVB avec des canaux multispectraux supplémentaires qui peuvent varier selon les capteurs. Torchgeo est la première bibliothèque à prendre en charge les modèles pré-formés sur différents capteurs multispectraux et adopte l'API multi-poids de TorchVision. Un résumé des poids actuellement disponibles peut être vu dans les documents. Pour créer un modèle TIMM RESNET-18 avec des poids qui ont été pré-entraînés sur l'imagerie Sentinel-2, vous pouvez effectuer ce qui suit:
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 ) Ces poids peuvent également être directement utilisés dans les modules Torchgeo Lightning qui sont indiqués dans la section suivante via l'argument weights . Pour un exemple de cahier, consultez ce tutoriel.
Afin de faciliter les comparaisons directes entre les résultats publiés dans la littérature et de réduire davantage le code de passe-partout nécessaire pour exécuter des expériences avec des ensembles de données dans Torchgeo, nous avons créé des données de la foudre avec des divisions de tests de trains bien définies pour diverses tâches telles que la classification, la régression et la segmentation sémantique. Ces datamodules montrent comment incorporer des augmentations de la bibliothèque de Kornia, incluent des transformations de prétraitement (avec des statistiques de canaux pré-calculées) et permettent aux utilisateurs expérimenter facilement des hyperparamètres liés aux données elle-même (par opposition au processus de modélisation). La formation d'un modèle de segmentation sémantique sur l'ensemble de données d'étiquetage d'image aérien d'Inria est aussi simple que quelques importations et quatre lignes de code.
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 prend également en charge la formation d'interface de ligne de commande à l'aide de LightningCli. Il peut être invoqué de deux manières:
# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeoIl prend en charge la configuration de la ligne de commande ou les fichiers de configuration YAML / JSON. Des options valides peuvent être trouvées à partir des messages d'aide:
# 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 EuroSAT100DataModuleUtilisation du fichier de configuration suivant:
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 : trueNous pouvons voir le script en action:
# 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=...Il peut également être importé et utilisé dans un script Python si vous devez l'étendre pour ajouter de nouvelles fonctionnalités:
from torchgeo . main import main
main ([ "fit" , "--config" , "config.yaml" ])Voir la documentation Lightning pour plus de détails.
Si vous utilisez ce logiciel dans votre travail, veuillez citer notre article:
@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 }
}Ce projet accueille les contributions et les suggestions. Si vous souhaitez soumettre une demande de traction, consultez notre guide de contribution pour plus d'informations.
Ce projet a adopté le code de conduite open source Microsoft. Pour plus d'informations, consultez le code de conduite FAQ ou contactez [email protected] avec toute question ou commentaire supplémentaire.
