Skip to main content

Using the 3D Buildings Tiler On-Premises


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


Extract the contents of

The main executable is 3d-buildings-tiler and can be found under bin.

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


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

Using the tiler

A typical tiler command follows the following format:

3d-buildings-tiler -I <input-type> -i <input-directory> -o <output-directory>

For example, a CityGML model of the German Reichstag building is included in the SampleData/Reichstag directory. Tile it by running:

3d-buildings-tiler -I CityGML -i SampleData/Reichstag -o Reichstag_Tiles

This will tile all valid CityGML files (.gml, .citygml, and .xml) in the SampleData/Reichstag directory into 3D Tiles. The final tileset will be placed in a new directory called Reichstag_Tiles.

You can also specify a single file directly:

3d-buildings-tiler -I CityGML -i SampleData/Reichstag/Reichstag.gml -o Reichstag_Tiles

KML works the same way. A KML building model is included in the SampleData/AGI_HQ_KML directory. Tile it by running:

3d-buildings-tiler -I KML -i SampleData/AGI_HQ_KML -o AGI_HQ_KML_Tiles

Clamping to terrain

The 3D buildings tiler supports clamping buildings to the underlying terrain. This is useful for applications that need to take into account building heights such as city planning or flood modeling.

Terrain can be provided as an ion asset ID, as shown below. You’ll need to provide an access token.

3d-buildings-tiler -I <input-type> -i <input-directory> -o <output-directory> --ion-terrain <asset-id> --ion-access-token <access-token>

Terrain can also be provided as a .terraindb file, as shown below. A .terraindb file can be generated by Cesium ion’s Terrain Tiler.

3d-buildings-tiler -I <input-type> -i <input-directory> -o <output-directory> -g WorldTerrain.terraindb

Alternatively, you can pass a URL to a hosted terrain server.

3d-buildings-tiler -I <input-type> -i <input-directory> -o <output-directory> -g http://localhost:8002/WorldTerrain

See the Adding terrain section below for an example of streaming buildings with terrain.

Available options

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

Basic options

Option                                            DescriptionRequiredDefault
--help, -hDisplay help message.
--version, -vDisplay version number.
--input, -iOne or more files or directories to recursively search for CityGML or KML files. Required if --input-list is not supplied. Cannot be used with --input-list.
--input-listA text file with a list of files to process, one file per line. Required if --input is not supplied. Cannot be used with --input.
--input-type, -IType of input to be tiled. Options are CityGML or KML.
--output, -oThe path to the output directory or a .3dtiles database file. Will overwrite the existing directory if found, or otherwise create a new directory.
--database, -dPath to use for the temporary database. This is required when multiple input paths are supplied.[--input]/../[inputDirectory].sqlite3
--quietSuppress output during tiling.false
--verboseShow verbose output.false
--concurrency, -xMaximum number of cores to use for CPU processing. Actual utilization depends on system resources. When running inside Docker, it is recommended to set this manually since containerization prevents the tiler from querying system resources.System available.
--per-feature-properties, -rFor KML input, pass a space separated list of property names from the input data to save as metadata in the output tileset. Property names are case sensitive. For CityGML input, all properties are automatically included.Longitude, Latitude, Height
--tileset-versionA version number or string to assign to the tileset. This is written to tileset.json and can be used as metadata to track changes.

Terrain clamping options

See the Clamping to terrain section above for examples.

Option                                            DescriptionRequiredDefault
--terrain, -gPath to terrain database (.terraindb file) or URL to terrain server used to clamp models to terrain.
--ion-terrainID of the ion asset used to clamp models to terrain. Use 1 for Cesium World Terrain.
--ion-access-tokenAccess token used to retrieve the specified ion terrain.
--ion-serverURL to the ion REST API endpoint.

Geometry and compression options

Option                                            DescriptionRequiredDefault
--disable-geometry-compressionDisable Draco geometry compression.false
--compression-levelDraco compression level between 0 and 10. In general, the highest setting, 10, will have the most compression but worst decompression speed. 0 will have the least compression, but best decompression speed. Compression level does not affect precision.7
--compression-precision-metersPrecision in meters for Draco compression. Defaults to millimeter precision. Set to 0 for lossless compression which produces larger tile sizes.0.001
--gzipSave tiles with gzip compression.false
--clear-normalsClear existing normals and regenerate them.false
--face-normalsGenerate face normals.false
--smooth-normalsGenerate smooth (vertex) normals.false
--single-sidedGenerate single-sided geometry. Double-sided geometry is used by default to improve rendering of unclosed geometry and building interiors, but may cause a performance hit in CesiumJS.false

You can read more about Draco compression on our blog.

Advanced options

Option                                            DescriptionRequiredDefault
--progress-percentShow overall progress percentage instead of individual progress bars for each stage.false
--tiler, -qSet a tiling strategy. Options are Adaptive, UniformGrid, NonUniformGrid, TMSGeodetic, TMSWGS84, TMSWebMercator. Options with the prefix TMS require setting the content-level option. Read about the different tiling schemes.Adaptive
--content-levelSets the maximum level. Required if using the TMS option with --tiler.

CityGML options

These options are specific to CityGML data.

Option                                            DescriptionRequiredDefault
--citygml.sourceSRSSets a Spatial Reference System (SRS) to override the SRS found in the input data, such as EPSG, WKT, OGC, URN etc. Use this if your CityGML data does not have an SRS or has an incorrect SRS.Uses SRS from the input data.
--citygml.levelOfDetailUse only the specified level of detail (LOD) for each object and disregard other LODs. Objects that don’t have the specified LOD are skipped.Uses the maximum LOD for each object.
--citygml.useKnownMaterialsUse colors from known materials for geometry without defined colors.false
--citygml.disableColorsDisable all colors and use white as the base color.false
--citygml.disableTexturesDisable textures in the CityGML dataset and use colors only.false
--citygml.enableVertexColorsStore per-vertex colors instead of using separate materials. This improves performance in CesiumJS for data with many colors by reducing draw calls, but it uses more memory.false
--citygml.setGroundZeroSet height of buildings to 0 if the building is determined to be on the ground. This is automatically set to true when terrain data is provided.false

Next steps

Now that we’ve tiled our building data into 3D Tiles, the next step is to stream it to CesiumJS. All we need is a web server to host our tiles, and then we can pass a URL to our tileset as shown below.

var viewer = new Cesium.Viewer('cesiumContainer');

const tileset = await Cesium.Cesium3DTileset.fromUrl('<URL to tileset.json>')


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

Adding terrain

If the tileset is clamped to Cesium World Terrain, add it to the viewer as shown below.

viewer.terrainProvider = await Cesium.createWorldTerrainAsync();

If you’re hosting your own terrain, pass the URL to the terrain server:

const terrainProvider = await Cesium.CesiumTerrainProvider.fromUrl('<URL to terrain>');
viewer.terrainProvider = terrainProvider;

Read more about serving terrain with the Hosting 3D Content tutorial.


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

Content and code examples at are available under the Apache 2.0 license. You can use the code examples in your commercial or non-commercial applications.