Changelog#

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]#

Add a new function called elevation_bygrid that samples elevation values from the USGS 10 m seamless DEM VRT at a grid of longitude/latitude coordinates. It reads directly from Cloud-Optimized GeoTIFFs (EPSG:4269) and supports configurable resampling methods (nearest, bilinear, cubic, cubic spline, and Lanczos) via a windowed read approach. This is useful for obtaining elevation values at arbitrary point locations without downloading full tiles.
Add numpy as an explicit dependency (previously only a transitive dependency via rasterio).

Improve thread safety in get_dem by opening a fresh DatasetReader per tile instead of sharing a single instance across threads. The VRTPool is now used only for metadata (bounds, transform, nodata), not for concurrent reads.
Add early-return optimization in get_map: skip downloading when all requested tiles already exist on disk (consistent with get_dem behavior).
Move the valid_types tuple in get_map to a module-level constant (VALID_MAP_TYPES).
Simplify tiffs_to_da by skipping the .rio.clip() step when the geometry is a bounding box, since .rio.clip_box() already handles that case.
Migrate documentation from ReadTheDocs to GitHub Pages with mike versioning.
Add a GitHub Actions workflow (docs.yml) for automated documentation deployment. Pushes to main deploy the dev version, and tagged releases deploy a stable version via mike.
Add a GitHub Actions workflow (docs.yml) for automated documentation deployment. Pushes to main deploy the dev version, and tagged releases deploy a stable version via mike.

Add a new function called tiffs_to_da that converts a list of GeoTIFF files to a xarray.DataArray object. This function is useful for combining multiple GeoTIFF files that get_map and get_dem produce, into a single xarray.DataArray object for further analysis. Note that for using this function shapely and rioxarray need to be installed. The required dependencies did not change, these two are optional dependencies that are only needed for this new function.

Switch to using the new TinyRetriever library that was developed partly based on this package. It has the same two dependencies and includes the same functionality with some additional features.
Improve handling of errors when using build_vrt function by explicitly catching errors raised by gdalbuildvrt and raising a more informative error message. This should make it easier to debug issues when creating VRT files.

Refactor the package to run in Jupyter notebooks without using nest-asyncio. This is done by creating and initializing a single global event loop thread dedicated to only running the asynchronous parts of this package. As a result, nest-asyncio is no longer needed as a dependency.
Remove the out_crs option from get_map since the 3DEP service returns inconsistent results when the output CRS is not its default value of 3857. This is a breaking change since this value cannot be configured and the default value has changed from 5070 to 3857.

Use aiohttp and aiofiles for more performant and robust handling of service calls and downloading of 3DEP map requests. This should limits the number of connections made to the dynamic 3DEP service to avoid hammering the service and can reduce the memory usage when downloading large files. As a results, aiohttp and aiofiles are now required dependencies and urllib3 is no longer needed.
More robust handling of closing VRTPool at exit by creating a new class method called close. This method is called by the atexit module to ensure that the pools are closed when the program exits.

Considerable improvements in making service calls by creating connection pools using urllib3.HTTPSConnectionPool and rasterio.open. This should improve performance and robustness of service calls, and reduce the number of connections made to both the static and dynamic 3DEP services. As a results, urllib3 is now a required dependency.
Add a new private module called _pools that contains the connection pools for making service calls. The pools are lazily initialized and are shared across threads. Especially the VRT pools are created only when a specific resolution is requested, and are reused for subsequent requests of the same resolution. As such, the VRT info are loaded only once per resolution without using lru_cache.

Improve downloading of 3DEP map requests in get_map by streaming the response content to a file instead of loading it into memory. Also make exception handling more robust. The function has been refactored for better readability and maintainability.
Change the dependency of build_vrt from gdal to libgdal-core as it is more lightweight and does not require the full gdal package to be installed.
Improve documentation.

Since 3DEP web service returns incorrect results when out_crs is 4326, get_map will not accept 4326 for the time being and the default value is set to 5070. This is a breaking change.
Improve exception handling when using ThreadPoolExecutor to ensure that exceptions are raised in the main thread.