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

package/src/gltf/lib/extensions/EXT_mesh_features.ts

@@ -0,0 +1,240 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// GLTF EXTENSION: EXT_mesh_features
+// https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features
+/* eslint-disable camelcase */
+import type {NumericArray} from '@loaders.gl/core/loader-utils';
+import type {GLTF, GLTFMeshPrimitive} from '../types/gltf-json-schema';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import {GLTFLoaderOptions} from '../../gltf-loader-types';
+import {GLTFWriterOptions} from '../../gltf-writer';
+import type {
+  GLTF_EXT_mesh_features,
+  GLTF_EXT_mesh_features_featureId
+} from '../types/gltf-ext-mesh-features-schema';
+
+import {GLTFScenegraph} from '../api/gltf-scenegraph';
+import {GLTFIterator} from '../api/gltf-iterator';
+import {getPrimitiveTextureData} from './utils/3d-tiles-utils';
+import {getComponentTypeFromArray} from '../gltf-utils/gltf-utils';
+
+const EXT_MESH_FEATURES_NAME = 'EXT_mesh_features';
+export const name = EXT_MESH_FEATURES_NAME;
+
+export async function decode(gltfData: GLTFWithBuffers, options: GLTFLoaderOptions): Promise<void> {
+  const iterator = new GLTFIterator(gltfData);
+  decodeExtMeshFeatures(iterator, options);
+}
+
+export function encode(gltfData: {json: GLTF}, options: GLTFWriterOptions): {json: GLTF} {
+  const scenegraph = new GLTFScenegraph(gltfData);
+  encodeExtMeshFeatures(scenegraph, options);
+  scenegraph.createBinaryChunk();
+  return scenegraph.gltf;
+}
+
+/**
+ * Decodes feature metadata from extension.
+ * @param {GLTFScenegraph} scenegraph - Instance of the class for structured access to GLTF data.
+ * @param {GLTFLoaderOptions} options - GLTFLoader options.
+ */
+function decodeExtMeshFeatures(iterator: GLTFIterator, options: GLTFLoaderOptions): void {
+  for (const mesh of iterator.meshes) {
+    for (const primitive of iterator.getReferences(mesh).primitives) {
+      processMeshPrimitiveFeatures(iterator, primitive, options);
+    }
+  }
+}
+
+/**
+ * Takes data from EXT_mesh_features and store it in 'data' property of featureIds.
+ * If combined with EXT_structural_metadata, corresponding data are taken from the property tables of that extension.
+ * @param {GLTFScenegraph} scenegraph - Instance of the class for structured access to GLTF data.
+ * @param {GLTFMeshPrimitive} primitive - Primitive that contains extensions.
+ * @param {GLTFLoaderOptions} options - GLTFLoader options.
+ */
+function processMeshPrimitiveFeatures(
+  iterator: GLTFIterator,
+  primitive: GLTFMeshPrimitive,
+  options: GLTFLoaderOptions
+): void {
+  const extension = iterator.getExtension<GLTF_EXT_mesh_features>(
+    primitive,
+    EXT_MESH_FEATURES_NAME
+  );
+  const featureIds: GLTF_EXT_mesh_features_featureId[] = extension?.featureIds || [];
+
+  if (!featureIds) {
+    return;
+  }
+
+  for (const featureId of featureIds) {
+    let featureIdData: NumericArray | undefined;
+    // Process "Feature ID by Vertex"
+    if (typeof featureId.attribute !== 'undefined') {
+      if (!options?.gltf?.loadBuffers) {
+        continue;
+      }
+      const accessorKey = `_FEATURE_ID_${featureId.attribute}`;
+      const accessorIndex = primitive.attributes[accessorKey];
+      featureIdData = iterator.getTypedArrayForAccessor(accessorIndex) as NumericArray;
+    }
+
+    // Process "Feature ID by Texture Coordinates"
+    else if (typeof featureId.texture !== 'undefined') {
+      if (!options?.gltf?.loadImages) {
+        continue;
+      }
+      featureIdData = getPrimitiveTextureData(iterator, featureId.texture, primitive);
+    }
+
+    // Process "Feature ID by Index"
+    else {
+      // When both featureId.attribute and featureId.texture are undefined,
+      // then the feature ID value for each vertex is given implicitly, via the index of the vertex.
+      // In this case, the featureCount must match the number of vertices of the mesh primitive.
+      const positionAccessor = primitive.attributes.POSITION;
+      const vertexCount =
+        typeof positionAccessor === 'number'
+          ? iterator.data.accessors?.[positionAccessor]?.count
+          : (positionAccessor as {count?: number} | undefined)?.count;
+      if (typeof vertexCount !== 'number' || !Number.isInteger(vertexCount) || vertexCount < 0) {
+        throw new Error('EXT_mesh_features: implicit feature IDs require a POSITION accessor');
+      }
+      if (featureId.featureCount !== vertexCount) {
+        throw new Error(
+          `EXT_mesh_features: implicit featureCount ${featureId.featureCount} does not match vertex count ${vertexCount}`
+        );
+      }
+      delete featureId.data;
+      Object.defineProperty(featureId, 'implicit', {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: {start: 0, count: vertexCount}
+      });
+    }
+
+    if (featureIdData) {
+      featureId.data = featureIdData;
+      delete featureId.implicit;
+    }
+  }
+}
+
+/*
+  Encoding data
+*/
+
+function encodeExtMeshFeatures(scenegraph: GLTFScenegraph, options: GLTFWriterOptions) {
+  const meshes = scenegraph.gltf.json.meshes;
+  if (!meshes) {
+    return;
+  }
+
+  // Iterate through all meshes/primitives.
+  for (const mesh of meshes) {
+    for (const primitive of mesh.primitives) {
+      encodeExtMeshFeaturesForPrimitive(scenegraph, primitive);
+    }
+  }
+}
+
+/**
+ * Creates ExtMeshFeatures, creates a featureId containing feature ids provided.
+ * @param scenegraph - Instance of the class for structured access to GLTF data.
+ * @param primitive - target primitive instance that will contain the extension
+ * @param featureIdArray - Array of feature id
+ * @param propertyTableIndex - index of the property table created by the ExtStructuralMetadata (optional).
+ */
+export function createExtMeshFeatures(
+  scenegraph: GLTFScenegraph,
+  primitive: GLTFMeshPrimitive,
+  featureIdArray: NumericArray,
+  propertyTableIndex?: number
+) {
+  if (!primitive.extensions) {
+    primitive.extensions = {};
+  }
+  let extension = primitive.extensions[EXT_MESH_FEATURES_NAME] as GLTF_EXT_mesh_features;
+  if (!extension) {
+    extension = {featureIds: []};
+    primitive.extensions[EXT_MESH_FEATURES_NAME] = extension;
+  }
+
+  const {featureIds} = extension;
+  const featureId: GLTF_EXT_mesh_features_featureId = {
+    featureCount: featureIdArray.length,
+    propertyTable: propertyTableIndex,
+    data: featureIdArray
+  };
+  featureIds.push(featureId);
+
+  scenegraph.addObjectExtension(primitive, EXT_MESH_FEATURES_NAME, extension);
+}
+
+/**
+ * Encodes a feature ID set to extension.
+ * @param scenegraph - Instance of the class for structured access to GLTF data.
+ * @param primitive - Primitive that the data encoded belongs to.
+ * @see https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features
+ */
+function encodeExtMeshFeaturesForPrimitive(
+  scenegraph: GLTFScenegraph,
+  primitive: GLTFMeshPrimitive
+) {
+  const extension = primitive.extensions?.[EXT_MESH_FEATURES_NAME] as GLTF_EXT_mesh_features;
+  if (!extension) {
+    return;
+  }
+  const featureIds: GLTF_EXT_mesh_features_featureId[] = extension.featureIds;
+  featureIds.forEach((featureId, elementIndex) => {
+    if (featureId.data) {
+      const {accessorKey, index} = createAccessorKey(primitive.attributes);
+      const typedArray = new Uint32Array(featureId.data as NumericArray);
+
+      // Clean up featureId object.
+      // Everything that could come from the original extension in case of round-trip decode/encode operations should be deleted.
+      // We need make sure the featureId object is clean.
+      featureIds[elementIndex] = {
+        featureCount: typedArray.length,
+        propertyTable: featureId.propertyTable,
+        attribute: index
+      };
+
+      const bufferViewIndex = scenegraph.addBufferView(typedArray);
+      const accessorIndex = scenegraph.addAccessor(bufferViewIndex, {
+        size: 1,
+        componentType: getComponentTypeFromArray(typedArray),
+        count: typedArray.length
+      });
+      primitive.attributes[accessorKey] = accessorIndex;
+    }
+  });
+}
+
+/**
+ * Creates an accessor key for the attribute array provided.
+ * The generated key has a suffix (number) that is the next consequtive in the list of existing accessors.
+ * @param attributes - attribute array
+ * @returns accessor key and the key suffix (number) used in the key.
+ */
+function createAccessorKey(attributes: {[k: string]: number}) {
+  const prefix = '_FEATURE_ID_';
+  // Search for all "_FEATURE_ID_n" attribures in the primitive provided if any.
+  // If there are some, e.g. "_FEATURE_ID_0", "_FEATURE_ID_1",
+  // we will add a new one with the name "_FEATURE_ID_2"
+  const attrs = Object.keys(attributes).filter(item => item.indexOf(prefix) === 0);
+  let max = -1;
+  for (const a of attrs) {
+    const n = Number(a.substring(prefix.length));
+    if (n > max) {
+      max = n;
+    }
+  }
+  max++;
+  const accessorKey = `${prefix}${max}`;
+  return {accessorKey, index: max};
+}

package/src/gltf/lib/extensions/EXT_mesh_polygon.ts

@@ -0,0 +1,172 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import type {NumericArray} from '@loaders.gl/core/loader-utils';
+import type {GLTFLoaderOptions} from '../../gltf-loader-types';
+import type {GLTFAccessor, GLTFMeshPrimitive} from '../types/gltf-json-schema';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import type {
+  GLTF_EXT_mesh_polygon,
+  GLTFMeshPolygonData,
+  GLTFPolygon
+} from '../types/gltf-vector-topology';
+import {GLTFIterator} from '../api/gltf-iterator';
+import {getPrimitiveRestartRanges} from './KHR_mesh_primitive_restart';
+
+/** Draft polygon-topology extension name. */
+export const name = 'EXT_mesh_polygon';
+
+/** Resolve and validate polygon topology accessors. */
+export async function decode(gltfData: GLTFWithBuffers, options: GLTFLoaderOptions): Promise<void> {
+  if (!options.gltf?.loadBuffers) {
+    return;
+  }
+  const iterator = new GLTFIterator(gltfData);
+  for (const mesh of iterator.meshes) {
+    for (const primitive of iterator.getReferences(mesh).primitives) {
+      const extension = iterator.getExtension<GLTF_EXT_mesh_polygon>(primitive, name);
+      if (extension) {
+        Object.defineProperty(extension, 'data', {
+          configurable: true,
+          enumerable: false,
+          writable: true,
+          value: decodePolygonData(iterator, primitive, extension)
+        });
+      }
+    }
+  }
+}
+
+/** Resolve the accessors referenced by one polygon extension. */
+function decodePolygonData(
+  iterator: GLTFIterator,
+  primitive: GLTFMeshPrimitive,
+  extension: GLTF_EXT_mesh_polygon
+): GLTFMeshPolygonData {
+  if (!Number.isInteger(extension.count) || extension.count < 1) {
+    throw new Error(`${name}: count must be a positive integer`);
+  }
+  if ((primitive.mode ?? 4) !== 4 || primitive.indices === undefined) {
+    throw new Error(`${name}: primitive must use TRIANGLES mode with indices`);
+  }
+
+  const triangleIndices = getUnsignedScalarAccessor(iterator, primitive.indices, 'indices');
+  const indicesOffsets = getUnsignedScalarAccessor(
+    iterator,
+    extension.indicesOffsets,
+    'indicesOffsets',
+    extension.count
+  );
+  const loopIndices = getUnsignedScalarAccessor(iterator, extension.loopIndices, 'loopIndices');
+  const loopIndicesOffsets = getUnsignedScalarAccessor(
+    iterator,
+    extension.loopIndicesOffsets,
+    'loopIndicesOffsets',
+    extension.count
+  );
+  const loopAccessor = iterator.data.accessors?.[extension.loopIndices] as GLTFAccessor;
+  const restartIndex = getUnsignedMaximum(loopAccessor.componentType);
+
+  validateOffsets(indicesOffsets, triangleIndices.length, 'indicesOffsets');
+  validateOffsets(loopIndicesOffsets, loopIndices.length, 'loopIndicesOffsets');
+
+  const polygons: GLTFPolygon[] = [];
+  for (let polygonIndex = 0; polygonIndex < extension.count; polygonIndex++) {
+    const triangleStart = Number(indicesOffsets[polygonIndex]);
+    const triangleEnd =
+      polygonIndex + 1 < extension.count
+        ? Number(indicesOffsets[polygonIndex + 1])
+        : triangleIndices.length;
+    const loopStart = Number(loopIndicesOffsets[polygonIndex]);
+    const loopEnd =
+      polygonIndex + 1 < extension.count
+        ? Number(loopIndicesOffsets[polygonIndex + 1])
+        : loopIndices.length;
+    const polygonLoopIndices = Array.from(loopIndices).slice(loopStart, loopEnd);
+    const loopRanges = getPrimitiveRestartRanges(polygonLoopIndices, restartIndex).map(range => ({
+      offset: range.offset + loopStart,
+      count: range.count
+    }));
+    if ((triangleEnd - triangleStart) % 3 !== 0) {
+      throw new Error(
+        `${name}: polygon ${polygonIndex} triangle range must contain complete triangles`
+      );
+    }
+    if (loopRanges.length === 0) {
+      throw new Error(`${name}: polygon ${polygonIndex} must contain at least one loop`);
+    }
+    if (loopRanges.some(range => range.count < 3)) {
+      throw new Error(`${name}: polygon ${polygonIndex} loops must contain at least three indices`);
+    }
+    polygons.push({
+      triangleRange: {offset: triangleStart, count: triangleEnd - triangleStart},
+      loopRanges
+    });
+  }
+
+  return {indicesOffsets, loopIndices, loopIndicesOffsets, polygons};
+}
+
+/** Resolve one unsigned scalar accessor with an optional expected count. */
+function getUnsignedScalarAccessor(
+  iterator: GLTFIterator,
+  accessorReference: number | GLTFAccessor,
+  label: string,
+  expectedCount?: number
+): NumericArray {
+  if (
+    typeof accessorReference === 'number' &&
+    (!Number.isInteger(accessorReference) || accessorReference < 0)
+  ) {
+    throw new Error(`${name}: ${label} must reference an accessor`);
+  }
+  const accessor =
+    typeof accessorReference === 'number'
+      ? iterator.data.accessors?.[accessorReference]
+      : accessorReference;
+  if (!accessor) {
+    throw new Error(`${name}: ${label} references missing accessor ${accessorReference}`);
+  }
+  if (accessor.type !== 'SCALAR' || ![5121, 5123, 5125].includes(accessor.componentType)) {
+    throw new Error(`${name}: ${label} must be an unsigned integer SCALAR accessor`);
+  }
+  if (expectedCount !== undefined && accessor.count !== expectedCount) {
+    throw new Error(`${name}: ${label} count must equal polygon count ${expectedCount}`);
+  }
+  return iterator.getTypedArrayForAccessor(accessorReference) as NumericArray;
+}
+
+/** Validate monotonic offsets into an index accessor. */
+function validateOffsets(offsets: NumericArray, targetLength: number, label: string): void {
+  if (Number(offsets[0]) !== 0) {
+    throw new Error(`${name}: ${label} must begin at zero`);
+  }
+  let previousOffset = -1;
+  for (let index = 0; index < offsets.length; index++) {
+    const offset = Number(offsets[index]);
+    if (
+      !Number.isInteger(offset) ||
+      offset < 0 ||
+      offset >= targetLength ||
+      offset <= previousOffset
+    ) {
+      throw new Error(`${name}: ${label} must contain increasing in-bounds offsets`);
+    }
+    previousOffset = offset;
+  }
+}
+
+/** Return the maximum value of an unsigned glTF accessor component type. */
+function getUnsignedMaximum(componentType: number): number {
+  switch (componentType) {
+    case 5121:
+      return 0xff;
+    case 5123:
+      return 0xffff;
+    case 5125:
+      return 0xffffffff;
+    default:
+      throw new Error(`${name}: unsupported loop index component type ${componentType}`);
+  }
+}

package/src/gltf/lib/extensions/EXT_meshopt_compression.ts

@@ -0,0 +1,33 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFLoaderOptions} from '../../gltf-loader-types';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import {decodeMeshoptCompression} from './meshopt-compression';
+
+/**
+ * Exact glTF identifier for the ratified vendor meshopt buffer-view compression extension.
+ *
+ * This identifier remains supported for existing assets alongside the newer
+ * `KHR_meshopt_compression` identifier.
+ */
+export const name = 'EXT_meshopt_compression';
+
+/**
+ * Decodes all `EXT_meshopt_compression` buffer views in a loaded glTF document.
+ *
+ * Processing is a no-op unless both `options.gltf.loadBuffers` and
+ * `options.gltf.decompressMeshes` are enabled. EXT streams use version 0 and the original four
+ * post-decode filters; the maintained decoder is shared with KHR processing without changing the
+ * EXT capability contract.
+ *
+ * @param gltfData Parsed glTF JSON together with its resolved source and destination buffers.
+ * @param options glTF loader options controlling buffer loading and mesh decompression.
+ * @returns A promise that resolves after all EXT meshopt buffer views have been decoded.
+ * @throws If KHR and EXT meshopt declarations are mixed on the same buffer view or buffer, or if a
+ * compressed stream is malformed.
+ */
+export async function decode(gltfData: GLTFWithBuffers, options: GLTFLoaderOptions): Promise<void> {
+  await decodeMeshoptCompression(gltfData, options, name);
+}

package/src/gltf/lib/extensions/EXT_primitive_voxels.ts

@@ -0,0 +1,85 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import type {GLTF, GLTFMeshPrimitive} from '../types/gltf-json-schema';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import type {
+  GLTF_EXT_primitive_voxels,
+  GLTFVoxelPrimitive
+} from '../types/gltf-ext-vector-voxel-schema';
+
+/** Voxel primitive extension name. */
+export const name = 'EXT_primitive_voxels';
+
+/** Validates and preserves lazy voxel primitive declarations. */
+export async function decode(gltfData: GLTFWithBuffers): Promise<void> {
+  for (const [meshIndex, mesh] of (gltfData.json.meshes || []).entries()) {
+    for (const [primitiveIndex, primitive] of mesh.primitives.entries()) {
+      const extension = primitive.extensions?.[name] as GLTF_EXT_primitive_voxels | undefined;
+      if (extension)
+        validateVoxelPrimitive(gltfData.json, primitive, extension, meshIndex, primitiveIndex);
+    }
+  }
+}
+
+/** Returns normalized lazy voxel descriptors without allocating dense volumes. */
+export function getVoxelPrimitives(gltf: GLTF | GLTFWithBuffers): GLTFVoxelPrimitive[] {
+  const json: GLTF = 'json' in gltf ? (gltf as GLTFWithBuffers).json : (gltf as GLTF);
+  const descriptors: GLTFVoxelPrimitive[] = [];
+  for (const [meshIndex, mesh] of (json.meshes || []).entries()) {
+    for (const [primitiveIndex, primitive] of mesh.primitives.entries()) {
+      const extension = primitive.extensions?.[name] as GLTF_EXT_primitive_voxels | undefined;
+      if (extension) {
+        descriptors.push({
+          meshIndex,
+          primitiveIndex,
+          attributes: {...primitive.attributes},
+          extension
+        });
+      }
+    }
+  }
+  return descriptors;
+}
+
+/** Validates shape, dimensions, mode, and accessor references for a lazy voxel primitive. */
+function validateVoxelPrimitive(
+  gltf: GLTF,
+  primitive: GLTFMeshPrimitive,
+  extension: GLTF_EXT_primitive_voxels,
+  meshIndex: number,
+  primitiveIndex: number
+): void {
+  if (!Number.isInteger(extension.shape) || extension.shape < 0) {
+    throw new Error(
+      `EXT_primitive_voxels: mesh ${meshIndex} primitive ${primitiveIndex} has invalid shape.`
+    );
+  }
+  if (
+    !Array.isArray(extension.dimensions) ||
+    extension.dimensions.length !== 3 ||
+    extension.dimensions.some(value => !Number.isInteger(value) || value <= 0)
+  ) {
+    throw new Error(
+      `EXT_primitive_voxels: mesh ${meshIndex} primitive ${primitiveIndex} must provide three positive dimensions.`
+    );
+  }
+  if (primitive.mode !== undefined && primitive.mode !== 2147483647) {
+    throw new Error(
+      `EXT_primitive_voxels: mesh ${meshIndex} primitive ${primitiveIndex} must use voxel mode.`
+    );
+  }
+  for (const attributeName of Object.keys(primitive.attributes)) {
+    const accessorIndex = primitive.attributes[attributeName];
+    if (
+      !Number.isInteger(accessorIndex) ||
+      accessorIndex < 0 ||
+      accessorIndex >= (gltf.accessors || []).length
+    ) {
+      throw new Error(
+        `EXT_primitive_voxels: mesh ${meshIndex} primitive ${primitiveIndex} has invalid accessor ${attributeName}.`
+      );
+    }
+  }
+}