@khronosgroup/gltf-asset-auditor

Khronos glTF Asset Auditor

SPDX-License-Identifier: Apache-2.0

Try out the Web Example: https://www.khronos.org/gltf/gltf-asset-auditor/

This is a typescript package that contains classes for checking a 3D file, in glTF format (.glb or .gltf), against a requirements schema definition in JSON. The schema file determines which of the checks, listed below, get run and what the passing values are. The result of each test is Pass, Fail, or Not Tested and some additional information may be available in a message.

This package can be used by both a command line interface (node), as well as a front-end web interface. The samples directory includes a command line interface (cli) as well as a web-based implementation to demonstrate how the package can be used in your own project.

Some of the checks can be SLOW for files with a lot of triangles. This is because the gltf format only stores geometry as individual triangles with independent vertices. If a test relies on shared edges, those edges have to be computed by checking each vertex's XYZ and/or UV location for a match. Beveled Edges and Non-Manifold edges both require XYZ edge computation. UV Gutter Width and UV Overlaps both require UV triangle computation. Each of those computations take about the same O(n log n) time, where n is the number of triangles. Typical run time without either of those computations is under 5 seconds, but if both types need to be run the test can take over a minute.

Checks available

• File Size
• Triangle Count
• Material Count
• Node Count
• Mesh Count
• Primitive Count
• Clean Origin for Root Node
• Beveled Edges (no hard edges >= 90 degrees) (SLOW)
• Non-Manifold Edges (SLOW)
• Dimensions
• Dimensions (product within tolerance)
• PBR Safe Colors
• Texture Map Resolution
• Texture Map Resolution Power of 2
• Texture Map Resolution Quadratic
• Texel Density
• 0-1 UV Texture Space
• Inverted UVs
• UV Overlaps (SLOW)
• UV Gutter Width (SLOW)

Example Implementations

There are two example implementations included:

• cli-example: Runs from a command line interface using Node.js
• web-example: Single page application that runs from the browser

Unit Tests

Unit tests can be run with

npm run test

Known Issues

• Files with draco mesh compression are not working - see: https://github.com/KhronosGroup/gltf-asset-auditor/issues/2

Product Info JSON file

For testing product dimensional tolerance, we need to know the dimensions of the product. The product info json file is used to provide that information. The product dimensions specified in the schema json file are different and more like a viewer bounding box check, but the percent tolerance value is used for both.

Schema JSON file

The schema is used to specify which checks are run and what the passing values are. Omitted values will use the default recommendations of the Khronos 3D Commerce Asset Creation Guidelines, which are set in Schema.ts. To turn off a test that would normally run by default, -1 should be specified for parameters of type number and false for booleans.

Version

version: string

This is the only required value. It corresponds to the version of this package and is used to identify which settings may be available. Features that were added after the version specified, starting with 1.0.0, will be turned off, rather than use default values.

File Size

fileSizeInKb?: { maximum?: number } (5120)

fileSizeInKb?: { minimum?: number } (1)

The size of the file in kilobytes.

Materials Count

materials?: { maximum?: number } (5)

materials?: { minimum?: number } (-1)

The number of all materials used in the entire file.

Model Attributes

_model?: {...}, _

This group of values is related to objects and geometry

Object Count

objectCount?: {...}

The number of objects can impact performance. Each primitive uses a separate draw call(s), based on the number of textures in its material.

---

nodes?: { maximum?: number } (-1)

nodes?: { minimum?: number } (-1)

Nodes establish parent / child structure between meshes.

---

meshes?: { maximum?: number } (-1)

meshes?: { minimum?: number } (-1)

Meshes are a groups of one or more primitives.

---

primitives?: { maximum?: number } (-1)

primitives?: { minimum?: number } (-1)

Primitives are collection of triangles that use one material.

---

Beveled Edges

requireBeveledEdges?: boolean (false)

Most objects in the real world do not have perfectly sharp edges, they are slightly rounded, so rendering non-beveled edges looks less realistic. This checks that the angle between all faces is greater than 90 degrees.

Clean Transform

requireCleanRootNodeTransform?: boolean (false)

The object's transform center should be (0,0,0), it's rotation should be (0,0,0) and it's scale should be (1,1,1).

Manifold Edges

requireManifoldEdges?: boolean (false)

Checks that all edges have 2 faces connected to them.

Triangle Count

triangles?: { maximum?: number } (100,000)

triangles?: { minimum?: number } (-1)

Specifies the range of number of triangles in the file.

Product Info

Dimensions

These dimensions can be thought of as a bounding box of what range a model size should fall within and is defined at the schema level, making it a test for all models. The test can help identify assets that are scaled incorrectly.

Dimensions provided separately with a product info json file are specific to a single model, which would likely come from an internal database. Both dimensional checks will use the percent tolerance value here to determine pass/fail.

product?: { dimensions?: { height?: { maximum?: number } } }

product?: { dimensions?: { height?: { minimum?: number } } }

product?: { dimensions?: { height?: { percentTolerance?: number } } }

---

product?: { dimensions?: { length?: { maximum?: number } } }

product?: { dimensions?: { length?: { minimum?: number } } }

product?: { dimensions?: { length?: { percentTolerance?: number } } }

---

product?: { dimensions?: { width?: { maximum?: number } } }

product?: { dimensions?: { width?: { minimum?: number } } }

product?: { dimensions?: { width?: { percentTolerance?: number } } }

Textures

textures?: {...}

Height

height?: { maximum?: number } (2048)

height?: { minimum?: number } (512)

The height of the texture maps.

PBR Color Range

pbrColorRange?: { maximum?: number } (243)

pbrColorRange?: { minimum?: number } (30)

The min/max luminosity value of every pixel in the base color texture images. For the rendering engine to be able to add or subtract light from the texture, additional headroom should be available.

Dimensions Power of Two

requireDimensionsBePowersOfTwo?: boolean (true)

For optimal processing on the GPU and for mip mapping, the file size should be a power of 2 (256, 512, 1024, 2048, 4096, ...)

Dimensions Quadratic

requireDimensionsBeQuadratic?: boolean (false)

When dimensions are quadratic, the height and width are the same.

Width

width?: { maximum?: number } (2048)

width?: { minimum?: number } (512)

The width of the texture maps.

UVs

uvs?: {...}

Gutter Width

gutterWidth?: { resolution256?: number }

gutterWidth?: { resolution512?: number }

gutterWidth?: { resolution1024?: number }

gutterWidth?: { resolution2048?: number }

gutterWidth?: { resolution4096?: number }

The gutter width is related to spacing between UV islands to prevent texture bleed when scaling to various resolutions, typically through mip mapping.

The number of pixels of padding required can be specified against various base resolutions. Only one of these needs to be specified and if there are more than one, the smallest computed grid size will be used. For example, specifying a value of 8 for resolution1024 yields grid size of 128, meaning that there needs to be at least 1px buffer between islands when resized to 128px. A value of 2 for resolution256 gives the same grid size of 128, whereas a value of 4 for resolution256 gives 64. If both resolution256: 4 and resolution1024: 8 are provided, the smaller grid size of 64px will be used for the test.

Not Inverted

requireNotInverted?: boolean (true)

UV faces should face upwards (wind in a clockwise direction)

Not Overlapping

requireNotOverlapping?: boolean (true)

UV triangles should not overlap

Texel Density

pixelsPerMeter?: { maximum?: number } (-1)

pixelsPerMeter?: { minimum?: number } (-1)

The min and max texel density of all triangles in the model based upon the largest and smallest texture sizes. This value is high when the UV area contains a lot of pixels that get squeezed into a small face and low when the UV area doesn't cover many pixels that get spread across a large face.

UVs in 0-1 Range

requireRangeZeroToOne?: boolean (false)

UV triangles should be in the 0-1 space when using atlas based textures that do not repeat, which is common practice for realtime assets.