❗️ 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 the3d-tiles-validator
repository- The
3d-tiles-samples-generator
can be found in the3d-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/
Flag | Description | Required |
---|---|---|
-i , --input |
Input directory of the tileset. | ✅ Yes |
-o , --output |
Output directory of the processed tileset. | No |
-t , --tilesOnly |
Only gzip tiles. | No, default false |
-f , --force |
Overwrite output directory if it exists. | No, default false |
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/
Flag | Description | Required |
---|---|---|
-i , --input |
Input directory of the tileset. | ✅ Yes |
-o , --output |
Output directory of the processed tileset. | No |
-f , --force |
Overwrite output directory if it exists. | No, default false |
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/
Flag | Description | Required |
---|---|---|
-i , --input |
Input directory of the tileset. | ✅ Yes |
-o , --output |
Output directory of the processed tileset. | No |
-r , --rootJson |
Relative path to the root tileset.json file. | No, default tileset.json |
-f , --force |
Overwrite output file if it exists. | No, default false |
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/
Flag | Description | Required |
---|---|---|
-i , --input |
Input directory of the tileset. | ✅ Yes |
-o , --output |
Output directory of the processed tileset. | No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .glb |
✅ Yes |
-o , --output |
Output path of the resulting .b3dm |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .glb |
✅ Yes |
-o , --output |
Output path of the resulting .i3dm |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .b3dm |
✅ Yes |
-o , --output |
Output path of the resulting .glb |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .i3dm |
✅ Yes |
-o , --output |
Output path of the resulting .glb |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .cmpt |
✅ Yes |
-o , --output |
Output path of the resulting .glb |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .b3dm |
✅ Yes |
-o , --output |
Output path of the resulting .b3dm |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
--options |
All arguments past this flag are consumed by gltf-pipeline. | No |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input path of the .i3dm |
✅ Yes |
-o , --output |
Output path of the resulting .i3dm |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
--options |
All arguments past this flag are consumed by gltf-pipeline. | No |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input directory of the tileset. | ✅ Yes |
-o , --output |
Output path of the resulting .3dtiles . |
No |
-f , --force |
Overwrite output file if it exists. | No, default false |
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
Flag | Description | Required |
---|---|---|
-i , --input |
Input .3dtiles database file. | ✅ Yes |
-o , --output |
Output directory of the unpacked tileset. | No |
-f , --force |
Overwrite output directory if it exists. | No, default false |
node ./bin/3d-tiles-tools.js pipeline ./specs/data/pipeline.json
node ./bin/3d-tiles-tools.js pipeline -i ./specs/data/pipeline.json
Flag | Description | Required |
---|---|---|
-i , --input |
Input pipeline JSON file. | ✅ Yes |
-f , --force |
Overwrite output directory if it exists. | No, default false |
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
Type | Description | Required | |
---|---|---|---|
tilesOnly | boolean |
Only gzip tiles. | No, default: false |
####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 clickDebug 'test'
. - To run a single test, change the test function from
it
tofit
.