OpenAerialMap#

class torchgeo.datasets.OpenAerialMap(paths='data', crs=None, res=None, bbox=None, zoom=19, max_items=1, transforms=None, cache=True, download=False, image_id=None, tile_size=256)[source]#

Bases: RasterDataset

OpenAerialMap dataset.

The OpenAerialMap (OAM) is an open service for accessing and sharing aerial imagery. The dataset provides access to crowd-sourced aerial imagery from various sources including drones, satellites, and aircraft.

This implementation uses the STAC API to query imagery and download tiles via TMS endpoints. The STAC API returns imagery sorted by most recent first.

Dataset features#

  • Aerial imagery from various sources (drones, satellites, aircraft)

  • Global coverage with varying resolution

  • STAC-based querying (most recent imagery first)

  • Tile naming following mercantile standard: OAM-{x}-{y}-{z}.tif

  • Automatic georeferencing using rasterio

  • RGB imagery (3-band)

  • Bbox format

Dataset usage#

Provide a bounding box and zoom level to download tiles:

dataset = OpenAerialMap(
    paths='data/openaerial',
    bbox=(lon_min, lat_min, lon_max, lat_max),
    zoom=19,
    download=True,
)

If you use this dataset in your research, please cite OpenAerialMap:

Added in version 0.10.

filename_glob = 'OAM-*.tif'#

Glob expression used to search for files.

This expression should be specific enough that it will not pick up files from other datasets. It should not include a file extension, as the dataset may be in a different file format than what it was originally downloaded as.

all_bands: tuple[str, ...] = ('R', 'G', 'B')#

Names of all available bands in the dataset

rgb_bands: tuple[str, ...] = ('R', 'G', 'B')#

Names of RGB bands in the dataset

__init__(paths='data', crs=None, res=None, bbox=None, zoom=19, max_items=1, transforms=None, cache=True, download=False, image_id=None, tile_size=256)[source]#

Initialize a new OpenAerialMap dataset instance.

Parameters:

  • paths (str | PathLike[str] | Iterable[str | PathLike[str]]) – one or more root directories to search or files to load

  • crs (CRS | None) – coordinate reference system (CRS) to warp to (defaults to EPSG:4326)

  • res (float | tuple[float, float] | None) – resolution of the dataset in units of CRS (defaults to resolution of first file found)

  • bbox (tuple[float, float, float, float] | None) – bounding box for STAC query as (xmin, ymin, xmax, ymax) in EPSG:4326.

  • zoom (int) – zoom level for tiles (15-23), only used when download=True. Higher zoom = more detail. Typical values: 18-20 for high-res drone imagery. Higher zoom gives higher resolution but covers less area per tile. Consider increasing tile_size for better quality at the same zoom. Check the GSD of the image before downloading.

  • max_items (int) – maximum number of STAC items to query.

  • transforms (Callable[[dict[str, Any]], dict[str, Any]] | None) – a function/transform that takes an input sample and returns a transformed version.

  • cache (bool) – if True, cache file handle to speed up repeated sampling

  • download (bool) – if True, download imagery from STAC API based on bbox

  • image_id (str | None) – optional STAC item ID to download specific imagery

  • tile_size (Literal[256, 512, 768, 1024]) – size of the tiles to download (supported : 256 , 512, 768, 1024); Do verify they exists in the remote image source as resolution of each image varies.

Raises:
plot(sample, show_titles=True, suptitle=None)[source]#

Plot a sample from the dataset.

Parameters:

  • sample (dict[str, Any]) – a sample returned by RasterDataset.__getitem__()

  • show_titles (bool) – flag indicating whether to show titles above each panel

  • suptitle (str | None) – optional string to use as a suptitle

Returns:

a matplotlib Figure with the rendered sample

Return type:

Figure