seamless-3dep 0.4.0

Easy retrieval of seamless DEM from 3DEP across US.

Seamless3DEP: Streamlined Access to USGS 3DEP Topographic Data

Seamless3DEP is a lightweight Python package that simplifies access to topographic data from the USGS 3D Elevation Program (3DEP). Whether you need elevation data or its derivatives, Seamless3DEP provides an efficient interface to both static and dynamic 3DEP products.

Seamless3DEP utilizes connection pooling across threads (safely) to optimize service calls and minimize redundant connections. This reduces both the service load and the time required to retrieve data, making it an ideal tool for handling large-scale topographic data requests.

📚 Full documentation is available here.

Available Products

Static DEMs

• 1/3 arc-second (10 meters)
• 1 arc-second (30 meters)
• 2 arc-second (60 meters)

Dynamic Products

• Digital Elevation Model (DEM)
• Hillshade Derivatives:
  • Gray Hillshade
  • Multidirectional Hillshade
  • GreyHillshade with Elevation Fill
  • Hillshade with Elevation Tint
• Terrain Analysis:
  • Aspect (Degrees and Map)
  • Slope (Degrees and Map)
  • Height (Ellipsoidal)
• Contours:
  • Contour 25 (Dynamically generates 25 contours for the area of interest)
  • Contour Smoothed 25 (Smoothed version of the 25 contours)

Core Functions

Seamless3DEP offers six main functions designed for efficient data retrieval and processing:

• get_dem: Retrieves static DEMs within a specified bounding box. The function automatically splits large areas into manageable tiles, downloads data as GeoTIFF files in EPSG:4326, and supports resolutions of 10m, 30m, or 60m.
• get_map: Fetches any 3DEP product (including DEMs) with customizable parameters. Works with all available product types, allows custom resolution settings, and downloads in EPSG:3857. Due to service limitations, the output projection is not configurable.
• elevation_bygrid: Samples elevation values from the 10 m seamless DEM at a grid of longitude/latitude coordinates. Reads directly from the USGS Cloud-Optimized GeoTIFFs (EPSG:4269) and supports configurable resampling methods including nearest, bilinear, cubic, cubic spline, and Lanczos.
• decompose_bbox: Handles large area requests by breaking down extensive bounding boxes into optimal sizes based on resolution and maximum pixel count, ensuring efficient data retrieval.
• build_vrt: Creates virtual raster datasets by combining multiple GeoTIFF files. Requires libgdal-core installation and supports efficient data handling for large areas. Note that libgdal-core is an optional dependency and is not installed when seamless-3dep is installed from PyPI. However, it is installed as a dependency when seamless-3dep is installed from conda-forge.
• tiffs_to_da: Converts a list of GeoTIFF files to an 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.

Important Notes

• Bounding box coordinates should be in decimal degrees (WGS84) format: (west, south, east, north)
• Default projection for requesting maps is EPSG:3857
• EPSG:4326 output projection is not supported in get_map due to service limitations

Installation

Choose your preferred installation method:

Using pip

pip install seamless-3dep

Using micromamba (recommended)

micromamba install -c conda-forge seamless-3dep

Alternatively, you can use conda or mamba.

Quick Start Guide

We can retrieve topographic data using Seamless3DEP in just a few lines of code. Then, we can visualize or even reproject the data using rioxarray.

Retrieving a DEM

from pathlib import Path
import seamless_3dep as s3dep
import rioxarray as rxr

# Define area of interest (west, south, east, north)
bbox = (-105.7006276, 39.8472777, -104.869054, 40.298293)
data_dir = Path("data")

# Download DEM
tiff_files = s3dep.get_dem(bbox, data_dir)

# Convert to xarray.DataArray
dem = s3dep.tiffs_to_da(tiff_files, bbox, crs=4326)

Retrieving a Slope Map

slope_files = s3dep.get_map("Slope Degrees", bbox, data_dir)
dem = s3dep.tiffs_to_da(slope_files, bbox)

Contributing

We welcome contributions! Please see the contributing section for guidelines and instructions.