py3dep.py3dep#
Get data from 3DEP database.
Module Contents#
- py3dep.py3dep.add_elevation(ds, resolution=None, x_dim='x', y_dim='y', mask=None)#
Add elevation data to a dataset as a new variable.
- Parameters:
ds (
xarray.DataArray
orxarray.Dataset
) – The dataset to add elevation data to. It must contain CRS information.resolution (
float
, optional) – Target DEM source resolution in meters, defaultsNone
, i.e., the resolution of the inputds
will be used.x_dim (
str
, optional) – Name of the x-coordinate dimension inds
, defaults tox
.y_dim (
str
, optional) – Name of the y-coordinate dimension inds
, defaults toy
.mask (
xarray.DataArray
, optional) – A mask to apply to the elevation data, defaults toNone
.
- Returns:
xarray.Dataset
– The dataset withelevation
variable added.- Return type:
- py3dep.py3dep.check_3dep_availability(bbox, crs=4326)#
Query 3DEP’s resolution availability within a bounding box.
This function checks availability of 3DEP’s at the following resolutions: 1 m, 3 m, 5 m, 10 m, 30 m, 60 m, and topobathy (integrated topobathymetry).
- Parameters:
- Returns:
dict
–True
if bbox intersects 3DEP elevation for each available resolution. Keys are the supported resolutions and values are their availability. If the query fails due to any reason, the value will beFailed
. If necessary, you can try again later until there is noFailed
value.- Return type:
Examples
>>> import py3dep >>> bbox = (-69.77, 45.07, -69.31, 45.45) >>> py3dep.check_3dep_availability(bbox) {'1m': True, '3m': False, '5m': False, '10m': True, '30m': True, '60m': False, 'topobathy': False}
- py3dep.py3dep.elevation_bycoords(coords: tuple[float, float], crs: CRSTYPE = ..., source: Literal['tep', 'tnm'] = ...) float #
- py3dep.py3dep.elevation_bycoords(coords: list[tuple[float, float]], crs: CRSTYPE = ..., source: Literal['tep', 'tnm'] = ...) list[float]
Get elevation for a list of coordinates.
- Parameters:
coords (
tuple
orlist
oftuple
) – Coordinates of target location(s), e.g.,[(x, y), ...]
.crs (
str
,int
, orpyproj.CRS
orpyproj.CRS
, optional) – Spatial reference (CRS) of coords, defaults toEPSG:4326
.source (
str
, optional) – Data source to be used, default totep
. Supported sources aretnm
(using The National Map’s Bulk Point Query Service with 10 m resolution) andtep
(using 3DEP’s static DEM VRTs at 10 m resolution). Thetnm
andtep
sources are more accurate since they use the 1/3 arc-second DEM layer from 3DEP service but it is limited to the US. Note thattnm
is bit unstable. It’s recommended to usetep
unless 10-m resolution accuracy is not necessary.
- Returns:
- py3dep.py3dep.elevation_bygrid(xcoords, ycoords, crs, resolution, depression_filling=False)#
Get elevation from DEM data for a grid.
This function is intended for getting elevations for a gridded dataset.
- Parameters:
xcoords (
list
) – List of x-coordinates of a grid.ycoords (
list
) – List of y-coordinates of a grid.crs (
str
,int
, orpyproj.CRS
orpyproj.CRS
) – The spatial reference system of the input grid, defaults toEPSG:4326
.resolution (
int
) – The accuracy of the output, defaults to 10 m which is the highest available resolution that covers CONUS. Note that higher resolution increases computation time so chose this value with caution.depression_filling (
bool
, optional) – Fill depressions before sampling using Wang and Liu (2006) method, defaults toFalse
.
- Returns:
xarray.DataArray
– Elevations of the input coordinates as axarray.DataArray
.- Return type:
- py3dep.py3dep.elevation_profile(lines, spacing, crs=4326)#
Get the elevation profile along a line at a given uniform spacing.
Note
This function converts the line to a spline and then calculates the elevation along the spline at a given uniform spacing using 10-m resolution DEM from 3DEP.
- Parameters:
lines (
LineString
orMultiLineString
) – Line segment(s) to be profiled. If its type isMultiLineString
, it will be converted to a singleLineString
and if this operation fails, anInputTypeError
will be raised.spacing (
float
) – Spacing between the sample points along the line in meters.crs (
str
,int
, orpyproj.CRS
, optional) – Spatial reference System (CRS) oflines
, defaults toEPSG:4326
.
- Returns:
xarray.DataArray
– Elevation profile with dimensionz
and three coordinates:x
,y
, anddistance
. Thedistance
coordinate is the distance from the start of the line in meters.- Return type:
- py3dep.py3dep.get_dem(geometry, resolution, crs=4326)#
Get DEM data at any resolution from 3DEP.
Notes
This function is a wrapper of
static_3dep_dem
andget_map
functions. Sincestatic_3dep_dem
is much faster, if the requested resolution is 10 m, 30 m, or 60 m,static_3dep_dem
will be used. Otherwise,get_map
will be used.- Parameters:
geometry (
Polygon
,MultiPolygon
, ortuple
oflength 4
) – Geometry to get DEM within. It can be a polygon or a boundong box of form (xmin, ymin, xmax, ymax).resolution (
int
) – Target DEM source resolution in meters.crs (
str
,int
, orpyproj.CRS
, optional) – The spatial reference system of the input geometry, defaults toEPSG:4326
.
- Returns:
xarray.DataArray
– DEM at the specified resolution in meters and 4326 CRS.- Return type:
- py3dep.py3dep.get_dem_vrt(bbox, resolution, vrt_path, tiff_dir='cache', crs=4326)#
Get DEM data at any resolution from 3DEP and save it as a VRT file.
- Parameters:
bbox (
tuple
oflength 4
) – The boundong box of form (xmin, ymin, xmax, ymax).resolution (
int
) – Target DEM source resolution in meters.vrt_path (
str
orpathlib.Path
) – Path to the output VRT file.tiff_dir (
str
orpathlib.Path
, optional) – Path to the directory to save the downloaded TIFF file, defaults to./cache
.crs (
str
,int
, orpyproj.CRS
, optional) – The spatial reference system ofbbox
, defaults toEPSG:4326
.
- py3dep.py3dep.get_map(layers: str, geometry: shapely.Polygon | shapely.MultiPolygon | tuple[float, float, float, float], resolution: int, geo_crs: CRSTYPE = ..., crs: CRSTYPE = ...) xarray.DataArray #
- py3dep.py3dep.get_map(layers: list[str], geometry: shapely.Polygon | shapely.MultiPolygon | tuple[float, float, float, float], resolution: int, geo_crs: CRSTYPE = ..., crs: CRSTYPE = ...) xarray.Dataset
Access dynamic layer of 3DEP.
The 3DEP service has multi-resolution sources, so depending on the user provided resolution the data is resampled on server-side based on all the available data sources. The following layers are available:
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
- Parameters:
layers (
str
orlist
ofstr
) – A valid 3DEP layer or a list of them.geometry (
Polygon
,MultiPolygon
, ortuple
) – A shapely Polygon or a bounding box of the form(west, south, east, north)
.resolution (
int
) – The target resolution in meters. The width and height of the output are computed in pixels based on the geometry bounds and the given resolution.geo_crs (
str
,int
, orpyproj.CRS
, optional) – The spatial reference system of the input geometry, defaults toEPSG:4326
.crs (
str
,int
, orpyproj.CRS
, optional) – The spatial reference system to be used for requesting the data, defaults toEPSG:4326
. Valid values areEPSG:4326
,EPSG:3576
,EPSG:3571
,EPSG:3575
,EPSG:3857
,EPSG:3572
,CRS:84
,EPSG:3573
, andEPSG:3574
.
- Returns:
xarray.DataArray
orxarray.Dataset
– The requested topographic data as anxarray.DataArray
orxarray.Dataset
.
- py3dep.py3dep.query_3dep_sources(bbox, crs=4326, res=None)#
Query 3DEP’s data sources within a bounding box.
This function queries the availability of the underlying data that 3DEP uses at the following resolutions: 1 m, 3 m, 5 m, 10 m, 30 m, 60 m, and topobathy (integrated topobathymetry).
- Parameters:
bbox (
tuple
) – Bounding box as tuple of(min_x, min_y, max_x, max_y)
.crs (
str
,int
, orpyproj.CRS
orpyproj.CRS
, optional) – Spatial reference (CRS) of bbox, defaults toEPSG:4326
.res (
str
,list
ofstr
, optional) – Resolution to query, defaults toNone
, i.e., all resolutions. Available resolutions are:1m
,3m
,5m
,10m
,30m
,60m
, andtopobathy
.
- Returns:
geopandas.GeoDataFrame
– Polygon(s) representing the 3DEP data sources at each resolution. Resolutions are given in thedem_res
column.- Return type:
Examples
>>> import py3dep >>> bbox = (-69.77, 45.07, -69.31, 45.45) >>> src = py3dep.query_3dep_sources(bbox) >>> src.groupby("dem_res")["OBJECTID"].count().to_dict() {'10m': 16, '1m': 4, '30m': 8} >>> src = py3dep.query_3dep_sources(bbox, res="1m") >>> src.groupby("dem_res")["OBJECTID"].count().to_dict() {'1m': 4}
- py3dep.py3dep.static_3dep_dem(geometry, crs, resolution=10)#
Get DEM data at specific resolution from 3DEP.
Notes
In contrast to
get_map
function, this function only gets DEM data at specific resolution, namely 10 m, 30 m, and 60 m. However, this function is faster. This function is intended for cases where only need DEM at a specific resolution is required and for the other requestsget_map
should be used.- Parameters:
geometry (
Polygon
,MultiPolygon
, ortuple
oflength 4
) – Geometry to get DEM within. It can be a polygon or a boundong box of form (xmin, ymin, xmax, ymax).resolution (
int
, optional) – Target DEM source resolution in meters, defaults to 10 m which is the highest resolution available over the US. Available options are 10, 30, and 60.
- Returns:
xarray.DataArray
– The request DEM at the specified resolution.- Return type: