gltf-transform-cli v0.0.4
🚨 In development
glTF-Transform
JavaScript and TypeScript utilities for processing glTF 3D models.
AGI's glTF-Pipeline and Microsoft's glTF-Toolkit are robust, well-maintained tools for production workflows — I fully recommend using them for the features the offer. However, neither covers the "long tail" of small, niche changes to a glTF model: adjusting a material parameter, adding extensions, and so on. For those situations, this framework provides a better alternative to starting from scratch, or modifying a library not designed with modularity in mind, for users who need to write or reuse a custom transformation.
glTF-Transform offers CLI and programmatic access to a library of packages, along with reusable utilities for extending the framework with new features. Most packages work both in Node.js and on the web.
Packages
| package | compatibility | description |
|---|---|---|
| core | Node.js, Web | Core framework utilities. |
| cli | Node.js | Commandline interface to Node.js-compatible packages. |
| --- | ||
| ao | Node.js, Web | Bakes per-vertex ambient occlusion. Cheaper but lower-quality than AO baked with a UV map. Powered by geo-ambient-occlusion |
| atlas | Node.js, Web | Merges small textures and materials, creating a basic texture atlas. |
| colorspace | Node.js, Web | Vertex color colorspace correction. |
| prune | Node.js, Web | Prunes duplicate accessors (and more, eventually). Based on a gist by mattdesl. |
| split | Node.js, Web | Splits the binary payload of a glTF file so separate mesh data is in separate .bin files. |
Roadmap and ideas
- deduplicate images
- defrag bufferviews
- merge geometry
- draco (de)compression
- unlit materials
- optimize animation
- sparse accessors
- flatten node hierarchy
- compute AABBs
- mesh optimization [1][2]
Usage
Programmatic
See full API documentation.
import { GLTFUtil, GLTFContainer, NodeIO, WebIO } from '@gltf-transform/core';
import { ao } from '@gltf-transform/ao';
const io = new WebIO();
const container = io.read( 'scene.gltf' );
// analyze
const analysis = GLTFUtil.analyze( container );
// ambient occlusion
ao( container, { samples: 1000 } );
// serialize
const glbBuffer = GLTFUtil.toGLB( container );CLI
# help
gltf-transform --help
# analyze
gltf-transform analyze input.glb
# ambient occlusion
gltf-transform ao --samples 1000 input.glb output.glbContributing
This project consists of multiple NPM packages, managed in one repository with https://lerna.js.org/. All code, excluding Node.js-based tests, is written in TypeScript. I recommend using VSCode for linting and type information, which becomes very helpful when modifying glTF schema objects.
After cloning the repository, run:
npm install && npm install -g lerna
lerna bootstrapThe command lerna bootstrap will install dependencies into each package, and will then
link them together. If you make changes to a package's dependencies (e.g. run
npm install <anything>) you will need to run lerna link re-create the symlinks.
To build and test all code, run:
npm run dist
npm run testTo run an arbitrary command across all packages:
lerna exec -- <command>While working, use npm run watch to watch and rebuild code after changes. To use a local
version of the CLI, run npm link within the packages/cli directory. Then
gltf-transform -h will use local code instead of any global installation.
In the event that dependencies get into a broken state, removing package-lock.json and
reinstalling may resolve things.
Releasing
NOTE: Only the author can create new releases.
Currently Lerna has trouble with 2FA OTPs. As a result, new packages need to be published manually before they can be included in a repo-wide release. Once that is done, normal releases should use:
NPM_CONFIG_OTP=123456 lerna publish <version> --force-publish=*