Package: bmi-topography
bmi-topographybmi-topographyis a Python library for fetching and caching
land elevation data
using theOpenTopographyREST API.Thebmi-topographylibrary provides access to the following global raster datasets:SRTMGL3 (SRTM GL3 90m)SRTMGL1 (SRTM GL1 30m)SRTMGL1_E (SRTM GL1 Ellipsoidal 30m)AW3D30 (ALOS World 3D 30m)AW3D30_E (ALOS World 3D Ellipsoidal, 30m)SRTM15Plus (Global Bathymetry SRTM15+ V2.1)NASADEM (NASADEM Global DEM)COP30 (Copernicus Global DSM 30m)COP90 (Copernicus Global DSM 90m)The library includes an API and a CLI that accept
the dataset type,
a latitude-longitude bounding box, and
the output file format.
Data are downloaded from OpenTopography and cached locally.
The cache is checked before downloading new data.
Data from a cached file can optionally be loaded into anxarrayDataArraythroughrioxarray.Thebmi-topographyAPI is wrapped with aBasic Model Interface(BMI),
which provides a standard set of functions for coupling with data or models
that also expose a BMI.
More information on the BMI can found in itsdocumentation.InstallationInstall the latest stable release ofbmi-topographywithpip:pip install bmi-topographyor withconda:conda install -c conda-forge bmi-topographyThebmi-topographylibrary can also be built and installed from source.
The library uses several other open source libraries,
so a convenient way of building and installing it is within aconda environment.
After cloning or downloading thebmi-topographyrepository,
change into the repository directory
and set up a conda environment with the included environment file:conda env create --file=environment.ymlThen build and installbmi-topographyfrom source withpip install -e .API keyTo better understand usage,
OpenTopographyrequires an API keyto access datasets they host.
Getting an API key is easy, and it's free:
just follow the instructions in the link above.Once you have an API key,
there are three ways to use it withbmi-topography:parameter: Pass the API key as a string through theapi_keyparameter.environment variable: In the shell, set theOPENTOPOGRAPHY_API_KEYenvironment variable to the API key value.dot file: Put the API key in the file.opentopography.txtin the current directory or in your home directory.If you attempt to usebmi-topographyto access an OpenTopography dataset without an API key,
you'll get a error like this:requests.exceptions.HTTPError: 401 Client Error: This dataset requires an API Key for access.ExamplesA brief example of using thebmi-topographyAPI is given in the following steps.Start a Python session and import theTopographyclass:>>>frombmi_topographyimportTopographyFor convenience,
a set of default parameter values forTopographyare included in the class definition.
Copy these and modify them with custom values:>>>params=Topography.DEFAULT.copy()>>>params["south"]=39.93>>>params["north"]=40.00>>>params["west"]=-105.33>>>params["east"]=-105.26>>>params{'dem_type':'SRTMGL3','south':39.93,'north':40.0,'west':-105.33,'east':-105.26,'output_format':'GTiff','cache_dir':'~/.bmi_topography'}These coordinate values represent an area around Boulder, Colorado.Make a instance ofTopographywith these parameters:>>>boulder=Topography(**params)then fetch the data from OpenTopography:>>>boulder.fetch()PosixPath('/Users/mpiper/.bmi_topography/SRTMGL3_39.93_-105.33_40.0_-105.26.tif')This step might take a few moments,
and it will increase for requests of larger areas.
Note that the file has been saved to a local cache directory.Load the data into an xarrayDataArrayfor further work:>>>boulder.load()<xarray.DataArray'SRTMGL3'(band:1,y:84,x:84)>array([[[2052,2035,...,1645,1643],[2084,2059,...,1643,1642],...,[2181,2170,...,1764,1763],[2184,2179,...,1773,1769]]],dtype=int16)Coordinates:*band(band)int641*x(x)float64-105.3-105.3-105.3...-105.3-105.3-105.3*y(y)float6440.040.040.040.0...39.9339.9339.9339.93spatial_refint640Attributes:_FillValue:0.0scale_factor:1.0add_offset:0.0units:meterslocation:nodeNote that coordinate reference system information is stored in thespatial_refnon-dimension coordinate:>>>boulder.da.spatial_ref<xarray.DataArray'spatial_ref'()>array(0)Coordinates:spatial_refint640Attributes:crs_wkt:GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["...semi_major_axis:6378137.0semi_minor_axis:6356752.314245179inverse_flattening:298.257223563reference_ellipsoid_name:WGS84longitude_of_prime_meridian:0.0prime_meridian_name:Greenwichgeographic_crs_name:WGS84grid_mapping_name:latitude_longitudespatial_ref:GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["...GeoTransform:-105.330416666683630.0008333333333331440....Display the elevations with the default xarrayDataArrayplotmethod.>>>importmatplotlib.pyplotasplt>>>boulder.da.plot()>>>plt.show()For examples with more detail,
see the two Jupyter Notebooks,
Python script, and shell script
included in theexamplesdirectory
of thebmi-topographyrepository.User and developer documentation forbmi-topographyis available athttps://bmi-topography.readthedocs.io.CreditsProject leadMark PiperContributorsEric HuttonMark PiperAcknowledgmentsThis work is supported by the National Science Foundation under Award No.2026951,EarthCube Capabilities: Cloud-Based Accessible and Reproducible Modeling for Water and Sediment Research.MIT LicenseCopyright (c) 2021 Community Surface Dynamics Modeling SystemPermission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.