Content pipeline tools for optimizing glTF assets by Richard Lee and the Cesium team.
This project is under active development, see the roadmap.
gltf-pipeline can be used as a command-line tool or Node.js module.
Clone this repo and install Node.js 6.x or later. From the root directory of this repo, run:
npm install
Command-Line Example:
node ./bin/gltf-pipeline.js -i ./specs/data/boxTexturedUnoptimized/CesiumTexturedBoxTest.gltf -o output.gltf
Compress textures to the dxt1 and etc1 formats
node ./bin/gltf-pipeline.js -i ./specs/data/boxTexturedUnoptimized/CesiumTexturedBoxTest.gltf -o output.gltf --texcomp.dxt1.enable --texcomp.dxt1.quality=10 --texcomp.etc1.enable
| Flag | Description | Required |
|---|---|---|
--help, -h |
Display help | No |
--input, -i |
input=PATH, Read unoptimized glTF from the specified file. | ✅ Yes |
--output, -o |
output=PATH, Write optimized glTF to the specified file. | No |
--binary, -b |
Write binary glTF file using KHR_binary_glTF extension. | No, default false |
--separate, -s |
Write separate geometry/animation data files, shader files, and textures instead of embedding them in the glTF asset. | No, default false |
--separateImage, -t |
Write out separate textures, but embeds geometry/animation data files and shader files in the glTF asset. | No, default false |
--quantize, -q |
Quantize the attributes of this glTF asset using the WEB3D_quantized_attributes extension. | No, default false |
--encodeNormals, -n |
Oct-encode the normals of this glTF asset. | No, default false |
--compressTextureCoordinates, -c |
Compress the testure coordinates of this glTF asset. | No, default false |
--removeNormals, -r |
Strips off existing normals, allowing them to be regenerated. | No, default false |
--smoothNormals, -m |
If normals are missing, they should be generated with smooth normals. | No, default false |
--faceNormals, -f |
If normals are missing, they should be generated using the face normal. | No, default false |
--cesium |
Optimize the glTF for Cesium by using the sun as a default light source. | No, default false |
--tangentsBitangents |
If normals and texture coordinates are given, generate tangents and bitangents. | No, default false |
--stats |
Print statistics to console for input and output glTF files. | No, default false |
--kmc.enable |
Materials should be expressed using the KHR_materials_common extension. If other kmc flags are enabled, this is implicitly true. |
No, default false |
--kmc.doubleSided |
Declares whether backface culling should be disabled. | No, default false |
--kmc.technique |
The lighting model to use. | No, default PHONG |
--ao.enable |
Bake ambient occlusion (to vertex data by default). If other ao flags are enabled, this is implicitly true. Advanced settings in lib/bakeAmbientOcclusion.js |
No, default false |
--ao.toTexture |
Bake AO to existing diffuse textures instead of to vertices. Does not modify shaders. | No, default false |
--ao.groundPlane |
Simulate a groundplane at the lowest point of the model when baking AO. | No, default false |
--ao.ambientShadowContribution |
Amount of AO to show when blending between shader computed lighting and AO. 1.0 is full AO, 0.5 is a 50/50 blend. | No, default 0.5 |
--ao.quality |
Quality to use when baking AO. Valid settings are high, medium, and low. | No, default low |
--texcomp.<format>.enable |
Whether to compress textures with the given compressed texture format. If other texcomp.<format> flags are enabled, this is implicitly true. Multiple formats may be supplied by repeating this flag. Must be one of the following: pvrtc1, pvrtc2, etc1, etc2, astc, dxt1, dxt3, dxt5, crunch-dxt1, crunch-dxt5. Compressed textures are saved as Cesium and 3D Tiles specific metadata inside image.extras.compressedImage3DTiles. More details about texture compression in glTF here: KhronosGroup/glTF#739 |
No, unless other texcomp options are set. |
--texcomp.<format>.quality |
The compressed texture quality from 0 to 10. | No, default 5 |
--texcomp.<format>.bitrate |
The bitrate when using the pvrtc or astc formats. For pvrtc formats this value must be 2.0 or 4.0. |
No, default 2.0 |
--texcomp.<format>.blockSize |
The block size for astc compression. Smaller block sizes result in higher bitrates. This value is ignored if options.bitrate is also set. Must be one of the following: 4x4, 5x4, 5x5, 6x5, 6x6, 8x5, 8x6, 8x8, 10x5, 10x6, 10x8, 10x10, 12x10, 12x12 |
No, default 8x8 |
--texcomp.<format>.alphaBit |
Store a single bit for alpha. Only supported for etc2. | No, default false |
Run the tests:
npm run test
To run JSHint on the entire codebase, run:
npm run jsHint
To run JSHint automatically when a file is saved, run the following and leave it open in a console window:
npm run jsHint-watch
Some functionality of gltf-pipeline is used by Cesium as a third party library. The necessary files can be generated using:
npm run build-cesium
This will output a portion of the gltf-pipeline code into the dist/cesium folder, reformatted into AMD style for use with RequireJS and Cesium in the browser.
This project bundles several native binaries for texture compression.
- [PVRTexTool] (https://community.imgtec.com/developers/powervr/tools/pvrtextool/) - Windows, macOS, and Linux binaries are provided by the PowerVR SDK.
- etc2comp - Windows, macOS, and Linux binaries built from source.
- crunch - Windows binary built from crunch, macOS binary built from BKcore/crunch-osx, Linux binary built from tomerb/linux_fixes.
- astc-encoder - Windows, macOS, and Linux binaries built from source.
On Linux you may need to install g++ 4.8 as some of the tools link to the libgcc and libstdc++ runtimes.
Run the help command for each tool for a more detailed description of the supported command-line options.
Some functionality of gltf-pipeline is used by other projects along with Cesium as a third party library. The necessary files can be generated using:
npm run build-cesium-combine
This will output a portion of the gltf-pipeline code into the dist/cesium-combined folder, reformatted into self-contained file. Currently, only files that have no other local dependencies are allowed.
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, which is tiny.
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
testtask, and clickDebug 'test'. - To run a single test, change the test function from
ittofit.
- Proofread CHANGES.md.
- Update the
versionin package.json to match the latest version in CHANGES.md. - Make sure to run the tests and ensure they pass.
- If any changes are required, commit and push them to the repository.
- Create and test the package.
## NPM Pack
## Creates tarball. Verify using 7-zip (or your favorite archiver).
## If you find unexpected/unwanted files, add them to .npmignore, and then run npm pack again.
npm pack
## Test the package
## Copy and install the package in a temporary directory
mkdir temp && cp <tarball> temp/
npm install --production <tarball>
node -e "var test = require('gltf-pipeline');" # No output on success
# If module has executables, then test those now.
- Tag and push the release.
git tag -a <version> -m "<message>"git push origin <version>
- Publish
npm publish
Contact @lilleyse if you need access to publish.
Pull requests are appreciated! Please use the same Contributor License Agreement (CLA) and Coding Guide used for Cesium.
This product includes components of the PowerVR Tools Software from Imagination Technologies Limited. https://community.imgtec.com/developers/powervr/powervr-tools-software-eula/
