elevation Documentation
Release 1.1.3.dev0

B-Open Solutions srl

2021-03-23

TABLE OF CONTENTS

1Quickstart
1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Command line usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Command line reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5 Project resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

333
4
5
5
5
5

2

Design2.1 Mission and vision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Software architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Version goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7
777i

ii

elevation Documentation, Release 1.1.3.dev0

Version 1.1.3.dev0
Date 2021-03-23
Easy access to global terrain digital elevation models, SRTM 30m DEM and SRTM 90m DEM.
If you have any feedback or you want to help out head over our main repository: https://github.com/bopen/elevation

TABLE OF CONTENTS

1elevation Documentation, Release 1.1.3.dev02

TABLE OF CONTENTSCHAPTERONEQUICKSTART

Global geographic elevation data made easy. Elevation provides easy download, cache and access of the global datasets
SRTM 30m Global 1 arc second V003 elaborated by NASA and NGA hosted on Amazon S3 and SRTM 90m Digital
Elevation Database v4.1 elaborated by CGIAR-CSI.
Note that any download policies of the respective providers apply.

1.1 Installation
Install the latest version of Elevation from the Python Package Index:$ pip install elevation

The following dependencies need to be installed and working:• GNU make• curl• unzip• gunzip• GDAL command line tools
The following command runs some basic checks and reports common issues:$ eio selfcheckYour system is ready.

GNU make, curl and unzip come pre-installed with most operating systems. The best way to install GDAL commandline tools varies across operating systems and distributions, please refer to the GDAL install documentation.
Note that starting from elevation v1.1 only Python 3 is officially supported. To get the last version sporting Python 2support please use pip install elevation=1.0.6.

1.2 Command line usage
Identify the geographic bounds of the area of interest and fetch the DEM with the eio command. For example to clip
the SRTM 30m DEM of Rome, around 41.9N 12.5E, to the Rome-30m-DEM.tif file:$ eio clip -o Rome-30m-DEM.tif --bounds 12.35 41.8 12.65 42

For the SRTM 90m DEM use:3

elevation Documentation, Release 1.1.3.dev0$ eio --product SRTM3 clip -o Rome-90m-DEM.tif --bounds 12.35 41.8 12.65 42

The --bounds option accepts latitude and longitude coordinates (more precisely in geodetic coordinates in theWGS84 reference system EPSG:4326 for those who care) given as left bottom right top similarly to therio command form rasterio.
If you have installed the packages rasterio and fiona you can clip a DEM on the same extent of any othergeospatial data source supported by GDAL and OGR, for example if you have a georeference image MyImage.tif
you can clip the corresponding DEM with:$ eio clip -o MyImage-DEM.tif --reference MyImage.tif
˓→rasterio# enable with: $ pip install

The --reference option can take also verctor data as input:$ eio clip -o MyShapefile-DEM.tif --reference MyShapefile.shp
˓→install fiona# enable with: $ pip

The first time an area is accessed Elevation downloads the data tiles from the USGS or CGIAR-CSI servers and caches
them in GeoTiff compressed formats, subsequent accesses to the same and nearby areas are much faster.
The clip sub-command doesn’t allow automatic download of a large amount of DEM tiles, please refer to theupstream providers’ websites to learn the preferred procedures for bulk download.
To clean up stale temporary files and fix the cache in the event of a server error use:
$ eio clean

1.3 Command line reference
The eio command as the following sub-commands and options:$ Usage: eio [OPTIONS] COMMAND [ARGS]...
Options:--version--product [SRTM1|SRTM3]--cache_dir DIRECTORY--helpCommands:
clean
clip
distclean
info
seed
selfcheck

Show the version and exit.
DEM product choice. [default: SRTM1]
Root of the DEM cache folder. [default:/Users/amici/Library/Caches/elevation]Show this message and exit.

Clean up the product cache from temporary files.
Clip the DEM to given bounds.
Remove the product cache entirely.
Show info about the product cache.
Seed the DEM to given bounds.
Audit the system for common issues.

The clip sub-command:$ eio clip --help
Usage: eio clip [OPTIONS]
Options:(continues on next page)

4

Chapter 1. Quickstartelevation Documentation, Release 1.1.3.dev0(continued from previous page)-o, --output PATH--bounds FLOAT...
-m, --margin TEXT-r, --reference TEXT--helpPath to output file. Existing files will beoverwritten. [default: out.tif]
Output bounds in 'left bottom right top' order.
Decimal degree margin added to the bounds. Use '%' forpercent margin. [default: 0]
Use the extent of a reference GDAL/OGR data source as
output bounds.
Show this message and exit.

Defaults can be defined by setting environment variables prefixed with EIO, e.g. EIO_PRODUCT=SRTM3 andEIO_CLIP_MARGIN=10%.

1.4 Python API
Every command has a corresponding API function in the elevation module:>>> import elevation>>> # clip the SRTM1 30m DEM of Rome and save it to Rome-DEM.tif>>> elevation.clip(bounds=(12.35, 41.8, 12.65, 42), output='Rome-DEM.tif')>>> # clean up stale temporary files and fix the cache in the event of a server error>>> elevation.clean()

1.5 Project resources
Documentation
SupportDevelopment
Download
Code quality

http://elevation.bopen.eu
https://stackoverflow.com/search?q=python+elevation
https://github.com/bopen/elevation
https://pypi.org/project/elevation

1.6 Contributing
Contributions are very welcome. Please see the CONTRIBUTING document for the best way to help. If you encounterany problems, please file an issue along with a detailed description.
Authors:• B-Open Solutions srl - @bopen - http://bopen.eu• Alessandro Amici - @alexamici

1.7 License
Elevation is free and open source software distributed under the terms of the Apache License, Version 2.0.

1.4. Python API5

elevation Documentation, Release 1.1.3.dev0

6Chapter 1. QuickstartCHAPTERTWODESIGNThis chapter documents the high-level design of the product and it is intended for developers contributing to theproject.
Note: Users of the product need not bother with the following. Unless they are curious :)2.1 Mission and vision
The project mission is to enable easy management of global digital elevation data.
Target use cases:
1. access DEM data on-demand from well-known repositories
2. download and store efficiently elevation data on large areas
Project goals:
1. data download from well-known repositories
2. compact storage of local data

2.2 Software architecture
Logical components:• the datasource Makefile• the Python API• the eio CLI

2.3 Version goals
This project strives to adhere to semantic versioning.

2.3.1 1.1.0 (upcoming release)
To be defined.

7

elevation Documentation, Release 1.1.3.dev0

2.3.2 1.0.0
Minimal set of features to be operationally useful. No completeness and no performance guarantees.
• Cache management:– new SRTM1 and old SRTM3 global high resolution digital elevation model– GNU Makefile for cache management (parallelism and dependency tracking)– GDAL VirtualRaster as main entry point

8Chapter 2. Design