v0.5.2

Release Notes

Added

• Add a resampling parameter to build_vrt (default "nearest") that is forwarded to
  gdalbuildvrt -r. "nearest" avoids propagating NaN from tile-boundary fringe pixels
  into the mosaic interior when source tiles have slightly different pixel grids. Use
  "bilinear" or higher only when smooth blending across deliberately different
  resolutions is needed.
• Add a use_vrt parameter to tiffs_to_da (default False). When False (default),
  tiles are mosaicked in memory via rioxarray.merge.merge_arrays backed by
  rasterio.merge — no gdalbuildvrt CLI or libgdal/gdal conda package required,
  only rasterio and rioxarray. Pass use_vrt=True to use the previous VRT-based
  path (requires gdalbuildvrt), which supports the full set of GDAL pixel functions
  such as "mean" and "median". The in-memory path supports None, "first",
  "min", and "max".

Changed

• tiffs_to_da no longer requires shapely. The geometry parameter now accepts any
  object that exposes a .bounds attribute (e.g., any shapely or GeoJSON-backed
  geometry) in addition to a (west, south, east, north) bounding box tuple. Passing a
  geometry object still clips to its exact shape; a plain tuple clips to the envelope
  only.
• build_vrt now automatically sets -vrtnodata nan for float rasters so uncovered
  mosaic gaps appear as NaN rather than the source file's finite nodata sentinel
  (e.g., -9999 or -3.4e38).

v0.5.1

Release Notes

Added

• Add get_image_server - a general-purpose downloader for any ArcGIS
  ImageServer/exportImage endpoint. Accepts any output CRS (int, str, or
  rasterio.crs.CRS), an optional Esri rendering rule, and handles URL validation,
  bbox tiling, and resume-on-failure automatically. get_map and get_global_dem are
  thin wrappers over this function.
• Add get_global_dem - a wrapper around the
  NOAA global DEM mosaic
  (SRTM + GEBCO + ICESat) for downloading elevation data anywhere on Earth. Returns
  GeoTIFFs in EPSG:3857 and includes sub-zero bathymetric values (down to ~-9982 m),
  making it the right choice outside the US or for coastal/marine workflows. Native
  resolution is approximately 30 m (1 arc-second); defaults to res=30.
• Add global_dem.ipynb example notebook that downloads both 3DEP and NOAA global DEM
  for the same Oregon coast bounding box, produces a three-panel visual comparison
  (shared colorscale), elevation distribution histograms, and pixel-level agreement
  statistics (overall and land-only).

Changed

• Refactor get_map as a thin wrapper over the new get_image_server. Behavior and
  signature are unchanged; the 3DEP URL is now the _3DEP_URL module-level constant.
• Add lazy loading to __init__.py: all public names are imported on first access
  rather than at module import time, reducing cold-start overhead for scripts that
  only use a subset of the package. Set EAGER_IMPORT=1 to restore eager loading.

Fixed

• Include the ImageServer endpoint URL and rendering rule in cache keys so calls with
  the same bounding box, resolution, name, and CRS cannot reuse stale TIFFs from a
  different source or raster function.
• Write clipped get_dem tiles through a temporary file before replacing the final
  cache path so failed writes cannot leave partial TIFFs that look like valid cache
  hits on a later retry.

v0.4.1

Release Notes

Fixed

• Fix sub-pixel interpolation in elevation_bygrid. Previously, _transform_xy called
  rasterio.transform.rowcol() with its default op=numpy.floor, which snapped every
  query coordinate to the nearest integer pixel index. When the query grid was finer
  than the ~10 m DEM pixels, multiple points mapped to the same pixel and received
  identical values, producing systematic staircase/plateau artifacts. Now fractional
  pixel coordinates are preserved and carried through to the
  rasterio.windows.Window, so GDAL's resampling kernel interpolates at the true
  sub-pixel position.

v0.4.0

Release Notes

Added

• 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).

Changed

• 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.

v0.3.1

Release Notes

Added

• 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.

Changed

• 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.

v0.3.0

Release Notes

Changed

• 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.

v0.2.3

Release Notes

Changed

• 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.

v0.2.2

Release Notes

Changed

• 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.

v0.2.1

Release Notes

Changed

• 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.

v0.2.0

Release Notes

Changed

• 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.