elevation.datasource
====================

.. py:module:: elevation.datasource


Attributes
----------

.. autoapisummary::

   elevation.datasource.AW3D30_SPEC
   elevation.datasource.AW3D30_TILE_INDECES_TRANSFORM
   elevation.datasource.CGIAR_L1_TILE_INDECES_TRANSFORM
   elevation.datasource.DEFAULT_GDAL_OPTIONS
   elevation.datasource.DEFAULT_OUTPUT
   elevation.datasource.DEFAULT_PRODUCT
   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
   elevation.datasource.GLO_90_SPEC
   elevation.datasource.MAPZEN_SPEC
   elevation.datasource.MARGIN
   elevation.datasource.MAX_DOWNLOAD_TILES
   elevation.datasource.PRODUCTS
   elevation.datasource.PRODUCTS_SPECS
   elevation.datasource.RETIRED_PRODUCTS
   elevation.datasource.SRTM1_ELLIP_SPEC
   elevation.datasource.SRTM1_GEOID_SPEC
   elevation.datasource.SRTM3_SPEC


Exceptions
----------

.. autoapisummary::

   elevation.datasource.ProductRetiredError


Classes
-------

.. autoapisummary::

   elevation.datasource.DatasourceSpec


Functions
---------

.. autoapisummary::

   elevation.datasource.build_bounds
   elevation.datasource.cgiar_l1_tiles
   elevation.datasource.clean
   elevation.datasource.clip
   elevation.datasource.dataset
   elevation.datasource.distclean
   elevation.datasource.dted_l2_tiles
   elevation.datasource.ensure_setup
   elevation.datasource.info
   elevation.datasource.latlon_to_indeces
   elevation.datasource.prepare_tile
   elevation.datasource.prepare_tile_member
   elevation.datasource.prepare_tile_zarr
   elevation.datasource.seed
   elevation.datasource.srtm_ellip_tiles
   elevation.datasource.zarr_tiles


Module Contents
---------------

.. py:exception:: ProductRetiredError

   Bases: :py:obj:`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.


.. py:class:: DatasourceSpec

   Bases: :py:obj:`TypedDict`


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


   .. py:attribute:: cached_tiles
      :type:  collections.abc.Callable[..., collections.abc.Iterator[elevation.cache.Tile]]


   .. py:attribute:: cached_tiles_kwargs
      :type:  NotRequired[dict[str, Any]]


   .. py:attribute:: empty_on_notfound
      :type:  NotRequired[bool]


   .. py:attribute:: prepare_tile
      :type:  collections.abc.Callable[..., str]


   .. py:attribute:: prepare_tile_kwargs
      :type:  dict[str, Any]


   .. py:attribute:: tile_gdal_options
      :type:  NotRequired[str]


.. py:function:: build_bounds(bounds, margin = MARGIN)

.. py:function:: cgiar_l1_tiles(left, bottom, right, top, tile_template = 'srtm_{ilon:02d}_{ilat:02d}')

.. py:function:: clean(cache_dir = None, product = DEFAULT_PRODUCT)

   Clean up the product cache from temporary files.

   :param cache_dir: Root of the DEM cache folder.
   :param product: DEM product choice.


.. py:function:: 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.

   :param bounds: Output bounds in 'left bottom right top' order.
   :param output: Path to output file. Existing files will be overwritten.
   :param margin: Decimal degree margin added to the bounds. Use '%' for percent margin.
   :param product: DEM product choice.
   :param cache_dir: Root of the DEM cache folder.
   :param gdal_options: GDAL creation options of the output file, e.g. '-co COMPRESS=LZW'.
   :param max_download_tiles: Maximum number of tiles to download.


.. py:function:: dataset(dataset = None)

   Show the STAC metadata of the datasets.

   :param dataset: Dataset choice, all the products if not given.
   :return: The dataset STAC files, in PRODUCTS order, as a stream of YAML documents.


.. py:function:: distclean(cache_dir = None, product = DEFAULT_PRODUCT)

   Remove the product cache entirely.

   :param cache_dir: Root of the DEM cache folder.
   :param product: DEM product choice.


.. py:function:: dted_l2_tiles(left, bottom, right, top, tile_name_template = '{slat}{slon}', transform = DTED_L2_TILE_INDECES_TRANSFORM, lat_digits = 2)

.. py:function:: ensure_setup(cache_dir, product)

.. py:function:: info(cache_dir = None, product = DEFAULT_PRODUCT)

   Show info about the product cache.

   :param cache_dir: Root of the DEM cache folder.
   :param product: DEM product choice.
   :return: The product cache report.


.. py:function:: latlon_to_indeces(transform, lon, lat)

.. py:function:: prepare_tile(gdal_source, tile_name, remote_ext = '.tif', **kwargs)

.. py:function:: prepare_tile_member(gdal_source, tile_name, remote_ext = '.zip', member_template = '{tile_name}.tif', **kwargs)

.. py:function:: prepare_tile_zarr(gdal_source, ilat, ilon, chunks, **kwargs)

.. py:function:: 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.

   :param cache_dir: Root of the DEM cache folder.
   :param product: DEM product choice.
   :param bounds: Output bounds in 'left bottom right top' order.
   :param max_download_tiles: Maximum number of tiles to download.
   :param margin: Decimal degree margin added to the bounds. Use '%' for percent margin.
   :return: The datasource root and the bounds with the margin applied.


.. py:function:: srtm_ellip_tiles(left, bottom, right, top, tile_name_template = '{slat}{slon}_wgs84')

.. py:function:: zarr_tiles(left, bottom, right, top, transform)

.. py:data:: AW3D30_SPEC
   :type:  DatasourceSpec

.. py:data:: AW3D30_TILE_INDECES_TRANSFORM
   :value: (0.0, 1.0, 0.0, 1.0)


.. py:data:: CGIAR_L1_TILE_INDECES_TRANSFORM

.. py:data:: DEFAULT_GDAL_OPTIONS
   :value: '-co TILED=YES -co COMPRESS=DEFLATE -co ZLEVEL=9 -co NUM_THREADS=ALL_CPUS'


.. py:data:: DEFAULT_OUTPUT
   :value: 'out.tif'


.. py:data:: DEFAULT_PRODUCT
   :value: 'MAPZEN'


.. py:data:: DTED_L2_TILE_INDECES_TRANSFORM

.. py:data:: EDH_L1_CHUNK_INDECES_TRANSFORM

.. py:data:: EDH_L2_CHUNK_INDECES_TRANSFORM

.. py:data:: GLO_30_SPEC
   :type:  DatasourceSpec

.. py:data:: GLO_90_SPEC
   :type:  DatasourceSpec

.. py:data:: MAPZEN_SPEC
   :type:  DatasourceSpec

.. py:data:: MARGIN
   :value: '0'


.. py:data:: MAX_DOWNLOAD_TILES
   :value: 25


.. py:data:: PRODUCTS
   :value: ['MAPZEN', 'GLO-30', 'AW3D30', 'SRTM1_GEOID', 'SRTM1_ELLIP', 'GLO-90', 'SRTM3']


.. py:data:: PRODUCTS_SPECS
   :type:  dict[str, DatasourceSpec]

.. py:data:: RETIRED_PRODUCTS
   :type:  dict[str, str]

.. py:data:: SRTM1_ELLIP_SPEC
   :type:  DatasourceSpec

.. py:data:: SRTM1_GEOID_SPEC
   :type:  DatasourceSpec

.. py:data:: SRTM3_SPEC
   :type:  DatasourceSpec