❗️ 3D Tiles Tools is not actively maintained. For converting source data to 3D Tiles check out Cesium ion. ❗️

A note about the repository structure

This repository was originally part of the 3d-tiles-validator repository, which contained multiple projects. Now, these project are maintained in separate repositories:

• The 3d-tiles-validator can be found in the 3d-tiles-validator repository
• The 3d-tiles-samples-generator can be found in the 3d-tiles-samples-generator repository

Node.js library and command-line tools for processing and converting 3D Tiles tilesets.

Clone this repo and install Node.js. From the root directory of this repo, run:

npm install

Gzips the input tileset.

node ./bin/3d-tiles-tools.js gzip ./specs/data/TilesetOfTilesets/ ./output/TilesetOfTilesets-gzipped/

node ./bin/3d-tiles-tools.js gzip -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-gzipped/

Ungzips the input tileset.

node ./bin/3d-tiles-tools.js ungzip ./specs/data/TilesetOfTilesets/ ./output/TilesetOfTilesets-ungzipped/

node ./bin/3d-tiles-tools.js ungzip -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-ungzipped/

Combines all external tilesets into a single tileset.json file.

node ./bin/3d-tiles-tools.js combine ./specs/data/TilesetOfTilesets/ ./output/TilesetOfTilesets-combined/

node ./bin/3d-tiles-tools.js combine -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-combined/

Upgrades the input tileset to the latest version of the 3D Tiles spec. Embedded glTF models will be upgraded to glTF 2.0.

node ./bin/3d-tiles-tools.js upgrade ./specs/data/TilesetOfTilesets/ ./output/TilesetOfTilesets-upgraded/

node ./bin/3d-tiles-tools.js upgrade -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-upgraded/

Creates a b3dm from a glb with an empty batch table. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js glbToB3dm ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb ./output/CesiumTexturedBox.b3dm

node ./bin/3d-tiles-tools.js glbToB3dm -i ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb -o ./output/CesiumTexturedBox.b3dm

Creates a i3dm from a glb with a single instance at position [0, 0, 0] and an empty batch table. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js glbToI3dm ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb ./output/CesiumTexturedBox.i3dm

node ./bin/3d-tiles-tools.js glbToI3dm -i ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb -o ./output/CesiumTexturedBox.i3dm

Creates a glb from a b3dm. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js b3dmToGlb -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/extracted.glb

Creates a glb from a i3dm. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js i3dmToGlb -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/extracted.glb

Extracts the glb models from a cmpt tile. If multiple models are found a number will be appended to the output file name. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js cmptToGlb -i ./specs/data/composite.cmpt -o ./output/extracted.glb

Optimize a b3dm using gltf-pipeline. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js optimizeB3dm -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/optimized.b3dm

Quantize floating-point attributes and oct-encode normals

node ./bin/3d-tiles-tools.js optimizeB3dm -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/optimized.b3dm --options -q -n

To use tileset texture compression, pass the texcomp flags

node ./bin/3d-tiles-tools.js optimizeB3dm -i ./specs/data/Textured/batchedTextured.b3dm -o ./output/optimized.b3dm --options --texcomp.dxt1.enable --texcomp.dxt1.quality=5 --texcomp.etc1.enable

This example optimizes the b3dm and compresses the textures into dxt1 and etc1 formats.

Optimize a i3dm using gltf-pipeline. Since this tool does not process an entire tileset, it cannot be used with the Pipeline tool.

node ./bin/3d-tiles-tools.js optimizeI3dm -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/optimized.i3dm

Quantize floating-point attributes and oct-encode normals

node ./bin/3d-tiles-tools.js optimizeI3dm -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/optimized.i3dm --options -q -n

To use tileset texture compression, pass the texcomp flags.

node ./bin/3d-tiles-tools.js optimizeI3dm -i ./specs/data/Textured/instancedTextured.i3dm -o ./output/optimized.i3dm --options --texcomp.dxt1.enable --texcomp.dxt1.quality=5 --texcomp.etc1.enable

This example optimizes the i3dm and compresses the textures into dxt1 and etc1 formats.

Generates a sqlite database for a tileset.

This tool cannot be used with the Pipeline tool.

Each tile is stored gzipped in the database. The specification for the tables in the database is not final, see 3d-tiles/#89.

node ./bin/3d-tiles-tools.js tilesetToDatabase ./specs/data/TilesetOfTilesets/ ./output/tileset.3dtiles

node ./bin/3d-tiles-tools.js tilesetToDatabase -i ./specs/data/TilesetOfTilesets/ -o ./output/tileset.3dtiles

Unpack a tileset database to a tileset folder.

This tool cannot be used with the Pipeline tool.

Each tile is stored gzipped in the database, and unzipped when unpacked. The specification for the tables in the database is not final, see 3d-tiles/#89.

node ./bin/3d-tiles-tools.js databaseToTileset ./specs/data/tileset.3dtiles ./output/Tileset

node ./bin/3d-tiles-tools.js databaseToTileset -i ./specs/data/tileset.3dtiles -o ./output/Tileset

node ./bin/3d-tiles-tools.js pipeline ./specs/data/pipeline.json

node ./bin/3d-tiles-tools.js pipeline -i ./specs/data/pipeline.json

Executes a pipeline JSON file containing an input directory, output directory, and list of stages to run. A stage can be a string specifying the stage name or an object specifying the stage name and any additional parameters. Stages are executed in the order listed.

This example pipeline.json gzips the input tilest and saves it in the given output directory.

{
    "input": "Tileset/",
    "output": "TilesetGzipped/",
    "stages": ["gzip"]
}

This pipeline uncompresses the input tileset and then compresses all the tiles. Files like tileset.json are left uncompressed.

{
    "input": "Tileset/",
    "output": "TilesetGzipped/",
    "stages": [
        "ungzip",
        {
            "name": "gzip",
            "tilesOnly": true
        }
    ]
}

###Pipeline Stages

####gzip

Gzips the input tileset.

Properties

####ungzip

Ungzips the input tileset.

Run the tests:

npm run test

To run ESLint on the entire codebase, run:

npm run eslint

To run ESLint automatically when a file is saved, run the following and leave it open in a console window:

npm run eslint-watch

Coverage uses istanbul. Run:

npm run coverage

For complete coverage details, open coverage/lcov-report/index.html.

The tests and coverage covers the Node.js module; it does not cover the command-line interface.

To generate the documentation:

npm run jsDoc

The documentation will be placed in the doc folder.

• To debug the tests in Webstorm, open the Gulp tab, right click the test task, and click Debug 'test'.
• To run a single test, change the test function from it to fit.