Skip to content

API Reference

Module for getting DEM from USGS's 3D Elevation Program (3DEP).

decompose_bbox #

decompose_bbox(bbox, res, pixel_max, buff_npixels=0.0)

Divide a Bbox into equal-area sub-bboxes based on pixel count.

Parameters:

  • bbox (tuple) –

    Bounding box coordinates in decimal degrees like so: (west, south, east, north).

  • res (int) –

    Resolution of the domain in meters.

  • pixel_max (int) –

    Maximum number of pixels allowed in each sub-bbox. If None, the bbox is not decomposed.

  • buff_npixels (float, default: 0.0 ) –

    Number of pixels to buffer each sub-bbox by, defaults to 0.

Returns:

  • boxes ( list of tuple ) –

    List of sub-bboxes in the form (west, south, east, north).

  • sub_width ( int ) –

    Width of each sub-bbox in degrees.

  • sub_height ( int ) –

    Height of each sub-bbox in degrees.

get_dem #

get_dem(bbox, save_dir, res=10, pixel_max=MAX_PIXELS)

Get DEM from 3DEP at 10, 30, or 60 meters resolutions.

Notes

If you need a different resolution, use the get_map function with map_type="DEM".

Parameters:

  • bbox (tuple) –

    Bounding box coordinates in decimal degrees: (west, south, east, north).

  • save_dir (str or Path) –

    Path to save the GeoTiff files.

  • res ((10, 30, 60), default: 10 ) –

    Target resolution of the DEM in meters, by default 10. Must be one of 10, 30, or 60.

  • pixel_max (int, default: MAX_PIXELS ) –

    Maximum number of pixels allowed in each sub-bbox for decomposing the bbox into equal-area sub-bboxes, defaults to 8 million. If None, the bbox is not decomposed and is downloaded as a single file. Values more than 8 million are not allowed.

Returns:

  • list of pathlib.Path –

    list of GeoTiff files containing the DEM clipped to the bounding box.

get_map #

get_map(
    map_type, bbox, save_dir, res=10, pixel_max=MAX_PIXELS
)

Get topo maps in 3857 coordinate system within US from 3DEP at any resolution.

Parameters:

  • map_type (MapTypes) –

    Type of map to get. Must be one of the following:

    • 'DEM'
    • 'Hillshade Gray'
    • 'Aspect Degrees'
    • 'Aspect Map'
    • 'GreyHillshade_elevationFill'
    • 'Hillshade Multidirectional'
    • 'Slope Map'
    • 'Slope Degrees'
    • 'Hillshade Elevation Tinted'
    • 'Height Ellipsoidal'
    • 'Contour 25'
    • 'Contour Smoothed 25'
  • bbox (tuple) –

    Bounding box coordinates in decimal degrees (WG84): (west, south, east, north).

  • save_dir (str or Path) –

    Path to save the GeoTiff files.

  • res (int, default: 10 ) –

    Target resolution of the map in meters, by default 10.

  • pixel_max (int, default: MAX_PIXELS ) –

    Maximum number of pixels allowed in each sub-bbox for decomposing the bbox into equal-area sub-bboxes, defaults to 8 million. If None, the bbox is not decomposed and is downloaded as a single file. Values more than 8 million are not allowed.

Returns:

  • list of pathlib.Path –

    list of GeoTiff files containing the DEM clipped to the bounding box.

build_vrt #

build_vrt(vrt_path, tiff_files)

Create a VRT from a list of GeoTIFF tiles.

Notes

This function requires the installation of libgdal-core. The recommended approach is to use conda (or alternatives like mamba or micromamba). However, if using the system's package manager is the only option, ensure that the gdal-bin or gdal package is installed. For detailed instructions, refer to the GDAL documentation here. When seamless-3dep is installed from Conda, libgdal-core is installed as a dependency and this function works without any additional steps.

Parameters:

  • vrt_path (str or Path) –

    Path to save the output VRT file.

  • tiff_files (list of str or Path) –

    List of file paths to include in the VRT.

tiffs_to_da #

tiffs_to_da(tiff_files, geometry, crs=4326)

Convert a list of tiff files to a vrt file and return a xarray.DataArray.

Parameters:

  • tiff_files (list of Path) –

    List of file paths to convert to a DataArray.

  • geometry (Polygon or Sequence) –

    Polygon or bounding box in the form (west, south, east, north).

  • crs (int, str, or CRS, default: 4326 ) –

    Coordinate reference system of the input geometry, by default 4326.

Returns:

  • DataArray –

    DataArray containing the clipped data.

elevation_bygrid #

elevation_bygrid(longs, lats, window=5, resampling=1)

Sample elevation from 3DEP at a grid of lon/lat coordinates.

Notes

Reads directly from the USGS 10 m seamless DEM VRT (Cloud-Optimized GeoTIFFs, EPSG:4269). A small pixel window around each query point is read and downsampled to a single value using the chosen resampling kernel.

Parameters:

  • longs (array - like) –

    1D sequence of longitude values in decimal degrees.

  • lats (array - like) –

    1D sequence of latitude values in decimal degrees.

  • window (int, default: 5 ) –

    Size of the read window for interpolation, must be odd, defaults to 5.

  • resampling (int, default: 1 ) –

    Resampling method from rasterio.enums.Resampling, defaults to 1 (bilinear). Methods applicable to DEM interpolation:

    • 0: nearest — fastest, no interpolation
    • 1: bilinear — good general-purpose default
    • 2: cubic — sharper than bilinear
    • 3: cubic_spline — smooth spline interpolation
    • 4: lanczos — high-quality windowed sinc

Returns:

  • ndarray –

    2D array of shape (len(lats), len(longs)) with elevation values in meters.