3D Buildings 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 3d-buildings-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

A typical tiler command follows the following format:

Copy to clipboard. Data copied clipboard.
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:

Copy to clipboard. Data copied clipboard.
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:

Copy to clipboard. Data copied clipboard.
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:

Copy to clipboard. Data copied clipboard.
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.

Copy to clipboard. Data copied clipboard.
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.

Copy to clipboard. Data copied clipboard.
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.

Copy to clipboard. Data copied clipboard.
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 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-list A text file with a list of files to process, one file per line.    
--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
--compression-precision-meters Precision in meters for Draco compression. Defaults to millimeter precision. Set to 0 for lossless compression which produces larger tile sizes.   0.001
--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
--single-sided Generate 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 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.

Copy to clipboard. Data copied clipboard.
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.

Copy to clipboard. Data copied clipboard.
viewer.terrainProvider = Cesium.createWorldTerrain();

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

Copy to clipboard. Data copied clipboard.
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 ThirdParty.pdf.