Content pipeline tools for optimizing glTF assets by Richard Lee and the Cesium team.
Supports common operations including:
- Converting glTF to glb (and reverse)
- Saving buffers/textures as embedded or separate files
- Converting glTF 1.0 models to glTF 2.0 (using the KHR_techniques_webgl and KHR_blend extensions)
- Applying Draco mesh compression
gltf-pipeline
can be used as a command-line tool or Node.js module.
Install Node.js if you don't already have it, and then:
npm install -g gltf-pipeline
gltf-pipeline -i model.gltf -o model.glb
gltf-pipeline -i model.gltf -b
gltf-pipeline -i model.glb -o model.gltf
gltf-pipeline -i model.glb -j
gltf-pipeline -i model.gltf -o modelDraco.gltf -d
gltf-pipeline -i model.gltf -o modelDraco.gltf -d --texcomp.dxt1.enable --texcomp.dxt1.quality=10 --texcomp.etc1.enable --texcomp.pvrtc2.enable
gltf-pipeline -i model.gltf -t
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const gltfToGlb = gltfPipeline.gltfToGlb;
const gltf = fsExtra.readJsonSync('model.gltf');
gltfToGlb(gltf)
.then(function(results) {
fsExtra.writeFileSync('model.glb', results.glb);
});
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const glbToGltf = gltfPipeline.glbToGltf;
const glb = fsExtra.readFileSync('model.glb');
glbToGltf(glb)
.then(function(results) {
fsExtra.writeJsonSync('model.gltf', results.gltf);
});
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const processGltf = gltfPipeline.processGltf;
const gltf = fsExtra.readJsonSync('model.gltf');
const options = {
dracoOptions: {
compressionLevel: 10
}
};
processGltf(gltf, options)
.then(function(results) {
fsExtra.writeJsonSync('model-draco.gltf', results.gltf);
});
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const processGltf = gltfPipeline.processGltf;
const gltf = fsExtra.readJsonSync('model.gltf');
const options = {
separateTextures: true
};
processGltf(gltf, options)
.then(function(results) {
fsExtra.writeJsonSync('model-separate.gltf', results.gltf);
// Save separate resources
const separateResources = results.separateResources;
for (const relativePath in separateResources) {
if (separateResources.hasOwnProperty(relativePath)) {
const resource = separateResources[relativePath];
fsExtra.writeFileSync(relativePath, resource);
}
}
});
Flag | Description | Required |
---|---|---|
--help , -h |
Display help | No |
--input , -i |
Path to the glTF or glb file. | โ Yes |
--output , -o |
Output path of the glTF or glb file. Separate resources will be saved to the same directory. | No |
--binary , -b |
Convert the input glTF to glb. | No, default false |
--json , -j |
Convert the input glb to glTF. | No, default false |
--separate , -s |
Write separate buffers, shaders, and textures instead of embedding them in the glTF. | No, default false |
--separateTextures , -t |
Write out separate textures only. | No, default false |
--secure |
Prevent the source model from referencing paths outside of its directory. | No, default false |
--stats |
Print statistics to console for output glTF file. | No, default false |
--draco.compressMeshes , -d |
Compress the meshes using Draco. Adds the KHR_draco_mesh_compression extension. | No, default false |
--draco.compressionLevel |
Draco compression level [0-10], most is 10, least is 0. A value of 0 will apply sequential encoding and preserve face order. | No, default 7 |
--draco.quantizePositionBits |
Quantization bits for position attribute when using Draco compression. | No, default 14 |
--draco.quantizeNormalBits |
Quantization bits for normal attribute when using Draco compression. | No, default 10 |
--draco.quantizeTexcoordBits |
Quantization bits for texture coordinate attribute when using Draco compression. | No, default 12 |
--draco.quantizeColorBits |
Quantization bits for color attribute when using Draco compression. | No, default 8 |
--draco.quantizeGenericBits |
Quantization bits for skinning attribute (joint indices and joint weights) and custom attributes when using Draco compression. | No, default 12 |
--draco.unifiedQuantization |
Quantize positions of all primitives using the same quantization grid. If not set, quantization is applied separately. | No, default false |
--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 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
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.
Coverage uses nyc. 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.
Pull requests are appreciated! Please use the same Contributor License Agreement (CLA) and Coding Guide used for Cesium.