📜 Documentation

Welcome to the complete documentation for the elevatr package. Here, you’ll find everything you need to know about the core functionality of the library.

elevatr - A Python package to simplify downloading and processing elevation data.

elevatr.get_elev_raster

elevatr.get_elev_raster(locations, zoom, crs='EPSG:3857', clip='bbox', cache_folder=None, *, use_cache=True, delete_cache=True, verbose=True)

Get elevation raster for a bounding box. The raster is downloaded from AWS Terrain Tiles.

Parameters:

  • locations (tuple) – Bounding box coordinates (min_lon, min_lat, max_lon, max_lat) in WGS84/EPSG:4326. (min_lon, min_lat) is the bottom-left corner and (max_lon, max_lat) is the top-right corner.

  • zoom (int) – Zoom level of the raster. Between 0 and 14. Greater zoom level means higher resolution.

  • crs (str, optional) – Coordinate Reference System of the raster, by default “EPSG:3857” (Web Mercator proj).

  • clip (str, optional) – Clip the raster to the bounding box (‘bbox’) or the tile (‘tile’), by default ‘bbox’.

  • cache_folder (str, optional) – Folder to store the downloaded tiles, by default settings.cache_folder. NOTE: If you want to change the cache folder, it is recommended to set it with settings.cache_folder = “your_folder” just after the import to standardize the cache folder across the package.

  • use_cache (bool, optional) – Use the cache if available, by default True

  • delete_cache (bool, optional) – Delete the cache folder after the raster is created, by default True

  • verbose (bool, optional) – Print progress messages, by default True

Returns:

A Raster object containing the elevation raster and metadata.

Return type:

Raster

Examples: >>> import elevatr as elv >>> locations = (-5.14, 41.33, 9.56, 51.09) >>> zoom = 6 >>> raster = elv.get_elev_raster(locations, zoom)

Raises:

  • AssertionError – If the inputs are not valid.

  • ValueError – If clip is not ‘bbox’ or ‘tile’.

  • TypeError – If cache_folder is not a string, use_cache is not a boolean, delete_cache is not a boolean or

  • verbose is not a boolean. –

Parameters:

  • locations (tuple[float, float, float, float])

  • zoom (int)

  • crs (str | None)

  • clip (str | None)

  • cache_folder (str | None)

  • use_cache (bool | None)

  • delete_cache (bool | None)

  • verbose (bool | None)

Return type:

Raster | None

elevatr.Raster

class elevatr.Raster(data, meta)

A class to manage raster data.

Parameters:

  • data (ndarray)

  • meta (dict[str, Any])

show(cmap='viridis', figsize=(10, 10), *, clip_zero=False, clip_color='white', show_extras=True, file_path=None, **kwargs)

Display the raster data as an image.

Parameters:

  • cmap (str, optional) – The colormap to use for the image, by default “viridis”.

  • figsize (tuple, optional) – The size of the figure, by default (10, 10).

  • clip_zero (bool, optional) – Whether to clip negative values to zero, by default False.

  • clip_color (str, optional) – The color to use for clipped values, by default “white”.

  • show_extras (bool, optional) – Whether to show the colorbar and axis, by default True.

  • file_path (str, optional) – The path to save the image to, by default None.

  • **kwargs (dict, optional) – Additional keyword arguments to pass to matplotlib.pyplot.imshow.

Return type:

None

to_numpy()

Return the raster data as a NumPy array.

Returns:

The raster data as a NumPy array.

Return type:

np.ndarray

to_tif(path, compress=None)

Write the raster data to a GeoTIFF file.

Parameters:

  • path (str) – The path to write the GeoTIFF file.

  • compress (str, optional) – The compression type to use for the GeoTIFF file, by default None. Options are: - None: no compression - “lzw”: Lempel-Ziv-Welch (LZW) compression, lossless, good for general use - “packbits”: PackBits compression, simple and fast, but less efficient - “deflate”: DEFLATE compression, lossless, balances speed and compression ratio - “zstd”: Zstandard compression, lossless, high compression ratio and fast decompression - “lzma”: LZMA compression, lossless, very high compression ratio but slower

Raises:

ValueError – If an invalid compression type is provided.

Return type:

None

reproject(crs)

Reproject raster data to the desired CRS.

Parameters:

crs (str) – The target coordinate reference system (CRS) to reproject the raster to.

Return type:

None

Notes: This method updates the class attributes in place. The original raster data is overwritten.

to_obj(output_path, *, clip_zero=False, zscale=1.0, solid=False, texture_path=None)

Write the raster data to an OBJ file.

Parameters:

  • output_path (str) – The path to write the OBJ file.

  • clip_zero (bool, optional) – Whether to clip negative values to zero (sea level), by default False.

  • zscale (float, optional) – The scaling factor to apply to the z-axis. Decrease to attenuate elevation and increase to accentuate it, by default 1.0.

  • solid (bool, optional) – Whether to add a base below the surface to create a solid object, by default False.

  • texture_path (str | Path | None, optional) – The path to the texture image file, by default None.

Raises:

ValueError – If the resolution is not defined.

Return type:

None

show_3d(*, clip_zero=False, zscale=1.0, solid=False, basemap_quality='auto', transparent_background=False, render_quality=5, phi=30, theta=0, zoom=1, light_intensity=0.5, file_path=None, cache_folder=None, show=True, verbose=True)

Display the raster data as a 3D model.

Parameters:

  • clip_zero (bool, optional) – Whether to clip negative values to zero (sea level), by default False.

  • zscale (float, optional) – The scaling factor to apply to the z-axis. Decrease to attenuate elevation and increase to accentuate it, by default 1.0.

  • solid (bool, optional) – Whether to add a base below the surface to create a solid object, by default False.

  • basemap_quality (Union[str, int], optional) – The zoom level of the basemap image, by default ‘auto’. Big zoom levels will result in higher resolution images.

  • transparent_background (bool, optional) – Whether to use a transparent background for the rendered image, by default False.

  • render_quality (int, optional) – The quality of the rendered image, by default 5. Higher values will result in higher resolution images.

  • phi (float, optional) – The elevation angle in degrees, by default 30.

  • theta (float, optional) – The angle of rotation around the z-axis in degrees, by default 0.

  • zoom (float, optional) – The zoom level of the camera, by default 1.

  • light_intensity (float, optional) – The intensity of the light source, by default 0.5.

  • file_path (str, optional) – The path to save the rendered image to, by default None.

  • cache_folder (str, optional) – The folder to store the cached basemap image, OBJ file, and rendered image, by default settings.cache_folder. NOTE: If you want to change the cache folder, it is recommended to set it with settings.cache_folder = “your_folder” just after the import to standardize the cache folder across the package.

  • show (bool, optional) – Whether to display the rendered image, by default True.

  • verbose (bool, optional) – Whether to display progress messages, by default True.

Return type:

None

Notes: We use sha256 hashes to cache the basemap image, OBJ file, and rendered image. This allows us to avoid downloading the same basemap image multiple times and to avoid regenerating the OBJ file and rendering the image when the input parameters are the same.

static quit(*, cache_folder=None)

Delete the cache directory.

Return type:

None

Parameters:

cache_folder (str | Path | None)