elevation.datasource#

Attributes#

AW3D30_SPEC

AW3D30_TILE_INDECES_TRANSFORM

CGIAR_L1_TILE_INDECES_TRANSFORM

DEFAULT_GDAL_OPTIONS

DEFAULT_OUTPUT

DEFAULT_PRODUCT

DTED_L2_TILE_INDECES_TRANSFORM

EDH_L1_CHUNK_INDECES_TRANSFORM

EDH_L2_CHUNK_INDECES_TRANSFORM

GLO_30_SPEC

GLO_90_SPEC

MAPZEN_SPEC

MARGIN

MAX_DOWNLOAD_TILES

PRODUCTS

PRODUCTS_SPECS

RETIRED_PRODUCTS

SRTM1_ELLIP_SPEC

SRTM1_GEOID_SPEC

SRTM3_SPEC

Exceptions#

ProductRetiredError

Raised when a product label retired in elevation 2.0 is requested.

Classes#

DatasourceSpec

How a DEM product lists, prepares and caches its tiles.

Functions#

build_bounds(bounds[, margin])

cgiar_l1_tiles(left, bottom, right, top[, tile_template])

clean([cache_dir, product])

Clean up the product cache from temporary files.

clip(bounds[, output, margin, product, cache_dir, ...])

Clip the DEM to given bounds.

dataset([dataset])

Show the STAC metadata of the datasets.

distclean([cache_dir, product])

Remove the product cache entirely.

dted_l2_tiles(left, bottom, right, top[, ...])

ensure_setup(cache_dir, product)

info([cache_dir, product])

Show info about the product cache.

latlon_to_indeces(transform, lon, lat)

prepare_tile(gdal_source, tile_name[, remote_ext])

prepare_tile_member(gdal_source, tile_name[, ...])

prepare_tile_zarr(gdal_source, ilat, ilon, chunks, ...)

seed([cache_dir, product, bounds, max_download_tiles, ...])

Seed the DEM to given bounds.

srtm_ellip_tiles(left, bottom, right, top[, ...])

zarr_tiles(left, bottom, right, top, transform)

Module Contents#

exception elevation.datasource.ProductRetiredError#

Bases: KeyError

Raised when a product label retired in elevation 2.0 is requested.

Subclasses KeyError, like an unknown product label, but renders the migration message without the repr quoting that KeyError adds.

class elevation.datasource.DatasourceSpec#

Bases: TypedDict

How a DEM product lists, prepares and caches its tiles.

cached_tiles: collections.abc.Callable[..., collections.abc.Iterator[elevation.cache.Tile]]#
cached_tiles_kwargs: NotRequired[dict[str, Any]]#
empty_on_notfound: NotRequired[bool]#
prepare_tile: collections.abc.Callable[..., str]#
prepare_tile_kwargs: dict[str, Any]#
tile_gdal_options: NotRequired[str]#
elevation.datasource.build_bounds(bounds, margin=MARGIN)#
elevation.datasource.cgiar_l1_tiles(left, bottom, right, top, tile_template='srtm_{ilon:02d}_{ilat:02d}')#
elevation.datasource.clean(cache_dir=None, product=DEFAULT_PRODUCT)#

Clean up the product cache from temporary files.

Parameters:

  • cache_dir – Root of the DEM cache folder.

  • product – DEM product choice.

elevation.datasource.clip(bounds, output=DEFAULT_OUTPUT, margin=MARGIN, product=DEFAULT_PRODUCT, *, cache_dir=None, gdal_options=DEFAULT_GDAL_OPTIONS, max_download_tiles=MAX_DOWNLOAD_TILES)#

Clip the DEM to given bounds.

Parameters:

  • bounds – Output bounds in ‘left bottom right top’ order.

  • output – Path to output file. Existing files will be overwritten.

  • margin – Decimal degree margin added to the bounds. Use ‘%’ for percent margin.

  • product – DEM product choice.

  • cache_dir – Root of the DEM cache folder.

  • gdal_options – GDAL creation options of the output file, e.g. ‘-co COMPRESS=LZW’.

  • max_download_tiles – Maximum number of tiles to download.

elevation.datasource.dataset(dataset=None)#

Show the STAC metadata of the datasets.

Parameters:

dataset – Dataset choice, all the products if not given.

Returns:

The dataset STAC files, in PRODUCTS order, as a stream of YAML documents.

elevation.datasource.distclean(cache_dir=None, product=DEFAULT_PRODUCT)#

Remove the product cache entirely.

Parameters:

  • cache_dir – Root of the DEM cache folder.

  • product – DEM product choice.

elevation.datasource.dted_l2_tiles(left, bottom, right, top, tile_name_template='{slat}{slon}', transform=DTED_L2_TILE_INDECES_TRANSFORM, lat_digits=2)#
elevation.datasource.ensure_setup(cache_dir, product)#
elevation.datasource.info(cache_dir=None, product=DEFAULT_PRODUCT)#

Show info about the product cache.

Parameters:

  • cache_dir – Root of the DEM cache folder.

  • product – DEM product choice.

Returns:

The product cache report.

elevation.datasource.latlon_to_indeces(transform, lon, lat)#
elevation.datasource.prepare_tile(gdal_source, tile_name, remote_ext='.tif', **kwargs)#
elevation.datasource.prepare_tile_member(gdal_source, tile_name, remote_ext='.zip', member_template='{tile_name}.tif', **kwargs)#
elevation.datasource.prepare_tile_zarr(gdal_source, ilat, ilon, chunks, **kwargs)#
elevation.datasource.seed(cache_dir=None, product=DEFAULT_PRODUCT, bounds=None, max_download_tiles=MAX_DOWNLOAD_TILES, *, margin=MARGIN)#

Seed the DEM to given bounds.

A remote product is not downloaded whole: only the chunks of the store that cover the bounds are read in place and cached.

Parameters:

  • cache_dir – Root of the DEM cache folder.

  • product – DEM product choice.

  • bounds – Output bounds in ‘left bottom right top’ order.

  • max_download_tiles – Maximum number of tiles to download.

  • margin – Decimal degree margin added to the bounds. Use ‘%’ for percent margin.

Returns:

The datasource root and the bounds with the margin applied.

elevation.datasource.srtm_ellip_tiles(left, bottom, right, top, tile_name_template='{slat}{slon}_wgs84')#
elevation.datasource.zarr_tiles(left, bottom, right, top, transform)#
elevation.datasource.AW3D30_SPEC: DatasourceSpec#
elevation.datasource.AW3D30_TILE_INDECES_TRANSFORM = (0.0, 1.0, 0.0, 1.0)#
elevation.datasource.CGIAR_L1_TILE_INDECES_TRANSFORM#
elevation.datasource.DEFAULT_GDAL_OPTIONS = '-co TILED=YES -co COMPRESS=DEFLATE -co ZLEVEL=9 -co NUM_THREADS=ALL_CPUS'#
elevation.datasource.DEFAULT_OUTPUT = 'out.tif'#
elevation.datasource.DEFAULT_PRODUCT = 'MAPZEN'#
elevation.datasource.DTED_L2_TILE_INDECES_TRANSFORM#
elevation.datasource.EDH_L1_CHUNK_INDECES_TRANSFORM#
elevation.datasource.EDH_L2_CHUNK_INDECES_TRANSFORM#
elevation.datasource.GLO_30_SPEC: DatasourceSpec#
elevation.datasource.GLO_90_SPEC: DatasourceSpec#
elevation.datasource.MAPZEN_SPEC: DatasourceSpec#
elevation.datasource.MARGIN = '0'#
elevation.datasource.MAX_DOWNLOAD_TILES = 25#
elevation.datasource.PRODUCTS = ['MAPZEN', 'GLO-30', 'AW3D30', 'SRTM1_GEOID', 'SRTM1_ELLIP', 'GLO-90', 'SRTM3']#
elevation.datasource.PRODUCTS_SPECS: dict[str, DatasourceSpec]#
elevation.datasource.RETIRED_PRODUCTS: dict[str, str]#
elevation.datasource.SRTM1_ELLIP_SPEC: DatasourceSpec#
elevation.datasource.SRTM1_GEOID_SPEC: DatasourceSpec#
elevation.datasource.SRTM3_SPEC: DatasourceSpec#