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

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

@@ -1,41 +1,53 @@
 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[] {
-  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 [];
   }
 
   const lights: Light[] = [];
+  const parentNodeById = createParentNodeMap(gltf.nodes || []);
+  const worldMatrixByNodeId = new Map<string, Matrix4>();
 
   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;
     }
 
-    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
@@ -46,15 +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: Readonly<[number, number, number]> = node.translation
-    ? ([...node.translation] as [number, number, number])
-    : ([0, 0, 0] as [number, number, number]);
+  const position = getLightPosition(worldMatrix);
 
   let attenuation: Readonly<[number, number, number]> = [1, 0, 0];
   if (range !== undefined && range > 0) {
@@ -70,17 +90,15 @@ 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 {
-  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 = getLightDirection(worldMatrix);
 
   return {
     type: 'directional',
@@ -89,3 +107,112 @@ function parseDirectionalLight(
     intensity
   };
 }
+
+/**
+ * Converts a glTF punctual light attached to a node into a spot light.
+ */
+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];
+  }
+
+  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;
+  }
+
+  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 a glTF node's local matrix from its matrix or TRS components.
+ */
+function getNodeLocalMatrix(node: GLTFNodePostprocessed): Matrix4 {
+  if (node.matrix) {
+    return new Matrix4(node.matrix);
+  }
+
+  const matrix = new Matrix4();
+
+  if (node.translation) {
+    matrix.translate(node.translation);
+  }
+
+  if (node.rotation) {
+    matrix.multiplyRight(new Matrix4().fromQuaternion(node.rotation));
+  }
+
+  if (node.scale) {
+    matrix.scale(node.scale);
+  }
+
+  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];
+}

package/src/parsers/parse-gltf.ts

@@ -3,26 +3,40 @@
 // Copyright (c) vis.gl contributors
 
 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 {
+  Geometry,
+  GeometryAttribute,
+  GroupNode,
+  Material,
+  MaterialFactory,
+  ModelNode,
+  type ModelProps
+} from '@luma.gl/engine';
+import {
+  type GLTFMaterialPostprocessed,
   type GLTFMeshPostprocessed,
   type GLTFNodePostprocessed,
   type GLTFPostprocessed
 } from '@loaders.gl/gltf';
-import {type GLTFScenePostprocessed} from '@loaders.gl/gltf/dist/lib/types/gltf-postprocessed-schema';
+import {pbrMaterial} from '@luma.gl/shadertools';
 
 import {type PBREnvironment} from '../pbr/pbr-environment';
 import {convertGLDrawModeToTopology} from '../webgl-to-webgpu/convert-webgl-topology';
-import {createGLTFModel} from '../gltf/create-gltf-model';
+import {createGLTFMaterial, 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,107 +55,166 @@ 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)
+  options: ParseGLTFOptions = {}
+): {
+  /** Scene roots generated from `gltf.scenes`. */
+  scenes: GroupNode[];
+  /** Materials aligned with the source `gltf.materials` array. */
+  materials: Material[];
+  /** 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 materialFactory = new MaterialFactory(device, {modules: [pbrMaterial]});
+  const materials = (gltf.materials || []).map((gltfMaterial, materialIndex) =>
+    createGLTFMaterial(device, {
+      id: getGLTFMaterialId(gltfMaterial, materialIndex),
+      parsedPPBRMaterial: parsePBRMaterial(
+        device,
+        gltfMaterial as any,
+        {},
+        {
+          ...combinedOptions,
+          gltf,
+          validateAttributes: false
+        }
+      ),
+      materialFactory
+    })
   );
-  return sceneNodes;
-}
+  const gltfMaterialIdToMaterialMap = new Map<string, Material>();
+  (gltf.materials || []).forEach((gltfMaterial, materialIndex) => {
+    gltfMaterialIdToMaterialMap.set(gltfMaterial.id, materials[materialIndex]);
+  });
 
-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 gltfMeshIdToNodeMap = new Map<string, GroupNode>();
+  gltf.meshes.forEach((gltfMesh, idx) => {
+    const newMesh = createNodeForGLTFMesh(
+      device,
+      gltfMesh,
+      gltf,
+      gltfMaterialIdToMaterialMap,
+      combinedOptions
+    );
+    gltfMeshIdToNodeMap.set(gltfMesh.id, newMesh);
   });
-  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));
+  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);
+  });
 
-    // Node can have children nodes and meshes at the same time
+  // 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;
+      })
+    );
+
+    // 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 gltfNode._node;
+  return {scenes, materials, gltfMeshIdToNodeMap, gltfNodeIdToNodeMap, gltfNodeIndexToNodeMap};
 }
 
-function createMesh(
+/** Creates a `GroupNode` for one glTF node transform. */
+function createNodeForGLTFNode(
   device: Device,
-  gltfMesh: GLTFMeshPostprocessed & {_mesh?: GroupNode},
+  gltfNode: GLTFNodePostprocessed,
   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;
-  }
-
-  return gltfMesh._mesh;
+  return new GroupNode({
+    id: gltfNode.name || gltfNode.id,
+    children: [],
+    matrix: gltfNode.matrix,
+    position: gltfNode.translation,
+    rotation: gltfNode.rotation,
+    scale: gltfNode.scale
+  });
 }
 
-function createPrimitive(
+/** Creates a mesh group node containing one model node per glTF primitive. */
+function createNodeForGLTFMesh(
   device: Device,
-  gltfPrimitive: any,
-  i: number,
   gltfMesh: GLTFMeshPostprocessed,
+  gltf: GLTFPostprocessed,
+  gltfMaterialIdToMaterialMap: Map<string, Material>,
   options: Required<ParseGLTFOptions>
-): ModelNode {
-  const id = gltfPrimitive.name || `${gltfMesh.name || gltfMesh.id}-primitive-${i}`;
+): GroupNode {
+  const gltfPrimitives = gltfMesh.primitives || [];
+  const primitives = gltfPrimitives.map((gltfPrimitive, i) =>
+    createNodeForGLTFPrimitive({
+      device,
+      gltfPrimitive,
+      primitiveIndex: i,
+      gltfMesh,
+      gltf,
+      gltfMaterialIdToMaterialMap,
+      options
+    })
+  );
+  const mesh = new GroupNode({
+    id: gltfMesh.name || gltfMesh.id,
+    children: primitives
+  });
+
+  return mesh;
+}
+
+/** Input options for creating one renderable glTF primitive model node. */
+type CreateNodeForGLTFPrimitiveOptions = {
+  device: Device;
+  gltfPrimitive: any;
+  primitiveIndex: number;
+  gltfMesh: GLTFMeshPostprocessed;
+  gltf: GLTFPostprocessed;
+  gltfMaterialIdToMaterialMap: Map<string, Material>;
+  options: Required<ParseGLTFOptions>;
+};
+
+/** Creates a renderable model node for one glTF primitive. */
+function createNodeForGLTFPrimitive({
+  device,
+  gltfPrimitive,
+  primitiveIndex,
+  gltfMesh,
+  gltf,
+  gltfMaterialIdToMaterialMap,
+  options
+}: CreateNodeForGLTFPrimitiveOptions): ModelNode {
+  const id = gltfPrimitive.name || `${gltfMesh.name || gltfMesh.id}-primitive-${primitiveIndex}`;
   const topology = convertGLDrawModeToTopology(gltfPrimitive.mode || 4);
   const vertexCount = gltfPrimitive.indices
     ? gltfPrimitive.indices.count
@@ -149,16 +222,17 @@ function createPrimitive(
 
   const geometry = createGeometry(id, gltfPrimitive, topology);
 
-  const parsedPPBRMaterial = parsePBRMaterial(
-    device,
-    gltfPrimitive.material,
-    geometry.attributes,
-    options
-  );
+  const parsedPPBRMaterial = parsePBRMaterial(device, gltfPrimitive.material, geometry.attributes, {
+    ...options,
+    gltf
+  });
 
   const modelNode = createGLTFModel(device, {
     id,
     geometry: createGeometry(id, gltfPrimitive, topology),
+    material: gltfPrimitive.material
+      ? gltfMaterialIdToMaterialMap.get(gltfPrimitive.material.id) || null
+      : null,
     parsedPPBRMaterial,
     modelOptions: options.modelOptions,
     vertexCount
@@ -171,10 +245,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)) {
@@ -190,3 +266,7 @@ function createGeometry(id: string, gltfPrimitive: any, topology: PrimitiveTopol
     attributes
   });
 }
+
+function getGLTFMaterialId(gltfMaterial: GLTFMaterialPostprocessed, materialIndex: number): string {
+  return gltfMaterial.name || gltfMaterial.id || `material-${materialIndex}`;
+}