\n\nContent pipeline tools for optimizing [glTF](https://www.khronos.org/gltf) assets by [Richard Lee](http://leerichard.net/) and the [Cesium team](https://cesium.com/).\n\nSupports common operations including:\n\n- Converting glTF to glb (and reverse)\n- Saving buffers/textures as embedded or separate files\n- Converting glTF 1.0 models to glTF 2.0\n- Applying [Draco](https://github.com/google/draco) mesh compression\n\n`gltf-pipeline` can be used as a command-line tool or Node.js module.\n\n## Getting Started\n\nInstall [Node.js](https://nodejs.org/en/) if you don't already have it, and then:\n\n```\nnpm install -g gltf-pipeline\n```\n\n### Using gltf-pipeline as a command-line tool:\n\n#### Converting a glTF to glb\n\n`gltf-pipeline -i model.gltf -o model.glb`\n\n`gltf-pipeline -i model.gltf -b`\n\n#### Converting a glb to glTF\n\n`gltf-pipeline -i model.glb -o model.gltf`\n\n`gltf-pipeline -i model.glb -j`\n\n#### Converting a glTF to Draco glTF\n\n`gltf-pipeline -i model.gltf -o modelDraco.gltf -d`\n\n### Saving separate textures\n\n`gltf-pipeline -i model.gltf -t`\n\n### Using gltf-pipeline as a library:\n\n#### Converting a glTF to glb:\n\n```javascript\nconst gltfPipeline = require(\"gltf-pipeline\");\nconst fsExtra = require(\"fs-extra\");\nconst gltfToGlb = gltfPipeline.gltfToGlb;\nconst gltf = fsExtra.readJsonSync(\"./input/model.gltf\");\nconst options = { resourceDirectory: \"./input/\" };\ngltfToGlb(gltf, options).then(function (results) {\n fsExtra.writeFileSync(\"model.glb\", results.glb);\n});\n```\n\n#### Converting a glb to embedded glTF\n\n```javascript\nconst gltfPipeline = require(\"gltf-pipeline\");\nconst fsExtra = require(\"fs-extra\");\nconst glbToGltf = gltfPipeline.glbToGltf;\nconst glb = fsExtra.readFileSync(\"model.glb\");\nglbToGltf(glb).then(function (results) {\n fsExtra.writeJsonSync(\"model.gltf\", results.gltf);\n});\n```\n\n#### Converting a glTF to Draco glTF\n\n```javascript\nconst gltfPipeline = require(\"gltf-pipeline\");\nconst fsExtra = require(\"fs-extra\");\nconst processGltf = gltfPipeline.processGltf;\nconst gltf = fsExtra.readJsonSync(\"model.gltf\");\nconst options = {\n dracoOptions: {\n compressionLevel: 10,\n },\n};\nprocessGltf(gltf, options).then(function (results) {\n fsExtra.writeJsonSync(\"model-draco.gltf\", results.gltf);\n});\n```\n\n#### Saving separate textures\n\n```javascript\nconst gltfPipeline = require(\"gltf-pipeline\");\nconst fsExtra = require(\"fs-extra\");\nconst processGltf = gltfPipeline.processGltf;\nconst gltf = fsExtra.readJsonSync(\"model.gltf\");\nconst options = {\n separateTextures: true,\n};\nprocessGltf(gltf, options).then(function (results) {\n fsExtra.writeJsonSync(\"model-separate.gltf\", results.gltf);\n // Save separate resources\n const separateResources = results.separateResources;\n for (const relativePath in separateResources) {\n if (separateResources.hasOwnProperty(relativePath)) {\n const resource = separateResources[relativePath];\n fsExtra.writeFileSync(relativePath, resource);\n }\n }\n});\n```\n\n#### A Note on `resourceDirectory` and `allowAbsolute`\n\nIf a `resourceDirectory` is not specified, the only possible paths in a glTF object are absolute. In the event `processGltf` is called without a `resourceDirectory` and the glTF references absolute paths, it will behave as if `allowAbsolute` is true, but also emit a warning if it's not. To get rid of this warning, add `allowAbsolute: true` to your options, e.g.,:\n\n```javascript\nconst options = {\n /*... */\n};\nconst results = await processGltf(gltf, options);\n```\n\nshould be changed to:\n\n```javascript\nconst options = {\n allowAbsolute: true,\n /*... */\n};\nconst results = await processGltf(gltf, options);\n```\n\n### Command-Line Flags\n\n| Flag | Description | Required |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |\n| `--help`, `-h` | Display help | No |\n| `--input`, `-i` | Path to the glTF or glb file. | :white_check_mark: Yes |\n| `--output`, `-o` | Output path of the glTF or glb file. Separate resources will be saved to the same directory. | No |\n| `--binary`, `-b` | Convert the input glTF to glb. | No, default `false` |\n| `--allowAbsolute`, `-a` | Allow glTF files to refer to file URLs outside of their source path | No, default `false` |\n| `--json`, `-j` | Convert the input glb to glTF. | No, default `false` |\n| `--separate`, `-s` | Write separate buffers, shaders, and textures instead of embedding them in the glTF. | No, default `false` |\n| `--separateTextures`, `-t` | Write out separate textures only. | No, default `false` |\n| `--stats` | Print statistics to console for output glTF file. | No, default `false` |\n| `--keepUnusedElements` | Keep unused materials, nodes and meshes. | No, default `false` |\n| `--keepLegacyExtensions` | When false, materials with `KHR_techniques_webgl`, `KHR_blend`, or `KHR_materials_common` will be converted to PBR. | No, default `false` |\n| `--draco.compressMeshes`, `-d` | Compress the meshes using Draco. Adds the `KHR_draco_mesh_compression` extension. | No, default `false` |\n| `--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` |\n| `--draco.quantizePositionBits` | Quantization bits for position attribute when using Draco compression. | No, default `11` |\n| `--draco.quantizeNormalBits` | Quantization bits for normal attribute when using Draco compression. | No, default `8` |\n| `--draco.quantizeTexcoordBits` | Quantization bits for texture coordinate attribute when using Draco compression. | No, default `10` |\n| `--draco.quantizeColorBits` | Quantization bits for color attribute when using Draco compression. | No, default `8` |\n| `--draco.quantizeGenericBits` | Quantization bits for skinning attribute (joint indices and joint weights) and custom attributes when using Draco compression. | No, default `8` |\n| `--draco.unifiedQuantization` | Quantize positions of all primitives using the same quantization grid. If not set, quantization is applied separately. | No, default `false` |\n| `--draco.uncompressedFallback` | Adds uncompressed fallback versions of the compressed meshes. | No, default `false` |\n| `--baseColorTextureNames` | Names of uniforms that should be considered to refer to base color textures when updating from the `KHR_techniques_webgl` extension to PBR materials. | No. (The defaults are not specified here) |\n| `--baseColorFactorNames` | Names of uniforms that should be considered to refer to base color factors when updating from the `KHR_techniques_webgl` extension to PBR materials. | No. (The defaults are not specified here) |\n\n## Build Instructions\n\nRun the tests:\n\n```\nnpm run test\n```\n\nTo run ESLint on the entire codebase, run:\n\n```\nnpm run eslint\n```\n\nTo run ESLint automatically when a file is saved, run the following and leave it open in a console window:\n\n```\nnpm run eslint-watch\n```\n\n### Building for CesiumJS integration\n\nSome functionality of gltf-pipeline is used by CesiumJS as a third party library. The necessary files can be generated using:\n\n```\nnpm run build-cesium\n```\n\nThis will output a portion of the gltf-pipeline code into the `dist/cesium` folder for use with CesiumJS in the browser. Copy the files into `Source/Scene/GltfPipeline/` in the [`cesium`](https://github.com/CesiumGS/cesium) repository and submit a pull request.\n\n### Running Test Coverage\n\nCoverage uses [nyc](https://github.com/istanbuljs/nyc). Run:\n\n```\nnpm run coverage\n```\n\nFor complete coverage details, open `coverage/lcov-report/index.html`.\n\nThe tests and coverage covers the Node.js module; it does not cover the command-line interface, which is tiny.\n\n## Generating Documentation\n\nTo generate the documentation:\n\n```\nnpm run jsdoc\n```\n\nThe documentation will be placed in the `doc` folder.\n\n## Contributions\n\nPull requests are appreciated! Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/main/CONTRIBUTING.md) and [Coding Guide](https://github.com/CesiumGS/cesium/blob/main/Documentation/Contributors/CodingGuide/README.md) used for [Cesium](https://github.com/CesiumGS/cesium).\n","readmeFilename":"README.md"}
![](\"doc/gltf.png\")
\n