Using the 3D Buildings 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 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:
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_TilesThis 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_TilesKML 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_TilesClamping 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.terraindbAlternatively, 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/WorldTerrainSee 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. Required if --input-list is not supplied. Cannot be used with --input-list. | ||
--input-list | A 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, -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.
var viewer = new Cesium.Viewer('cesiumContainer');
const tileset = await Cesium.Cesium3DTileset.fromUrl('<URL to tileset.json>')
viewer.scene.primitives.add(tileset);
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 = 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.
License
Third-party licenses used by the tilers can be found in ThirdParty.pdf.