glTF Pipeline

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.

Instructions

Clone this repo and install Node.js. 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

Command-Line Flags

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
--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
--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.enable	Compress textures.	No, default false
--texcomp.format	The compressed texture format.	No, unless texcomp.enable is defined.
--texcomp.quality	The compressed texture quality from 0 to 10.	No, default 5
--texcomp.bitrate	The bitrate when using the pvrtc or astc formats	No, default 2.0
--texcomp.blockSize	The block size for astc compression. Smaller block sizes result in higher bitrates. This value is ignored if options.bitrate is also set.	No, default 8x8
--texcomp.alphaBit	Store a single bit for alpha. Not supported for all compression formats or tools.	No, default false

Build Instructions

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

Running Test Coverage

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.

Generating Documentation

To generate the documentation:

npm run jsdoc

The documentation will be placed in the doc folder.

Debugging

• 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.

Contributions

Pull requests are appreciated! Please use the same Contributor License Agreement (CLA) and Coding Guide used for Cesium.

Attribution

This product includes components of the PowerVR Tools Software from Imagination Technologies Limited.

---