@luma.gl/gltf 9.3.0-alpha.4 → 9.3.0-alpha.6

package/src/gltf/gltf-animator.ts

@@ -2,32 +2,47 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {GLTFNodePostprocessed} from '@loaders.gl/gltf';
 import {log} from '@luma.gl/core';
 import {GroupNode} from '@luma.gl/engine';
-import {Matrix4} from '@math.gl/core';
 import {GLTFAnimation} from './animations/animations';
 import {interpolate} from './animations/interpolate';
 
+/** Construction props for a single glTF animation controller. */
 type GLTFSingleAnimatorProps = {
+  /** Animation data to evaluate. */
   animation: GLTFAnimation;
+  /** Mapping from glTF node ids to scenegraph nodes. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
+  /** Start time in seconds. */
   startTime?: number;
+  /** Whether playback is active. */
   playing?: boolean;
+  /** Playback speed multiplier. */
   speed?: number;
 };
 
+/** Evaluates one glTF animation against the generated scenegraph. */
 class GLTFSingleAnimator {
+  /** Animation definition being played. */
   animation: GLTFAnimation;
+  /** Target scenegraph lookup table. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
+  /** Playback start time in seconds. */
   startTime: number = 0;
+  /** Whether playback is currently enabled. */
   playing: boolean = true;
+  /** Playback speed multiplier. */
   speed: number = 1;
 
+  /** Creates a single-animation controller. */
   constructor(props: GLTFSingleAnimatorProps) {
     this.animation = props.animation;
+    this.gltfNodeIdToNodeMap = props.gltfNodeIdToNodeMap;
     this.animation.name ||= 'unnamed';
     Object.assign(this, props);
   }
 
+  /** Advances the animation to the supplied wall-clock time in milliseconds. */
   setTime(timeMs: number) {
     if (!this.playing) {
       return;
@@ -36,24 +51,36 @@ class GLTFSingleAnimator {
     const absTime = timeMs / 1000;
     const time = (absTime - this.startTime) * this.speed;
 
-    this.animation.channels.forEach(({sampler, target, path}) => {
-      interpolate(time, sampler, target, path);
-      applyTranslationRotationScale(target, (target as any)._node as GroupNode);
+    this.animation.channels.forEach(({sampler, targetNodeId, path}) => {
+      const targetNode = this.gltfNodeIdToNodeMap.get(targetNodeId);
+      if (!targetNode) {
+        throw new Error(`Cannot find animation target node ${targetNodeId}`);
+      }
+
+      interpolate(time, sampler, targetNode, path);
     });
   }
 }
 
+/** Construction props for {@link GLTFAnimator}. */
 export type GLTFAnimatorProps = {
+  /** Parsed animations from the source glTF. */
   animations: GLTFAnimation[];
+  /** Mapping from glTF node ids to scenegraph nodes. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
 };
 
+/** Coordinates playback of every animation found in a glTF scene. */
 export class GLTFAnimator {
+  /** Individual animation controllers. */
   animations: GLTFSingleAnimator[];
 
+  /** Creates an animator for the supplied glTF scenegraph. */
   constructor(props: GLTFAnimatorProps) {
     this.animations = props.animations.map((animation, index) => {
       const name = animation.name || `Animation-${index}`;
       return new GLTFSingleAnimator({
+        gltfNodeIdToNodeMap: props.gltfNodeIdToNodeMap,
         animation: {name, channels: animation.channels}
       });
     });
@@ -65,31 +92,13 @@ export class GLTFAnimator {
     this.setTime(time);
   }
 
+  /** Advances every animation to the supplied wall-clock time in milliseconds. */
   setTime(time: number): void {
     this.animations.forEach(animation => animation.setTime(time));
   }
 
+  /** Returns the per-animation controllers managed by this animator. */
   getAnimations() {
     return this.animations;
   }
 }
-
-// TODO: share with GLTFInstantiator
-const scratchMatrix = new Matrix4();
-
-function applyTranslationRotationScale(gltfNode: GLTFNodePostprocessed, node: GroupNode) {
-  node.matrix.identity();
-
-  if (gltfNode.translation) {
-    node.matrix.translate(gltfNode.translation);
-  }
-
-  if (gltfNode.rotation) {
-    const rotationMatrix = scratchMatrix.fromQuaternion(gltfNode.rotation);
-    node.matrix.multiplyRight(rotationMatrix);
-  }
-
-  if (gltfNode.scale) {
-    node.matrix.scale(gltfNode.scale);
-  }
-}

package/src/index.ts

@@ -3,9 +3,8 @@
 export {loadPBREnvironment, type PBREnvironment} from './pbr/pbr-environment';
 export {type ParsedPBRMaterial} from './pbr/pbr-material';
 export {parsePBRMaterial, type ParsePBRMaterialOptions} from './parsers/parse-pbr-material';
-export {} from './pbr/pbr-environment';
 export {parseGLTFLights} from './parsers/parse-gltf-lights';
 
 // glTF Scenegraph Instantiator
-export {createScenegraphsFromGLTF} from './gltf/create-scenegraph-from-gltf';
+export {createScenegraphsFromGLTF, type GLTFScenegraphs} from './gltf/create-scenegraph-from-gltf';
 export {GLTFAnimator} from './gltf/gltf-animator';

package/src/parsers/parse-gltf-animations.ts

@@ -4,6 +4,7 @@
 
 import {type GLTFAccessorPostprocessed, type GLTFPostprocessed} from '@loaders.gl/gltf';
 import {
+  GLTFAnimationPath,
   type GLTFAnimation,
   type GLTFAnimationChannel,
   type GLTFAnimationSampler
@@ -11,45 +12,81 @@ import {
 
 import {accessorToTypedArray} from '..//webgl-to-webgpu/convert-webgl-attribute';
 
+/** Parses glTF animation records into the runtime animation model used by `GLTFAnimator`. */
 export function parseGLTFAnimations(gltf: GLTFPostprocessed): GLTFAnimation[] {
   const gltfAnimations = gltf.animations || [];
+  const accessorCache1D = new Map<GLTFAccessorPostprocessed, number[]>();
+  const accessorCache2D = new Map<GLTFAccessorPostprocessed, number[][]>();
+
   return gltfAnimations.map((animation, index) => {
     const name = animation.name || `Animation-${index}`;
     const samplers: GLTFAnimationSampler[] = animation.samplers.map(
       ({input, interpolation = 'LINEAR', output}) => ({
-        input: accessorToJsArray(gltf.accessors[input]) as number[],
+        input: accessorToJsArray1D(gltf.accessors[input], accessorCache1D),
         interpolation,
-        output: accessorToJsArray(gltf.accessors[output])
+        output: accessorToJsArray2D(gltf.accessors[output], accessorCache2D)
       })
     );
-    const channels: GLTFAnimationChannel[] = animation.channels.map(({sampler, target}) => ({
-      sampler: samplers[sampler],
-      target: gltf.nodes[target.node ?? 0],
-      path: target.path as GLTFAnimationChannel['path']
-    }));
+
+    const channels: GLTFAnimationChannel[] = animation.channels.map(({sampler, target}) => {
+      const targetNode = gltf.nodes[target.node ?? 0];
+      if (!targetNode) {
+        throw new Error(`Cannot find animation target ${target.node}`);
+      }
+      return {
+        sampler: samplers[sampler],
+        targetNodeId: targetNode.id,
+        path: target.path as GLTFAnimationPath
+      };
+    });
+
     return {name, channels};
   });
 }
 
-//
-
-function accessorToJsArray(
-  accessor: GLTFAccessorPostprocessed & {_animation?: number[] | number[][]}
-): number[] | number[][] {
-  if (!accessor._animation) {
-    const {typedArray: array, components} = accessorToTypedArray(accessor);
-
-    if (components === 1) {
-      accessor._animation = Array.from(array);
-    } else {
-      // Slice array
-      const slicedArray: number[][] = [];
-      for (let i = 0; i < array.length; i += components) {
-        slicedArray.push(Array.from(array.slice(i, i + components)));
-      }
-      accessor._animation = slicedArray;
-    }
+/** Converts a scalar accessor into a cached JavaScript number array. */
+function accessorToJsArray1D(
+  accessor: GLTFAccessorPostprocessed,
+  accessorCache: Map<GLTFAccessorPostprocessed, number[]>
+): number[] {
+  if (accessorCache.has(accessor)) {
+    return accessorCache.get(accessor)!;
   }
 
-  return accessor._animation;
+  const {typedArray: array, components} = accessorToTypedArray(accessor);
+  assert(components === 1, 'accessorToJsArray1D must have exactly 1 component');
+  const result = Array.from(array);
+
+  accessorCache.set(accessor, result);
+  return result;
+}
+
+/** Converts a vector or matrix accessor into a cached JavaScript array-of-arrays. */
+function accessorToJsArray2D(
+  accessor: GLTFAccessorPostprocessed,
+  accessorCache: Map<GLTFAccessorPostprocessed, number[][]>
+): number[][] {
+  if (accessorCache.has(accessor)) {
+    return accessorCache.get(accessor)!;
+  }
+
+  const {typedArray: array, components} = accessorToTypedArray(accessor);
+  assert(components > 1, 'accessorToJsArray2D must have more than 1 component');
+
+  const result = [];
+
+  // Slice array
+  for (let i = 0; i < array.length; i += components) {
+    result.push(Array.from(array.slice(i, i + components)));
+  }
+
+  accessorCache.set(accessor, result);
+  return result;
+}
+
+/** Throws when the supplied condition is false. */
+function assert(condition: boolean, message?: string): asserts condition {
+  if (!condition) {
+    throw new Error(message);
+  }
 }

package/src/parsers/parse-gltf-lights.ts

@@ -4,7 +4,10 @@ import type {DirectionalLight, Light, PointLight} from '@luma.gl/shadertools';
 
 /** Parse KHR_lights_punctual extension into luma.gl light definitions */
 export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
-  const lightDefs = gltf.extensions?.['KHR_lights_punctual']?.['lights'];
+  const lightDefs =
+    // `postProcessGLTF()` moves KHR_lights_punctual into `gltf.lights`.
+    (gltf as GLTFPostprocessed & {lights?: any[]}).lights ||
+    gltf.extensions?.['KHR_lights_punctual']?.['lights'];
   if (!lightDefs || !Array.isArray(lightDefs) || lightDefs.length === 0) {
     return [];
   }
@@ -12,12 +15,14 @@ export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
   const lights: Light[] = [];
 
   for (const node of gltf.nodes || []) {
-    const nodeLight = node.extensions?.KHR_lights_punctual;
-    if (!nodeLight || typeof nodeLight.light !== 'number') {
+    const lightIndex =
+      (node as GLTFNodePostprocessed & {light?: number}).light ??
+      node.extensions?.KHR_lights_punctual?.light;
+    if (typeof lightIndex !== 'number') {
       // eslint-disable-next-line no-continue
       continue;
     }
-    const gltfLight = lightDefs[nodeLight.light];
+    const gltfLight = lightDefs[lightIndex];
     if (!gltfLight) {
       // eslint-disable-next-line no-continue
       continue;
@@ -46,15 +51,16 @@ export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
   return lights;
 }
 
+/**
+ * Converts a glTF punctual light attached to a node into a point light.
+ */
 function parsePointLight(
   node: GLTFNodePostprocessed,
   color: [number, number, number],
   intensity: number,
   range?: number
 ): PointLight {
-  const position: Readonly<[number, number, number]> = node.translation
-    ? ([...node.translation] as [number, number, number])
-    : ([0, 0, 0] as [number, number, number]);
+  const position = getNodePosition(node);
 
   let attenuation: Readonly<[number, number, number]> = [1, 0, 0];
   if (range !== undefined && range > 0) {
@@ -70,17 +76,15 @@ function parsePointLight(
   };
 }
 
+/**
+ * Converts a glTF punctual light attached to a node into a directional light.
+ */
 function parseDirectionalLight(
   node: GLTFNodePostprocessed,
   color: [number, number, number],
   intensity: number
 ): DirectionalLight {
-  let direction: [number, number, number] = [0, 0, -1];
-
-  if (node.rotation) {
-    const orientation = new Matrix4().fromQuaternion(node.rotation);
-    direction = orientation.transformDirection([0, 0, -1]) as [number, number, number];
-  }
+  const direction = getNodeDirection(node);
 
   return {
     type: 'directional',
@@ -89,3 +93,37 @@ function parseDirectionalLight(
     intensity
   };
 }
+
+/**
+ * Resolves the world-space position of a glTF node from its matrix or translation.
+ */
+function getNodePosition(node: GLTFNodePostprocessed): [number, number, number] {
+  if (node.matrix) {
+    return new Matrix4(node.matrix).transformAsPoint([0, 0, 0]) as [number, number, number];
+  }
+
+  if (node.translation) {
+    return [...node.translation] as [number, number, number];
+  }
+
+  return [0, 0, 0];
+}
+
+/**
+ * Resolves the forward direction of a glTF node from its matrix or rotation.
+ */
+function getNodeDirection(node: GLTFNodePostprocessed): [number, number, number] {
+  if (node.matrix) {
+    return new Matrix4(node.matrix).transformDirection([0, 0, -1]) as [number, number, number];
+  }
+
+  if (node.rotation) {
+    return new Matrix4().fromQuaternion(node.rotation).transformDirection([0, 0, -1]) as [
+      number,
+      number,
+      number
+    ];
+  }
+
+  return [0, 0, -1];
+}

package/src/parsers/parse-gltf.ts

@@ -4,13 +4,11 @@
 
 import {Device, type PrimitiveTopology} from '@luma.gl/core';
 import {Geometry, GeometryAttribute, GroupNode, ModelNode, type ModelProps} from '@luma.gl/engine';
-import {Matrix4} from '@math.gl/core';
 import {
   type GLTFMeshPostprocessed,
   type GLTFNodePostprocessed,
   type GLTFPostprocessed
 } from '@loaders.gl/gltf';
-import {type GLTFScenePostprocessed} from '@loaders.gl/gltf/dist/lib/types/gltf-postprocessed-schema';
 
 import {type PBREnvironment} from '../pbr/pbr-environment';
 import {convertGLDrawModeToTopology} from '../webgl-to-webgpu/convert-webgl-topology';
@@ -18,11 +16,17 @@ import {createGLTFModel} from '../gltf/create-gltf-model';
 
 import {parsePBRMaterial} from './parse-pbr-material';
 
+/** Options that influence how a post-processed glTF is turned into a luma.gl scenegraph. */
 export type ParseGLTFOptions = {
+  /** Additional model props applied to each generated primitive model. */
   modelOptions?: Partial<ModelProps>;
+  /** Enables shader-level PBR debug output. */
   pbrDebug?: boolean;
+  /** Optional image-based lighting environment. */
   imageBasedLightingEnvironment?: PBREnvironment;
+  /** Enables punctual light extraction. */
   lights?: boolean;
+  /** Enables tangent usage when available. */
   useTangents?: boolean;
 };
 
@@ -41,100 +45,107 @@ const defaultOptions: Required<ParseGLTFOptions> = {
 export function parseGLTF(
   device: Device,
   gltf: GLTFPostprocessed,
-  options_: ParseGLTFOptions = {}
-): GroupNode[] {
-  const options = {...defaultOptions, ...options_};
-  const sceneNodes = gltf.scenes.map(gltfScene =>
-    createScene(device, gltfScene, gltf.nodes, options)
-  );
-  return sceneNodes;
-}
+  options: ParseGLTFOptions = {}
+): {
+  /** Scene roots generated from `gltf.scenes`. */
+  scenes: GroupNode[];
+  /** Map from glTF mesh ids to generated mesh group nodes. */
+  gltfMeshIdToNodeMap: Map<string, GroupNode>;
+  /** Map from glTF node indices to generated scenegraph nodes. */
+  gltfNodeIndexToNodeMap: Map<number, GroupNode>;
+  /** Map from glTF node ids to generated scenegraph nodes. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
+} {
+  const combinedOptions = {...defaultOptions, ...options};
+
+  const gltfMeshIdToNodeMap = new Map<string, GroupNode>();
+  gltf.meshes.forEach((gltfMesh, idx) => {
+    const newMesh = createNodeForGLTFMesh(device, gltfMesh, combinedOptions);
+    gltfMeshIdToNodeMap.set(gltfMesh.id, newMesh);
+  });
 
-function createScene(
-  device: Device,
-  gltfScene: GLTFScenePostprocessed,
-  gltfNodes: GLTFNodePostprocessed[],
-  options: Required<ParseGLTFOptions>
-): GroupNode {
-  const gltfSceneNodes = gltfScene.nodes || [];
-  const nodes = gltfSceneNodes.map(node => createNode(device, node, gltfNodes, options));
-  const sceneNode = new GroupNode({
-    id: gltfScene.name || gltfScene.id,
-    children: nodes
+  const gltfNodeIndexToNodeMap = new Map<number, GroupNode>();
+  const gltfNodeIdToNodeMap = new Map<string, GroupNode>();
+  // Step 1/2: Generate a GroupNode for each gltf node. (1:1 mapping).
+  gltf.nodes.forEach((gltfNode, idx) => {
+    const newNode = createNodeForGLTFNode(device, gltfNode, combinedOptions);
+    gltfNodeIndexToNodeMap.set(idx, newNode);
+    gltfNodeIdToNodeMap.set(gltfNode.id, newNode);
   });
-  return sceneNode;
-}
 
-function createNode(
-  device: Device,
-  gltfNode: GLTFNodePostprocessed & {_node?: GroupNode},
-  gltfNodes: GLTFNodePostprocessed[],
-  options: Required<ParseGLTFOptions>
-): GroupNode {
-  if (!gltfNode._node) {
-    const gltfChildren = gltfNode.children || [];
-    const children = gltfChildren.map(child => createNode(device, child, gltfNodes, options));
+  // Step 2/2: Go though each gltf node and attach the children.
+  // This guarantees that each gltf node will have exactly one luma GroupNode.
+  gltf.nodes.forEach((gltfNode, idx) => {
+    gltfNodeIndexToNodeMap.get(idx)!.add(
+      (gltfNode.children ?? []).map(({id}) => {
+        const child = gltfNodeIdToNodeMap.get(id);
+        if (!child) throw new Error(`Cannot find child ${id} of node ${idx}`);
+        return child;
+      })
+    );
 
-    // Node can have children nodes and meshes at the same time
+    // Nodes can have children nodes and one optional child mesh at the same time.
     if (gltfNode.mesh) {
-      children.push(createMesh(device, gltfNode.mesh, options));
+      const mesh = gltfMeshIdToNodeMap.get(gltfNode.mesh.id);
+      if (!mesh) {
+        throw new Error(`Cannot find mesh child ${gltfNode.mesh.id} of node ${idx}`);
+      }
+      gltfNodeIndexToNodeMap.get(idx)!.add(mesh);
     }
+  });
 
-    const node = new GroupNode({
-      id: gltfNode.name || gltfNode.id,
+  const scenes = gltf.scenes.map(gltfScene => {
+    const children = (gltfScene.nodes || []).map(({id}) => {
+      const child = gltfNodeIdToNodeMap.get(id);
+      if (!child)
+        throw new Error(`Cannot find child ${id} of scene ${gltfScene.name || gltfScene.id}`);
+      return child;
+    });
+    return new GroupNode({
+      id: gltfScene.name || gltfScene.id,
       children
     });
+  });
 
-    if (gltfNode.matrix) {
-      node.setMatrix(gltfNode.matrix);
-    } else {
-      node.matrix.identity();
-
-      if (gltfNode.translation) {
-        node.matrix.translate(gltfNode.translation);
-      }
-
-      if (gltfNode.rotation) {
-        const rotationMatrix = new Matrix4().fromQuaternion(gltfNode.rotation);
-        node.matrix.multiplyRight(rotationMatrix);
-      }
-
-      if (gltfNode.scale) {
-        node.matrix.scale(gltfNode.scale);
-      }
-    }
-    gltfNode._node = node;
-  }
-
-  // Copy _node so that gltf-animator can access
-  const topLevelNode = gltfNodes.find(node => node.id === gltfNode.id) as any;
-  topLevelNode._node = gltfNode._node;
+  return {scenes, gltfMeshIdToNodeMap, gltfNodeIdToNodeMap, gltfNodeIndexToNodeMap};
+}
 
-  return gltfNode._node;
+/** Creates a `GroupNode` for one glTF node transform. */
+function createNodeForGLTFNode(
+  device: Device,
+  gltfNode: GLTFNodePostprocessed,
+  options: Required<ParseGLTFOptions>
+): GroupNode {
+  return new GroupNode({
+    id: gltfNode.name || gltfNode.id,
+    children: [],
+    matrix: gltfNode.matrix,
+    position: gltfNode.translation,
+    rotation: gltfNode.rotation,
+    scale: gltfNode.scale
+  });
 }
 
-function createMesh(
+/** Creates a mesh group node containing one model node per glTF primitive. */
+function createNodeForGLTFMesh(
   device: Device,
-  gltfMesh: GLTFMeshPostprocessed & {_mesh?: GroupNode},
+  gltfMesh: GLTFMeshPostprocessed,
   options: Required<ParseGLTFOptions>
 ): GroupNode {
-  // TODO: avoid changing the gltf
-  if (!gltfMesh._mesh) {
-    const gltfPrimitives = gltfMesh.primitives || [];
-    const primitives = gltfPrimitives.map((gltfPrimitive, i) =>
-      createPrimitive(device, gltfPrimitive, i, gltfMesh, options)
-    );
-    const mesh = new GroupNode({
-      id: gltfMesh.name || gltfMesh.id,
-      children: primitives
-    });
-    gltfMesh._mesh = mesh;
-  }
+  const gltfPrimitives = gltfMesh.primitives || [];
+  const primitives = gltfPrimitives.map((gltfPrimitive, i) =>
+    createNodeForGLTFPrimitive(device, gltfPrimitive, i, gltfMesh, options)
+  );
+  const mesh = new GroupNode({
+    id: gltfMesh.name || gltfMesh.id,
+    children: primitives
+  });
 
-  return gltfMesh._mesh;
+  return mesh;
 }
 
-function createPrimitive(
+/** Creates a renderable model node for one glTF primitive. */
+function createNodeForGLTFPrimitive(
   device: Device,
   gltfPrimitive: any,
   i: number,
@@ -171,10 +182,12 @@ function createPrimitive(
   return modelNode;
 }
 
+/** Computes the vertex count for a primitive without indices. */
 function getVertexCount(attributes: any) {
   throw new Error('getVertexCount not implemented');
 }
 
+/** Converts glTF primitive attributes and indices into a luma.gl `Geometry`. */
 function createGeometry(id: string, gltfPrimitive: any, topology: PrimitiveTopology): Geometry {
   const attributes: Record<string, GeometryAttribute> = {};
   for (const [attributeName, attribute] of Object.entries(gltfPrimitive.attributes)) {