3D Buildings Tiler

Tile 3D building models from CityGML and KML/COLLADA into 3D Tiles.

Setup

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

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

Windows

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

Linux

Install libGLU using your system’s package manager, as shown below.

# Ubuntu / apt-get based distributions
apt-get install libglu1-mesa

# Fedora / Enterprise Linux / CentOS / RPM based distributions
yum install mesa-libGLU

Using the tiler

The general usage command is the following.

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

For example, to tile a CityGML dataset into 3D Tiles, run the following.

bin/3d-buildings-tiler -i CityGMLData -I CityGML -o Tileset

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

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.

bin/3d-buildings-tiler -i <input-directory> -I <data-type> -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.

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

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

bin/3d-buildings-tiler -i <input-directory> -I <data-type> -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 Description Required Default
--help, -h Display help message.    
--version, -v Display version number.    
--input, -i One or more files or directories to recursively search for CityGML or KML files.  
--input-type, -I Type of input to be tiled. Options are CityGML or KML.  
--output, -o The path to the output directory or a .3dtiles database file. Will overwrite the existing directory if found, or otherwise create a new directory.  
--database, -d Path to use for the temporary database. This is required when multiple input paths are supplied.   [--input]/../[inputDirectory].sqlite3
--quiet Suppress output during tiling.   false
--verbose Show verbose output.   false
--concurrency, -x Maximum 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, -r For 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-version A 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 Description Required Default
--terrain, -g Path to terrain database (.terraindb file) or URL to terrain server used to clamp models to terrain.    
--ion-terrain ID of the ion asset used to clamp models to terrain. Use 1 for Cesium World Terrain.    
--ion-access-token Access token used to retrieve the specified ion terrain.    
--ion-server URL to the ion REST API endpoint.   https://api.cesium.com

Geometry and compression options

Option Description Required Default
--disable-geometry-compression Disable Draco geometry compression.   false
--compression-level Draco 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
--gzip Save tiles with gzip compression.   false
--clear-normals Clear existing normals and regenerate them.   false
--face-normals Generate face normals.   false
--smooth-normals Generate smooth (vertex) normals.   false

You can read more about Draco compression on our blog.

Advanced options

Option Description Required Default
--progress-percent Show overall progress percentage instead of individual progress bars for each stage.   false
--tiler, -q Set 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-level Sets the maximum level. Required if using the TMS option with tiler.    

CityGML options

These options are specific to CityGML data.

Option Description Required Default
--citygml.sourceSRS Sets 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.levelOfDetail Use 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.useKnownMaterials Use colors from known materials for geometry without defined colors.   false
--citygml.disableColors Disable all colors and use white as the base color.   false
--citygml.disableTextures Disable textures in the CityGML dataset and use colors only.   false
--citygml.enableVertexColors Store 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.setGroundZero Set 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');

var tileset = viewer.scene.primitives.add(
    new Cesium.Cesium3DTileset({
        url : '<URL to tileset.json>',
    })
);

viewer.zoomTo(tileset);

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 = Cesium.createWorldTerrain();

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

var terrainProvider = new Cesium.CesiumTerrainProvider({
    url: '<URL to terrain>'
});
viewer.terrainProvider = terrainProvider;

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

License

Third-party licenses used by the tilers can be found in LICENSE.json.

Community Support

Cesium has an active community of developers and users. Along with members of the Cesium team, they support all kinds of technical questions.

Ask the forum