torchgeo
v0.6.2
Torchgeo adalah perpustakaan domain Pytorch, mirip dengan TorchVision, menyediakan kumpulan data, sampler, transformasi, dan model pra-terlatih khusus untuk data geospasial.
Tujuan perpustakaan ini adalah untuk membuatnya sederhana:
Masyarakat:
Kemasan:
Pengujian:
Cara yang disarankan untuk menginstal Torchgeo adalah dengan PIP:
pip install torchgeoUntuk instruksi instalasi Conda dan Spack, lihat dokumentasi.
Anda dapat menemukan dokumentasi untuk Torchgeo di ReadThedocs. Ini termasuk dokumentasi API, instruksi yang berkontribusi, dan beberapa tutorial. Untuk detail lebih lanjut, lihat makalah kami, episode podcast, tutorial, dan posting blog.
Bagian berikut memberikan contoh dasar tentang apa yang dapat Anda lakukan dengan Torchgeo.
Pertama, kami akan mengimpor berbagai kelas dan fungsi yang digunakan di bagian berikut:
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 SemanticSegmentationTaskBanyak aplikasi penginderaan jauh melibatkan bekerja dengan kumpulan data geospasial - data dengan metadata geografis. Kumpulan data ini dapat menjadi tantangan untuk dikerjakan karena beragam data. Citra geospasial sering kali multispektral dengan jumlah pita spektral yang berbeda dan resolusi spasial untuk setiap satelit. Selain itu, setiap file mungkin berada dalam sistem referensi koordinat yang berbeda (CRS), yang mengharuskan data untuk dikembalikan ke CRS yang cocok.
Dalam contoh ini, kami menunjukkan betapa mudahnya bekerja dengan data geospasial dan untuk mencicipi tambalan gambar kecil dari kombinasi data Landsat dan Cropland Data Layer (CDL) menggunakan TorchGeo. Pertama, kami berasumsi bahwa pengguna memiliki citra Landsat 7 dan 8 yang diunduh. Karena Landsat 8 memiliki lebih banyak pita spektral daripada Landsat 7, kita hanya akan menggunakan pita yang dimiliki kedua satelit. Kami akan membuat satu dataset termasuk semua gambar dari kedua data Landsat 7 dan 8 dengan mengambil persatuan di antara kedua dataset ini.
landsat7 = Landsat7 ( paths = "..." , bands = [ "B1" , ..., "B7" ])
landsat8 = Landsat8 ( paths = "..." , bands = [ "B2" , ..., "B8" ])
landsat = landsat7 | landsat8Selanjutnya, kami mengambil persimpangan antara dataset ini dan dataset CDL. Kami ingin mengambil persimpangan alih -alih Union untuk memastikan bahwa kami hanya mengambil sampel dari daerah yang memiliki data Landsat dan CDL. Perhatikan bahwa kami dapat secara otomatis mengunduh dan memeriksa data CDL. Perhatikan juga bahwa masing -masing set data ini dapat berisi file dalam berbagai sistem referensi koordinat (CRS) atau resolusi, tetapi TorchGeo secara otomatis memastikan bahwa CRS dan resolusi yang cocok digunakan.
cdl = CDL ( paths = "..." , download = True , checksum = True )
dataset = landsat & cdlDataset ini sekarang dapat digunakan dengan loader data Pytorch. Tidak seperti dataset benchmark, kumpulan data geospasial sering menyertakan gambar yang sangat besar. Misalnya, dataset CDL terdiri dari satu gambar yang mencakup seluruh benua Amerika Serikat. Untuk mencicipi dari kumpulan data ini menggunakan koordinat geospasial, Torchgeo mendefinisikan sejumlah sampler . Dalam contoh ini, kami akan menggunakan sampler acak yang mengembalikan gambar 256 x 256 piksel dan 10.000 sampel per zaman. Kami juga menggunakan fungsi kolasi khusus untuk menggabungkan setiap kamus sampel menjadi mini-batch sampel.
sampler = RandomGeoSampler ( dataset , size = 256 , length = 10000 )
dataloader = DataLoader ( dataset , batch_size = 128 , sampler = sampler , collate_fn = stack_samples )Loader data ini sekarang dapat digunakan dalam pipa pelatihan/evaluasi normal Anda.
for batch in dataloader :
image = batch [ "image" ]
mask = batch [ "mask" ]
# train a model, or make predictions using a pre-trained modelBanyak aplikasi melibatkan menyusun set data yang cerdas berdasarkan metadata geospasial seperti ini. Misalnya, pengguna mungkin ingin:
Kombinasi ini mensyaratkan bahwa semua kueri hadir dalam setidaknya satu dataset, dan dapat dibuat menggunakan UnionDataset . Demikian pula, pengguna mungkin ingin:
Kombinasi ini mensyaratkan bahwa semua kueri hadir di kedua dataset, dan dapat dibuat menggunakan IntersectionDataset . Torchgeo secara otomatis menyusun dataset ini untuk Anda saat Anda menggunakan operator persimpangan ( & ) dan Union ( | ).
Torchgeo mencakup sejumlah dataset benchmark - data yang mencakup gambar input dan label target. Ini termasuk kumpulan data untuk tugas -tugas seperti klasifikasi gambar, regresi, segmentasi semantik, deteksi objek, segmentasi instan, deteksi perubahan, dan banyak lagi.
Jika Anda pernah menggunakan TorchVision sebelumnya, kumpulan data ini tampaknya sangat akrab. Dalam contoh ini, kami akan membuat dataset untuk Northwestern Polytechical University (NWPU) yang sangat beresolusi tinggi sepuluh kelas (VHR-10) dataset deteksi objek geospasial. Dataset ini dapat diunduh secara otomatis, checksummed, dan diekstraksi, seperti halnya dengan 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 Semua kumpulan data Torchgeo kompatibel dengan loader data Pytorch, membuatnya mudah untuk diintegrasikan ke dalam alur kerja pelatihan yang ada. Satu -satunya perbedaan antara dataset benchmark di Torchgeo dan dataset serupa di TorchVision adalah bahwa setiap dataset mengembalikan kamus dengan kunci untuk setiap tentorch Tensor .
Bobot pra-terlatih telah terbukti sangat bermanfaat untuk mentransfer tugas pembelajaran dalam visi komputer. Praktisi biasanya menggunakan model yang sudah dilatih sebelumnya pada dataset Imagenet, yang berisi gambar RGB. Namun, data penginderaan jauh sering melampaui RGB dengan saluran multispektral tambahan yang dapat bervariasi di seluruh sensor. Torchgeo adalah perpustakaan pertama yang mendukung model yang sudah dilatih sebelumnya pada berbagai sensor multispektral, dan mengadopsi API multi-weight TorchVision. Ringkasan bobot yang tersedia saat ini dapat dilihat di dokumen. Untuk membuat model Timm ResNet-18 dengan bobot yang telah diatur pada citra Sentinel-2, Anda dapat melakukan hal berikut:
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 ) Bobot ini juga dapat secara langsung digunakan dalam modul petir oborgeo yang ditampilkan di bagian berikut melalui argumen weights . Untuk contoh notebook, lihat tutorial ini.
Untuk memfasilitasi perbandingan langsung antara hasil yang diterbitkan dalam literatur dan selanjutnya mengurangi kode boilerplate yang diperlukan untuk menjalankan percobaan dengan set data di Torchgeo, kami telah membuat kilat data dengan pemisahan dan pelatih uji-val yang terdefinisi dengan baik untuk berbagai tugas seperti klasifikasi, regresi, dan segmentasi semantik. Datamodul ini menunjukkan cara menggabungkan augmentasi dari perpustakaan Kornia, termasuk transformasi preprocessing (dengan statistik saluran yang telah dihitung sebelumnya), dan memungkinkan pengguna dengan mudah bereksperimen dengan hyperparameters yang terkait dengan data itu sendiri (berlawanan dengan proses pemodelan). Melatih model segmentasi semantik pada dataset pelabelan gambar udara INRIA semudah beberapa impor dan empat baris kode.
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 juga mendukung pelatihan antarmuka baris perintah menggunakan Lightningcli. Itu dapat dipanggil dalam dua cara:
# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeoIni mendukung konfigurasi baris perintah atau file konfigurasi YAML/JSON. Opsi yang valid dapat ditemukan dari pesan bantuan:
# 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 EuroSAT100DataModuleMenggunakan file konfigurasi berikut:
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 : truekita dapat melihat skrip beraksi:
# 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=...Ini juga dapat diimpor dan digunakan dalam skrip Python jika Anda perlu memperpanjangnya untuk menambahkan fitur baru:
from torchgeo . main import main
main ([ "fit" , "--config" , "config.yaml" ])Lihat dokumentasi Lightning untuk lebih jelasnya.
Jika Anda menggunakan perangkat lunak ini dalam pekerjaan Anda, silakan kutip kertas kami:
@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 }
}Proyek ini menyambut kontribusi dan saran. Jika Anda ingin mengirimkan permintaan tarik, lihat Panduan Kontribusi kami untuk informasi lebih lanjut.
Proyek ini telah mengadopsi kode perilaku open source Microsoft. Untuk informasi lebih lanjut, lihat FAQ Kode Perilaku atau hubungi [email protected] dengan pertanyaan atau komentar tambahan.
