{"id":13423654,"url":"https://github.com/heremaps/tin-terrain","last_synced_at":"2025-03-15T17:32:05.072Z","repository":{"id":41570795,"uuid":"148305288","full_name":"heremaps/tin-terrain","owner":"heremaps","description":"A command-line tool for converting heightmaps in GeoTIFF format into tiled optimized meshes.","archived":true,"fork":false,"pushed_at":"2023-03-08T09:05:58.000Z","size":2978,"stargazers_count":585,"open_issues_count":28,"forks_count":127,"subscribers_count":45,"default_branch":"master","last_synced_at":"2024-10-26T23:11:47.486Z","etag":null,"topics":["3d","c-plus-plus","cesium","cesium-terrain","geotiff","mesh-generation","quantized-mesh","triangulation"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heremaps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-09-11T11:15:17.000Z","updated_at":"2024-10-19T16:46:44.000Z","dependencies_parsed_at":"2024-01-12T00:28:08.697Z","dependency_job_id":"422abe62-f086-4761-a16c-40199845ee66","html_url":"https://github.com/heremaps/tin-terrain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Ftin-terrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Ftin-terrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Ftin-terrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Ftin-terrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heremaps","download_url":"https://codeload.github.com/heremaps/tin-terrain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243767087,"owners_count":20344869,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","c-plus-plus","cesium","cesium-terrain","geotiff","mesh-generation","quantized-mesh","triangulation"],"created_at":"2024-07-31T00:00:39.900Z","updated_at":"2025-03-15T17:32:03.518Z","avatar_url":"https://github.com/heremaps.png","language":"C++","readme":"# 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.\n\n# TIN Terrain\n\n[![Build Status](https://travis-ci.com/heremaps/tin-terrain.svg?branch=master)](https://travis-ci.com/heremaps/tin-terrain)\n\nTIN 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.\n\nCheck out [heremaps/quantized-mesh-viewer](https://github.com/heremaps/quantized-mesh-viewer) for examples of rendering output in [Cesium.js](https://github.com/heremaps/quantized-mesh-viewer/blob/master/src/map/surface-provider.js) and [Three.js](https://github.com/heremaps/quantized-mesh-viewer/blob/master/src/tile/index.js).\n\nNote: This is experimental code, expect changes.\n\n![dem2tin GeoTIFF to mesh on USGS craterlake DEM](docs/resources/dem2tin.jpg)\n\n## Features\n\n* Takes GeoTIFF with heightmap as an input\n* Transforms heightmap into a TIN mesh with a given max-error parameter and outputs into `.obj` format\n* Transforms heightmap into tiled TIN mesh for a given zoom range and outputs tiled pyramid into [quantized-mesh-1.0](https://github.com/AnalyticalGraphicsInc/quantized-mesh) terrain format\n\n## Let us know what you think!\n\nYou can help us a lot to prioritize issues in tin-terrain if you submit a [short anonymous survey](https://survey.research-feedback.com/jfe/form/SV_6qVft7VrQfwsDml)\n\n## Installation\n\nYou 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.\n\nDetailed instructions for each platform are provided below.\n\n\n### Building with Docker\n\nThe provided Dockerfile builds the TIN Terrain executable on Ubuntu Linux.\n\nTo build the container, execute:\n\n```\n./build-docker.sh\n```\n\nTo run TIN Terrain from Docker, type e.g. \n\n```\ndocker run -v [local data directory]:/data:cached --name tin-terrain --rm -i -t tin-terrain tin-terrain ...\n```\n\nwhere `[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:\n\n```\ndocker run -v [local data directory]:/data:cached --name tin-terrain --rm -i -t tin-terrain tin-terrain dem2tin --input /data/... --output /data/... \n```\n\nAlternatively, use \n\n```\ndocker run -v [local data directory]:/data:cached --name tin-terrain --rm -i -t tin-terrain bash \n```\n    \nto 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.\n\n\n### Prerequisites \u0026 Dependencies\n\nIf you choose to compile and run \"TIN Terrain\" directly on your system, please note that the following packages must be installed on your system:\n* The C++ standard library from the compiler (tested with `clang` `9.1.0` and `gcc` `7.3.0`)\n* Boost (BSL-1.0) `program_options`, `filesystem`, `system` (tested with version `1.67`)\n* GDAL (MIT) `gdal`, `gdal_priv`, `cpl_conv` (tested with version `2.3`)\n\nTIN Terrain also downloads some source code of 3rd party libraries during the CMake configure phase:\n* [libfmt](https://github.com/fmtlib/fmt) (BSD-2-Clause)\n* [glm](https://github.com/g-truc/glm) (MIT)\n* [Catch2](https://github.com/catchorg/Catch2) (BSL-1.0)\n\nYou can disable this behaviour by passing the `-DTNTN_DOWNLOAD_DEPS=OFF` option to CMake when generating the project/makefiles.\nIf 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\nas well as `TNTN_CATCH2_SOURCE_DIR` if you want to run the tests.\n\nSee [download-deps.cmake](download-deps.cmake) for detailed version info.\n\n\n### Building on macOS\n\n1. Install dependencies, preferably with homebrew:\n    ```\n    brew install boost\n    brew install cmake\n    brew install gdal\n    ```\n2. Create an XCode project:\n    ```\n    mkdir build-cmake-xcode\n    cd build-cmake-xcode\n    cmake -GXcode path/to/sourcecode/\n    open tin-terrain.xcodeproj\n    ```\n3. Build the TIN Terrain target.\n\nThe resulting binaries will be in the Debug/Release subdirectory.\n\nTo run the tests, build and run the tntn-tests target.\n\n#### Possible linking issues with GDAL\n\nIf another version of GDAL is present on your machine, the FindGDAL.cmake provided with cmake might not be able\nto properly detect the newest version of GDAL you installed through homebrew (or any other prefered method).\n\nWhether this is the case, can be easily detected, if the linking step in the compilation errors on linking GDAL.\n\nTherefore you might need to guide cmake to the right location of the GDAL:\n\n```\ncmake -GXcode -DGDAL_LIBRARY=PATH/TO/GDAL/LIB path/to/sourcecode/\n```\ne.g\n```\ncmake -GXcode -DGDAL_LIBRARY=/usr/local/Cellar/gdal/2.3.1_2/lib/libgdal.dylib path/to/sourcecode/\n```\n\n\n### Building on Linux\n\n1. Install dependencies, e.g. on Ubuntu:\n    ```\n    apt-get install build-essential cmake libboost-all-dev libgdal-dev\n    ```\n2. Create Makefile:\n    ```\n    mkdir build-cmake-release\n    cd build-cmake-release\n    cmake -DCMAKE_BUILD_TYPE=Release path/to/sourcecode/\n    ```\n3. Build the `tin-terrain` target\n    ```\n    VERBOSE=1 make tin-terrain\n    ```\n\nThe resulting binary should then be ready.\nTo run the tests, build and run the tntn-tests target:\n\n1. Recreate Makefile (and set TNTN_TEST=ON):\n    ```\n    cd build-cmake-release\n    cmake -DTNTN_TEST=ON -DCMAKE_BUILD_TYPE=Debug path/to/sourcecode/\n    ```\n2. Build the `tntn-tests` target\n    ```\n    VERBOSE=1 make tntn-tests\n    ```\n\n## Usage\n\nThe `tin-terrain` command-line tool has a few subcommands. You can run `tin-terrain --help` to see all available subcommands.\n\n```\n$ tin-terrain --help\nusage:\n  tin-terrain [OPTION]... \u003csubcommand\u003e ...\n\nGlobal Options:\n  -h [ --help ]               print this help message\n  --log arg (=stdout)         diagnostics output/log target, can be stdout,\n                              stderr, or none\n  -v [ --verbose ] [=arg(=1)] be more verbose\n  --subcommand arg            command to execute\n  --subargs arg               arguments for command\n\navailable subcommands:\n  dem2tin - convert a DEM into a mesh/tin\n  dem2tintiles - convert a DEM into mesh/tin tiles\n  benchmark - run all available meshing methods on a given set of input files and produce statistics (performance, error rate)\n  version - print version information\n```\n\n\n### Projections\n\nThe `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.:\n\n```\ngdalwarp -t_srs EPSG:3857 ned19_n37x75_w122x50_ca_goldengate_2010.img ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif\n```\n\n\n### Creating a single mesh/TIN\n\nYou can use the `dem2tin` subcommand to convert a raster heightmap into a single big mesh/TIN in the OBJ format.\n\nYou can see all available options by running `tin-terrain dem2tin --help`.\n\n```\n$ tin-terrain dem2tin --help\nusage:\n  tin-terrain dem2tin [OPTIONS]...\n\ndem2tin options:\n  --input arg                 input filename\n  --input-format arg (=auto)  input file format, can be any of: auto, asc, xyz,\n                              tiff\n  --output arg                output filename\n  --output-format arg (=auto) output file format, can be any of: auto, obj,\n                              off, terrain (quantized mesh), json/geojson\n  --method arg (=terra)       meshing method, valid values are: terra, zemlya and dense\n  --max-error arg             (terra \u0026 zemlya) maximum geometric error\n  --step arg (=1)\t\t      (dense) grid spacing in pixels\n\n\nmethods:\n  terra     - implements a delaunay based triangulation with point selection using a fast greedy insert mechnism\n    reference: Garland, Michael, and Paul S. Heckbert. \"Fast polygonal approximation of terrains and height fields.\" (1995).\n    paper: https://mgarland.org/papers/scape.pdf\n    and http://mgarland.org/archive/cmu/scape/terra.html\n  zemlya    - hierarchical greedy insertion\n    reference: Zheng, Xianwei, et al. \"A VIRTUAL GLOBE-BASED MULTI-RESOLUTION TIN SURFACE MODELING AND VISUALIZETION METHOD.\" International Archives of the Photogrammetry, Remote Sensing \u0026 Spatial Information Sciences 41 (2016).\n    paper: https://www.int-arch-photogramm-remote-sens-spatial-inf-sci.net/XLI-B2/459/2016/isprs-archives-XLI-B2-459-2016.pdf\n  dense     - generates a simple mesh grid from the raster input by placing one vertex per pixel\n```\n\nFor 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:\n\n```\ntin-terrain dem2tin --input /data/ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif --output /data/terrain.obj --max-error 2.0\n```\n\nAfter running this command, you should see a \"terrain.obj\" output file in the same directory. This OBJ file contains the generated mesh.\n\nThe `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.\n\n\n### Creating a pyramid of mesh/TIN tiles\n\nThe `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](https://github.com/AnalyticalGraphicsInc/quantized-mesh) terrain format.\n\nYou can see all available options by running `tin-terrain dem2tintiles --help`.\n\n```\n$ tin-terrain dem2tintiles --help\nusage:\n  tin-terrain dem2tintiles [OPTION]...\n\ndem2tintiles options:\n  --input arg                    input filename\n  --output-dir arg (=./output)\n  --max-zoom arg (=-1)           maximum zoom level to generate tiles for. will\n                                 guesstimate from resolution if not provided.\n  --min-zoom arg (=-1)           minimum zoom level to generate tiles for will\n                                 guesstimate from resolution if not provided.\n  --max-error arg                (terra or zemlya) max error when using\n  --step arg (=1)            \t (dense) grid spacing in pixels\n  --output-format arg (=terrain) output tiles in terrain (quantized mesh) or\n                                 obj\n  --method arg (=terra)          meshing algorithm. one of: terra, zemlya or dense\n```\n\n\nFor example, you can run the following command to convert \"ned19_n37x75_w122x50_ca_goldengate_2010_mercator.tif\" to a pyramid of mesh tiles.\n\n```\ntin-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\n```\n\nWhen this command finishes running, you should see an output folder containing all the mesh tiles, organized into a pyramid of subfolders.\n\n    ├── 10\n    │   ├── 163\n    │   │   ├── 627.terrain\n    │   │   └── 628.terrain\n    │   └── 164\n    │       ├── 627.terrain\n    │       └── 628.terrain\n    ...\n\nThe folder structure follows the map tile convention: `Z/X/Y.terrain`.\n\nThese mesh tiles can then be easily served from a webserver and be consumed by frontend applications for purposes such as terrain visualization.\n\n### Sample Datasets\n\nWhen 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.\n\nFor 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 \u003chttp://oe.oregonexplorer.info/craterlake/\u003e.\n\nTo 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:\n\n```sh\ngdalwarp -t_srs EPSG:3857 -r cubic -of GTiff -ot Float32 dems_10m.dem dems_10m.tif\n```\n\nThen you can run `tin-terrain` on this reprojected GeoTIFF file to create a mesh:\n\n```sh\n./tin-terrain dem2tin --input dems_10m.tif --output terrain.obj --max-error 2.0 --method terra\n```\n\n## License\n\nCopyright (C) 2018 HERE Europe B.V.\n\nSee the [LICENSE](LICENSE) file in the root of this project for license details.\n\n## Papers\n\nSome algorithms are based on ideas from:\n\n* [Garland, Michael, and Paul S. Heckbert. \"Fast polygonal approximation of terrains and height fields.\" (1995).](https://mgarland.org/papers/scape.pdf)\n* [Zheng, Xianwei, et al. \"A VIRTUAL GLOBE-BASED MULTI-RESOLUTION TIN SURFACE MODELING AND VISUALIZETION METHOD.\" International Archives of the Photogrammetry, Remote Sensing \u0026 Spatial Information Sciences 41 (2016).](https://www.int-arch-photogramm-remote-sens-spatial-inf-sci.net/XLI-B2/459/2016/isprs-archives-XLI-B2-459-2016.pdf)\n","funding_links":[],"categories":["C++","Geospatial Library","DEM projects"],"sub_categories":["C++","EUMETlab"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheremaps%2Ftin-terrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheremaps%2Ftin-terrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheremaps%2Ftin-terrain/lists"}