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

package/src/gltf/create-scenegraph-from-gltf.ts

@@ -3,22 +3,44 @@
 // Copyright (c) vis.gl contributors
 
 import {Device} from '@luma.gl/core';
-import {GroupNode} from '@luma.gl/engine';
+import {GroupNode, Material} from '@luma.gl/engine';
 import {GLTFPostprocessed} from '@loaders.gl/gltf';
 import {Light} from '@luma.gl/shadertools';
 import {parseGLTF, type ParseGLTFOptions} from '../parsers/parse-gltf';
 import {parseGLTFLights} from '../parsers/parse-gltf-lights';
 import {GLTFAnimator} from './gltf-animator';
 import {parseGLTFAnimations} from '../parsers/parse-gltf-animations';
+import {getGLTFExtensionSupport, type GLTFExtensionSupport} from './gltf-extension-support';
+
+export type GLTFScenegraphBounds = {
+  /** World-space axis-aligned bounds for the scene or model. */
+  bounds: [[number, number, number], [number, number, number]] | null;
+  /** World-space center of the bounds. */
+  center: [number, number, number];
+  /** World-space bounds size on each axis. */
+  size: [number, number, number];
+  /** Half of the world-space bounds diagonal, clamped to a small practical minimum. */
+  radius: number;
+  /** Suggested orbit distance for a 60-degree field of view camera. */
+  recommendedOrbitDistance: number;
+};
 
 /** Scenegraph bundle returned from a parsed glTF asset. */
 export type GLTFScenegraphs = {
   /** Scene roots produced from the glTF scenes array. */
   scenes: GroupNode[];
+  /** Materials aligned with the source glTF `materials` array. */
+  materials: Material[];
   /** Animation controller for glTF animations. */
   animator: GLTFAnimator;
   /** Parsed punctual lights from the asset. */
   lights: Light[];
+  /** Extensions reported by the asset and whether luma.gl supports them. */
+  extensionSupport: Map<string, GLTFExtensionSupport>;
+  /** Camera-friendly bounds for each scene in `scenes`, in matching order. */
+  sceneBounds: GLTFScenegraphBounds[];
+  /** Combined camera-friendly bounds for the entire loaded asset. */
+  modelBounds: GLTFScenegraphBounds;
 
   /** Map from glTF mesh ids to generated mesh group nodes. */
   gltfMeshIdToNodeMap: Map<string, GroupNode>;
@@ -37,23 +59,92 @@ export function createScenegraphsFromGLTF(
   gltf: GLTFPostprocessed,
   options?: ParseGLTFOptions
 ): GLTFScenegraphs {
-  const {scenes, gltfMeshIdToNodeMap, gltfNodeIdToNodeMap, gltfNodeIndexToNodeMap} = parseGLTF(
-    device,
-    gltf,
-    options
-  );
+  const {scenes, materials, gltfMeshIdToNodeMap, gltfNodeIdToNodeMap, gltfNodeIndexToNodeMap} =
+    parseGLTF(device, gltf, options);
 
   const animations = parseGLTFAnimations(gltf);
   const animator = new GLTFAnimator({animations, gltfNodeIdToNodeMap});
   const lights = parseGLTFLights(gltf);
+  const extensionSupport = getGLTFExtensionSupport(gltf);
+  const sceneBounds = scenes.map(scene => getScenegraphBounds(scene.getBounds()));
+  const modelBounds = getCombinedScenegraphBounds(sceneBounds);
 
   return {
     scenes,
+    materials,
     animator,
     lights,
+    extensionSupport,
+    sceneBounds,
+    modelBounds,
     gltfMeshIdToNodeMap,
     gltfNodeIdToNodeMap,
     gltfNodeIndexToNodeMap,
     gltf
   };
 }
+
+function getScenegraphBounds(bounds: [number[], number[]] | null): GLTFScenegraphBounds {
+  if (!bounds) {
+    return {
+      bounds: null,
+      center: [0, 0, 0],
+      size: [0, 0, 0],
+      radius: 0.5,
+      recommendedOrbitDistance: 1
+    };
+  }
+
+  const normalizedBounds: [[number, number, number], [number, number, number]] = [
+    [bounds[0][0], bounds[0][1], bounds[0][2]],
+    [bounds[1][0], bounds[1][1], bounds[1][2]]
+  ];
+  const size: [number, number, number] = [
+    normalizedBounds[1][0] - normalizedBounds[0][0],
+    normalizedBounds[1][1] - normalizedBounds[0][1],
+    normalizedBounds[1][2] - normalizedBounds[0][2]
+  ];
+  const center: [number, number, number] = [
+    normalizedBounds[0][0] + size[0] * 0.5,
+    normalizedBounds[0][1] + size[1] * 0.5,
+    normalizedBounds[0][2] + size[2] * 0.5
+  ];
+  const maxHalfExtent = Math.max(size[0], size[1], size[2]) * 0.5;
+  const radius = Math.max(0.5 * Math.hypot(size[0], size[1], size[2]), 0.001);
+
+  return {
+    bounds: normalizedBounds,
+    center,
+    size,
+    radius,
+    recommendedOrbitDistance: Math.max(
+      (Math.max(maxHalfExtent, 0.001) / Math.tan(Math.PI / 6)) * 1.15,
+      radius * 1.1
+    )
+  };
+}
+
+function getCombinedScenegraphBounds(sceneBounds: GLTFScenegraphBounds[]): GLTFScenegraphBounds {
+  let combinedBounds: [[number, number, number], [number, number, number]] | null = null;
+
+  for (const sceneBoundInfo of sceneBounds) {
+    if (!sceneBoundInfo.bounds) {
+      continue;
+    }
+
+    if (!combinedBounds) {
+      combinedBounds = [
+        [...sceneBoundInfo.bounds[0]] as [number, number, number],
+        [...sceneBoundInfo.bounds[1]] as [number, number, number]
+      ];
+      continue;
+    }
+
+    for (let axis = 0; axis < 3; axis++) {
+      combinedBounds[0][axis] = Math.min(combinedBounds[0][axis], sceneBoundInfo.bounds[0][axis]);
+      combinedBounds[1][axis] = Math.max(combinedBounds[1][axis], sceneBoundInfo.bounds[1][axis]);
+    }
+  }
+
+  return getScenegraphBounds(combinedBounds);
+}

package/src/gltf/gltf-extension-support.ts

@@ -0,0 +1,214 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFPostprocessed} from '@loaders.gl/gltf';
+
+export type GLTFExtensionSupportLevel = 'built-in' | 'parsed-and-wired' | 'loader-only' | 'none';
+
+export type GLTFExtensionSupport = {
+  extensionName: string;
+  supported: boolean;
+  supportLevel: GLTFExtensionSupportLevel;
+  comment: string;
+};
+
+type GLTFExtensionSupportDefinition = Omit<GLTFExtensionSupport, 'extensionName' | 'supported'>;
+
+type GLTFPostprocessedWithRemovedExtensions = GLTFPostprocessed & {
+  extensionsRemoved?: string[];
+  lights?: unknown[];
+};
+
+const UNKNOWN_EXTENSION_SUPPORT: GLTFExtensionSupportDefinition = {
+  supportLevel: 'none',
+  comment: 'Not currently listed in the luma.gl glTF extension support registry.'
+};
+
+const GLTF_EXTENSION_SUPPORT_REGISTRY: Record<string, GLTFExtensionSupportDefinition> = {
+  KHR_draco_mesh_compression: {
+    supportLevel: 'built-in',
+    comment: 'Decoded by loaders.gl before luma.gl builds the scenegraph.'
+  },
+  EXT_meshopt_compression: {
+    supportLevel: 'built-in',
+    comment: 'Meshopt-compressed primitives are decoded during load.'
+  },
+  KHR_mesh_quantization: {
+    supportLevel: 'built-in',
+    comment: 'Quantized accessors are unpacked before geometry creation.'
+  },
+  KHR_lights_punctual: {
+    supportLevel: 'built-in',
+    comment: 'Parsed into luma.gl Light objects.'
+  },
+  KHR_materials_unlit: {
+    supportLevel: 'built-in',
+    comment: 'Unlit materials bypass the default lighting path.'
+  },
+  KHR_materials_emissive_strength: {
+    supportLevel: 'built-in',
+    comment: 'Applied by the stock PBR shader.'
+  },
+  KHR_texture_basisu: {
+    supportLevel: 'built-in',
+    comment: 'BasisU / KTX2 textures pass through when the device supports them.'
+  },
+  KHR_texture_transform: {
+    supportLevel: 'built-in',
+    comment: 'UV transforms are applied during load.'
+  },
+  EXT_texture_webp: {
+    supportLevel: 'loader-only',
+    comment:
+      'Texture source is resolved during load; final support depends on browser and device decode support.'
+  },
+  EXT_texture_avif: {
+    supportLevel: 'loader-only',
+    comment:
+      'Texture source is resolved during load; final support depends on browser and device decode support.'
+  },
+  KHR_materials_specular: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now applies specular factors and textures to the dielectric F0 term.'
+  },
+  KHR_materials_ior: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now drives dielectric reflectance from the glTF IOR value.'
+  },
+  KHR_materials_transmission: {
+    supportLevel: 'built-in',
+    comment:
+      'The stock shader now applies transmission to the base layer and exposes transparency through alpha, without a scene-color refraction buffer.'
+  },
+  KHR_materials_volume: {
+    supportLevel: 'built-in',
+    comment: 'Thickness and attenuation now tint transmitted light in the stock shader.'
+  },
+  KHR_materials_clearcoat: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now adds a secondary clearcoat specular lobe.'
+  },
+  KHR_materials_sheen: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now adds a sheen lobe for cloth-like materials.'
+  },
+  KHR_materials_iridescence: {
+    supportLevel: 'built-in',
+    comment:
+      'The stock shader now tints specular response with a view-dependent thin-film iridescence approximation.'
+  },
+  KHR_materials_anisotropy: {
+    supportLevel: 'built-in',
+    comment:
+      'The stock shader now shapes highlights and IBL response with an anisotropy-direction approximation.'
+  },
+  KHR_materials_pbrSpecularGlossiness: {
+    supportLevel: 'loader-only',
+    comment:
+      'Extension data can be loaded, but it is not translated into the default metallic-roughness material path.'
+  },
+  KHR_materials_variants: {
+    supportLevel: 'loader-only',
+    comment: 'Variant metadata can be loaded, but applications must choose and apply variants.'
+  },
+  EXT_mesh_gpu_instancing: {
+    supportLevel: 'none',
+    comment: 'GPU instancing data is not yet converted into luma.gl instanced draw setup.'
+  },
+  KHR_node_visibility: {
+    supportLevel: 'none',
+    comment: 'Node-visibility animations and toggles are not mapped onto runtime scenegraph state.'
+  },
+  KHR_animation_pointer: {
+    supportLevel: 'none',
+    comment: 'Animation pointers are not mapped onto runtime scenegraph updates.'
+  },
+  KHR_materials_diffuse_transmission: {
+    supportLevel: 'none',
+    comment: 'Diffuse-transmission shading is not implemented in the stock PBR shader.'
+  },
+  KHR_materials_dispersion: {
+    supportLevel: 'none',
+    comment: 'Chromatic dispersion is not implemented in the stock PBR shader.'
+  },
+  KHR_materials_volume_scatter: {
+    supportLevel: 'none',
+    comment: 'Volume scattering is not implemented in the stock PBR shader.'
+  },
+  KHR_xmp: {
+    supportLevel: 'none',
+    comment: 'Metadata payloads remain in the loaded glTF, but luma.gl does not interpret them.'
+  },
+  KHR_xmp_json_ld: {
+    supportLevel: 'none',
+    comment: 'Metadata is preserved in the glTF, but luma.gl does not interpret it.'
+  },
+  EXT_lights_image_based: {
+    supportLevel: 'none',
+    comment: 'Use loadPBREnvironment() or custom environment setup instead.'
+  },
+  EXT_texture_video: {
+    supportLevel: 'none',
+    comment: 'Video textures are not created automatically by the stock pipeline.'
+  },
+  MSFT_lod: {
+    supportLevel: 'none',
+    comment: 'Level-of-detail switching is not implemented in the stock scenegraph loader.'
+  }
+};
+
+export function getGLTFExtensionSupport(
+  gltf: GLTFPostprocessed
+): Map<string, GLTFExtensionSupport> {
+  const extensionNames = Array.from(collectGLTFExtensionNames(gltf)).sort();
+  const extensionSupportEntries: [string, GLTFExtensionSupport][] = extensionNames.map(
+    extensionName => {
+      const extensionSupportDefinition =
+        GLTF_EXTENSION_SUPPORT_REGISTRY[extensionName] || UNKNOWN_EXTENSION_SUPPORT;
+
+      return [
+        extensionName,
+        {
+          extensionName,
+          supported: extensionSupportDefinition.supportLevel === 'built-in',
+          supportLevel: extensionSupportDefinition.supportLevel,
+          comment: extensionSupportDefinition.comment
+        }
+      ];
+    }
+  );
+
+  return new Map(extensionSupportEntries);
+}
+
+function collectGLTFExtensionNames(gltf: GLTFPostprocessed): Set<string> {
+  const gltfWithRemovedExtensions = gltf as GLTFPostprocessedWithRemovedExtensions;
+  const extensionNames = new Set<string>();
+
+  addExtensionNames(extensionNames, gltf.extensionsUsed);
+  addExtensionNames(extensionNames, gltf.extensionsRequired);
+  addExtensionNames(extensionNames, gltfWithRemovedExtensions.extensionsRemoved);
+  addExtensionNames(extensionNames, Object.keys(gltf.extensions || {}));
+
+  if (gltfWithRemovedExtensions.lights?.length || gltf.nodes.some(node => 'light' in node)) {
+    extensionNames.add('KHR_lights_punctual');
+  }
+
+  if (
+    gltf.materials.some(material => {
+      const gltfMaterial = material as typeof material & {unlit?: boolean};
+      return gltfMaterial.unlit || gltfMaterial.extensions?.KHR_materials_unlit;
+    })
+  ) {
+    extensionNames.add('KHR_materials_unlit');
+  }
+
+  return extensionNames;
+}
+
+function addExtensionNames(extensionNames: Set<string>, newExtensionNames: string[] = []): void {
+  for (const extensionName of newExtensionNames) {
+    extensionNames.add(extensionName);
+  }
+}

package/src/index.ts

@@ -6,5 +6,14 @@ export {parsePBRMaterial, type ParsePBRMaterialOptions} from './parsers/parse-pb
 export {parseGLTFLights} from './parsers/parse-gltf-lights';
 
 // glTF Scenegraph Instantiator
-export {createScenegraphsFromGLTF, type GLTFScenegraphs} from './gltf/create-scenegraph-from-gltf';
+export {
+  createScenegraphsFromGLTF,
+  type GLTFScenegraphBounds,
+  type GLTFScenegraphs
+} from './gltf/create-scenegraph-from-gltf';
+export {
+  getGLTFExtensionSupport,
+  type GLTFExtensionSupport,
+  type GLTFExtensionSupportLevel
+} from './gltf/gltf-extension-support';
 export {GLTFAnimator} from './gltf/gltf-animator';

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

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {log} from '@luma.gl/core';
 import {type GLTFAccessorPostprocessed, type GLTFPostprocessed} from '@loaders.gl/gltf';
 import {
   GLTFAnimationPath,
@@ -18,32 +19,55 @@ export function parseGLTFAnimations(gltf: GLTFPostprocessed): GLTFAnimation[] {
   const accessorCache1D = new Map<GLTFAccessorPostprocessed, number[]>();
   const accessorCache2D = new Map<GLTFAccessorPostprocessed, number[][]>();
 
-  return gltfAnimations.map((animation, index) => {
+  return gltfAnimations.flatMap((animation, index) => {
     const name = animation.name || `Animation-${index}`;
-    const samplers: GLTFAnimationSampler[] = animation.samplers.map(
-      ({input, interpolation = 'LINEAR', output}) => ({
-        input: accessorToJsArray1D(gltf.accessors[input], accessorCache1D),
-        interpolation,
-        output: accessorToJsArray2D(gltf.accessors[output], accessorCache2D)
-      })
-    );
-
-    const channels: GLTFAnimationChannel[] = animation.channels.map(({sampler, target}) => {
+    const samplerCache = new Map<number, GLTFAnimationSampler>();
+    const channels: GLTFAnimationChannel[] = animation.channels.flatMap(({sampler, target}) => {
+      const path = getSupportedAnimationPath(target.path);
+      if (!path) {
+        return [];
+      }
+
       const targetNode = gltf.nodes[target.node ?? 0];
       if (!targetNode) {
         throw new Error(`Cannot find animation target ${target.node}`);
       }
+
+      let parsedSampler = samplerCache.get(sampler);
+      if (!parsedSampler) {
+        const gltfSampler = animation.samplers[sampler];
+        if (!gltfSampler) {
+          throw new Error(`Cannot find animation sampler ${sampler}`);
+        }
+        const {input, interpolation = 'LINEAR', output} = gltfSampler;
+        parsedSampler = {
+          input: accessorToJsArray1D(gltf.accessors[input], accessorCache1D),
+          interpolation,
+          output: accessorToJsArray2D(gltf.accessors[output], accessorCache2D)
+        };
+        samplerCache.set(sampler, parsedSampler);
+      }
+
       return {
-        sampler: samplers[sampler],
+        sampler: parsedSampler,
         targetNodeId: targetNode.id,
-        path: target.path as GLTFAnimationPath
+        path
       };
     });
 
-    return {name, channels};
+    return channels.length ? [{name, channels}] : [];
   });
 }
 
+function getSupportedAnimationPath(path: string): GLTFAnimationPath | null {
+  if (path === 'pointer') {
+    log.warn('KHR_animation_pointer channels are not supported and will be skipped')();
+    return null;
+  }
+
+  return path as GLTFAnimationPath;
+}
+
 /** Converts a scalar accessor into a cached JavaScript number array. */
 function accessorToJsArray1D(
   accessor: GLTFAccessorPostprocessed,
@@ -61,7 +85,7 @@ function accessorToJsArray1D(
   return result;
 }
 
-/** Converts a vector or matrix accessor into a cached JavaScript array-of-arrays. */
+/** Converts a scalar, vector, or matrix accessor into a cached JavaScript array-of-arrays. */
 function accessorToJsArray2D(
   accessor: GLTFAccessorPostprocessed,
   accessorCache: Map<GLTFAccessorPostprocessed, number[][]>
@@ -71,7 +95,7 @@ function accessorToJsArray2D(
   }
 
   const {typedArray: array, components} = accessorToTypedArray(accessor);
-  assert(components > 1, 'accessorToJsArray2D must have more than 1 component');
+  assert(components >= 1, 'accessorToJsArray2D must have at least 1 component');
 
   const result = [];
 

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

@@ -1,6 +1,8 @@
 import {Matrix4} from '@math.gl/core';
 import type {GLTFNodePostprocessed, GLTFPostprocessed} from '@loaders.gl/gltf';
-import type {DirectionalLight, Light, PointLight} from '@luma.gl/shadertools';
+import type {DirectionalLight, Light, PointLight, SpotLight} from '@luma.gl/shadertools';
+
+const GLTF_COLOR_FACTOR = 255;
 
 /** Parse KHR_lights_punctual extension into luma.gl light definitions */
 export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
@@ -13,6 +15,8 @@ export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
   }
 
   const lights: Light[] = [];
+  const parentNodeById = createParentNodeMap(gltf.nodes || []);
+  const worldMatrixByNodeId = new Map<string, Matrix4>();
 
   for (const node of gltf.nodes || []) {
     const lightIndex =
@@ -28,19 +32,22 @@ export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
       continue;
     }
 
-    const color = (gltfLight.color || [1, 1, 1]) as [number, number, number];
+    const color = normalizeGLTFLightColor(
+      (gltfLight.color || [1, 1, 1]) as [number, number, number]
+    );
     const intensity = gltfLight.intensity ?? 1;
     const range = gltfLight.range;
+    const worldMatrix = getNodeWorldMatrix(node, parentNodeById, worldMatrixByNodeId);
 
     switch (gltfLight.type) {
       case 'directional':
-        lights.push(parseDirectionalLight(node, color, intensity));
+        lights.push(parseDirectionalLight(worldMatrix, color, intensity));
         break;
       case 'point':
-        lights.push(parsePointLight(node, color, intensity, range));
+        lights.push(parsePointLight(worldMatrix, color, intensity, range));
         break;
       case 'spot':
-        lights.push(parsePointLight(node, color, intensity, range));
+        lights.push(parseSpotLight(worldMatrix, color, intensity, range, gltfLight.spot));
         break;
       default:
         // Unsupported light type
@@ -51,16 +58,23 @@ export function parseGLTFLights(gltf: GLTFPostprocessed): Light[] {
   return lights;
 }
 
+/**
+ * Converts glTF colors from the 0-1 spec range to luma.gl's 0-255 light convention.
+ */
+function normalizeGLTFLightColor(color: [number, number, number]): [number, number, number] {
+  return color.map(component => component * GLTF_COLOR_FACTOR) as [number, number, number];
+}
+
 /**
  * Converts a glTF punctual light attached to a node into a point light.
  */
 function parsePointLight(
-  node: GLTFNodePostprocessed,
+  worldMatrix: Matrix4,
   color: [number, number, number],
   intensity: number,
   range?: number
 ): PointLight {
-  const position = getNodePosition(node);
+  const position = getLightPosition(worldMatrix);
 
   let attenuation: Readonly<[number, number, number]> = [1, 0, 0];
   if (range !== undefined && range > 0) {
@@ -80,11 +94,11 @@ function parsePointLight(
  * Converts a glTF punctual light attached to a node into a directional light.
  */
 function parseDirectionalLight(
-  node: GLTFNodePostprocessed,
+  worldMatrix: Matrix4,
   color: [number, number, number],
   intensity: number
 ): DirectionalLight {
-  const direction = getNodeDirection(node);
+  const direction = getLightDirection(worldMatrix);
 
   return {
     type: 'directional',
@@ -95,35 +109,110 @@ function parseDirectionalLight(
 }
 
 /**
- * Resolves the world-space position of a glTF node from its matrix or translation.
+ * Converts a glTF punctual light attached to a node into a spot light.
  */
-function getNodePosition(node: GLTFNodePostprocessed): [number, number, number] {
-  if (node.matrix) {
-    return new Matrix4(node.matrix).transformAsPoint([0, 0, 0]) as [number, number, number];
+function parseSpotLight(
+  worldMatrix: Matrix4,
+  color: [number, number, number],
+  intensity: number,
+  range?: number,
+  spot: {innerConeAngle?: number; outerConeAngle?: number} = {}
+): SpotLight {
+  const position = getLightPosition(worldMatrix);
+  const direction = getLightDirection(worldMatrix);
+
+  let attenuation: Readonly<[number, number, number]> = [1, 0, 0];
+  if (range !== undefined && range > 0) {
+    attenuation = [1, 0, 1 / (range * range)] as [number, number, number];
   }
 
-  if (node.translation) {
-    return [...node.translation] as [number, number, number];
+  return {
+    type: 'spot',
+    position,
+    direction,
+    color,
+    intensity,
+    attenuation,
+    innerConeAngle: spot.innerConeAngle ?? 0,
+    outerConeAngle: spot.outerConeAngle ?? Math.PI / 4
+  };
+}
+
+/**
+ * Builds a parent lookup so punctual lights can be resolved in world space.
+ */
+function createParentNodeMap(nodes: GLTFNodePostprocessed[]): Map<string, GLTFNodePostprocessed> {
+  const parentNodeById = new Map<string, GLTFNodePostprocessed>();
+
+  for (const node of nodes) {
+    for (const childNode of node.children || []) {
+      parentNodeById.set(childNode.id, node);
+    }
+  }
+
+  return parentNodeById;
+}
+
+/**
+ * Resolves a glTF node's world matrix from its local transform and parent chain.
+ */
+function getNodeWorldMatrix(
+  node: GLTFNodePostprocessed,
+  parentNodeById: Map<string, GLTFNodePostprocessed>,
+  worldMatrixByNodeId: Map<string, Matrix4>
+): Matrix4 {
+  const cachedWorldMatrix = worldMatrixByNodeId.get(node.id);
+  if (cachedWorldMatrix) {
+    return cachedWorldMatrix;
   }
 
-  return [0, 0, 0];
+  const localMatrix = getNodeLocalMatrix(node);
+  const parentNode = parentNodeById.get(node.id);
+  const worldMatrix = parentNode
+    ? new Matrix4(
+        getNodeWorldMatrix(parentNode, parentNodeById, worldMatrixByNodeId)
+      ).multiplyRight(localMatrix)
+    : localMatrix;
+
+  worldMatrixByNodeId.set(node.id, worldMatrix);
+  return worldMatrix;
 }
 
 /**
- * Resolves the forward direction of a glTF node from its matrix or rotation.
+ * Resolves a glTF node's local matrix from its matrix or TRS components.
  */
-function getNodeDirection(node: GLTFNodePostprocessed): [number, number, number] {
+function getNodeLocalMatrix(node: GLTFNodePostprocessed): Matrix4 {
   if (node.matrix) {
-    return new Matrix4(node.matrix).transformDirection([0, 0, -1]) as [number, number, number];
+    return new Matrix4(node.matrix);
+  }
+
+  const matrix = new Matrix4();
+
+  if (node.translation) {
+    matrix.translate(node.translation);
   }
 
   if (node.rotation) {
-    return new Matrix4().fromQuaternion(node.rotation).transformDirection([0, 0, -1]) as [
-      number,
-      number,
-      number
-    ];
+    matrix.multiplyRight(new Matrix4().fromQuaternion(node.rotation));
+  }
+
+  if (node.scale) {
+    matrix.scale(node.scale);
   }
 
-  return [0, 0, -1];
+  return matrix;
+}
+
+/**
+ * Resolves the world-space position of a glTF light node.
+ */
+function getLightPosition(worldMatrix: Matrix4): [number, number, number] {
+  return worldMatrix.transformAsPoint([0, 0, 0]) as [number, number, number];
+}
+
+/**
+ * Resolves the world-space forward direction of a glTF light node.
+ */
+function getLightDirection(worldMatrix: Matrix4): [number, number, number] {
+  return worldMatrix.transformDirection([0, 0, -1]) as [number, number, number];
 }