Terrain Tiler

Looking for on-premise 3D Tiling? Contact sales for an evaluation.

Contact sales

Setup

Extract the contents of Cesium-ion-3D-Tiling-Pipeline.zip.

The main executable is terrain-tiler and can be found under bin.

If you wish to run the examples download and extract SampleData.zip into a new SampleData directory.

Windows

Windows binaries require Visual C++ Redistributable for Visual Studio 2017. Download and run the installer.

Using the tiler

The Cesium ion terrain tiler outputs a terraindb file that can be streamed over the web using the Cesium ion Asset Server.

A typical tiler command follows the following format:

Copy to clipboard. Data copied clipboard.
terrain-tiler -i <input1.tif> <input2.tif> -o <output.terraindb>

For example, a small section of ZionNationalPark is included at SampleData/ZionNationalPark.tiff. Tile it into a Cesium terrain database by running:

Copy to clipboard. Data copied clipboard.
terrain-tiler -i SampleData/ZionNationalPark.tiff -o ZionNationalPark.terraindb

When using multiple overlapping terrain files, the files earlier in the list will be given preference.

Merging new data into an existing terrain tileset

To merge new raster data into an existing terrain tileset, just pass the existing terraindb file as the output path:

Copy to clipboard. Data copied clipboard.
terrain-tiler -i <new.tif> -o <old.terraindb>

If old.terraindb already exists, then new.tif will be tiled and layered on top of the data in old.terraindb. This layering works the same as when tiling multiple raster files into one terraindb, where files earlier in the input list will overwrite ones later in the list wherever they overlap. When --void-fill is set to Underlying, any void data in the new layer will be filled by data from the layer underneath it.

Available options

Below is a full list of command line options to configure the tiler.

Option Description Required Default
--help, -h Display help message.    
--version, -v Display version number.    
--input, -i One or more terrain files to be tiled into a single layer. For overlapping terrain files, files earlier in the list are given preference. Input must be single band. Most raster formats are supported. We’re always adding support for more so don’t hesitate to reach out if you found something that’s incompatible. Required if --input-list is not supplied. Cannot be used with --input-list.    
--input-list A text file containing a list of one or more terrain files to be tiled into a single layer. Required if --input is not supplied. Cannot be used with --input.    
--output, -o Path to the output .terraindb file. If an output file already exists, the newly tiled dataset will be layered above the currently existing one.  
--attribution, -a Custom attribution string that will be stored in the final tileset.    
--quiet Suppress output during tiling.   false
--verbose Show verbose output.   false
--height-reference, -r Specifies what the input elevation values are relative to. Set to Ellipsoid to use the WSG84 ellipsoid or MeanSeaLevel to use the EGM96 model.   MeanSeaLevel
--void-fill, -f Configures the default value to use when encountering void elevation values. Set to MeanSeaLevel to use the EGM96 model or Underlying to use elevation values from underlying terrain layers (or the EGM96 model when no underlying terrain layers exist).   Underlying
--water-mask, -w Set to true to treat elevation values at sea level as water. This will add a water mask to the terrain tileset that CesiumJS will use to display water.   false

Next steps

Now that we’ve tiled our terrain, the next step is to stream it into CesiumJS. Terrain can be served with the Cesium ion Asset Server. We can then supply a URL to our terrain as shown below.

Copy to clipboard. Data copied clipboard.
var viewer = new Cesium.Viewer('cesiumContainer', {
    terrainProvider : new Cesium.CesiumTerrainProvider({
        url : '<URL-To-Terrain-Server>'
    })
});

The Hosting 3D Content tutorial walks you through setting up the Cesium ion Asset Server and streaming your terrain with CesiumJS.

License

Third-party licenses used by the tilers can be found in ThirdParty.pdf.