.. image:: https://travis-ci.org/GIScience/openelevationservice.svg?branch=master :target: https://travis-ci.com/GIScience/openelevationservice :alt: Build status

.. image:: https://readthedocs.org/projects/openelevationservice/badge/?version=latest :target: https://openelevationservice.readthedocs.io/en/latest/ :alt: Documentation Status

Quickstart

Description

openelevationservice is a Flask application which extracts elevation from various elevation datasets for Point or LineString 2D geometries and returns 3D geometries in various formats.

Supported formats are:

• GeoJSON
• Polyline, i.e. list of vertices
• Google's encoded polyline_
• Point, i.e. one vertex

For general support and questions, please contact our forum. After successful installation, you can also find a API documentation locally at https://localhost:5000/apidocs, provided via flasgger.

For issues and improvement suggestions, use the repo's issue tracker_.

This service is part of the GIScience software stack, crafted at HeiGIT institute at the University of Heidelberg.

You can also use our free API via (also check Endpoints for usage):

• https://api.openrouteservice.org/elevation/point?api_key=YOUR_KEY
• https://api.openrouteservice.org/elevation/line?api_key=YOUR_KEY

.. GIScience: https://github.com/GIScience .. HeiGIT institute: https://heigit.org .. SRTM v4.1: http://srtm.csi.cgiar.org .. encoded polyline: https://developers.google.com/maps/documentation/utilities/polylinealgorithm .. forum: https://ask.openrouteservice.org/c/elevation .. issue tracker: https://github.com/GIScience/openelevationservice/issues .. flasgger: https://github.com/rochacbruno/flasgger .. free API: https://openrouteservice.org/sign-up

Installation

You can either run this service on a host machine (like your PC) in a virtual environment or via docker (recommended).

Docker installation ####################################################

Prerequisites ++++++++++++++++++++++++++++++++++++++++++++++++++++

• Docker
• PostGIS installation (recommended Kartoza's docker_)

Run Docker container ++++++++++++++++++++++++++++++++++++++++++++++++++++

1. Customize ops_settings_docker.sample.yml to your needs and name it ops_settings_docker.yml

2. Build container sudo docker-compose up -d

3. Create the database

.. code-block:: bash

sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask create"

4. Download SRTM data

.. code-block:: bash

sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask download --xyrange=0,0,73,25"

The optional xyrange parameter specfies the minx,miny,maxx,maxy indices of the available tiles, default is 0,0,73,25. You can see a representation of indices in the map on the CGIAR website_.

Note, that you need to have credentials to access the FTP site , which you can request here.

5. Import SRTM data

.. code-block:: bash

sudo docker exec  -it <container ID> bash -c "source /oes_venv/bin/activate; flask importdata"

The import command will import whatever .tif files it finds in ./tiles. Now, it's time to grab a coffee, this might take a while. Expect a few hours for a remote database connection with HDD's and the global dataset.

After it's all finished, the service will listen on port 5020 of your host machine, unless specified differently in docker-compose.yml.

.. _Kartoza's docker: https://github.com/kartoza/docker-postgis .. here: https://harvestchoice.wufoo.com/forms/download-cgiarcsi-srtm/ .. FTP site: http://data.cgiar-csi.org/srtm/tiles/GeoTIFF/ .. _CGIAR website: http://srtm.csi.cgiar.org/SELECTION/inputCoord.asp

Conventional installation ####################################################

This tutorial assumes a Ubuntu system.

Max OSX should be similar, if not the same. Windows is of course possible, but many of the commands will have to be altered.

Prerequisites ++++++++++++++++++++++++++++++++++++++++++++++++++++

• Python 3.6 or higher
• PostGIS installation on the host machine (solely needed for raster2pgsql)
• (Optional) Remote PostGIS installation (if you want to use a different data server)

Create virtual environment +++++++++++++++++++++++++++++++++++++++++++++++++++++

First, customize ./openelevationservice/server/ops_settings.sample.yml and name it ops_settings.yml.

• Set coord_precision to 0.00083333333333333333.
• The part of srtm_parameters need not be changed.
• For part of provider_parameters, do one of the following for each connection property to the remote database server:
  • Write the connection properties in the file to the remote database server.
  • Set the property as environment variables, turning to upper case and adding the prefix OES_ to the variable name, e.g. db_name to OES_DB_NAME.

Then you can set up the environment:

.. code-block:: bash

Either via virtualenv, venv package or conda

python3 -m venv .venv

or

virtualenv -p python3 .venv

or

conda create -n oes python=3.6

Activate virtual env (or equivalent conda command)

source .venv/bin/activate

Install required packages

pip install -r requirements.txt

When your environment is set up, you can run the import process and start the server:

.. code-block:: bash

inside the repo root directory

flask create

rather as a background/nohup job, will download 27 GB

flask download --xyrange=0,0,73,25 flask importdata

Start the server

flask --app manage run # HTTP mode

or

python3 run_grpc_server.py # GRPC mode

The service will now listen on http://localhost:5000.

Windows with remote PostGIS set up +++++++++++++++++++++++++++++++++++++++++++++++++++++

Rename ./openelevationservice/server/ops_settings.sample.yml to ops_settings.yml:

• Set coord_precision to 0.00083333333333333333.
• The part of srtm_parameters need not be changed.
• For part of provider_parameters, do one of the following for each connection property to the remote database server:
  • Write the property in the file.
  • Set the property as environment variables, turning to upper case and adding the prefix OES_ to the variable name, e.g. db_name to OES_DB_NAME.

Steps to establish the environment and run the server:

.. code-block:: bash

Python virtual environment setup and activate

python -m venv .env cd ..env\Scripts .\activate cd ....

Install required packages

If a sequence of errors occurs, in "requirements.txt", replace the last line:

- "psycopg2-binary==2.8.4" by "psycopg2-binary>=2.8.4"

pip install -r requirements.txt

Start the server

flask --app manage run # HTTP mode

or

python run_grpc_server.py # GRPC mode

Endpoints

The default base url is http://localhost:5000/.

The openelevationservice exposes 2 endpoints:

• /elevation/polygon: used for Polygon geometries
• /elevation/line: used for LineString geometries
• /elevation/point: used for single Point geometries

+-----------------------+-------------------+------------+---------+---------------------------------------------------------+ | Endpoint | Method(s) allowed | Parameter | Default | Values | +=======================+===================+============+=========+=========================================================+ | /elevation/polygon| POST | format_in | -- | geojson, polygon | | | +------------+---------+---------------------------------------------------------+ | | | geometry | -- | depends on format_in | | | +------------+---------+---------------------------------------------------------+ | | | format_out | geojson | geojson, polygon, colorpolygon | | | +------------+---------+---------------------------------------------------------+ | | | dataset | srtm | srtm (so far) | +-----------------------+-------------------+------------+---------+---------------------------------------------------------+ | /elevation/line | POST | format_in | -- | geojson, polyline, encodedpolyline5, encodedpolyline6 | | | +------------+---------+---------------------------------------------------------+ | | | geometry | -- | depends on format_in | | | +------------+---------+---------------------------------------------------------+ | | | format_out | geojson | geojson, polyline, encodedpolyline5, encodedpolyline6 | | | +------------+---------+---------------------------------------------------------+ | | | dataset | srtm | srtm (so far) | +-----------------------+-------------------+------------+---------+---------------------------------------------------------+ | /elevation/point | GET, POST | format_in | -- | geojson, point | | | +------------+---------+---------------------------------------------------------+ | | | geometry | -- | depends on format_in | | | +------------+---------+---------------------------------------------------------+ | | | format_out | geojson | geojson, point | | | +------------+---------+---------------------------------------------------------+ | | | dataset | srtm | srtm (so far) | +-----------------------+-------------------+------------+---------+---------------------------------------------------------+

For more detailed information, please visit the API documentation_.

When hosted locally, visit https://localhost:5000/apidocs.

.. _API documentation: https://coming.soon

Environment variables ##########################################################

openelevationservice recognizes the following environment variables:

+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+	variable	function	Default	Values	+=================+=========================================+=======================================================+=============================+	OES_LOGLEVEL	Sets the level of logging output	INFO	DEBUG, INFO, WARNING, ERROR	+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+	APP_SETTINGS	Controls the behavior of config.py	openelevationservice.server.config.ProductionConfig	ProductionConfig,
			DevelopmentConfig

+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+ | FLASK_APP | Sets the app | manage | | +-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+ | FLASK_ENV | Development/Production server | development | production, development | +-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+ | TESTING | Sets flask testing environment | None | true | +-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+

In the case of the Docker setup, you don't need to worry about environment variables for the most part.

CLI ##########################################################

The flask command line interface has a few additional commands:

• flask create: creates a table for CGIAR data
• flask download --xyrange=0,73,0,25: downloads CGIAR data and limits the X, Y indices optionally with xyrange
• flask importdata: imports CGIAR tiles it finds in ./tiles/
• flask drop: drops CGIAR table

Testing ########################################################

The testing framework is nosetests, which makes it very easy to run the tests:

.. code-block:: bash

TESTING=true nosetests -v

Usage

GET point #########################################################

.. code-block:: bash

curl -XGET https://localhost:5000/elevation/point?geometry=13.349762,38.11295

POST point as geometry #########################################################

.. code-block:: bash

curl -XPOST http://localhost:5000/elevation/point \ -H 'Content-Type: application/json' \ -d '{ "format_in": "point", "format_out": "point", "geometry": [13.349762, 38.11295] }'

POST LineString as polyline (geometry) #########################################################

.. code-block:: bash

curl -XPOST http://localhost:5000/elevation/line \ -H 'Content-Type: application/json' \ -d '{ "format_in": "polyline", "format_out": "polyline", "geometry": [ [13.349762, 38.11295], [12.638397, 37.645772] ] }'

POST Polygon as geometry #########################################################

.. code-block:: bash

curl -XPOST http://localhost:5000/elevation/polygon \ -H 'Content-Type: application/json' \ -d '{ "format_in": "polygon", "format_out": "colorpolygon", "geometry": [ [75, 29], [75.003, 29], [75.003, 29.002], [75, 29.002], [75, 29] ] }'

With the "format_out" as "geojson" or "polygon", the result will be simple multipoints with the elevation values as 3rd dimension in the coordinates.

With the "format_out" as "colorpolygon", the result will be a feature collection (GeoJSON) with the grouped elevation values assigned as properties to geometries of polygon or multipolygon.