donmccurdy/gltf-transform

glTF 2.0 SDK for JavaScript and TypeScript, on Web and Node.js.

gltf-transform's Issues

KHR_materials_transmission

KhronosGroup/glTF#1698

Create @gltf-transform/inspect package.

There's a basic "inspect()" function checked into the CLI package, but I'd like to put that into its own npm package so it's available both in web and node.js. The current script prints a number of tables describing the content of the file, and is intended to be useful for understanding performance behavior, and whether the model follows basic best practice¹. For example:

• how many meshes and materials are there?
• how many materials use alpha blending?
• how many textures are included, and how large is each texture?

The goal for a @gltf-transform/inspect package would be to abstract that into something that returns JSON. Users can read the JSON on Web/Node.js, and the CLI tool can use it to print the same tables it does today. Example usage:

import { WebIO } from '@gltf-transform/core';
import { inspect } from '@gltf-transform/inspect';

const doc = await new WebIO().read('path/to/model.glb');
const report = inspect(doc);
console.log(report);

¹ Best practice, as opposed to whether it's a technically valid glTF file. The glTF-Validator already covers the latter case very well.

Fails to read glb files

Hi; I know this is in development, so feel free to close if this isn't expected to be working yet. I came here because of the de-duplication idea (based on Matt Deslaurier's gist).
I cloned the repo, did npm install, lerna bootstrap, and npm run dist, then ran node_modules/.bin/gltf-transform analyze DamagedHelmet.glb and got this error:

/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:600
        if (bufferView.byteLength > 0) {
                       ^

TypeError: Cannot read property 'byteLength' of undefined
    at Function.removeBufferView (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:600:24)
    at forEach (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:236:22)
    at Array.forEach (<anonymous>)
    at PackedGLTFContainer.unpack (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:231:29)
    at Function.fromGLB (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:338:54)
    at NodeIO.readGLB (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:766:25)
    at NodeIO.read (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:761:29)
    at Command.program.command.argument.action [as _action] (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/src/cli.js:26:30)
    at Command._run (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/node_modules/caporal/lib/command.js:413:40)
    at Program._run (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/node_modules/caporal/lib/program.js:170:16)
    at Program.parse (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/node_modules/caporal/lib/program.js:276:17)
    at Object.<anonymous> (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/src/cli.js:99:6)
    at Module._compile (internal/modules/cjs/loader.js:778:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)

If I load my own model, I get a slightly different error:

/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:91
                throw new Error(`Empty top-level array, "${this.json[key]}".`);
                ^

Error: Empty top-level array, "".
    at GLTFContainer.validate (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:91:23)
    at PackedGLTFContainer.unpack (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:241:19)
    at Function.fromGLB (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:338:54)
    at NodeIO.readGLB (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:766:25)
    at NodeIO.read (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/node_modules/@gltf-transform/core/dist/gltf-transform-core.js:761:29)
    at Command.program.command.argument.action [as _action] (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/src/cli.js:26:30)
    at Command._run (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/node_modules/caporal/lib/command.js:413:40)
    at Program._run (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/node_modules/caporal/lib/program.js:170:16)
    at Program.parse (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/node_modules/caporal/lib/program.js:276:17)
    at Object.<anonymous> (/c/DSS/Product/Horizon/WebProjects/horizon-project/horizon-data-converters/glTF-Transform/packages/cli/src/cli.js:99:6)
    at Module._compile (internal/modules/cjs/loader.js:778:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)

(I tried modifying packages/core/src/packed-container.ts to see if I could print the "key" it's looking for, and re-running npm run dist but it didn't pick up my changes -- I'm not a lerna person so I assume I missed a step.)

Move CLI to TypeScript

I think I originally used JS here for easier debugging or something? Practically the unit tests seem to be working well for that, I'd rather have the CLI use TS and ts-node at this point.

Sections in CLI --help output

Looks like Caporal now supports sections in its --help output, which could be nice:

general

• analyze
• validate
• repack

modify

• unlit
• colorspace
• ao

clean

• prune
• deduplicate

compress

• ktx
• gzip
• draco

KHR_materials_volume

KhronosGroup/glTF#1726

Separate larger TS files

Split mesh.ts, animation.ts, and texture.ts into a file for each class.

Add node transform helpers

Methods to get world transforms without manually traversing the scene graph. Using gl-matrix.

Documentation

Install

After cloning the repository, run: yarn install

This produce error:" [Errno 2] No such file or directory: 'install'"
Could you help with newbie how to proceed with installation?

Omit tests from npm publish

files: [
  "*",
  "!test/"
]

Scoped packages

Consider:

@gltf-transform/cli
@gltf-transform/util

@gltf-transform/occlusion-vertex
@gltf-transform/prune
@gltf-transform/split
@gltf-transform/atlas
...

[atlas] Create texture atlases

See: https://github.com/oguzeroglu/TextureMerger/blob/master/TextureMerger.js

Run validator on outputs

Preferably automatically in a lint sweep.

Add node.traverse( fn ) method

Similar to three.js, just traverse a node's descendants. Probably add to Scene, too?

CLI 'inspect' command can list only extensions it recognizes.

Ideally it would print the first table with basic information it can get from a NativeDocument, before trying to parse and showing the error. The other tables could be omitted.

I think this requires editing the i/o classes a bit, so that they have methods to create a NativeDocument from a URI, and convert that to a Document as a second step.

[screenshot] Support screenshot generation on Web and Node.js

Related links:

• google/filament#2647
• https://github.com/google/filament/tree/main/web/docs
• https://cx20.github.io/gltf-test/examples/filament/index.js

Usage:

gltf-transform screenshot model.glb --options ...

import { screenshot } from '@gltf-transform/screenshot';
import { NodeIO } from '@gltf-transform/core';


const doc = new NodeIO().read('model.glb');
const screenshotBuffer = screenshot(doc);
fs.writeFileSync('screenshot.png', screenshotBuffer);

[core] Enable `--format modern,umd` in dist/ builds

When it lands in Microbundle 0.12.0, this should hopefully reduce bundle size a bit.

Consolidate transforms into a 'lib' package.

Keeping a package for each transform (ao, colorspace, prune, split, ...) is messy, I often find myself wanting to rename things, or add something quickly, and because NPM packages can't be deleted there's an aspect of "cluttering" the namespace as that goes on. I think all of these could be consolidated into a single package (perhaps "lib"?) that provides functions built on top of the core and extension APIs. In dependency order:

cli > lib > extensions > core

[core] Enable property mangling in dist/ builds.

See https://github.com/developit/microbundle/wiki/mangle.json.

Bring test coverage back up to >80%

Test coveraged slipped with new features in v0.5, let's try to get this back above 80%.

Build only cjs and modern output.

Remove legacy module and umd output. Should resolve the warnings of the form No name was provided for external module, and make building faster.

CLI methods should all warn about unknown extensions.

Basic snippet:

	// Warn for unknown extensions.
	const extensionsRecognized = new Set();
	doc.getRoot().listExtensionsUsed().forEach((ext) => extensionsRecognized.add(ext.extensionName));
	extensionsUsed.forEach((extensionName) => {
		if (!extensionsRecognized.has(extensionName)) {
			logger.warn(`Extension "${extensionName}" not recognized by this tool.`);
		}
	});

Not sure if this belongs in CLI or core I/O.

[texture] JPEG/PNG optimization

Pending GoogleChromeLabs/squoosh#280.

KHR_lights_punctual

Add documentation about toktx dependency

Encoding basis seems to be done via toktx tool that could be downloaded from here https://github.com/KhronosGroup/KTX-Software/releases/tag/v4.0.0-beta3

Revisit "Scripting & CLI" page

CLI preview is already out of date and will probably keep becoming so unless I automate it. The "transforms" should probably go into a "library page". Maybe that leaves "installation" and "scripting"?

Function to flatten node hierarchy, merge meshes

Plan —

• (1) Add transformPrimitive(prim, matrix), transformMesh(mesh, matrix)
  • #700
  • #657
• (2) Add clearNodeParent(node), clearNodeTransform(node). Requires (1).
  • Detaches node from its parent, applies world transform to node.mesh
  • #784
• (3) Add document.transform(flatten()). Requires (1) and (2).
  • #790
  • Deletes unneeded empties (with options to keep them)
  • Keeps armatures
  • Clears parents and transforms of nodes where possible
• (4) Add joinPrimitives(prim: Primitive[]).
  • #707
• (5) Add document.transform(join()). Requires (1), (2), (3), (4).
  • Assumes node hierarchy has already been flattened as desired, using (3).
  • Joins all compatible meshes that are siblings in the scene hierarchy.
  • Maximum vertex counts per draw? Spatial locality?
  • #658

---

Other considerations —

• Update IBMs if node is a joint?
• clearNodeTransform must warn on attached camera or light
• Apply world transforms to TRS animations?
• Apply world transforms to volumetric properties?
• Detach shared vertex streams? Deal with detached accessors?

Convert spec/gloss → metal/rough

Details in KhronosGroup/glTF#1719 (comment). May need get-pixels to rewrite glossiness->roughness.

Usage:

gltf-transform metalrough input.glb output.glb

import {metalRough} from '@gltf-transform/lib';
import {NodeIO} from '@gltf-transform/core';

const io = new NodeIO(fs, path);
const doc = io.read('input.glb');
metalRough(doc);
io.write('output.glb', doc);

Similar API to existing unlit function.

[cli] Dependencies are not declared in package.json

Missing dependencies for canvas and @gltf-transform/atlas.

Should probably also add a test to catch this in the future...

Support chaining commands on CLI

gltf-transform \
  [ prune ] \
  [ atlas --size 1024 ] \
  [ ao --samples 500 ]

https://github.com/SamVerschueren/listr

Update Caporal.js

The new version is a breaking change, but has an improved API, and supports sections in the help output that look useful to me.

[core] abstract api away from accessor/bufferview/buffer syntax

Not ideal for an SDK, which is what the core lib seems to be headed toward. Perhaps something like:

• accessors, images are automatically unpacked and can be written and read individually
• repack at export, defragmenting, splitting, and compressing
• handle references without indices. Augment typings? Point directly to objects? Helper methods?

setBaseColorFactorHex() and setBaseColorFactorOpacity()

Accept (sRGB) hex value and convert to linear vec3.

[core] Generate API docs

[core] Test coverage

• GLTFUtil
• GLTFContainer
• NodeIO
• WebIO

KHR_texture_basisu

Writing Accessors Min/Max null

When reading the attatched lamp.gltf file and then writing it, some accessors' min and max arrays will have null values. (This prevents the next tool in our pipeline to convert it to usdz). We know that the original .gltf file has some issues, but we would expect that upon successful reading of the file that it would also write a correct file.

lamp.zip

const io = new NodeIO(fs, path);  
var doc = io.read("lamp/lamp.gltf");  
io.write("lamp/lampOut.gltf", doc);

gltf-transform/core version: 0.3.2

KHR_draco_mesh_compression

Add draco package

KHR_texture_transform

[ao] Add unlit option

--unlit to bake occlusion to vertex colors?

[cli] cannot resolve colorspace module

New installation of CLI:

Error: Cannot find module '@gltf-transform/colorspace'

Add 'variants' lib and CLI function

See KhronosGroup/glTF#1681, similar to https://github.com/facebookincubator/glTFVariantMeld. Would be added to the lib package and available through the CLI. Not sure whether the existing meld API is the right one, maybe this should take a config file pointing to external textures, and a single glTF, instead?

Add 'xmp' lib and CLI function

KhronosGroup/glTF#1553

Add 'instance' transform

Given a model in which a particular mesh is repeated many times in the scene, with different transforms, output a model using EXT_gpu_mesh_compression to instance the mesh. Ideally with options for tiling the instances for better culling. Some ideas for sample models:

• https://sketchfab.com/search?features=downloadable&q=grass+field&sort_by=-relevance&type=models
• https://sketchfab.com/3d-models/pine-forest-ece69535f7584e099488f65f2072264e
• https://sketchfab.com/Somersby

Clean up extra files

• tsconfig.json
• LICENSE
• rollup.config.js
• typings/
• scripts/
• dist/
• static/ (to package)

[prune] Deduplicate images

Support extensions

Hey, I know support for extensions is in development in the v0.4 branch but according to the comment, the only thing missing is documentation.

Can I start using this branch? Is there anything else I can do to help with it?

I'm using glTF-Transform to extract the 3D models from a proprietary format and I'd like to use the KHR_materials_unlit extension.

KHR_materials_pbrSpecularGlossiness

Add 'debug' or 'doctor' package

Intended to look for common validity issues in the Document that would prevent its being exported, before the Document is written to a file (after which glTF-Validator is the better thing to use). Things like:

• cyclic dependencies
• unassigned buffers
• unassigned but required properties
• ...