torchgeo
v0.6.2
A Torchgeo é uma biblioteca de domínio Pytorch, semelhante à Torchvision, fornecendo conjuntos de dados, amostradores, transformações e modelos pré-treinados específicos para dados geoespaciais.
O objetivo desta biblioteca é simplificar:
Comunidade:
Embalagem:
Teste:
A maneira recomendada de instalar Torchgeo é com PIP:
pip install torchgeoPara instruções de instalação do CONDA e SPACK, consulte a documentação.
Você pode encontrar a documentação para Torchgeo no ReadThEdocs. Isso inclui documentação da API, instruções contribuintes e vários tutoriais. Para mais detalhes, consulte nosso artigo, episódio de podcast, tutorial e postagem no blog.
As seções a seguir fornecem exemplos básicos do que você pode fazer com Torchgeo.
Primeiro, importaremos várias classes e funções usadas nas seções a seguir:
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 SemanticSegmentationTaskMuitas aplicações de sensoriamento remoto envolvem trabalhar com conjuntos de dados geoespaciais - dados com metadados geográficos. Esses conjuntos de dados podem ser difíceis de trabalhar devido à grande variedade de dados. As imagens geoespaciais geralmente são multiespectral com um número diferente de bandas espectrais e resolução espacial para cada satélite. Além disso, cada arquivo pode estar em um sistema de referência de coordenadas diferente (CRS), exigindo que os dados sejam reproduzidos em um CRS correspondente.
Neste exemplo, mostramos como é fácil trabalhar com dados geoespaciais e amostrar pequenos patches de imagem a partir de uma combinação de dados de camada de dados Landsat e Crodades Prov Crown (CDL) usando o Torchgeo. Primeiro, assumimos que o usuário possui imagens Landsat 7 e 8 baixadas. Como o Landsat 8 possui mais bandas espectrais que o Landsat 7, usaremos apenas as bandas que ambos os satélites têm em comum. Criaremos um único conjunto de dados, incluindo todas as imagens dos dados do Landsat 7 e 8, levando a união entre esses dois conjuntos de dados.
landsat7 = Landsat7 ( paths = "..." , bands = [ "B1" , ..., "B7" ])
landsat8 = Landsat8 ( paths = "..." , bands = [ "B2" , ..., "B8" ])
landsat = landsat7 | landsat8Em seguida, fazemos o cruzamento entre esse conjunto de dados e o conjunto de dados CDL. Queremos fazer o cruzamento em vez do sindicato para garantir que apenas provemos de regiões que possuem dados Landsat e CDL. Observe que podemos baixar automaticamente e verificação de dados CDL. Observe também que cada um desses conjuntos de dados pode conter arquivos em diferentes sistemas de referência de coordenadas (CRS) ou resoluções, mas a Torchgeo garante automaticamente que um CRS e resolução correspondentes sejam usados.
cdl = CDL ( paths = "..." , download = True , checksum = True )
dataset = landsat & cdlEsse conjunto de dados agora pode ser usado com um carregador de dados Pytorch. Ao contrário dos conjuntos de dados de benchmark, os conjuntos de dados geoespaciais geralmente incluem imagens muito grandes. Por exemplo, o conjunto de dados CDL consiste em uma única imagem que cobre todos os Estados Unidos continentais. Para amostrar desses conjuntos de dados usando coordenadas geoespaciais, a Torchgeo define vários amostradores . Neste exemplo, usaremos um amostrador aleatório que retorna imagens de 256 x 256 pixels e 10.000 amostras por época. Também usamos uma função de agrupamento personalizada para combinar cada dicionário de amostra em um mini-lote de amostras.
sampler = RandomGeoSampler ( dataset , size = 256 , length = 10000 )
dataloader = DataLoader ( dataset , batch_size = 128 , sampler = sampler , collate_fn = stack_samples )Este carregador de dados agora pode ser usado no seu pipeline de treinamento/avaliação normal.
for batch in dataloader :
image = batch [ "image" ]
mask = batch [ "mask" ]
# train a model, or make predictions using a pre-trained modelMuitas aplicações envolvem composição de dados de forma inteligente com base em metadados geoespaciais como este. Por exemplo, os usuários podem querer:
Essas combinações exigem que todas as consultas estejam presentes em pelo menos um conjunto de dados e possam ser criadas usando um UnionDataset . Da mesma forma, os usuários podem querer:
Essas combinações exigem que todas as consultas estejam presentes nos dois conjuntos de dados e possam ser criadas usando um IntersectionDataset . A Torchgeo compõe automaticamente esses conjuntos de dados para você quando você usa os operadores de interseção ( & ) e união ( | ).
A Torchgeo inclui vários conjuntos de dados de referência - dados que incluem imagens de entrada e etiquetas de destino. Isso inclui conjuntos de dados para tarefas como classificação de imagem, regressão, segmentação semântica, detecção de objetos, segmentação de instância, detecção de alterações e muito mais.
Se você usou a Torchvision antes, esses conjuntos de dados devem parecer muito familiares. Neste exemplo, criaremos um conjunto de dados para a Northwestern Polytechnical University (NWPU) de alta resolução de alta resolução (VHR-10) de detecção de objetos geoespaciais. Esse conjunto de dados pode ser baixado automaticamente, verificações e extraídas, assim como no 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 os conjuntos de dados Torchgeo são compatíveis com os carregadores de dados da Pytorch, facilitando a integração nos fluxos de trabalho de treinamento existentes. A única diferença entre um conjunto de dados de referência no Torchgeo e um conjunto de dados semelhante no TorchVision é que cada conjunto de dados retorna um dicionário com chaves para cada Tensor de pytorch.
Os pesos pré-treinados provaram ser tremendamente benéficos para tarefas de aprendizado de transferência na visão computacional. Os profissionais geralmente utilizam modelos pré-treinados no conjunto de dados ImageNet, contendo imagens RGB. No entanto, os dados de sensoriamento remoto geralmente vão além do RGB com canais multiespectrais adicionais que podem variar entre sensores. Torchgeo é a primeira biblioteca a suportar modelos pré-treinados em diferentes sensores multiespectrais e adota a API de vários pesos da Torchvision. Um resumo dos pesos atualmente disponíveis pode ser visto nos documentos. Para criar um modelo Timm ResNet-18 com pesos pré-terem sido pré-criados em imagens Sentinel-2, você pode fazer o seguinte:
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 ) Esses pesos também podem ser usados diretamente nos módulos de Lightning Torchgeo que são mostrados na seção a seguir através do argumento de weights . Para um exemplo de notebook, consulte este tutorial.
Para facilitar as comparações diretas entre os resultados publicados na literatura e reduzir ainda mais o código de caldeira necessário para executar experimentos com conjuntos de dados no Torchgeo, criamos datamódulos de raios com divisões e treinadores bem definidos para o teste de treinamento para várias tarefas como classificação, regressão e segmentação semântica. Esses dados mostram como incorporar aumentos da biblioteca de Kornia, incluem transformações de pré-processamento (com estatísticas de canal pré-calculadas) e permitem que os usuários experimentem facilmente hiperparâmetros relacionados aos próprios dados (em oposição ao processo de modelagem). Treinar um modelo de segmentação semântica no conjunto de dados de rotulagem de imagem aérea da Inria é tão fácil quanto algumas importações e quatro linhas 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 também suporta treinamento de interface da linha de comando usando o LightningCli. Pode ser invocado de duas maneiras:
# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeoEle suporta arquivos de configuração de linha de comando ou arquivos de configuração YAML/JSON. Opções válidas podem ser encontradas nas mensagens de ajuda:
# 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 o seguinte arquivo de configuração:
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 o script em ação:
# 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=...Também pode ser importado e usado em um script python, se você precisar estendê -lo para adicionar novos recursos:
from torchgeo . main import main
main ([ "fit" , "--config" , "config.yaml" ])Veja a documentação do Lightning para obter mais detalhes.
Se você usar este software em seu trabalho, cite nosso artigo:
@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 projeto recebe contribuições e sugestões. Se você deseja enviar uma solicitação de tração, consulte nosso guia de contribuição para obter mais informações.
Este projeto adotou o Código de Conduta Open Microsoft. Para obter mais informações, consulte o Código de Conduta Perguntas frequentes ou entre em contato com [email protected] com quaisquer perguntas ou comentários adicionais.
