@loaders.gl/scene 5.0.0-alpha.8 → 5.0.0-beta.1

package/src/gltf/lib/api/convert-gltf-v1-materials.ts

@@ -0,0 +1,351 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF} from '../types/gltf-types';
+import type {GLTFMaterial, GLTFTextureInfo} from '../types/gltf-json-schema';
+
+const COMMON_MATERIAL_EXTENSION = 'KHR_materials_common';
+const UNLIT_MATERIAL_EXTENSION = 'KHR_materials_unlit';
+
+/** Legacy programmable material properties retained as provenance after conversion. */
+type LegacyMaterial = GLTFMaterial & {
+  /** Optional fallback technique identifier. */
+  technique?: unknown;
+  /** Fallback shader uniform values. */
+  values?: unknown;
+};
+
+/** A validated legacy color or resolved texture, expressed without changing image bytes. */
+type MaterialValue = {
+  /** RGBA color, or a white multiplier for texture-only values. */
+  readonly factor: number[];
+  /** Resolved texture using the default coordinate set. */
+  readonly texture?: GLTFTextureInfo;
+};
+
+/** Convert conventional and common materials, returning overridden fallback technique IDs. */
+export function convertGLTFV1Materials(
+  json: GLTF,
+  reportUnsupported: (feature: string) => void,
+  reportNote: (message: string) => void
+): Set<string> {
+  const fallbackTechniques = new Set<string>();
+  const commonRequired = json.extensionsRequired?.includes(COMMON_MATERIAL_EXTENSION) || false;
+  for (const [materialIndex, material] of (json.materials || []).entries()) {
+    const legacyMaterial = material as LegacyMaterial;
+    const common = material.extensions?.[COMMON_MATERIAL_EXTENSION] as unknown;
+    if (common === undefined) {
+      convertConventionalMaterial(legacyMaterial, json, reportUnsupported, reportNote);
+      continue;
+    }
+    preserveMaterialSource(legacyMaterial, common);
+    const label = `material ${materialIndex}`;
+    if (
+      !isRecord(common) ||
+      typeof common.technique !== 'string' ||
+      !['CONSTANT', 'LAMBERT', 'PHONG', 'BLINN'].includes(common.technique)
+    ) {
+      reportUnsupported(`${label} unknown ${COMMON_MATERIAL_EXTENSION} technique`);
+      continue;
+    }
+    if (common.values !== undefined && !isRecord(common.values)) {
+      reportUnsupported(`${label} common material values must be an object`);
+      continue;
+    }
+    const values = (common.values || {}) as Record<string, unknown>;
+    const unknownFields = Object.keys(common).filter(
+      field => !['technique', 'values', 'doubleSided', 'transparent', 'jointCount'].includes(field)
+    );
+    const unknownValues = Object.keys(values).filter(
+      field =>
+        ![
+          'ambient',
+          'diffuse',
+          'emission',
+          'specular',
+          'shininess',
+          'transparency',
+          'doubleSided',
+          'transparent'
+        ].includes(field)
+    );
+    if (unknownFields.length || unknownValues.length)
+      reportUnsupported(
+        `${label} unrecognized common material fields ${[...unknownFields, ...unknownValues].join(', ')}`
+      );
+    if (
+      common.jointCount !== undefined &&
+      (!Number.isSafeInteger(common.jointCount) || Number(common.jointCount) < 0)
+    )
+      reportUnsupported(`${label} invalid common material jointCount`);
+    const emission = readMaterialValue(
+      values.emission,
+      json,
+      `${label} emission`,
+      reportUnsupported
+    );
+    const constant = common.technique === 'CONSTANT';
+    const diffuse = constant
+      ? emission
+      : readMaterialValue(values.diffuse, json, `${label} diffuse`, reportUnsupported);
+    const opacity = values.transparency === undefined ? 1 : values.transparency;
+    const validOpacity =
+      typeof opacity === 'number' && Number.isFinite(opacity) && opacity >= 0 && opacity <= 1;
+    if (!validOpacity) reportUnsupported(`${label} common material transparency must be in [0, 1]`);
+    const transparent = readCommonFlag(common, values, 'transparent', label, reportUnsupported);
+    const doubleSided = readCommonFlag(common, values, 'doubleSided', label, reportUnsupported);
+    if (values.ambient !== undefined && !isBlackColor(values.ambient))
+      reportUnsupported(`${label} ambient lighting`);
+    if (['PHONG', 'BLINN'].includes(String(common.technique))) {
+      if (values.specular !== undefined && !isBlackColor(values.specular))
+        reportUnsupported(`${label} specular/shininess lighting`);
+      if (
+        values.shininess !== undefined &&
+        (typeof values.shininess !== 'number' ||
+          !Number.isFinite(values.shininess) ||
+          values.shininess < 0)
+      )
+        reportUnsupported(`${label} invalid common material shininess`);
+    }
+    material.pbrMetallicRoughness ||= {};
+    const physicallyBasedMaterial = material.pbrMetallicRoughness;
+    physicallyBasedMaterial.metallicFactor ??= 0;
+    physicallyBasedMaterial.roughnessFactor ??= 1;
+    if (diffuse) {
+      const factor = [...diffuse.factor];
+      factor[3] *= validOpacity ? opacity : 1;
+      physicallyBasedMaterial.baseColorFactor ??= factor;
+      if (diffuse.texture) physicallyBasedMaterial.baseColorTexture ??= diffuse.texture;
+    }
+    material.doubleSided ??= doubleSided;
+    material.alphaMode ??= transparent ? 'BLEND' : 'OPAQUE';
+    if (constant) {
+      material.extensions![UNLIT_MATERIAL_EXTENSION] ??= {};
+      declareExtension(json, UNLIT_MATERIAL_EXTENSION, commonRequired);
+      reportNote(`Converted ${label} CONSTANT emission to an unlit material.`);
+    } else {
+      if (emission) {
+        material.emissiveFactor ??= emission.factor.slice(0, 3);
+        if (emission.texture) material.emissiveTexture ??= emission.texture;
+      }
+      reportNote(
+        `Approximated ${label} ${String(common.technique)} lighting with rough non-metallic PBR factors.`
+      );
+    }
+    if (typeof legacyMaterial.technique === 'string')
+      fallbackTechniques.add(legacyMaterial.technique);
+    else if (legacyMaterial.technique !== undefined)
+      reportUnsupported(`${label} invalid fallback technique ID`);
+    delete legacyMaterial.technique;
+    delete legacyMaterial.values;
+    delete material.extensions![COMMON_MATERIAL_EXTENSION];
+    if (!Object.keys(material.extensions!).length) delete material.extensions;
+  }
+  const remaining = collectExtensionNames(json);
+  if (
+    json.extensions?.[COMMON_MATERIAL_EXTENSION] !== undefined ||
+    (json.nodes || []).some(node => node.extensions?.[COMMON_MATERIAL_EXTENSION] !== undefined)
+  )
+    reportUnsupported(`${COMMON_MATERIAL_EXTENSION} lights or scene payloads`);
+  if (!remaining.has(COMMON_MATERIAL_EXTENSION)) {
+    json.extensionsUsed = json.extensionsUsed?.filter(
+      extension => extension !== COMMON_MATERIAL_EXTENSION
+    );
+    json.extensionsRequired = json.extensionsRequired?.filter(
+      extension => extension !== COMMON_MATERIAL_EXTENSION
+    );
+  }
+  return fallbackTechniques;
+}
+
+/** Recognize resources overridden by converted common materials, without claiming shader translation. */
+export function canPreserveGLTFV1MaterialFallbacks(
+  json: GLTF,
+  fallbackTechniques: Set<string>
+): boolean {
+  if (
+    !fallbackTechniques.size ||
+    [...collectExtensionNames(json)].some(
+      extension => ![COMMON_MATERIAL_EXTENSION, UNLIT_MATERIAL_EXTENSION].includes(extension)
+    )
+  )
+    return false;
+  if (
+    (json.materials || []).some(
+      material =>
+        (material as LegacyMaterial).technique !== undefined ||
+        (material as LegacyMaterial).values !== undefined
+    )
+  )
+    return false;
+  const legacyJson = json as unknown as Record<string, unknown>;
+  if (
+    ['techniques', 'programs', 'shaders'].some(
+      collection => legacyJson[collection] !== undefined && !isRecord(legacyJson[collection])
+    )
+  )
+    return false;
+  const techniques = isRecord(legacyJson.techniques) ? legacyJson.techniques : {};
+  const programs = isRecord(legacyJson.programs) ? legacyJson.programs : {};
+  const shaders = isRecord(legacyJson.shaders) ? legacyJson.shaders : {};
+  const coveredPrograms = new Set<string>();
+  const coveredShaders = new Set<string>();
+  if (Object.keys(techniques).some(identifier => !fallbackTechniques.has(identifier))) return false;
+  for (const technique of Object.values(techniques))
+    if (isRecord(technique) && typeof technique.program === 'string')
+      coveredPrograms.add(technique.program);
+  if (Object.keys(programs).some(identifier => !coveredPrograms.has(identifier))) return false;
+  for (const program of Object.values(programs))
+    if (isRecord(program))
+      for (const field of ['vertexShader', 'fragmentShader'])
+        if (typeof program[field] === 'string') coveredShaders.add(program[field]);
+  return Object.keys(shaders).every(identifier => coveredShaders.has(identifier));
+}
+
+/** Preserve the existing conventional uniform heuristic for programmable materials. */
+function convertConventionalMaterial(
+  material: LegacyMaterial,
+  json: GLTF,
+  reportUnsupported: (feature: string) => void,
+  reportNote: (message: string) => void
+): void {
+  preserveMaterialSource(material);
+  const values = isRecord(material.values) ? material.values : {};
+  const textureIdentifier = values.tex || values.texture2d_0 || values.diffuseTex || values.diffuse;
+  const textureIndex = findTextureIndex(json, textureIdentifier);
+  const diffuseColor = isUnitColorFactor(values.diffuse) ? values.diffuse : undefined;
+  if (textureIndex !== -1 || diffuseColor) {
+    const factor = diffuseColor ? [...diffuseColor] : [1, 1, 1, 1];
+    const transparency = values.transparency;
+    if (typeof transparency === 'number' && transparency >= 0 && transparency <= 1)
+      factor[3] *= transparency;
+    material.pbrMetallicRoughness ||= {};
+    material.pbrMetallicRoughness.metallicFactor ??= 0;
+    material.pbrMetallicRoughness.roughnessFactor ??= 1;
+    material.pbrMetallicRoughness.baseColorFactor ??= factor;
+    if (textureIndex !== -1)
+      material.pbrMetallicRoughness.baseColorTexture ??= {index: textureIndex};
+    if (material.pbrMetallicRoughness.baseColorFactor[3] < 1) material.alphaMode ||= 'BLEND';
+    reportNote('Approximated glTF v1 diffuse material values with PBR material factors.');
+  }
+  if (material.technique || material.values)
+    reportUnsupported(`material technique ${material.technique || '<unnamed>'}`);
+}
+
+/** Resolve a common color/texture, using its specified black default rather than inventing a diffuse value. */
+function readMaterialValue(
+  value: unknown,
+  json: GLTF,
+  label: string,
+  reportUnsupported: (feature: string) => void
+): MaterialValue | null {
+  if (value === undefined) return {factor: [0, 0, 0, 1]};
+  if (isUnitColorFactor(value)) return {factor: [...value]};
+  const textureIndex = findTextureIndex(json, value);
+  if (textureIndex !== -1) return {factor: [1, 1, 1, 1], texture: {index: textureIndex}};
+  reportUnsupported(`${label} requires an RGBA factor in [0, 1] or a resolved texture ID`);
+  return null;
+}
+
+/** Resolve string texture IDs retained during dictionary-to-array conversion. */
+function findTextureIndex(json: GLTF, value: unknown): number {
+  if (typeof value !== 'string') return -1;
+  return (json.textures || []).findIndex(
+    texture => (texture as unknown as {id?: string}).id === value
+  );
+}
+
+/** Accept common flags in values or the exporter-style extension location, diagnosing conflicts. */
+function readCommonFlag(
+  common: Record<string, unknown>,
+  values: Record<string, unknown>,
+  field: string,
+  label: string,
+  reportUnsupported: (feature: string) => void
+): boolean {
+  if (common[field] !== undefined && values[field] !== undefined && common[field] !== values[field])
+    reportUnsupported(`${label} conflicting common material ${field}`);
+  const value =
+    values[field] !== undefined
+      ? values[field]
+      : common[field] !== undefined
+        ? common[field]
+        : false;
+  if (typeof value === 'boolean') return value;
+  reportUnsupported(`${label} common material ${field} must be boolean`);
+  return false;
+}
+
+/** Retain caller extras and previous provenance alongside all source material values. */
+function preserveMaterialSource(material: LegacyMaterial, common?: unknown): void {
+  const extras: Record<string, unknown> = isRecord(material.extras)
+    ? material.extras
+    : material.extras === undefined
+      ? {}
+      : {originalExtras: material.extras};
+  const previous = isRecord(extras.gltf1)
+    ? extras.gltf1
+    : extras.gltf1 === undefined
+      ? {}
+      : {originalExtras: extras.gltf1};
+  const source = {
+    technique: material.technique,
+    values: material.values,
+    ...(common === undefined ? {} : {commonMaterial: common})
+  };
+  const conflicting = Object.keys(source).some(field => Object.hasOwn(previous, field));
+  material.extras = {
+    ...extras,
+    gltf1: {...previous, ...source, ...(conflicting ? {originalExtras: previous} : {})}
+  };
+}
+
+/** Add accurate, duplicate-free declarations for generated material extensions. */
+function declareExtension(json: GLTF, extension: string, required: boolean): void {
+  json.extensionsUsed = [...new Set([...(json.extensionsUsed || []), extension])];
+  if (required)
+    json.extensionsRequired = [...new Set([...(json.extensionsRequired || []), extension])];
+}
+
+/** Inventory live extension owners, excluding application extras and copied legacy provenance. */
+function collectExtensionNames(value: unknown): Set<string> {
+  const names = new Set<string>();
+  const pending = [value];
+  const visited = new Set<object>();
+  while (pending.length) {
+    const object = pending.pop();
+    if (!object || typeof object !== 'object' || visited.has(object)) continue;
+    visited.add(object);
+    if (isRecord(object) && isRecord(object.extensions))
+      for (const name of Object.keys(object.extensions)) names.add(name);
+    for (const [field, child] of Object.entries(object))
+      if (field !== 'extras') pending.push(child);
+  }
+  return names;
+}
+
+/** Check finite RGBA factors accepted by core glTF 2 material properties. */
+function isUnitColorFactor(value: unknown): value is number[] {
+  return (
+    Array.isArray(value) &&
+    value.length === 4 &&
+    value.every(
+      component =>
+        typeof component === 'number' &&
+        Number.isFinite(component) &&
+        component >= 0 &&
+        component <= 1
+    )
+  );
+}
+
+/** Recognize a zero RGB lighting term independently of its unused alpha component. */
+function isBlackColor(value: unknown): boolean {
+  return isUnitColorFactor(value) && value.slice(0, 3).every(component => component === 0);
+}
+
+/** Distinguish JSON objects from scalar and array extras or malformed extension payloads. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/gltf/lib/api/convert-gltf-v1-matrix-nodes.ts

@@ -0,0 +1,116 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4, Quaternion} from '@math.gl/core';
+import type {GLTF} from '../types/gltf-types';
+
+/** Convert translation-only animated matrices while preserving their entire linear transform. */
+export function convertGLTFV1MatrixNodes(
+  json: GLTF,
+  reportUnsupported: (feature: string) => void,
+  reportNote: (message: string) => void
+): void {
+  const targets = new Map<number, Set<string>>();
+  for (const animation of json.animations || [])
+    for (const channel of animation.channels || []) {
+      const nodeIndex = channel.target?.node;
+      if (!Number.isSafeInteger(nodeIndex)) continue;
+      const paths = targets.get(nodeIndex as number) || new Set<string>();
+      paths.add(channel.target.path);
+      targets.set(nodeIndex as number, paths);
+    }
+  const plans: Array<() => void> = [];
+  for (const [nodeIndex, paths] of targets) {
+    const node = json.nodes?.[nodeIndex];
+    if (node?.matrix === undefined) continue;
+    const label = `animated matrix node ${nodeIndex}`;
+    if (paths.size !== 1 || !paths.has('translation')) {
+      reportUnsupported(`${label} rotation or scale animation requires an unambiguous TRS basis`);
+      continue;
+    }
+    if (
+      node.translation !== undefined ||
+      node.rotation !== undefined ||
+      node.scale !== undefined ||
+      node.extensions !== undefined
+    ) {
+      reportUnsupported(`${label} has conflicting TRS fields or opaque extensions`);
+      continue;
+    }
+    const transform = decomposeMatrix(node.matrix);
+    if (!transform) {
+      reportUnsupported(`${label} requires a finite affine, nonsingular matrix without shear`);
+      continue;
+    }
+    plans.push(() => {
+      Object.assign(node, transform);
+      delete node.matrix;
+      reportNote(
+        `Decomposed translation-only animated matrix node ${nodeIndex}, preserving its linear transform.`
+      );
+    });
+  }
+  for (const apply of plans) apply();
+}
+
+/** TRS representation checked by recomposing the complete source transform. */
+type MatrixTransform = {
+  /** Original local translation. */
+  translation: number[];
+  /** Unit quaternion, with reflected scale assigned to the first axis. */
+  rotation: number[];
+  /** Column lengths, retaining the determinant sign on the first axis. */
+  scale: number[];
+};
+
+/** Decompose orthogonal columns; reject singular, perspective, and shear transforms. */
+function decomposeMatrix(matrix: number[]): MatrixTransform | null {
+  if (
+    !Array.isArray(matrix) ||
+    matrix.length !== 16 ||
+    Array.from(matrix).some(value => !Number.isFinite(value)) ||
+    matrix[3] !== 0 ||
+    matrix[7] !== 0 ||
+    matrix[11] !== 0 ||
+    matrix[15] !== 1
+  )
+    return null;
+  const scale = [0, 1, 2].map(column => Math.hypot(...matrix.slice(column * 4, column * 4 + 3)));
+  if (scale.some(value => !Number.isFinite(value) || value === 0)) return null;
+  const columns = scale.map((length, column) =>
+    matrix.slice(column * 4, column * 4 + 3).map(value => value / length)
+  );
+  for (let first = 0; first < 3; first++)
+    for (let second = first + 1; second < 3; second++)
+      if (
+        Math.abs(
+          columns[first].reduce((sum, value, row) => sum + value * columns[second][row], 0)
+        ) > 1e-6
+      )
+        return null;
+  const determinant =
+    columns[0][0] * (columns[1][1] * columns[2][2] - columns[1][2] * columns[2][1]) -
+    columns[1][0] * (columns[0][1] * columns[2][2] - columns[0][2] * columns[2][1]) +
+    columns[2][0] * (columns[0][1] * columns[1][2] - columns[0][2] * columns[1][1]);
+  if (Math.abs(Math.abs(determinant) - 1) > 1e-6) return null;
+  if (determinant < 0) {
+    scale[0] = -scale[0];
+    columns[0] = columns[0].map(value => -value);
+  }
+  const rotation = Array.from(new Quaternion().fromMatrix3(columns.flat()).normalize());
+  const translation = matrix.slice(12, 15);
+  const reconstructed = new Matrix4()
+    .translate(translation)
+    .multiplyRight(new Matrix4().fromQuaternion(rotation))
+    .scale(scale);
+  if (
+    Array.from(reconstructed).some(
+      (value, index) =>
+        !Number.isFinite(value) ||
+        Math.abs(value - matrix[index]) > 1e-6 * Math.max(1, Math.abs(matrix[index]))
+    )
+  )
+    return null;
+  return {translation, rotation, scale};
+}

package/src/gltf/lib/api/convert-gltf-v1-skin-scenes.ts

@@ -0,0 +1,88 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF} from '../types/gltf-types';
+
+/** Attach fully detached, non-renderable skeleton hierarchies to scenes using their skins. */
+export function convertGLTFV1SkinScenes(
+  json: GLTF,
+  reportUnsupported: (feature: string) => void,
+  reportNote: (message: string) => void
+): void {
+  const nodes = json.nodes || [];
+  const parents = new Map<number, number | null>();
+  for (const [parentIndex, node] of nodes.entries())
+    for (const childIndex of node.children || []) {
+      parents.set(childIndex, parents.has(childIndex) ? null : parentIndex);
+    }
+  const plans: Array<() => void> = [];
+  for (const [sceneIndex, scene] of (json.scenes || []).entries()) {
+    const reachable = collectNodes(scene.nodes || []);
+    if (!reachable) {
+      reportUnsupported(`scene ${sceneIndex} invalid node hierarchy`);
+      continue;
+    }
+    for (const nodeIndex of Array.from(reachable)) {
+      const skin = json.skins?.[nodes[nodeIndex].skin as number];
+      if (!Array.isArray(skin?.joints) || !skin.joints.length || skin.skeleton === undefined)
+        continue;
+      if (
+        reachable.has(skin.skeleton) &&
+        skin.joints.every(jointIndex => reachable.has(jointIndex))
+      )
+        continue;
+      let rootIndex = skin.skeleton;
+      const ancestors = new Set<number>();
+      while (!ancestors.has(rootIndex) && typeof parents.get(rootIndex) === 'number') {
+        ancestors.add(rootIndex);
+        rootIndex = parents.get(rootIndex) as number;
+      }
+      const hierarchy = collectNodes([rootIndex]);
+      if (
+        ancestors.has(rootIndex) ||
+        parents.get(rootIndex) === null ||
+        !hierarchy ||
+        !skin.joints.every(jointIndex => hierarchy.has(jointIndex)) ||
+        Array.from(hierarchy).some(
+          index =>
+            reachable.has(index) ||
+            nodes[index].mesh !== undefined ||
+            nodes[index].camera !== undefined ||
+            nodes[index].extensions !== undefined
+        )
+      ) {
+        reportUnsupported(
+          `scene ${sceneIndex} skin ${nodes[nodeIndex].skin} cannot safely attach detached skeleton`
+        );
+        continue;
+      }
+      for (const index of hierarchy) reachable.add(index);
+      plans.push(() => {
+        scene.nodes ||= [];
+        scene.nodes.push(rootIndex);
+        reportNote(`Attached detached skeleton root ${rootIndex} to scene ${sceneIndex}.`);
+      });
+    }
+  }
+  for (const apply of plans) apply();
+
+  /** Traverse a forest while detecting missing nodes, cycles, and repeated paths. */
+  function collectNodes(roots: number[]): Set<number> | null {
+    const visited = new Set<number>();
+    const pending = [...roots];
+    while (pending.length) {
+      const index = pending.pop()!;
+      if (
+        !Number.isSafeInteger(index) ||
+        !nodes[index] ||
+        visited.has(index) ||
+        parents.get(index) === null
+      )
+        return null;
+      visited.add(index);
+      pending.push(...(nodes[index].children || []));
+    }
+    return visited;
+  }
+}