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

package/src/gltf/lib/api/normalize-gltf-v1.ts

@@ -0,0 +1,603 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable camelcase */
+import * as KHR_binary_glTF from '../extensions/KHR_binary_gltf';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import {convertGLTFV1AccessorStrides} from './convert-gltf-v1-accessors';
+import {convertGLTFV1Skins} from './convert-gltf-v1-skins';
+import {bakeGLTFV1BindShapes} from './bake-gltf-v1-bind-shapes';
+import {
+  prepareGLTFV1AccessorConversions,
+  repackGLTFV1Accessors,
+  type GLTFV1AccessorConversion
+} from './repack-gltf-v1-accessors';
+import {cleanGLTFV1Fields, convertGLTFV1AttributeName} from './clean-gltf-v1-fields';
+import {convertGLTFV1Animations} from './convert-gltf-v1-animations';
+import {convertGLTFV1SkinScenes} from './convert-gltf-v1-skin-scenes';
+import {validateGLTFV1Cameras} from './validate-gltf-v1-cameras';
+import {validateGLTFV1Payloads} from './validate-gltf-v1-payloads';
+import {validateGLTFV1Buffers} from './validate-gltf-v1-buffers';
+import {convertGLTFV1MatrixNodes} from './convert-gltf-v1-matrix-nodes';
+import {
+  convertGLTFV1Materials,
+  canPreserveGLTFV1MaterialFallbacks
+} from './convert-gltf-v1-materials';
+
+// Binary format changes (mainly implemented by GLBLoader)
+// https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Khronos/KHR_binary_glTF
+
+// JSON format changes:
+// https://github.com/khronosgroup/gltf/issues/605
+
+// - [x] Top-level JSON objects are arrays now
+// - [ ] Removed indirection from animation: sampler now refers directly to accessors, #712
+// - [ ] material.parameter.value and technique.parameter.value must be an array, #690
+// - [ ] Node can have only one mesh #821
+// - [ ] Added reqs on JSON encoding
+// - [ ] Added reqs on binary data alignment #802 (comment)
+
+// Additions:
+// - [ ] Added accessor.normalized, #691, #706
+// - [ ] Added glExtensionsUsed property and 5125 (UNSIGNED_INT) accessor.componentType value, #619
+// - [ ] Added extensionsRequired property, #720, #721
+// - [ ] Added "STEP" as valid animation.sampler.interpolation value, #712
+
+// Removals:
+// - [x] Removed buffer.type, #786, #629
+// - [ ] Removed revision number from profile.version, #709
+// - [ ] Removed technique.functions.scissor and removed 3089 (SCISSOR_TEST) as a valid value for technique.states.enable, #681
+// - [ ] Techniques, programs, and shaders were moved out to KHR_technique_webgl extension.
+
+// Other edits:
+// - [x] asset is now required, #642
+// - [ ] buffer.byteLength and bufferView.byteLength are now required, #560.
+// - [ ] accessor.min and accessor.max are now required, #593, and clarified that the JSON value and binary data must be the same, #628.
+// - [ ] Clarified animation.sampler and animation.channel restrictions, #712
+// - [ ] skin.inverseBindMatrices is now optional, #461.
+// - [ ] Attribute parameters can't have a value defined in the technique or parameter, #563 (comment).
+// - [ ] Only TEXCOORD and COLOR attribute semantics can be written in the form [semantic]_[set_index], #563 (comment).
+// - [ ] TEXCOORD and COLOR attribute semantics must be written in the form [semantic]_[set_index], e.g., just TEXCOORD should be TEXCOORD_0, and just COLOR should be COLOR_0, #649
+// - [ ] camera.perspective.aspectRatio and camera.perspective.yfov must now be > 0, not >= 0, #563 (comment).
+// - [ ] Application-specific parameter semantics must start with an underscore, e.g., _TEMPERATURE and _SIMULATION_TIME, #563 (comment).
+// - [ ] Properties in technique.parameters must be defined in technique.uniforms or technique.attributes,
+
+// #563 (comment).
+// - [ ] technique.parameter.count can only be defined when the semantic is JOINTMATRIX or an application-specific semantic is used. It can never be defined for attribute parameters; only uniforms, d2f6945
+// - [ ] technique.parameter.semantic is required when the parameter is an attribute, 28e113d
+// - [ ] Mesh-only models are allowed, e.g., without materials, #642
+// - [ ] Skeleton hierarchies (nodes containing jointName) must be separated from non-skeleton hierarchies., #647
+// - [ ] technique.states.functions.blendColor and technique.states.functions.depthRange parameters now must match WebGL function min/max, #707
+
+const GLTF_ARRAYS = {
+  accessors: 'accessor',
+  animations: 'animation',
+  buffers: 'buffer',
+  bufferViews: 'bufferView',
+  cameras: 'camera',
+  images: 'image',
+  materials: 'material',
+  meshes: 'mesh',
+  nodes: 'node',
+  samplers: 'sampler',
+  scenes: 'scene',
+  skins: 'skin',
+  textures: 'texture'
+};
+
+const GLTF_KEYS = {
+  accessor: 'accessors',
+  animations: 'animation',
+  buffer: 'buffers',
+  bufferView: 'bufferViews',
+  camera: 'cameras',
+  inverseBindMatrices: 'accessors',
+  image: 'images',
+  material: 'materials',
+  mesh: 'meshes',
+  node: 'nodes',
+  sampler: 'samplers',
+  scene: 'scenes',
+  skin: 'skins',
+  texture: 'textures'
+};
+
+/** Diagnostics emitted while converting a glTF 1 asset to glTF 2. */
+export type GLTFV1NormalizationReport = {
+  /** Whether a glTF 1 asset was detected and converted. */
+  converted: boolean;
+  /** Whether the input JSON was mutated in place. */
+  mutated: boolean;
+  /** Features that could not be represented without loss. */
+  unsupported: string[];
+  /** Non-fatal conversion notes. */
+  warnings: string[];
+};
+
+/** Lazy logging methods compatible with probe.gl and loaders.gl core loggers. */
+export type GLTFV1NormalizationLog = {
+  /** Create a level-controlled informational callback. */
+  log(priority: number, message: string): () => void;
+  /** Create a warning callback. */
+  warn(message: string): () => void;
+};
+
+/** Options for glTF 1 to glTF 2 conversion. */
+export type GLTFV1NormalizationOptions = {
+  /** Enable conversion. `'strict'` rejects unsupported features; other values are best effort. */
+  normalize?: boolean | 'best-effort' | 'strict';
+  /** Mutate the supplied JSON. Defaults to true for backwards compatibility. */
+  mutate?: boolean;
+  /** Optional probe.gl-compatible logger; absent or null leaves diagnostics in the report only. */
+  log?: GLTFV1NormalizationLog | null;
+};
+
+/**
+ * Converts (normalizes) glTF v1 to v2
+ */
+class GLTFV1Normalizer {
+  idToIndexMap = {
+    animations: {},
+    accessors: {},
+    buffers: {},
+    bufferViews: {},
+    cameras: {},
+    images: {},
+    materials: {},
+    meshes: {},
+    nodes: {},
+    samplers: {},
+    scenes: {},
+    skins: {},
+    textures: {}
+  };
+
+  json;
+  /** Diagnostics collected during this normalization pass. */
+  report: GLTFV1NormalizationReport = {
+    converted: false,
+    mutated: false,
+    unsupported: [],
+    warnings: []
+  };
+  /** Whether unsupported legacy features should abort conversion. */
+  strict = false;
+  /** Caller-owned logger receiving conversion notes and unsupported-feature warnings. */
+  log?: GLTFV1NormalizationLog | null;
+  /** Whether binary baking and final diagnostics have already completed. */
+  finished = false;
+  /** Accessors whose loaded payload needs alignment or stride repair. */
+  pendingAccessors = new Set<number>();
+  /** Separated consumer interpretations, captured before legacy strides are consumed. */
+  accessorConversions = new Map<number, GLTFV1AccessorConversion>();
+  /** URI origins retained because the loader removes fetched URIs before binary completion. */
+  uriBufferIndices = new Set<number>();
+
+  // constructor() {}
+
+  /**
+   * Convert (normalize) glTF < 2.0 to glTF 2.0
+   * @param gltf - object with json and binChunks
+   * @param options
+   * @param options normalize Whether to actually normalize
+   * @param deferBinaryBaking Complete matrix baking after the loader resolves linked buffers.
+   */
+  normalize(
+    gltf,
+    options: GLTFV1NormalizationOptions = {},
+    deferBinaryBaking = false
+  ): GLTFV1NormalizationReport {
+    if (options.mutate === false) {
+      const converted = {...gltf, json: JSON.parse(JSON.stringify(gltf.json))};
+      const report = new GLTFV1Normalizer().normalize(converted, {...options, mutate: true});
+      report.mutated = false;
+      return report;
+    }
+    this.strict = options.normalize === 'strict';
+    this.log = options.log;
+    this.json = gltf.json;
+    const json = gltf.json;
+
+    // Check version
+    switch (json.asset && json.asset.version) {
+      // We are converting to v2 format. Return if there is nothing to do
+      case '2.0':
+      case '2.1':
+        return this.report;
+
+      // This class is written to convert 1.0
+      case undefined:
+      case '1.0':
+        break;
+
+      default:
+        this._warning(`Unknown glTF version ${json.asset.version}`);
+        return this.report;
+    }
+
+    if (!options.normalize) {
+      // We are still missing a few conversion tricks, remove once addressed
+      throw new Error('glTF v1 is not supported.');
+    }
+
+    this.report.converted = true;
+    this.report.mutated = true;
+
+    this.log?.log(1, 'glTF: Converting glTF v1 to glTF v2 using experimental normalization.')();
+
+    this._addAsset(json);
+    this._orderBinaryBufferPayloads(gltf);
+
+    // In glTF2 top-level fields are Arrays not Object maps
+    this._convertTopLevelObjectsToArrays(json);
+
+    // Extract bufferView indices for images
+    // (this extension needs to be invoked early in the normalization process)
+    // TODO can this be handled by standard extension processing instead of called explicitly?
+    KHR_binary_glTF.preprocess(gltf);
+
+    // Convert object references from ids to indices
+    this._convertObjectIdsToArrayIndices(json);
+
+    this._updateObjects(json);
+    for (const [bufferIndex, buffer] of (json.buffers || []).entries())
+      if (typeof buffer.uri === 'string') this.uriBufferIndices.add(bufferIndex);
+
+    const commonMaterialFallbacks = convertGLTFV1Materials(
+      json,
+      feature => this._unsupported(feature),
+      message => this._warning(message)
+    );
+    convertGLTFV1Animations(
+      json,
+      (reference, collection) => this._convertIdToIndex(reference, collection),
+      feature => this._unsupported(feature)
+    );
+    validateGLTFV1Cameras(json, feature => this._unsupported(feature));
+    convertGLTFV1MatrixNodes(
+      json,
+      feature => this._unsupported(feature),
+      message => this._warning(message)
+    );
+    cleanGLTFV1Fields(json, feature => this._unsupported(feature));
+    this.accessorConversions = prepareGLTFV1AccessorConversions(json);
+    convertGLTFV1AccessorStrides(json, accessorIndex => this.pendingAccessors.add(accessorIndex));
+    convertGLTFV1Skins(
+      json,
+      nodeId => this._convertIdToIndex(nodeId, 'node'),
+      feature => this._unsupported(feature)
+    );
+    this._updateNodes(json);
+    convertGLTFV1SkinScenes(
+      json,
+      feature => this._unsupported(feature),
+      message => this._warning(message)
+    );
+    this._preserveLegacyResources(json, commonMaterialFallbacks);
+    this._removeEmptyCollections(json);
+    return deferBinaryBaking ? this.report : this.finishNormalization(gltf);
+  }
+
+  /** Complete binary baking once linked buffers are available; repeated calls are harmless. */
+  finishNormalization(gltf: GLTFWithBuffers): GLTFV1NormalizationReport {
+    if (this.report.converted && !this.finished) {
+      validateGLTFV1Buffers(
+        gltf,
+        this.uriBufferIndices,
+        feature => this._unsupported(feature),
+        message => this._warning(message)
+      );
+      repackGLTFV1Accessors(
+        gltf,
+        this.accessorConversions,
+        this.pendingAccessors,
+        feature => this._unsupported(feature),
+        message => this._warning(message)
+      );
+      bakeGLTFV1BindShapes(gltf, feature => this._unsupported(feature));
+      validateGLTFV1Payloads(
+        gltf,
+        feature => this._unsupported(feature),
+        message => this._warning(message)
+      );
+      this._finishReport();
+      this.log?.log(
+        1,
+        `glTF: Completed glTF v1 normalization (${this.report.unsupported.length} unsupported features).`
+      )();
+      this.finished = true;
+    }
+    return this.report;
+  }
+
+  /** Record a feature that requires a lossy best-effort conversion. */
+  _unsupported(feature: string): void {
+    this.report.unsupported.push(feature);
+    this.log?.warn(`glTF v1 normalization does not support ${feature}`)();
+    if (this.strict) {
+      throw new Error(`glTF v1 normalization does not support ${feature}`);
+    }
+  }
+
+  /** Add a diagnostic without rejecting conversion. */
+  _warning(message: string): void {
+    this.report.warnings.push(message);
+    this.log?.warn(`glTF: ${message}`)();
+  }
+
+  // asset is now required, #642 https://github.com/KhronosGroup/glTF/issues/639
+  _addAsset(json) {
+    json.asset = json.asset || {};
+    // We are normalizing to glTF v2, so change version to "2.0"
+    json.asset.version = '2.0';
+    json.asset.generator = json.asset.generator || 'Normalized to glTF 2.0 by loaders.gl';
+  }
+
+  /** Keep loaded buffer payloads aligned when the GLB 1 body is moved to index zero. */
+  _orderBinaryBufferPayloads(gltf: GLTFWithBuffers): void {
+    const buffers = this.json.buffers;
+    if (!buffers || Array.isArray(buffers) || !buffers.binary_glTF) {
+      return;
+    }
+    const bufferIds = Object.keys(buffers);
+    const binaryBufferIndex = bufferIds.indexOf('binary_glTF');
+    if (binaryBufferIndex > 0) {
+      if (gltf.buffers?.length) {
+        gltf.buffers = [
+          gltf.buffers[binaryBufferIndex],
+          ...gltf.buffers.filter((buffer, bufferIndex) => bufferIndex !== binaryBufferIndex)
+        ];
+      }
+    }
+  }
+
+  _convertTopLevelObjectsToArrays(json) {
+    // TODO check that all arrays are covered
+    for (const arrayName in GLTF_ARRAYS) {
+      this._convertTopLevelObjectToArray(json, arrayName);
+    }
+  }
+
+  /** Convert one top level object to array */
+  _convertTopLevelObjectToArray(json, mapName) {
+    const objectMap = json[mapName];
+    if (!objectMap || Array.isArray(objectMap)) {
+      return;
+    }
+
+    // Rewrite the top-level field as an array
+    json[mapName] = [];
+    // Copy the map key into object.id
+    const objectIds = Object.keys(objectMap);
+    const orderedIds =
+      mapName === 'buffers' && objectIds.includes('binary_glTF')
+        ? ['binary_glTF', ...objectIds.filter(id => id !== 'binary_glTF')]
+        : objectIds;
+    for (const id of orderedIds) {
+      const object = objectMap[id];
+      object.id = object.id || id; // Mutates the loaded object
+      const index = json[mapName].length;
+      json[mapName].push(object);
+      this.idToIndexMap[mapName][id] = index;
+    }
+  }
+
+  /** Go through all objects in all top-level arrays and replace ids with indices */
+  _convertObjectIdsToArrayIndices(json) {
+    for (const arrayName in GLTF_ARRAYS) {
+      this._convertIdsToIndices(json, arrayName);
+    }
+    if ('scene' in json) {
+      json.scene = this._convertIdToIndex(json.scene, 'scene');
+    }
+
+    // Convert any index references that are not using array names
+
+    // texture.source (image)
+    for (const texture of json.textures) {
+      this._convertTextureIds(texture);
+    }
+    for (const mesh of json.meshes) {
+      this._convertMeshIds(mesh);
+    }
+    for (const node of json.nodes) {
+      this._convertNodeIds(node);
+    }
+    for (const node of json.scenes) {
+      this._convertSceneIds(node);
+    }
+  }
+
+  _convertTextureIds(texture) {
+    if (texture.source) {
+      texture.source = this._convertIdToIndex(texture.source, 'image');
+    }
+  }
+
+  _convertMeshIds(mesh) {
+    for (const primitive of mesh.primitives) {
+      const {attributes, indices, material} = primitive;
+      const convertedNames = new Map<string, string>();
+      for (const attributeName in attributes) {
+        const convertedName = convertGLTFV1AttributeName(attributeName);
+        const previousName = convertedNames.get(convertedName);
+        if (previousName !== undefined && attributes[previousName] !== attributes[attributeName]) {
+          throw new Error(
+            `glTF v1: conflicting attribute aliases ${previousName} and ${attributeName}`
+          );
+        }
+        convertedNames.set(convertedName, attributeName);
+      }
+      primitive.attributes = Object.fromEntries(
+        Object.entries(attributes).map(([attributeName, accessorId]) => [
+          convertGLTFV1AttributeName(attributeName),
+          this._convertIdToIndex(accessorId, 'accessor')
+        ])
+      );
+      if (indices) {
+        primitive.indices = this._convertIdToIndex(indices, 'accessor');
+      }
+      if (material) {
+        primitive.material = this._convertIdToIndex(material, 'material');
+      }
+    }
+  }
+
+  _convertNodeIds(node) {
+    if (node.children) {
+      node.children = node.children.map(child => this._convertIdToIndex(child, 'node'));
+    }
+    if (node.meshes) {
+      node.meshes = node.meshes.map(mesh => this._convertIdToIndex(mesh, 'mesh'));
+    }
+  }
+
+  _convertSceneIds(scene) {
+    if (scene.nodes) {
+      scene.nodes = scene.nodes.map(node => this._convertIdToIndex(node, 'node'));
+    }
+  }
+
+  /** Go through all objects in a top-level array and replace ids with indices */
+  _convertIdsToIndices(json, topLevelArrayName) {
+    if (!json[topLevelArrayName]) {
+      // Optional absent collections need no assumption or warning.
+      json[topLevelArrayName] = [];
+    }
+    for (const object of json[topLevelArrayName]) {
+      for (const key in object) {
+        const id = object[key];
+        const index = this._convertIdToIndex(id, key);
+        object[key] = index;
+      }
+    }
+  }
+
+  _convertIdToIndex(id, key) {
+    const arrayName = GLTF_KEYS[key];
+    if (arrayName in this.idToIndexMap) {
+      const index = this.idToIndexMap[arrayName][id];
+      if (!Number.isFinite(index)) {
+        throw new Error(`gltf v1: failed to resolve ${key} with id ${id}`);
+      }
+      return index;
+    }
+    return id;
+  }
+
+  /**
+   *
+   * @param {*} json
+   */
+  _updateObjects(json) {
+    for (const buffer of this.json.buffers) {
+      // - [x] Removed buffer.type, #786, #629
+      delete buffer.type;
+    }
+  }
+
+  /** Split glTF 1 nodes that reference multiple meshes into glTF 2-compatible nodes. */
+  _updateNodes(json): void {
+    const nodes = json.nodes || [];
+    for (let nodeIndex = 0; nodeIndex < nodes.length; nodeIndex++) {
+      const node = nodes[nodeIndex];
+      if (!Array.isArray(node.meshes)) {
+        continue;
+      }
+      const meshIndices = node.meshes;
+      delete node.meshes;
+      node.mesh = meshIndices.shift();
+      for (const meshIndex of meshIndices) {
+        const extraNode = {...node, mesh: meshIndex, children: undefined};
+        delete extraNode.id;
+        delete extraNode.matrix;
+        delete extraNode.translation;
+        delete extraNode.rotation;
+        delete extraNode.scale;
+        nodes.push(extraNode);
+        node.children ||= [];
+        node.children.push(nodes.length - 1);
+      }
+    }
+  }
+
+  /** Preserve v1 techniques, programs, and shaders without pretending they are PBR materials. */
+  _preserveLegacyResources(json, commonMaterialFallbacks: Set<string>): void {
+    const coveredFallbacks = canPreserveGLTFV1MaterialFallbacks(json, commonMaterialFallbacks);
+    const resources = {};
+    for (const resourceName of ['techniques', 'programs', 'shaders']) {
+      if (json[resourceName]) {
+        resources[resourceName] = json[resourceName];
+        delete json[resourceName];
+        if (!coveredFallbacks) this._unsupported(`legacy ${resourceName}`);
+      }
+    }
+    if (Object.keys(resources).length) {
+      json.extras = {...json.extras, gltf1Resources: resources};
+      if (coveredFallbacks)
+        this._warning('Preserved shader resources overridden by converted common materials.');
+    }
+  }
+
+  /** Omit optional empty root collections, child lists, and scene roots rejected by glTF 2. */
+  _removeEmptyCollections(json): void {
+    for (const node of json.nodes || []) {
+      if (Array.isArray(node.children) && node.children.length === 0) delete node.children;
+    }
+    for (const scene of json.scenes || []) {
+      if (Array.isArray(scene.nodes) && scene.nodes.length === 0) delete scene.nodes;
+    }
+    for (const collectionName of [
+      ...Object.keys(GLTF_ARRAYS),
+      'extensionsUsed',
+      'extensionsRequired'
+    ]) {
+      if (Array.isArray(json[collectionName]) && json[collectionName].length === 0) {
+        delete json[collectionName];
+      }
+    }
+  }
+
+  /** Finalize report diagnostics. */
+  _finishReport(): void {
+    if (this.report.unsupported.length) {
+      this.report.warnings.push(
+        `Converted glTF v1 with unsupported features: ${this.report.unsupported.join(', ')}`
+      );
+    }
+  }
+}
+
+/** Normalize a glTF 1 asset in place, preserving the historical loader behavior. */
+export function normalizeGLTFV1(
+  gltf: GLTFWithBuffers,
+  options: GLTFV1NormalizationOptions = {}
+): GLTFV1NormalizationReport {
+  return new GLTFV1Normalizer().normalize(gltf, options);
+}
+
+/** Normalize parser JSON now, returning an internal completion step for linked-buffer baking. */
+export function normalizeGLTFV1WithDeferredBuffers(
+  gltf: GLTFWithBuffers,
+  options: Pick<GLTFV1NormalizationOptions, 'normalize' | 'log'> = {}
+): () => GLTFV1NormalizationReport {
+  const normalizer = new GLTFV1Normalizer();
+  normalizer.normalize(gltf, options, true);
+  return () => normalizer.finishNormalization(gltf);
+}
+
+/** Convert glTF 1 JSON without mutating the caller-owned asset or its binary buffers. */
+export function convertGLTFV1ToGLTF2(
+  gltf: GLTFWithBuffers,
+  options: Omit<GLTFV1NormalizationOptions, 'mutate'> = {}
+): GLTFWithBuffers & {normalizationReport: GLTFV1NormalizationReport} {
+  const converted = {...gltf, json: JSON.parse(JSON.stringify(gltf.json))};
+  const normalizationReport = normalizeGLTFV1(converted, {
+    normalize: options.normalize || 'best-effort',
+    mutate: true,
+    log: options.log
+  });
+  normalizationReport.mutated = false;
+  return {...converted, normalizationReport};
+}