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 dimensiona
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 unitsChanged in version 0.4:
length
parameter is now optional, a reasonable default will be usedNew 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 unitsgenerator (torch._C.Generator | None) – pseudo-random number generator (PRNG).
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
andstride
arguments can either be:a single
float
- in which case the same value is used for the height and width dimensiona
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:
dataset (GeoDataset) – dataset to index from
size (tuple[float, float] | float) – dimensions of each patch
stride (tuple[float, float] | float) – distance to skip between each patch
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
andstride
are in pixel or CRS units
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 anIntersectionDataset
, 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.
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 dimensiona
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 unitsChanged in version 0.4:
length
parameter is now optional, a reasonable default will be usedNew 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 unitsgenerator (torch._C.Generator | None) – pseudo-random number generator (PRNG).
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 anyGeoDataset
. This includes things like latitude, longitude, height, width, projection, coordinate system, and time.- __init__(dataset, roi=None)[source]¶
Initialize a new Sampler instance.
- 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
)
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 anyGeoDataset
. This includes things like latitude, longitude, height, width, projection, coordinate system, and time.- __init__(dataset, roi=None)[source]¶
Initialize a new Sampler instance.
- 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
)
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 dimensiona
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:
bounds (BoundingBox) – the larger bounding box to sample from
size (tuple[float, float] | float) – the size of the bounding box to sample
res (float) – the resolution of the image
generator (torch._C.Generator | None) – pseudo-random number generator (PRNG).
- Returns:
randomly sampled bounding box from the extent of the input
- Return type:
- 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:
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
andBatchGeoSampler
.- PIXELS = 1¶
Units in number of pixels
- CRS = 2¶
Units of coordinate reference system (CRS)