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

package/src/gltf/lib/api/bake-gltf-v1-bind-shapes.ts

@@ -0,0 +1,178 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {appendGLTFV1BufferData} from './append-gltf-v1-buffer-data';
+import type {GLTFWithBuffers, GLTFSkin} from '../types/gltf-types';
+
+/** Skin metadata retained until its legacy transform has been baked. */
+type BindShapeSkin = GLTFSkin & {
+  /** Column-major transform applied before inverse-bind matrices. */
+  bindShapeMatrix?: number[];
+  /** Joint names retained on an unresolved best-effort binding. */
+  jointNames?: string[];
+};
+
+/** Validated matrix data to append without overwriting shared source accessors. */
+type BindShapeBake = {
+  /** Source buffer receiving this appended payload. */
+  bufferIndex: number;
+  /** Number of matrices, preserving source accessor order. */
+  count: number;
+  /** Packed little-endian FLOAT MAT4 values. */
+  matrixBytes: ArrayBuffer;
+  /** Equivalent skin instances sharing this baked accessor. */
+  skins: BindShapeSkin[];
+};
+
+/**
+ * Bake affine bind shapes as `inverseBindMatrix * bindShapeMatrix`.
+ * New matrices are appended to copied source buffers, leaving shared accessors and caller bytes
+ * unchanged. Each changed buffer is copied once; URI-backed buffers receive updated data URIs.
+ */
+export function bakeGLTFV1BindShapes(
+  gltf: GLTFWithBuffers,
+  reportUnsupported: (feature: string) => void
+): void {
+  const plannedBindings = new Map<string, BindShapeBake>();
+
+  for (const [skinIndex, skin] of ((gltf.json.skins || []) as BindShapeSkin[]).entries()) {
+    if (skin.bindShapeMatrix === undefined) continue;
+    const bindShapeMatrix = skin.bindShapeMatrix;
+    if (!isFiniteAffineMatrix(bindShapeMatrix)) {
+      reportUnsupported(
+        `skin ${skinIndex} non-identity bindShapeMatrix requires a finite affine matrix`
+      );
+      continue;
+    }
+    const bindingKey = `${skin.inverseBindMatrices}:${bindShapeMatrix.join(',')}`;
+    const existingPlan = plannedBindings.get(bindingKey);
+    if (existingPlan) {
+      if ((skin.joints || skin.jointNames || []).length > existingPlan.count) {
+        reportUnsupported(
+          `skin ${skinIndex} non-identity bindShapeMatrix has too few inverse-bind matrices`
+        );
+        continue;
+      }
+      existingPlan.skins.push(skin);
+      continue;
+    }
+    const plan = prepareBindShapeBake(gltf, skin, bindShapeMatrix);
+    if (typeof plan === 'string') {
+      reportUnsupported(`skin ${skinIndex} non-identity bindShapeMatrix ${plan}`);
+      continue;
+    }
+    plannedBindings.set(bindingKey, plan);
+  }
+  appendGLTFV1BufferData(
+    gltf,
+    Array.from(plannedBindings.values(), plan => ({
+      bufferIndex: plan.bufferIndex,
+      bytes: plan.matrixBytes,
+      apply: bufferViewIndex => {
+        gltf.json.accessors ||= [];
+        const accessorIndex = gltf.json.accessors.length;
+        gltf.json.accessors.push({
+          bufferView: bufferViewIndex,
+          byteOffset: 0,
+          componentType: 5126,
+          count: plan.count,
+          type: 'MAT4'
+        });
+        for (const skin of plan.skins) {
+          skin.inverseBindMatrices = accessorIndex;
+          delete skin.bindShapeMatrix;
+        }
+      }
+    }))
+  );
+}
+
+/** Validate the source and calculate a complete payload before committing any buffer changes. */
+function prepareBindShapeBake(
+  gltf: GLTFWithBuffers,
+  skin: BindShapeSkin,
+  bindShapeMatrix: number[]
+): BindShapeBake | string {
+  const accessor = gltf.json.accessors?.[skin.inverseBindMatrices as number];
+  const jointCount = (skin.joints || skin.jointNames || []).length;
+  if (
+    !accessor ||
+    accessor.componentType !== 5126 ||
+    accessor.type !== 'MAT4' ||
+    accessor.normalized ||
+    accessor.sparse ||
+    accessor.extensions ||
+    Object.hasOwn(accessor, 'byteStride') ||
+    !Number.isSafeInteger(accessor.count) ||
+    accessor.count < 1
+  )
+    return 'requires packed FLOAT MAT4 inverse-bind matrices';
+  if (accessor.count < jointCount) return 'has too few inverse-bind matrices';
+  const bufferView = gltf.json.bufferViews?.[accessor.bufferView as number];
+  const bufferIndex = bufferView?.buffer;
+  const bufferDefinition = gltf.json.buffers?.[bufferIndex as number];
+  const loadedBuffer = gltf.buffers[bufferIndex as number];
+  if (!bufferView || bufferIndex === undefined || !bufferDefinition || !loadedBuffer)
+    return 'requires a loaded inverse-bind buffer';
+  if (bufferView.extensions) return 'does not support inverse-bind buffer-view extensions';
+  const bufferViewByteOffset = bufferView.byteOffset ?? 0;
+  const accessorByteOffset = accessor.byteOffset ?? 0;
+  const matrixByteLength = accessor.count * 64;
+  if (
+    !(loadedBuffer.arrayBuffer instanceof ArrayBuffer) ||
+    !Number.isSafeInteger(bufferDefinition.byteLength) ||
+    bufferDefinition.byteLength < 1 ||
+    !Number.isSafeInteger(loadedBuffer.byteOffset) ||
+    loadedBuffer.byteOffset < 0 ||
+    !Number.isSafeInteger(loadedBuffer.byteLength) ||
+    loadedBuffer.byteLength < bufferDefinition.byteLength ||
+    loadedBuffer.byteOffset + loadedBuffer.byteLength > loadedBuffer.arrayBuffer.byteLength ||
+    !Number.isSafeInteger(bufferViewByteOffset) ||
+    bufferViewByteOffset < 0 ||
+    bufferViewByteOffset % 4 !== 0 ||
+    !Number.isSafeInteger(bufferView.byteLength) ||
+    bufferView.byteLength < 1 ||
+    bufferView.byteStride !== undefined ||
+    bufferViewByteOffset + bufferView.byteLength > bufferDefinition.byteLength ||
+    !Number.isSafeInteger(accessorByteOffset) ||
+    accessorByteOffset < 0 ||
+    accessorByteOffset % 4 !== 0 ||
+    accessorByteOffset + matrixByteLength > bufferView.byteLength
+  )
+    return 'has an invalid inverse-bind buffer layout';
+
+  const sourceData = new DataView(loadedBuffer.arrayBuffer);
+  const sourceByteOffset = loadedBuffer.byteOffset + bufferViewByteOffset + accessorByteOffset;
+  const matrixBytes = new ArrayBuffer(matrixByteLength);
+  const outputData = new DataView(matrixBytes);
+  for (let matrixIndex = 0; matrixIndex < accessor.count; matrixIndex++) {
+    const inverseBindMatrix = Array.from({length: 16}, (_, componentIndex) =>
+      sourceData.getFloat32(sourceByteOffset + matrixIndex * 64 + componentIndex * 4, true)
+    );
+    if (!isFiniteAffineMatrix(inverseBindMatrix))
+      return 'requires finite affine inverse-bind matrices';
+    for (let columnIndex = 0; columnIndex < 4; columnIndex++) {
+      for (let rowIndex = 0; rowIndex < 4; rowIndex++) {
+        let value = 0;
+        for (let innerIndex = 0; innerIndex < 4; innerIndex++) {
+          value +=
+            inverseBindMatrix[innerIndex * 4 + rowIndex] *
+            bindShapeMatrix[columnIndex * 4 + innerIndex];
+        }
+        if (!Number.isFinite(Math.fround(value))) return 'produces non-finite FLOAT matrix values';
+        outputData.setFloat32(matrixIndex * 64 + (columnIndex * 4 + rowIndex) * 4, value, true);
+      }
+    }
+  }
+  return {bufferIndex, count: accessor.count, matrixBytes, skins: [skin]};
+}
+
+/** Check glTF 2's finite values and required affine fourth row, including sparse JS arrays. */
+function isFiniteAffineMatrix(matrix: unknown): matrix is number[] {
+  if (!Array.isArray(matrix) || matrix.length !== 16) return false;
+  for (let componentIndex = 0; componentIndex < 16; componentIndex++) {
+    if (!Number.isFinite(matrix[componentIndex])) return false;
+  }
+  return matrix[3] === 0 && matrix[7] === 0 && matrix[11] === 0 && matrix[15] === 1;
+}

package/src/gltf/lib/api/clean-gltf-v1-fields.ts

@@ -0,0 +1,94 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF} from '../types/gltf-types';
+
+/** Preserve obsolete fields under extras, reporting rendering semantics that cannot be removed safely. */
+export function cleanGLTFV1Fields(json: GLTF, reportUnsupported: (feature: string) => void): void {
+  const asset = json.asset as unknown as Record<string, unknown>;
+  if (asset.premultipliedAlpha) reportUnsupported('asset premultipliedAlpha rendering');
+  preserveLegacyFields(asset, ['profile', 'premultipliedAlpha']);
+  for (const [textureIndex, texture] of (json.textures || []).entries()) {
+    const legacyTexture = texture as unknown as Record<string, unknown>;
+    for (const [field, defaultValue] of Object.entries({
+      format: 6408,
+      internalFormat: 6408,
+      target: 3553,
+      type: 5121
+    })) {
+      if (legacyTexture[field] !== undefined && legacyTexture[field] !== defaultValue) {
+        reportUnsupported(`texture ${textureIndex} non-default ${field} rendering`);
+      }
+    }
+    preserveLegacyFields(legacyTexture, ['format', 'internalFormat', 'target', 'type']);
+  }
+}
+
+/** Move specified source properties without discarding application extras or existing provenance. */
+function preserveLegacyFields(object: Record<string, unknown>, fields: string[]): void {
+  const legacyFields: Record<string, unknown> = {};
+  for (const field of fields)
+    if (Object.hasOwn(object, field)) {
+      legacyFields[field] = object[field];
+      delete object[field];
+    }
+  if (!Object.keys(legacyFields).length) return;
+  const extras = isRecord(object.extras)
+    ? object.extras
+    : object.extras === undefined
+      ? {}
+      : {originalExtras: object.extras};
+  const provenance = isRecord(extras.gltf1)
+    ? extras.gltf1
+    : extras.gltf1 === undefined
+      ? {}
+      : {originalExtras: extras.gltf1};
+  const previousFields = isRecord(provenance.legacyFields)
+    ? provenance.legacyFields
+    : provenance.legacyFields === undefined
+      ? {}
+      : {originalExtras: provenance.legacyFields};
+  const conflictingFields = Object.keys(legacyFields).some(field =>
+    Object.hasOwn(previousFields, field)
+  );
+  object.extras = {
+    ...extras,
+    gltf1: {
+      ...provenance,
+      legacyFields: {
+        ...previousFields,
+        ...legacyFields,
+        ...(conflictingFields ? {originalExtras: previousFields} : {})
+      }
+    }
+  };
+}
+
+/** JSON extras may be scalar or array values, rather than mergeable objects. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Rename conventional indexed semantics and put application-specific names in their glTF 2 namespace. */
+export function convertGLTFV1AttributeName(name: string): string {
+  const indexed = /^(JOINTS?|WEIGHTS?|TEXCOORD|COLOR)(?:_(\d+))?$/.exec(name);
+  if (indexed) {
+    const semantic = indexed[1].startsWith('JOINT')
+      ? 'JOINTS'
+      : indexed[1].startsWith('WEIGHT')
+        ? 'WEIGHTS'
+        : indexed[1];
+    const index = Number(indexed[2] || 0);
+    if (!Number.isSafeInteger(index) || index > 999999999)
+      throw new Error(`glTF v1: invalid attribute set index ${name}`);
+    return `${semantic}_${index}`;
+  }
+  if (
+    ['POSITION', 'NORMAL', 'TANGENT'].includes(name) ||
+    name.startsWith('_') ||
+    name.includes(':')
+  )
+    return name;
+  return `_${name}`;
+}

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

@@ -0,0 +1,170 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF, GLTFAccessor, GLTFBufferView} from '../types/gltf-types';
+
+/** The core use of an accessor after its references have been normalized. */
+type AccessorUsage = 'vertex' | 'indices' | 'animation' | 'inverseBind' | 'unused' | 'mixed';
+
+/** A glTF 1 accessor carries its own stride rather than a buffer-view stride. */
+type LegacyAccessor = GLTFAccessor & {
+  /** Byte distance between elements; zero or absence means tightly packed. */
+  byteStride?: number;
+};
+
+/** Byte widths of component types usable in stable glTF 2. */
+const COMPONENT_BYTE_LENGTHS: Record<number, number> = {
+  5120: 1,
+  5121: 1,
+  5122: 2,
+  5123: 2,
+  5125: 4,
+  5126: 4
+};
+
+/** Component counts of core scalar, vector, and matrix accessor types. */
+const ELEMENT_COMPONENT_COUNTS: Record<string, number> = {
+  SCALAR: 1,
+  VEC2: 2,
+  VEC3: 3,
+  VEC4: 4,
+  MAT2: 4,
+  MAT3: 9,
+  MAT4: 16
+};
+
+/**
+ * Move legacy strides to compatible buffer views without modifying binary payloads.
+ * Views are split by usage and stride so packed and interleaved accessors cannot affect each other.
+ * Layouts requiring binary repacking remain intact and are queued until their buffers load.
+ */
+export function convertGLTFV1AccessorStrides(
+  json: GLTF,
+  queueRepacking: (accessorIndex: number) => void
+): void {
+  const accessors = (json.accessors || []) as LegacyAccessor[];
+  const bufferViews = json.bufferViews || [];
+  const usages = collectAccessorUsages(json);
+  const convertedViews = new Map<string, number>();
+
+  for (const [accessorIndex, accessor] of accessors.entries()) {
+    const bufferViewIndex = accessor.bufferView;
+    if (bufferViewIndex === undefined && !accessor.byteStride) {
+      delete accessor.byteStride;
+      continue;
+    }
+    const bufferView = bufferViews[bufferViewIndex as number];
+    const usage = usages.get(accessorIndex) || 'unused';
+    const elementByteLength = getLegacyElementByteLength(accessor);
+    const byteStride =
+      accessor.byteStride === 0 ? elementByteLength : (accessor.byteStride ?? elementByteLength);
+    const byteOffset = accessor.byteOffset ?? 0;
+    const bufferViewByteOffset = bufferView?.byteOffset ?? 0;
+    const componentByteLength =
+      typeof accessor.componentType === 'number' &&
+      Object.hasOwn(COMPONENT_BYTE_LENGTHS, accessor.componentType)
+        ? COMPONENT_BYTE_LENGTHS[accessor.componentType]
+        : 0;
+    const isVertex = usage === 'vertex';
+    const hasCompatibleStride = isVertex
+      ? byteStride >= elementByteLength &&
+        byteStride >= 4 &&
+        byteStride <= 252 &&
+        byteStride % 4 === 0 &&
+        byteOffset % 4 === 0 &&
+        (bufferViewByteOffset + byteOffset) % 4 === 0
+      : byteStride === elementByteLength;
+
+    if (
+      !bufferView ||
+      !elementByteLength ||
+      usage === 'mixed' ||
+      !Number.isInteger(byteStride) ||
+      !hasCompatibleStride ||
+      (isVertex && byteStride > bufferView.byteLength) ||
+      !Number.isInteger(accessor.count) ||
+      accessor.count < 1 ||
+      !Number.isInteger(byteOffset) ||
+      byteOffset < 0 ||
+      !Number.isInteger(bufferViewByteOffset) ||
+      bufferViewByteOffset < 0 ||
+      byteOffset % componentByteLength !== 0 ||
+      (bufferViewByteOffset + byteOffset) % componentByteLength !== 0 ||
+      (accessor.type.startsWith('MAT') && (bufferViewByteOffset + byteOffset) % 4 !== 0) ||
+      !Number.isInteger(bufferView.byteLength) ||
+      byteOffset + (accessor.count - 1) * byteStride + elementByteLength > bufferView.byteLength
+    ) {
+      queueRepacking(accessorIndex);
+      continue;
+    }
+
+    // Keep image/extension views unchanged; accessors with different roles get separate views.
+    const viewKey = `${bufferViewIndex}:${usage}:${isVertex ? byteStride : 0}`;
+    let convertedViewIndex = convertedViews.get(viewKey);
+    if (convertedViewIndex === undefined) {
+      const convertedView: GLTFBufferView & {id?: string} = {...bufferView};
+      delete convertedView.id;
+      delete convertedView.byteStride;
+      delete convertedView.target;
+      if (isVertex) {
+        convertedView.byteStride = byteStride;
+        convertedView.target = 34962;
+      } else if (usage === 'indices') {
+        convertedView.target = 34963;
+      }
+      convertedViewIndex = bufferViews.length;
+      bufferViews.push(convertedView);
+      convertedViews.set(viewKey, convertedViewIndex);
+    }
+    accessor.bufferView = convertedViewIndex;
+    delete accessor.byteStride;
+  }
+}
+
+/** Track core accessor consumers so strides are only emitted for vertex attributes. */
+function collectAccessorUsages(json: GLTF): Map<number, AccessorUsage> {
+  const usages = new Map<number, AccessorUsage>();
+  /** Record one use, preserving a diagnostic marker when consumers have incompatible roles. */
+  const addUsage = (accessorIndex: number | undefined, usage: AccessorUsage): void => {
+    if (accessorIndex === undefined) return;
+    const previousUsage = usages.get(accessorIndex);
+    usages.set(accessorIndex, previousUsage && previousUsage !== usage ? 'mixed' : usage);
+  };
+  for (const mesh of json.meshes || []) {
+    for (const primitive of mesh.primitives) {
+      for (const accessorIndex of Object.values(primitive.attributes)) {
+        addUsage(accessorIndex, 'vertex');
+      }
+      addUsage(primitive.indices, 'indices');
+    }
+  }
+  for (const animation of json.animations || []) {
+    for (const sampler of animation.samplers) {
+      addUsage(sampler.input, 'animation');
+      addUsage(sampler.output, 'animation');
+    }
+  }
+  for (const skin of json.skins || []) {
+    addUsage(skin.inverseBindMatrices, 'inverseBind');
+  }
+  return usages;
+}
+
+/** Return the legacy element width, excluding matrix layouts that require glTF 2 padding. */
+function getLegacyElementByteLength(accessor: GLTFAccessor): number {
+  const componentByteLength =
+    typeof accessor.componentType === 'number' &&
+    Object.hasOwn(COMPONENT_BYTE_LENGTHS, accessor.componentType)
+      ? COMPONENT_BYTE_LENGTHS[accessor.componentType]
+      : 0;
+  const componentCount = Object.hasOwn(ELEMENT_COMPONENT_COUNTS, accessor.type)
+    ? ELEMENT_COMPONENT_COUNTS[accessor.type]
+    : 0;
+  if (!componentByteLength || !componentCount) return 0;
+  const columnComponentCount = accessor.type === 'MAT2' ? 2 : accessor.type === 'MAT3' ? 3 : 4;
+  if (accessor.type.startsWith('MAT') && (columnComponentCount * componentByteLength) % 4 !== 0) {
+    return 0;
+  }
+  return (componentByteLength || 0) * componentCount;
+}

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

@@ -0,0 +1,79 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF} from '../types/gltf-types';
+import type {GLTFAnimationSampler} from '../types/gltf-json-schema';
+
+/** Convert dictionary or hybrid array animation references without losing malformed source references. */
+export function convertGLTFV1Animations(
+  json: GLTF,
+  resolveReference: (reference: string, collection: 'accessor' | 'node') => number,
+  reportUnsupported: (feature: string) => void
+): void {
+  for (const [animationIndex, animation] of (json.animations || []).entries()) {
+    const legacy = animation as typeof animation & {parameters?: Record<string, unknown>};
+    const parameters = legacy.parameters || {};
+    const samplerIndices = new Map<string, number>();
+    const legacySamplers = animation.samplers as
+      | GLTFAnimationSampler[]
+      | Record<string, GLTFAnimationSampler>;
+    const samplerEntries: Array<readonly [string, GLTFAnimationSampler]> = Array.isArray(
+      legacySamplers
+    )
+      ? legacySamplers.map((sampler, samplerIndex) => [String(samplerIndex), sampler] as const)
+      : Object.entries(legacySamplers || {});
+    animation.samplers = samplerEntries.map(([samplerId, sampler], samplerIndex) => {
+      samplerIndices.set(samplerId, samplerIndex);
+      for (const field of ['input', 'output'] as const) {
+        const reference = sampler[field];
+        const accessorId = Object.hasOwn(parameters, reference) ? parameters[reference] : reference;
+        sampler[field] = convertReference(accessorId, 'accessor', `sampler ${samplerId} ${field}`);
+      }
+      sampler.interpolation ??= 'LINEAR';
+      return sampler;
+    });
+    delete legacy.parameters;
+    for (const [channelIndex, channel] of (animation.channels || []).entries()) {
+      if (typeof channel.sampler === 'string') {
+        const samplerIndex = samplerIndices.get(channel.sampler);
+        if (samplerIndex === undefined)
+          reportUnsupported(
+            `animation ${animationIndex} channel ${channelIndex} unresolved sampler ${channel.sampler}`
+          );
+        else channel.sampler = samplerIndex;
+      }
+      const target = channel.target as typeof channel.target & {id?: string | number};
+      if (target?.id !== undefined) {
+        target.node = convertReference(target.id, 'node', `channel ${channelIndex} target`);
+        delete target.id;
+      } else if (typeof target?.node === 'string') {
+        target.node = convertReference(target.node, 'node', `channel ${channelIndex} target`);
+      }
+    }
+
+    /** Resolve known references, preserving invalid originals for best-effort diagnostics. */
+    function convertReference(
+      reference: unknown,
+      collection: 'accessor' | 'node',
+      label: string
+    ): number {
+      try {
+        const index =
+          typeof reference === 'string' ? resolveReference(reference, collection) : reference;
+        const values = collection === 'accessor' ? json.accessors : json.nodes;
+        if (
+          typeof index === 'number' &&
+          Number.isSafeInteger(index) &&
+          index >= 0 &&
+          values?.[index]
+        )
+          return index;
+      } catch {
+        // The report decides whether unresolved references abort conversion.
+      }
+      reportUnsupported(`animation ${animationIndex} ${label} unresolved ${collection} reference`);
+      return reference as number;
+    }
+  }
+}