Using the Terrain Tiler On-Premises

Looking for on-premises 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:

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:

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:

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. 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. The Cesium ion terrain tiler outputs a terraindb file that can be streamed over the web using the Cesium ion Asset Server. We can then supply a URL to our terrain as shown below.

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`.