torchgeo
v0.6.2
Torchgeo es una biblioteca de dominio de Pytorch, similar a TorchVision, que proporciona conjuntos de datos, muestreadores, transformaciones y modelos previamente capacitados específicos de datos geoespaciales.
El objetivo de esta biblioteca es simplificarlo:
Comunidad:
Embalaje:
Pruebas:
La forma recomendada de instalar Torchgeo es con PIP:
pip install torchgeoPara las instrucciones de instalación de Conda y Spack, consulte la documentación.
Puede encontrar la documentación para Torchgeo en Readthedocs. Esto incluye documentación de API, instrucciones de contribución y varios tutoriales. Para obtener más detalles, consulte nuestro documento, episodio de podcast, tutorial y publicación de blog.
Las siguientes secciones dan ejemplos básicos de lo que puede hacer con Torchgeo.
Primero importaremos varias clases y funciones utilizadas en las siguientes secciones:
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 SemanticSegmentationTaskMuchas aplicaciones de teledetección implican trabajar con conjuntos de datos geoespaciales : datos con metadatos geográficos. Estos conjuntos de datos pueden ser difíciles de trabajar debido a la gran variedad de datos. Las imágenes geoespaciales a menudo son multiespectrales con un número diferente de bandas espectrales y resolución espacial para cada satélite. Además, cada archivo puede estar en un sistema de referencia de coordenadas (CRS) diferente, lo que requiere que los datos se reprojecten en un CRS coincidente.
En este ejemplo, mostramos qué tan fácil es trabajar con datos geoespaciales y probar pequeños parches de imágenes de una combinación de datos de la capa de datos de Landsat y Cropland (CDL) utilizando Torchgeo. Primero, suponemos que el usuario tiene descargas de imágenes Landsat 7 y 8. Dado que Landsat 8 tiene más bandas espectrales que Landsat 7, solo usaremos las bandas que ambos satélites tienen en común. Crearemos un solo conjunto de datos que incluye todas las imágenes de los datos de Landsat 7 y 8 tomando la unión entre estos dos conjuntos de datos.
landsat7 = Landsat7 ( paths = "..." , bands = [ "B1" , ..., "B7" ])
landsat8 = Landsat8 ( paths = "..." , bands = [ "B2" , ..., "B8" ])
landsat = landsat7 | landsat8A continuación, tomamos la intersección entre este conjunto de datos y el conjunto de datos CDL. Queremos tomar la intersección en lugar de la unión para garantizar que solo muestramos regiones que tienen datos Landsat y CDL. Tenga en cuenta que podemos descargar automáticamente los datos de CDL de suma de comprobación. También tenga en cuenta que cada uno de estos conjuntos de datos puede contener archivos en diferentes sistemas de referencia de coordenadas (CRS) o resoluciones, pero Torchgeo garantiza automáticamente que se utilice un CRS y resolución coincidente.
cdl = CDL ( paths = "..." , download = True , checksum = True )
dataset = landsat & cdlEste conjunto de datos ahora se puede usar con un cargador de datos Pytorch. A diferencia de los conjuntos de datos de referencia, los conjuntos de datos geoespaciales a menudo incluyen imágenes muy grandes. Por ejemplo, el conjunto de datos CDL consiste en una sola imagen que cubre todo Estados Unidos continental. Para probar de estos conjuntos de datos utilizando coordenadas geoespaciales, Torchgeo define una serie de muestreadores . En este ejemplo, usaremos una muestra aleatoria que devuelve 256 x 256 imágenes de píxeles y 10,000 muestras por época. También utilizamos una función de recopilación personalizada para combinar cada diccionario de muestra en un mini lote de muestras.
sampler = RandomGeoSampler ( dataset , size = 256 , length = 10000 )
dataloader = DataLoader ( dataset , batch_size = 128 , sampler = sampler , collate_fn = stack_samples )Este cargador de datos ahora se puede usar en su canal de entrenamiento/evaluación normal.
for batch in dataloader :
image = batch [ "image" ]
mask = batch [ "mask" ]
# train a model, or make predictions using a pre-trained modelMuchas aplicaciones implican componer conjuntos de datos de manera inteligente basados en metadatos geoespaciales como este. Por ejemplo, los usuarios pueden querer:
Estas combinaciones requieren que todas las consultas estén presentes en al menos un conjunto de datos, y se pueden crear utilizando un UnionDataset . Del mismo modo, los usuarios pueden querer:
Estas combinaciones requieren que todas las consultas estén presentes en ambos conjuntos de datos, y se pueden crear utilizando un IntersectionDataset . Torchgeo lo compone automáticamente estos conjuntos de datos cuando usa los operadores de intersección ( & ) y unión ( | ).
Torchgeo incluye una serie de conjuntos de datos de referencia , datos que incluyen imágenes de entrada y etiquetas de destino. Esto incluye conjuntos de datos para tareas como clasificación de imágenes, regresión, segmentación semántica, detección de objetos, segmentación de instancias, detección de cambios y más.
Si ha usado TorchVision antes, estos conjuntos de datos deberían parecer muy familiares. En este ejemplo, crearemos un conjunto de datos para la Universidad Politécnica del Noroeste (NWPU) de muy alta resolución de diez clases (VHR-10) Detección de objetos geoespaciales. Este conjunto de datos se puede descargar, verificar y extraerse automáticamente, al igual que con 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 Todos los conjuntos de datos Torchgeo son compatibles con los cargadores de datos de Pytorch, lo que los hace fáciles de integrar en los flujos de trabajo de capacitación existentes. La única diferencia entre un conjunto de datos de referencia en Torchgeo y un conjunto de datos similar en TorchVision es que cada conjunto de datos devuelve un diccionario con claves para cada Tensor de Pytorch.
Los pesos previamente capacitados han demostrado ser tremendamente beneficiosos para las tareas de aprendizaje de transferencia en la visión por computadora. Los profesionales generalmente utilizan modelos previamente entrenados en el conjunto de datos ImageNet, que contiene imágenes RGB. Sin embargo, los datos de detección remota a menudo van más allá de RGB con canales multiespectrales adicionales que pueden variar en los sensores. Torchgeo es la primera biblioteca en admitir modelos previamente entrenados en diferentes sensores multiespectrales, y adopta la API de peso múltiple de Torchvision. Se puede ver un resumen de los pesos actualmente disponibles en los documentos. Para crear un modelo TIMM RESNET-18 con pesos que se han practicado en imágenes Sentinel-2, puede hacer lo siguiente:
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 ) Estos pesos también se pueden usar directamente en módulos de rayos Torchgeo que se muestran en la siguiente sección a través del argumento weights . Para un ejemplo de cuaderno, consulte este tutorial.
Para facilitar las comparaciones directas entre los resultados publicados en la literatura y reducir aún más el código básico necesario para ejecutar experimentos con conjuntos de datos en Torchgeo, hemos creado Lightning DataModules con divisiones y entrenadores de prueba de tren bien definidos para diversas tareas como clasificación, regresión y segmentación semántica. Estos datamodules muestran cómo incorporar aumentos de la Biblioteca Kornia, incluyen transformaciones de preprocesamiento (con estadísticas de canales precalculadas) y permiten a los usuarios experimentar fácilmente con hiperparámetros relacionados con los datos en sí (en oposición al proceso de modelado). Entrenar un modelo de segmentación semántica en el conjunto de datos de etiquetado de imágenes aéreas de INRIA es tan fácil como unas pocas importaciones y cuatro líneas de código.
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 también admite el entrenamiento de interfaz de línea de comandos utilizando LightningCli. Se puede invocar de dos maneras:
# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeoAdmite configuración de línea de comandos o archivos de configuración YAML/JSON. Las opciones válidas se pueden encontrar en los mensajes de ayuda:
# 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 EuroSAT100DataModuleUsando el siguiente archivo de configuración:
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 : truePodemos ver el script en acción:
# 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=...También se puede importar y usar en un script de Python si necesita extenderlo para agregar nuevas características:
from torchgeo . main import main
main ([ "fit" , "--config" , "config.yaml" ])Consulte la documentación de Lightning para obtener más detalles.
Si usa este software en su trabajo, cite nuestro documento:
@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 }
}Este proyecto da la bienvenida a las contribuciones y sugerencias. Si desea enviar una solicitud de extracción, consulte nuestra guía de contribución para obtener más información.
Este proyecto ha adoptado el Código de Conducta Open Open Microsoft. Para obtener más información, consulte el Código de Conducta Preguntas frecuentes o comuníquese con [email protected] con cualquier pregunta o comentario adicional.
