Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dkogan/horizonator

Terrain renderer based on SRTM DEMs
https://github.com/dkogan/horizonator

Last synced: about 1 year ago
JSON representation

Terrain renderer based on SRTM DEMs

Awesome Lists containing this project

README 

          
#+TITLE: Horizonator!



* Overview

This tool renders terrain data, and can be used to simulate views captured by

a camera. This is most useful in areas with significant topographic relief.



There are a number of other, more polished tools to do this



- http://www.udeuschle.selfhost.pro/panoramas/makepanoramas_en.htm

- https://www.peakfinder.org/

- https://www.caltopo.com (right click, "point info", "view from here")



Although less polished, the implementation in the horizonator is freely licensed

(under any version of the LGPL), and is a good base for experimentation. The

horizonator is mostly intended as a building block for other tools, so the

user-facing UI tool is somewhat feature-sparse.



The horizonator consists of a [[https://github.com/dkogan/horizonator/blob/master/horizonator.h][C library]], a [[https://github.com/dkogan/horizonator/blob/master/horizonator.docstring][Python library]] and two user-facing

tools:



- The =horizonator= tool: an interactive [[https://www.fltk.org/][FLTK]] application that displays an

  overhead map and a render, allowing the user to interactively move around in

  both those views, and to relate the views to each other



- The =standalone= tool: a one-render application. Can produce either a static

  GLUT window or a =.png= image on disk



* Building the horizonator

This isn't "released", so I'm not providing packages, and building from source

is required. This probably can work on any recent UNIXy platform, but I've only

tested on Debian and CentOS.



On Debian, you need the following packages (I believe that's it; may be missing

one or two):



- libfltk1.3-dev

- libboost-filesystem-dev

- libboost-system-dev

- libboost-thread-dev

- libcurl4-gnutls-dev

- libgl1-mesa-dev

- libepoxy-dev

- libglu-dev

- libpng12-dev

- libfreeimage-dev

- libtinyxml-dev

- libpython3-dev



Once you have those, run =make=. You also need =wget= at runtime to download

the tiles.



* Using the horizonator 

Before running the tool, you need data to render. By default the horizonator

uses 3sec [[https://en.wikipedia.org/wiki/Shuttle_Radar_Topography_Mission][SRTM]] DEMs. Raw SRTM data contains gaps, so I usually use the

gap-filled SRTM data from



  http://viewfinderpanoramas.org/dem3.html



You need to download the archive for your area (for North America, you can [[http://viewfinderpanoramas.org/Coverage%20map%20viewfinderpanoramas_org3.htm][pick

from a map]]). Then extract the =.hgt= files to



  =~/.horizonator/DEMs_SRTM3=



Any missing DEM files are assumed to describe an area at elevation = 0 (such as

an area of open ocean). After the DEMs are downloaded, the tool can be run

(OpenStreetMap tiles are required too, but those are downloaded automatically at

runtime).



There's an interactive tool for humans to mess around with, and a standalone

tool to just make single renders (useful for scripting)



** Interactive

The interactive tool is invoked by running the =./horizonator= executable.

=./horizonator --help= has basic usage instructions. The only required arguments

are the latitude and longitude of the viewer. Example: standing on top of Iron

Mt, looking N and E towards Mount Baden-Powell and Baldy:



#+begin_example

./horizonator --zfar-color 8000 34.2884 -117.7134 45 80

#+end_example



[[file:example-interactive.png]]



This brings up a window where the top half shows an OpenStreetMap slippy map.

OSM tiles are downloaded (and cached locally to =~/.horizonator/tiles/=) as

required. The extents of the current view are shown as lines in the render. The

currently-loaded data is also shown, as a rectangle. The data is loaded at the

beginning, centered on the latitude,longitude given on the commandline. To load

a different set of data, re-launch the application.



The bottom half shows the render. By default, the shade of red encodes the

distance to the viewer. It is possible instead to texture the render using the

map; pass =--texture= to select this mode. Currently this uses the same

OpenStreetMap tiles that are used in the slippy-map, which isn't terribly

useful. Eventually topography or aerial imagery should be hooked in here.



The initial render is made from the latitude,longitude position given on the

commandline (the altitude is sampled from the DEM). The user may change the

viewpoint at runtime, but new data is loaded /only/ at the start.



*** UI

- Mousewheel up/down in the slippy map: zoom in/out

- Left click/drag in the slippy map: pan

- Right click in the slippy map: re-render the currently-loaded data from that

  location

- Mousewheel up/down in the render: zoom in/out. Changes the azimuth extents.

  Does /not/ change the pitch or roll or yaw. The viewer always look out

  parallel to the ground plane: pitch, roll are always 0.

- Mousewheel left/right in the render: pan left/right. Changes the yaw only.

- Left click/drag in the render: pan by moving the azimuth extents and/or the

  yaw. Exactly what the mousewheel does.

- Right click in the render: display the rendered point on the slippy map.

  Useful for identifying peaks.

- Keyboard =w=: cycle between filled triangles, wireframe and point renders

- Keyboard =r=: cycle between the two winding directions; this is only useful

  for debugging.

- Keyboard =q=: quit



** Commandline

If all we want is a single render from a known position, with known azimuth

bounds, run the =./standalone= tool. Example:



#+begin_example

./standalone --width 800 --image example-standalone.png  --zfar-color 8000 34.2884 -117.7134 -35 125

#+end_example



[[file:example-standalone.png]]



This can either run a static GLUT application, or it can render to a =.png=

image on disk and/or a binary range image. Run with =--help= for details. Note

that the azimuth extents are currently specified differently than they are in

the interactive tool.



** C API

The tool can be invoked from C. The [[https://github.com/dkogan/horizonator/blob/master/horizonator.h][header comments]] and its usages in the

commandline tool should be clear.



** Python API

A Python interface is provided, and is built as part of the normal invocation of

=make=. The Python library consists of



- [[https://github.com/dkogan/horizonator/blob/master/horizonator.docstring][a =horizonator= object constructor]]

- [[https://github.com/dkogan/horizonator/blob/master/render.docstring][a =render= function]]



This works similarly to the other components: the constructor loads the data,

and we can then render it in different ways by calling =render()= repeatedly.



* Render details

The tool uses an equirectangular projection. The x coordinate of the rendered

image represents the azimuth: the viewing direction. The y coordinate represents

the elevation: the angle above/below the horizontal. The same angular resolution

is used in both directions. As elevation increases, this projection acquires

more and more distortion, but with small elevation angles (the usual case)

things works well.



The view straight ahead (elevation = 0) is at the center of the render.



This tool operates in the tangent plane to the viewer, so it assumes that

locally, the Earth is flat. This produces small inaccuracies, but unless we care

about small pixel-level errors, this is a good approximation. I will eventually

fix this.



* DEM resolution

By default, 3" DEMs are used. These are the low-res SRTM data, which is

generally plenty hi-res-enough for this application. For more faithful rendering

of very near objects, the resolution can become a problem, so the

higher-resolution 1" DEMS may be used. These are better, but they exacerbate an

implementation detail in the horizonator, so the 3" DEMs are used by default.

Currently every triangle in the mesh is rendered, even those that are very far

away, and look tiny. A coarser mesh would be more appropriate for far-off

objects. Until that is implemented, the 9x increase in triangles present in the

SRTM1 data could become a problem. Support for 1" data /is/ in place, and can be

selected with the =SRTM1= option in all the APIs and commandline tools.



* Nice-to-have improvements

In no particular order:



- Texturing with aerial imagery

- Being more efficient about data loading: the DEM and texture resolution needs

  to be high close-in, but can be dramatically lower further out.

- Higher-res DEMs are available (1sec SRTM instead of 3sec). It would be nice to

  use them, /if/ we can do so efficiently

- Nicer handling of the mesh immediately near the viewer.

- Intelligently loading faraway data. Currently we load data a constant number

  of cells away from the viewer

- Peak-labelling the render

- More UI stuff

  - text showing the current lat, lon, az bounds

  - text inputs to change the current lat, lon, az bounds

  - controls to re-center the data, to get more data in some particular

    direction

  - controls to change the texturing, shading configuration, etc

  - controls to save renders to disk

- Auto-downloading DEMs



* License and copyright

** Horizonator (everything except =florb/=)

Copyright 2012-2021 Dima Kogan 

Released under the terms of the GNU LGPL (any version)



** =florb/=

Copyright (c) 2010, Björn Rehm (bjoern@shugaa.de)

Released under the terms of the MIT license