elevation
=========

.. py:module:: elevation


Submodules
----------

.. toctree::
   :maxdepth: 1

   /_api/elevation/cache/index
   /_api/elevation/datasource/index
   /_api/elevation/spatial/index


Attributes
----------

.. autoapisummary::

   elevation.CACHE_DIR
   elevation.DEFAULT_GDAL_OPTIONS
   elevation.DEFAULT_OUTPUT
   elevation.DEFAULT_PRODUCT
   elevation.MARGIN
   elevation.MAX_DOWNLOAD_TILES
   elevation.PRODUCTS
   elevation.RETIRED_PRODUCTS
   elevation.TOOLS


Exceptions
----------

.. autoapisummary::

   elevation.ProductRetiredError


Functions
---------

.. autoapisummary::

   elevation.clean
   elevation.clip
   elevation.dataset
   elevation.distclean
   elevation.info
   elevation.resolve_cache_dir
   elevation.seed
   elevation.selfcheck


Package 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: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:: 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:: resolve_cache_dir(cache_dir)

   Return the DEM cache folder to use, as an absolute path.

   The ``cache_dir`` argument takes precedence over the ``EIO_CACHE_DIR`` environment
   variable, that takes precedence over the ``CACHE_DIR`` default.


.. 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:: selfcheck(tools = TOOLS, verbose = False)

   Audit the system for issues.

   :param tools: Tools description, defaults to TOOLS.
   :param verbose: Report each tool as it is tested.


.. py:data:: CACHE_DIR
   :type:  str

.. 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:: 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:: RETIRED_PRODUCTS
   :type:  dict[str, str]

.. py:data:: TOOLS
   :type:  list[tuple[str, str]]
   :value: [('gdal_translate', 'gdal_translate --version'), ('gdalbuildvrt', 'gdalbuildvrt --version'),...