Shortcuts

torchgeo.samplers

Samplers

Samplers are used to index a dataset, retrieving a single query at a time. For NonGeoDataset, dataset objects can be indexed with integers, and PyTorch’s builtin samplers are sufficient. For GeoDataset, dataset objects require a bounding box for indexing. For this reason, we define our own GeoSampler implementations below. These can be used like so:

from torch.utils.data import DataLoader

from torchgeo.datasets import Landsat
from torchgeo.samplers import RandomGeoSampler

dataset = Landsat(...)
sampler = RandomGeoSampler(dataset, size=256, length=10000)
dataloader = DataLoader(dataset, sampler=sampler)

This data loader will return 256x256 px images, and has an epoch length of 10,000.

Random Geo Sampler

class torchgeo.samplers.RandomGeoSampler(dataset, size, length=None, roi=None, units=Units.PIXELS, generator=None)[source]

Bases: GeoSampler

Samples elements from a region of interest randomly.

This is particularly useful during training when you want to maximize the size of the dataset and return as many random chips as possible. Note that randomly sampled chips may overlap.

This sampler is not recommended for use with tile-based datasets. Use RandomBatchGeoSampler instead.

__init__(dataset, size, length=None, roi=None, units=Units.PIXELS, generator=None)[source]

Initialize a new Sampler instance.

The size argument can either be:

  • a single float - in which case the same value is used for the height and width dimension

  • a tuple of two floats - in which case, the first float is used for the height dimension, and the second float for the width dimension

Changed in version 0.3: Added units parameter, changed default to pixel units

Changed in version 0.4: length parameter is now optional, a reasonable default will be used

New in version 0.7: The generator parameter.

Parameters:
  • dataset (GeoDataset) – dataset to index from

  • size (tuple[float, float] | float) – dimensions of each patch

  • length (int | None) – number of random samples to draw per epoch (defaults to approximately the maximal number of non-overlapping chips of size size that could be sampled from the dataset)

  • roi (torchgeo.datasets.utils.BoundingBox | None) – region of interest to sample from (minx, maxx, miny, maxy, mint, maxt) (defaults to the bounds of dataset.index)

  • units (Units) – defines if size is in pixel or CRS units

  • generator (torch._C.Generator | None) – pseudo-random number generator (PRNG).

__iter__()[source]

Return the index of a dataset.

Returns:

(minx, maxx, miny, maxy, mint, maxt) coordinates to index a dataset

Return type:

Iterator[BoundingBox]

__len__()[source]

Return the number of samples in a single epoch.

Returns:

length of the epoch

Return type:

int

Grid Geo Sampler

class torchgeo.samplers.GridGeoSampler(dataset, size, stride, roi=None, units=Units.PIXELS)[source]

Bases: GeoSampler

Samples elements in a grid-like fashion.

This is particularly useful during evaluation when you want to make predictions for an entire region of interest. You want to minimize the amount of redundant computation by minimizing overlap between chips.

Usually the stride should be slightly smaller than the chip size such that each chip has some small overlap with surrounding chips. This is used to prevent stitching artifacts when combining each prediction patch. The overlap between each chip (chip_size - stride) should be approximately equal to the receptive field of the CNN.

__init__(dataset, size, stride, roi=None, units=Units.PIXELS)[source]

Initialize a new Sampler instance.

The size and stride arguments can either be:

  • a single float - in which case the same value is used for the height and width dimension

  • a tuple of two floats - in which case, the first float is used for the height dimension, and the second float for the width dimension

Changed in version 0.3: Added units parameter, changed default to pixel units

Parameters:
__iter__()[source]

Return the index of a dataset.

Returns:

(minx, maxx, miny, maxy, mint, maxt) coordinates to index a dataset

Return type:

Iterator[BoundingBox]

__len__()[source]

Return the number of samples over the ROI.

Returns:

number of patches that will be sampled

Return type:

int

Pre-chipped Geo Sampler

class torchgeo.samplers.PreChippedGeoSampler(dataset, roi=None, shuffle=False, generator=None)[source]

Bases: GeoSampler

Samples entire files at a time.

This is particularly useful for datasets that contain geospatial metadata and subclass GeoDataset but have already been pre-processed into chips.

This sampler should not be used with NonGeoDataset. You may encounter problems when using an ROI that partially intersects with one of the file bounding boxes, when using an IntersectionDataset, or when each file is in a different CRS. These issues can be solved by adding padding.

__init__(dataset, roi=None, shuffle=False, generator=None)[source]

Initialize a new Sampler instance.

New in version 0.3.

New in version 0.7: The generator parameter.

Parameters:
  • dataset (GeoDataset) – dataset to index from

  • roi (torchgeo.datasets.utils.BoundingBox | None) – region of interest to sample from (minx, maxx, miny, maxy, mint, maxt) (defaults to the bounds of dataset.index)

  • shuffle (bool) – if True, reshuffle data at every epoch

  • generator (torch._C.Generator | None) – pseudo-random number generator (PRNG) used in combination with shuffle.

__iter__()[source]

Return the index of a dataset.

Returns:

(minx, maxx, miny, maxy, mint, maxt) coordinates to index a dataset

Return type:

Iterator[BoundingBox]

__len__()[source]

Return the number of samples over the ROI.

Returns:

number of patches that will be sampled

Return type:

int

Batch Samplers

When working with large tile-based datasets, randomly sampling patches from each tile can be extremely time consuming. It’s much more efficient to choose a tile, load it, warp it to the appropriate coordinate reference system (CRS) and resolution, and then sample random patches from that tile to construct a mini-batch of data. For this reason, we define our own BatchGeoSampler implementations below. These can be used like so:

from torch.utils.data import DataLoader

from torchgeo.datasets import Landsat
from torchgeo.samplers import RandomBatchGeoSampler

dataset = Landsat(...)
sampler = RandomBatchGeoSampler(dataset, size=256, batch_size=128, length=10000)
dataloader = DataLoader(dataset, batch_sampler=sampler)

This data loader will return 256x256 px images, and has a batch size of 128 and an epoch length of 10,000.

Random Batch Geo Sampler

class torchgeo.samplers.RandomBatchGeoSampler(dataset, size, batch_size, length=None, roi=None, units=Units.PIXELS, generator=None)[source]

Bases: BatchGeoSampler

Samples batches of elements from a region of interest randomly.

This is particularly useful during training when you want to maximize the size of the dataset and return as many random chips as possible. Note that randomly sampled chips may overlap.

__init__(dataset, size, batch_size, length=None, roi=None, units=Units.PIXELS, generator=None)[source]

Initialize a new Sampler instance.

The size argument can either be:

  • a single float - in which case the same value is used for the height and width dimension

  • a tuple of two floats - in which case, the first float is used for the height dimension, and the second float for the width dimension

Changed in version 0.3: Added units parameter, changed default to pixel units

Changed in version 0.4: length parameter is now optional, a reasonable default will be used

New in version 0.7: The generator parameter.

Parameters:
  • dataset (GeoDataset) – dataset to index from

  • size (tuple[float, float] | float) – dimensions of each patch

  • batch_size (int) – number of samples per batch

  • length (int | None) – number of samples per epoch (defaults to approximately the maximal number of non-overlapping chips of size size that could be sampled from the dataset)

  • roi (torchgeo.datasets.utils.BoundingBox | None) – region of interest to sample from (minx, maxx, miny, maxy, mint, maxt) (defaults to the bounds of dataset.index)

  • units (Units) – defines if size is in pixel or CRS units

  • generator (torch._C.Generator | None) – pseudo-random number generator (PRNG).

__iter__()[source]

Return the indices of a dataset.

Returns:

batch of (minx, maxx, miny, maxy, mint, maxt) coordinates to index a dataset

Return type:

Iterator[list[torchgeo.datasets.utils.BoundingBox]]

__len__()[source]

Return the number of batches in a single epoch.

Returns:

number of batches in an epoch

Return type:

int

Base Classes

If you want to write your own custom sampler, you can extend one of these abstract base classes.

Geo Sampler

class torchgeo.samplers.GeoSampler(dataset, roi=None)[source]

Bases: Sampler[BoundingBox], ABC

Abstract base class for sampling from GeoDataset.

Unlike PyTorch’s Sampler, GeoSampler returns enough geospatial information to uniquely index any GeoDataset. This includes things like latitude, longitude, height, width, projection, coordinate system, and time.

__init__(dataset, roi=None)[source]

Initialize a new Sampler instance.

Parameters:
abstract __iter__()[source]

Return the index of a dataset.

Returns:

(minx, maxx, miny, maxy, mint, maxt) coordinates to index a dataset

Return type:

Iterator[BoundingBox]

Batch Geo Sampler

class torchgeo.samplers.BatchGeoSampler(dataset, roi=None)[source]

Bases: Sampler[list[BoundingBox]], ABC

Abstract base class for sampling from GeoDataset.

Unlike PyTorch’s BatchSampler, BatchGeoSampler returns enough geospatial information to uniquely index any GeoDataset. This includes things like latitude, longitude, height, width, projection, coordinate system, and time.

__init__(dataset, roi=None)[source]

Initialize a new Sampler instance.

Parameters:
abstract __iter__()[source]

Return a batch of indices of a dataset.

Returns:

batch of (minx, maxx, miny, maxy, mint, maxt) coordinates to index a dataset

Return type:

Iterator[list[torchgeo.datasets.utils.BoundingBox]]

Utilities

torchgeo.samplers.get_random_bounding_box(bounds, size, res, generator=None)[source]

Returns a random bounding box within a given bounding box.

The size argument can either be:

  • a single float - in which case the same value is used for the height and width dimension

  • a tuple of two floats - in which case, the first float is used for the height dimension, and the second float for the width dimension

New in version 0.7: The generator parameter.

Parameters:
Returns:

randomly sampled bounding box from the extent of the input

Return type:

BoundingBox

torchgeo.samplers.tile_to_chips(bounds, size, stride=None)[source]

Compute number of chips that can be sampled from a tile.

Let \(i\) be the size of the input tile. Let \(k\) be the requested size of the output patch. Let \(s\) be the requested stride. Let \(o\) be the number of output chips sampled from each tile. \(o\) can then be computed as:

\[o = \left\lceil \frac{i - k}{s} \right\rceil + 1\]

This is almost identical to relationship 5 in https://doi.org/10.48550/arXiv.1603.07285. However, we use ceiling instead of floor because we want to include the final remaining chip in each row/column when bounds is not an integer multiple of stride.

Parameters:
Returns:

the number of rows/columns that can be sampled

Return type:

tuple[int, int]

New in version 0.4.

Units

By default, the size parameter specifies the size of the image in pixel units. If you would instead like to specify the size in CRS units, you can change the units parameter like so:

from torch.utils.data import DataLoader

from torchgeo.datasets import Landsat
from torchgeo.samplers import RandomGeoSampler, Units

dataset = Landsat(...)
sampler = RandomGeoSampler(dataset, size=256 * 30, length=10000, units=Units.CRS)
dataloader = DataLoader(dataset, sampler=sampler)

Assuming that each pixel in the CRS is 30 m, this data loader will return 256x256 px images, and has an epoch length of 10,000.

class torchgeo.samplers.Units(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration defining units of size parameter.

Used by GeoSampler and BatchGeoSampler.

PIXELS = 1

Units in number of pixels

CRS = 2

Units of coordinate reference system (CRS)

Docs

Access comprehensive developer documentation for PyTorch

View Docs

Tutorials

Get in-depth tutorials for beginners and advanced developers

View Tutorials

Resources

Find development resources and get your questions answered

View Resources