• This repository has been archived on 08/Mar/2023
  • Stars
    star
    581
  • Rank 76,901 (Top 2 %)
  • Language
    C++
  • License
    MIT License
  • Created about 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A command-line tool for converting heightmaps in GeoTIFF format into tiled optimized meshes.

NOTE: This repository has been archived as it is no longer maintained. HERE thanks the community for their contributions so far and encourages any interested party to come forward and discuss taking over maintenance.

TIN Terrain

Build Status

TIN Terrain is a command-line tool for converting heightmaps presented in GeoTIFF format into tiled optimized meshes (Triangulated Irregular Network) with different levels of details.

Check out heremaps/quantized-mesh-viewer for examples of rendering output in Cesium.js and Three.js.

Note: This is experimental code, expect changes.

dem2tin GeoTIFF to mesh on USGS craterlake DEM

Features

  • Takes GeoTIFF with heightmap as an input
  • Transforms heightmap into a TIN mesh with a given max-error parameter and outputs into .obj format
  • Transforms heightmap into tiled TIN mesh for a given zoom range and outputs tiled pyramid into quantized-mesh-1.0 terrain format

Let us know what you think!

You can help us a lot to prioritize issues in tin-terrain if you submit a short anonymous survey

Installation

You can build and run this tool either with Docker or directly on your system. Building with Docker is easier and works on macOS, Linux, and Windows.

Detailed instructions for each platform are provided below.

Building with Docker

The provided Dockerfile builds the TIN Terrain executable on Ubuntu Linux.

To build the container, execute:

./build-docker.sh

To run TIN Terrain from Docker, type e.g.

docker run -v [local data directory]:/data:cached --name tin-terrain --rm -i -t tin-terrain tin-terrain ...

where [local data directory] is the folder that contains your DEM files and will receive the output files. This will be mapped to /data in the Docker instance, so you should use:

docker run -v [local data directory]:/data:cached --name tin-terrain --rm -i -t tin-terrain tin-terrain dem2tin --input /data/... --output /data/... 

Alternatively, use

docker run -v [local data directory]:/data:cached --name tin-terrain --rm -i -t tin-terrain bash 

to open an interactive shell which lets you execute tin-terrain and access /data. Any files not stored in /data will be lost when closing the session.

Prerequisites & Dependencies

If you choose to compile and run "TIN Terrain" directly on your system, please note that the following packages must be installed on your system:

  • The C++ standard library from the compiler (tested with clang 9.1.0 and gcc 7.3.0)
  • Boost (BSL-1.0) program_options, filesystem, system (tested with version 1.67)
  • GDAL (MIT) gdal, gdal_priv, cpl_conv (tested with version 2.3)

TIN Terrain also downloads some source code of 3rd party libraries during the CMake configure phase:

You can disable this behaviour by passing the -DTNTN_DOWNLOAD_DEPS=OFF option to CMake when generating the project/makefiles. If you do so, you have to download dependencies yourself and also pass the TNTN_LIBGLM_SOURCE_DIR and TNTN_LIBFMT_SOURCE_DIR variables to CMake as well as TNTN_CATCH2_SOURCE_DIR if you want to run the tests.

See download-deps.cmake for detailed version info.

Building on macOS

  1. Install dependencies, preferably with homebrew:
    brew install boost
    brew install cmake
    brew install gdal
    
  2. Create an XCode project:
    mkdir build-cmake-xcode
    cd build-cmake-xcode
    cmake -GXcode path/to/sourcecode/
    open tin-terrain.xcodeproj
    
  3. Build the TIN Terrain target.

The resulting binaries will be in the Debug/Release subdirectory.

To run the tests, build and run the tntn-tests target.

Possible linking issues with GDAL

If another version of GDAL is present on your machine, the FindGDAL.cmake provided with cmake might not be able to properly detect the newest version of GDAL you installed through homebrew (or any other prefered method).

Whether this is the case, can be easily detected, if the linking step in the compilation errors on linking GDAL.

Therefore you might need to guide cmake to the right location of the GDAL:

cmake -GXcode -DGDAL_LIBRARY=PATH/TO/GDAL/LIB path/to/sourcecode/

e.g

cmake -GXcode -DGDAL_LIBRARY=/usr/local/Cellar/gdal/2.3.1_2/lib/libgdal.dylib path/to/sourcecode/

Building on Linux

  1. Install dependencies, e.g. on Ubuntu:
    apt-get install build-essential cmake libboost-all-dev libgdal-dev
    
  2. Create Makefile:
    mkdir build-cmake-release
    cd build-cmake-release
    cmake -DCMAKE_BUILD_TYPE=Release path/to/sourcecode/
    
  3. Build the tin-terrain target
    VERBOSE=1 make tin-terrain
    

The resulting binary should then be ready. To run the tests, build and run the tntn-tests target:

  1. Recreate Makefile (and set TNTN_TEST=ON):
    cd build-cmake-release
    cmake -DTNTN_TEST=ON -DCMAKE_BUILD_TYPE=Debug path/to/sourcecode/
    
  2. Build the tntn-tests target
    VERBOSE=1 make tntn-tests
    

Usage

The tin-terrain command-line tool has a few subcommands. You can run tin-terrain --help to see all available subcommands.

$ tin-terrain --help
usage:
  tin-terrain [OPTION]... <subcommand> ...

Global Options:
  -h [ --help ]               print this help message
  --log arg (=stdout)         diagnostics output/log target, can be stdout,
                              stderr, or none
  -v [ --verbose ] [=arg(=1)] be more verbose
  --subcommand arg            command to execute
  --subargs arg               arguments for command

available subcommands:
  dem2tin - convert a DEM into a mesh/tin
  dem2tintiles - convert a DEM into mesh/tin tiles
  benchmark - run all available meshing methods on a given set of input files and produce statistics (performance, error rate)
  version - print version information

Projections

The tin-terrain tool requires your datasets to be in the Web Mercator projection (EPSG:3857). If your datasets are not in this projection, you can quite easily reproject your datasets with gdalwarp, e.g.:

gdalwarp -t_srs EPSG:3857 ned19_n37x75_w122x50_ca_goldengate_2010.img ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif

Creating a single mesh/TIN

You can use the dem2tin subcommand to convert a raster heightmap into a single big mesh/TIN in the OBJ format.

You can see all available options by running tin-terrain dem2tin --help.

$ tin-terrain dem2tin --help
usage:
  tin-terrain dem2tin [OPTIONS]...

dem2tin options:
  --input arg                 input filename
  --input-format arg (=auto)  input file format, can be any of: auto, asc, xyz,
                              tiff
  --output arg                output filename
  --output-format arg (=auto) output file format, can be any of: auto, obj,
                              off, terrain (quantized mesh), json/geojson
  --method arg (=terra)       meshing method, valid values are: terra, zemlya and dense
  --max-error arg             (terra & zemlya) maximum geometric error
  --step arg (=1)		      (dense) grid spacing in pixels


methods:
  terra     - implements a delaunay based triangulation with point selection using a fast greedy insert mechnism
    reference: Garland, Michael, and Paul S. Heckbert. "Fast polygonal approximation of terrains and height fields." (1995).
    paper: https://mgarland.org/papers/scape.pdf
    and http://mgarland.org/archive/cmu/scape/terra.html
  zemlya    - hierarchical greedy insertion
    reference: Zheng, Xianwei, et al. "A VIRTUAL GLOBE-BASED MULTI-RESOLUTION TIN SURFACE MODELING AND VISUALIZETION METHOD." International Archives of the Photogrammetry, Remote Sensing & Spatial Information Sciences 41 (2016).
    paper: https://www.int-arch-photogramm-remote-sens-spatial-inf-sci.net/XLI-B2/459/2016/isprs-archives-XLI-B2-459-2016.pdf
  dense     - generates a simple mesh grid from the raster input by placing one vertex per pixel

For example, you can run the following command to convert "ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif" to a single big mesh, using a max-error parameter of 2.0 meters:

tin-terrain dem2tin --input /data/ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif --output /data/terrain.obj --max-error 2.0

After running this command, you should see a "terrain.obj" output file in the same directory. This OBJ file contains the generated mesh.

The max-error parameter specifies the vertical error allowance in meters, so a smaller max-error parameter results in more triangles in the output mesh, better mesh quality, and longer running time.

Creating a pyramid of mesh/TIN tiles

The dem2tintiles subcommand takes a raster heightmap as the input, and creates tiled TIN mesh for a given zoom range. The output tiles can be either in the OBJ format or in the quantized-mesh-1.0 terrain format.

You can see all available options by running tin-terrain dem2tintiles --help.

$ tin-terrain dem2tintiles --help
usage:
  tin-terrain dem2tintiles [OPTION]...

dem2tintiles options:
  --input arg                    input filename
  --output-dir arg (=./output)
  --max-zoom arg (=-1)           maximum zoom level to generate tiles for. will
                                 guesstimate from resolution if not provided.
  --min-zoom arg (=-1)           minimum zoom level to generate tiles for will
                                 guesstimate from resolution if not provided.
  --max-error arg                (terra or zemlya) max error when using
  --step arg (=1)            	 (dense) grid spacing in pixels
  --output-format arg (=terrain) output tiles in terrain (quantized mesh) or
                                 obj
  --method arg (=terra)          meshing algorithm. one of: terra, zemlya or dense

For example, you can run the following command to convert "ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif" to a pyramid of mesh tiles.

tin-terrain dem2tintiles --input /data/ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif --output-dir /data/output --min-zoom 5 --max-zoom 14 --output-format=terrain --max-error 2.0

When this command finishes running, you should see an output folder containing all the mesh tiles, organized into a pyramid of subfolders.

├── 10
│   ├── 163
│   │   ├── 627.terrain
│   │   └── 628.terrain
│   └── 164
│       ├── 627.terrain
│       └── 628.terrain
...

The folder structure follows the map tile convention: Z/X/Y.terrain.

These mesh tiles can then be easily served from a webserver and be consumed by frontend applications for purposes such as terrain visualization.

Sample Datasets

When you enable the TNTN_TEST and TNTN_DOWNLOAD_DEPS options in the CMake configuration, a few sample datasets will be downloaded into the ${CMAKE_SOURCE_DIR}/3rdparty/ folder.

For example, you will find the crater lake dataset in the ${CMAKE_SOURCE_DIR}/3rdparty/craterlake folder. This dataset is created and maintained by the U.S. Geological Survey (USGS) and can be downloaded from http://oe.oregonexplorer.info/craterlake/.

To generate a mesh from this dataset, you need to reproject it to the Web Mercator projection first, using the gdalwarp command-line tool which comes with your GDAL installation:

gdalwarp -t_srs EPSG:3857 -r cubic -of GTiff -ot Float32 dems_10m.dem dems_10m.tif

Then you can run tin-terrain on this reprojected GeoTIFF file to create a mesh:

./tin-terrain dem2tin --input dems_10m.tif --output terrain.obj --max-error 2.0 --method terra

License

Copyright (C) 2018 HERE Europe B.V.

See the LICENSE file in the root of this project for license details.

Papers

Some algorithms are based on ideas from:

More Repositories

1

harp.gl

3D web map rendering engine written in TypeScript using three.js
TypeScript
1,284
star
2

pptk

The Point Processing Toolkit (pptk) is a Python package for visualizing and processing 2-d/3-d point clouds.
C++
613
star
3

oksse

An extension library for OkHttp to create a Server-Sent Event (SSE) client.
Java
230
star
4

here-covid-19-tracker

Using HERE Technologies APIs, fork and build your own COVID-19 Tracker. For a live version, see the website.
JavaScript
212
star
5

gluecodium

Cross-language bindings generator for C++, Java, Swift, and Dart
Dart
202
star
6

maps-api-for-javascript-examples

Self-contained examples for Maps API for JavaScript v3.
JavaScript
196
star
7

quantized-mesh-viewer

Render custom quantized mesh tiles in Cesium.js and debug individual tiles using THREE.js renderer.
JavaScript
183
star
8

flatdata

Write-once, read-many, minimal overhead binary structured file format.
Python
179
star
9

here-sdk-examples

Android, iOS and Flutter example apps for the HERE SDK 4.x (Lite Edition, Explore Edition, Navigate Edition)
169
star
10

here-android-sdk-examples

Java-based projects using the HERE SDK for Android.
Java
145
star
11

postman-collections

Postman collections for HERE REST APIs.
133
star
12

flexible-polyline

Flexible Polyline encoding: a lossy compressed representation of a list of coordinate pairs or triples
Rust
91
star
13

devrel-workshops

Workshop in-a-box for developer events such as conferences, meetups, and hackathons.
JavaScript
69
star
14

xyz-hub

XYZ Hub is a RESTful web service for the access and management of geospatial data.
Java
65
star
15

here-icons

HERE icons are visual cues of objects, points, actions, and tools found across HERE products.
63
star
16

xyz-maps

XYZ Maps is an open-source map editor written in TypeScript.
TypeScript
60
star
17

here-ios-sdk-examples

Objective-C and Swift projects using the HERE SDK for iOS.
Objective-C
60
star
18

gradle-jenkins-jobdsl-plugin

A plugin for Gradle to manage Jenkins Job DSL projects.
Groovy
53
star
19

here-data-sdk-cpp

The HERE Data SDK for C++ is a modern, lightweight and modular SDK for the HERE platform
C++
51
star
20

msdkui-android

The HERE Mobile SDK UI Kit for Android provides ready-to-use UI components for the HERE Mobile SDK for Android.
Java
51
star
21

movetk

MoveTK is a library for computational movement analysis written in C++.
C++
47
star
22

xyz-documentation

This repository contains the Open Documentation for HERE XYZ.
45
star
23

here-sdk-ref-app-flutter

This project is the HERE SDK reference application for Flutter
Dart
44
star
24

xyz-showcase

Showcase of web maps made with HERE XYZ
HTML
43
star
25

quantized-mesh-decoder

JavaScript decoder for the Quantized Mesh format
JavaScript
40
star
26

here-cli

A command-line interface to work with HERE XYZ Hub and other HERE APIs
JavaScript
38
star
27

msdkui-ios

The HERE Mobile SDK UI Kit for iOS provides ready-to-use UI components for the HERE Mobile SDK for iOS.
Swift
38
star
28

here-map-widget-for-jupyter

Use HERE Maps API for JavaScript in your Jupyter Notebook.
JavaScript
36
star
29

here-data-sdk-typescript

The HERE Data SDK for TypeScript is a modern, lightweight and modular SDK for the HERE platform
TypeScript
32
star
30

harp-terrain-datasource

Render and style 3D terrain
JavaScript
31
star
31

xyz-spaces-python

Manage your XYZ Hub or HERE Data Hub spaces from Python.
Python
30
star
32

here-aws-sar

HERE Maps API for Serverless Application Repository
JavaScript
30
star
33

here-aaa-java-sdk

HERE Authentication, Authorization, and Accounting Java Client library.
Java
27
star
34

xyz-qgis-plugin

Plugin for QGIS to connect to the HERE Platform IML
Python
27
star
35

here-location-services-python

A Python client for HERE Location Services.
Python
27
star
36

bike-navigation

A companion device to use the HERE app on Android for bike navigation. Note: Not actively developed anymore!
C
26
star
37

here-workspace-examples-java-scala

HERE Workspace Examples for Java and Scala Developers
Java
26
star
38

here-sbt-bom

SBT BOM is the plugin for SBT for dealing with Maven BOM in SBT projects
Scala
19
star
39

jsfiddle-github

JSFiddle implementation for interactive JavaScript examples.
JavaScript
18
star
40

harp-leaflet

Leaflet plugin for harp.gl
TypeScript
17
star
41

here-tracking-js

JS library for accessing the HERE Tracking API
JavaScript
15
star
42

harp-map-editor

Simple map editor for harp.gl map styles
TypeScript
13
star
43

here-tracking-c

HERE Tracking Library for C
C
12
star
44

developer-blog

Examples and projects featured on the HERE developer blog.
JavaScript
11
star
45

here-vector-tile-examples

Examples of the HERE Vector Tile API with various 3rd party web map renderers
JavaScript
9
star
46

here-interactive-map-layer-examples

Use case examples for interactive map layers including geometry simplification, data sampling, clustering, and spatial/property search.
JavaScript
9
star
47

devrel-livestreams

Source code and resources related to the Developer Relations livestreams
HTML
8
star
48

here-artifact-maven-wagon

The HERE platform Maven Wagon plugin provides Java and Scala developers with access to platform artifacts via Maven
Java
7
star
49

here-azure-serverless

Azure Functions for HERE Location Services
JavaScript
6
star
50

harp-fontcatalog-generator

Generator to create fontcatalogs to be used by harp.gl
JavaScript
6
star
51

here-data-sdk-examples-python

Examples for HERE Data SDK for Python
Jupyter Notebook
6
star
52

com.here.validate.svrl.overrides

Shows how to add, remove or extend the ruleset of the base DITA Validator (com.here.validate.svrl).
XSLT
5
star
53

com.here.validate.svrl

A structure, style and content checker for DITA documents in the form of a DITA OT plug-in.
XSLT
5
star
54

saturate-nodes-plugin

A Jenkins plugin which allows to saturate nodes as much as possible
Java
5
star
55

heremaps.github.io

Landing page for all HERE OSS projects on GitHub
CSS
5
star
56

naksha

Naksha Hub is a RESTful web service for the access and management of geospatial data.
Java
5
star
57

deployment-api

A front-end for DC/OS service creation
Java
4
star
58

map-linkbuilder-app

A reference web application showcasing "deeplinking" to https://wego.here.com/.
JavaScript
3
star
59

here-polyline-converter

encode/decode/convert HERE legacy polyline strings
Python
3
star
60

com.here.validate.svrl.text-rules

Simple rule-based spelling and grammar validation DITA OT plug-in for text elements within DITA documents.
XSLT
3
star
61

homebrew-olp-cli

Use the Command Line Interface (CLI) to access HERE platform services from a command line or with scripts.
Ruby
3
star
62

harp-font-resources

Font catalog to use with the harp.gl renderer
TypeScript
3
star
63

buildrotator-plugin

A Jenkins plugin to perform rotation of build history with low memory pressure.
Java
3
star
64

dita-ot-plugins

This repository serves to organize a set of DITA OT plug-ins developed internally at HERE.
2
star
65

here-artifact-sbt-resolver

The HERE platform SBT Resolver plugin provides Java and Scala developers with access to platform artifacts via SBT
Scala
2
star
66

mobility-on-demand-use-cases-nodejs

HERE mobility on-demand demos written as NodeJS applications.
JavaScript
2
star
67

mobility-on-demand-use-cases-ios

HERE mobility on-demand demo written as an iOS application.
Objective-C
2
star
68

devrel-samples

JavaScript
1
star
69

fluentd-plugin

A Jenkins plugin which allows to publish json data directly to Fluentd.
Java
1
star