torchgeo/torchgeo

TorchGeo là một PyTorch thư viện miền, tương tự như tầm nhìn ngọn đuốc, cung cấp bộ dữ liệu, bộ lấy mẫu, biến đổi và các mô hình được đào tạo trước dành riêng cho dữ liệu không gian địa lý.

Mục tiêu của thư viện này là làm cho nó đơn giản:

1. để các chuyên gia học máy làm việc với dữ liệu không gian địa lý và
2. để các chuyên gia viễn thám khám phá các giải pháp học máy.

Cộng đồng:

Bao bì:

Kiểm tra:

Cài đặt

Cách được khuyến nghị để cài đặt TorchGeo là với pip:

pip install torchgeo

hoặc với tia cực tím:

uv add torchgeo

cho chung cư và rác rưởi hướng dẫn cài đặt, xem tài liệu.

Tài liệu

Bạn có thể tìm tài liệu về TorchGeo trên ĐọcTheDocs. Điều này bao gồm tài liệu API, hướng dẫn đóng góp và một số hướng dẫn. Để biết thêm chi tiết, hãy xem giấy, bài đăng trên blogvà kênh YouTube.

Cách sử dụng ví dụ

Các phần sau đây đưa ra những ví dụ cơ bản về những gì bạn có thể làm với TorchGeo.

Đầu tiên chúng ta sẽ nhập các lớp và hàm khác nhau được sử dụng trong các phần sau:

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 RandomPatchSampler
from torchgeo.tasks import SemanticSegmentation

Bộ dữ liệu và bộ lấy mẫu không gian địa lý

Nhiều ứng dụng viễn thám liên quan đến việc làm việc với bộ dữ liệu không gian địa lý—bộ dữ liệu có siêu dữ liệu địa lý. Những bộ dữ liệu này có thể gặp khó khăn khi làm việc do có quá nhiều dữ liệu. Hình ảnh không gian địa lý thường là đa phổ với số dải phổ và độ phân giải không gian khác nhau cho mỗi vệ tinh. Ngoài ra, mỗi tệp có thể nằm trong một hệ quy chiếu tọa độ (CRS) khác nhau, yêu cầu dữ liệu phải được chuyển đổi thành CRS phù hợp.

Trong ví dụ này, chúng tôi cho thấy việc làm việc với dữ liệu không gian địa lý và lấy mẫu các mảng hình ảnh nhỏ dễ dàng như thế nào từ sự kết hợp của Landsat và Lớp dữ liệu đất trồng trọt (CDL) dữ liệu sử dụng TorchGeo. Đầu tiên, chúng tôi giả định rằng người dùng đã tải xuống hình ảnh Landsat 7 và 8. Vì Landsat 8 có nhiều dải quang phổ hơn Landsat 7 nên chúng tôi sẽ chỉ sử dụng các dải phổ chung của cả hai vệ tinh. Chúng tôi sẽ tạo một tập dữ liệu duy nhất bao gồm tất cả các hình ảnh từ cả dữ liệu Landsat 7 và 8 bằng cách kết hợp giữa hai tập dữ liệu này.

landsat7 = Landsat7(paths='...', bands=['B1', ..., 'B7'])
landsat8 = Landsat8(paths='...', bands=['B2', ..., 'B8'])
landsat = landsat7 | landsat8

Tiếp theo, chúng tôi lấy phần giao nhau giữa tập dữ liệu này và tập dữ liệu CDL. Chúng tôi muốn lấy giao điểm thay vì hợp nhất để đảm bảo rằng chúng tôi chỉ lấy mẫu từ các khu vực có cả dữ liệu Landsat và CDL. Lưu ý rằng chúng tôi có thể tự động tải xuống và kiểm tra dữ liệu CDL. Cũng lưu ý rằng mỗi bộ dữ liệu này có thể chứa các tệp ở các hệ quy chiếu tọa độ (CRS) hoặc độ phân giải khác nhau, nhưng TorchGeo tự động đảm bảo rằng CRS và độ phân giải phù hợp được sử dụng.

cdl = CDL(paths='...', download=True, checksum=True)
dataset = landsat & cdl

Hiện tại, tập dữ liệu này có thể được sử dụng với trình tải dữ liệu PyTorch. Không giống như bộ dữ liệu chuẩn, bộ dữ liệu không gian địa lý thường bao gồm các hình ảnh rất lớn. Ví dụ: bộ dữ liệu CDL bao gồm một hình ảnh duy nhất bao phủ toàn bộ lục địa Hoa Kỳ. Để lấy mẫu từ các bộ dữ liệu này bằng tọa độ không gian địa lý, TorchGeo xác định một số người lấy mẫu. Trong ví dụ này, chúng tôi sẽ sử dụng bộ lấy mẫu ngẫu nhiên trả về hình ảnh 256 x 256 pixel và 10.000 mẫu mỗi kỷ nguyên. Chúng tôi cũng sử dụng chức năng đối chiếu tùy chỉnh để kết hợp từng từ điển mẫu thành một lô mẫu nhỏ.

sampler = RandomPatchSampler(dataset, size=256, length=10000)
dataloader = DataLoader(
    dataset, batch_size=128, sampler=sampler, collate_fn=stack_samples
)

Trình tải dữ liệu này hiện có thể được sử dụng trong quy trình đánh giá/đào tạo thông thường của bạn.

for batch in dataloader:
    image = batch['image']
    mask = batch['mask']

    # train a model, or make predictions using a pre-trained model

Nhiều ứng dụng liên quan đến việc soạn thảo các bộ dữ liệu một cách thông minh dựa trên siêu dữ liệu không gian địa lý như thế này. Ví dụ: người dùng có thể muốn:

• Kết hợp các tập dữ liệu cho nhiều nguồn hình ảnh và coi chúng là tương đương (ví dụ: Landsat 7 và 8)
• Kết hợp các bộ dữ liệu cho các vị trí không gian địa lý khác nhau (ví dụ: Chesapeake NY và PA)

Những kết hợp này yêu cầu tất cả các truy vấn phải có trong ít nhất một tập dữ liệu và có thể được tạo bằng cách sử dụng một UnionDataset. Tương tự, người dùng có thể muốn:

• Kết hợp nhãn hình ảnh và mục tiêu cũng như mẫu từ cả hai cùng một lúc (ví dụ: Landsat và CDL)
• Kết hợp các bộ dữ liệu cho nhiều nguồn hình ảnh để học tập đa phương thức hoặc tổng hợp dữ liệu (ví dụ: Landsat và Sentinel)

Những kết hợp này yêu cầu tất cả các truy vấn phải có trong cả hai tập dữ liệu và có thể được tạo bằng cách sử dụng một IntersectionDataset. TorchGeo tự động soạn các bộ dữ liệu này cho bạn khi bạn sử dụng giao lộ (&) và hợp (|) toán tử.

Bộ dữ liệu điểm chuẩn

TorchGeo bao gồm một số bộ dữ liệu điểm chuẩn—bộ dữ liệu bao gồm cả hình ảnh đầu vào và nhãn đích. Điều này bao gồm các bộ dữ liệu cho các tác vụ như phân loại hình ảnh, hồi quy, phân đoạn ngữ nghĩa, phát hiện đối tượng, phân đoạn phiên bản, phát hiện thay đổi, v.v.

Nếu bạn đã sử dụng tầm nhìn ngọn đuốc trước đây, những bộ dữ liệu này có vẻ rất quen thuộc. Trong ví dụ này, chúng tôi sẽ tạo một tập dữ liệu cho lớp mười có độ phân giải rất cao của Đại học Bách khoa Tây Bắc (NWPU) (VHR-10) tập dữ liệu phát hiện đối tượng không gian địa lý. Tập dữ liệu này có thể được tự động tải xuống, kiểm tra và trích xuất, giống như với 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:
    image = batch['image']  # list of images
    bbox_xyxy = batch['bbox_xyxy']  # list of boxes
    label = batch['label']  # list of labels
    mask = batch['mask']  # list of masks

    # train a model, or make predictions using a pre-trained model

Tất cả các bộ dữ liệu TorchGeo đều tương thích với trình tải dữ liệu PyTorch, giúp chúng dễ dàng tích hợp vào quy trình đào tạo hiện có. Sự khác biệt duy nhất giữa tập dữ liệu chuẩn trong TorchGeo và tập dữ liệu tương tự trong torchvision là mỗi tập dữ liệu trả về một từ điển có khóa cho mỗi PyTorch Tensor.

Trọng lượng được đào tạo trước

Trọng số được huấn luyện trước đã được chứng minh là cực kỳ có lợi cho việc chuyển giao các nhiệm vụ học tập trong thị giác máy tính. Những người thực hành thường sử dụng các mô hình được đào tạo trước trên bộ dữ liệu ImageNet, chứa hình ảnh RGB. Tuy nhiên, dữ liệu viễn thám thường vượt xa RGB với các kênh đa phổ bổ sung có thể khác nhau giữa các cảm biến. TorchGeo là thư viện đầu tiên hỗ trợ các mô hình được đào tạo trước trên các cảm biến đa quang phổ khác nhau và áp dụng công nghệ của torchvision đa trọng lượng API. Bạn có thể xem bản tóm tắt về các trọng số hiện có trong tài liệu. Để tạo một timm Với mô hình Resnet-18 với các trọng số đã được tiền xử lý trên hình ảnh Sentinel-2, bạn có thể thực hiện như sau:

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, check_hash=True, weights_only=True),
    strict=False,
)

Các trọng số này cũng có thể được sử dụng trực tiếp trong các mô-đun TorchGeo Lightning được hiển thị trong phần sau thông qua weights lý lẽ. Để biết ví dụ về sổ ghi chép, hãy xem cái này hướng dẫn.

Khả năng tái tạo với Lightning

Để tạo điều kiện so sánh trực tiếp giữa các kết quả được công bố trong tài liệu và giảm hơn nữa mã soạn sẵn cần thiết để chạy thử nghiệm với bộ dữ liệu trong TorchGeo, chúng tôi đã tạo Lightning mô-đun dữ liệu với sự phân chia thử nghiệm đào tạo được xác định rõ ràng và nhiệm vụ cho các nhiệm vụ khác nhau như phân loại, hồi quy và phân đoạn ngữ nghĩa. Các mô-đun dữ liệu này cho thấy cách kết hợp các phần mở rộng từ thư viện kornia, bao gồm các biến đổi tiền xử lý (với số liệu thống kê kênh được tính toán trước) và cho phép người dùng dễ dàng thử nghiệm các siêu tham số liên quan đến chính dữ liệu (trái ngược với quy trình lập mô hình). Huấn luyện mô hình phân đoạn ngữ nghĩa trên Ghi nhãn hình ảnh trên không Inria tập dữ liệu dễ dàng chỉ bằng một vài thao tác nhập và bốn dòng mã.

datamodule = InriaAerialImageLabelingDataModule(
    root='...', batch_size=64, num_workers=6
)
task = SemanticSegmentation(
    model='unet',
    backbone='resnet50',
    weights=True,
    in_channels=3,
    task='binary',
    loss='bce',
)
trainer = Trainer(default_root_dir='...')

trainer.fit(model=task, datamodule=datamodule)

TorchGeo cũng hỗ trợ đào tạo giao diện dòng lệnh bằng cách sử dụng LightningCLI. Nó có thể được gọi theo hai cách:

# If torchgeo has been installed
torchgeo
# If torchgeo has been installed, or if it has been cloned to the current directory
python3 -m torchgeo

Nó hỗ trợ cấu hình dòng lệnh hoặc tệp cấu hình YAML/JSON. Các tùy chọn hợp lệ có thể được tìm thấy từ các thông báo trợ giúp:

# See valid stages
torchgeo --help
# See valid trainer options
torchgeo fit --help
# See valid model options
torchgeo fit --model.help Classification
# See valid data options
torchgeo fit --data.help EuroSAT100DataModule

Sử dụng tệp cấu hình sau:

trainer:
  max_epochs: 20
model:
  class_path: Classification
  init_args:
    model: 'resnet18'
    in_channels: 13
    num_classes: 10
data:
  class_path: EuroSAT100DataModule
  init_args:
    batch_size: 8
  dict_kwargs:
    download: true

chúng ta có thể thấy kịch bản đang hoạt động:

# Train and validate a model
torchgeo fit --config config.yaml
# Validate-only
torchgeo validate --config config.yaml --ckpt_path=...
# Calculate and report test accuracy
torchgeo test --config config.yaml --ckpt_path=...

Nó cũng có thể được nhập và sử dụng trong tập lệnh Python nếu bạn cần mở rộng nó để thêm các tính năng mới:

from torchgeo.main import main

main(['fit', '--config', 'config.yaml'])

Xem Tài liệu sét để biết thêm chi tiết.

Trích dẫn

Nếu bạn sử dụng phần mềm này trong công việc của mình, vui lòng trích dẫn của chúng tôi giấy:

@article{stewart2024torchgeo,
    author = {Stewart, Adam J. and Robinson, Caleb and Corley, Isaac A. and Ortiz, Anthony and Lavista Ferres, Juan M. and Banerjee, Arindam},
    title = {{TorchGeo}: Deep Learning With Geospatial Data},
    journal = {ACM Transactions on Spatial Algorithms and Systems},
    volume = {11},
    number = {4},
    pages = {1--28},
    month = aug,
    year = {2025}
}

Đóng góp

Dự án này hoan nghênh những đóng góp và đề xuất. Nếu bạn muốn gửi yêu cầu kéo, hãy xem Hướng dẫn đóng góp để biết thêm thông tin.

Dự án này đã áp dụng Quy tắc ứng xử trong giao ước của người đóng góp. Để biết thêm thông tin, hãy xem Câu hỏi thường gặp về Quy tắc ứng xử của Công ước cộng tác viên hoặc liên hệ với @adamjstewart trên chùng xuống với bất kỳ câu hỏi hoặc ý kiến bổ sung.