@loaders.gl/tile-converter 5.0.0-alpha.12 → 5.0.0-alpha.14

package/src/v5/mesh-source-features.ts

@@ -2,15 +2,29 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {MeshGeometry} from '@loaders.gl/schema';
-import type {GLTFPostprocessed, GLTFMeshPrimitivePostprocessed} from '@loaders.gl/gltf';
-import type {I3SMeshFeatures} from '@loaders.gl/i3s';
+import type {MeshGeometry} from '@loaders.gl/core/schema';
+import type {
+  GLTFWithBuffers,
+  GLTFMeshPrimitive,
+  GLTF_EXT_mesh_features,
+  GLTF_EXT_structural_metadata_GLTF
+} from '@loaders.gl/gltf';
+import {getGLTFAccessor, getGLTFAccessorValue} from '@loaders.gl/gltf';
+import type {I3SMeshFeatures} from '@loaders.gl/tiles-3d/i3s';
 import {convertFeatureAttributesToArrowBatches} from './feature-arrow.js';
 import type {FeatureArrowBatchOptions} from './feature-arrow.js';
 import {createMeshSourceFeatureOptions} from './mesh-source-schema.js';
 import type {MeshSourceSchemaOptions} from './mesh-source-schema.js';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 
+/** Data-only rule for absent columns and decoded noData values. */
+interface MeshSourcePropertyMapping {
+  /** Value used for an absent column or a decoded noData cell. */
+  readonly defaultValue: unknown;
+  /** Decoded sentinel; omitted for absent-column defaults. */
+  readonly noData?: unknown;
+}
+
 /** Explicit source feature mapping; target type changes must be authorized separately. */
 export interface MeshSourceFeatureOptions extends FeatureArrowBatchOptions {
   /** Batch-table class label, or the exact structural-metadata class to select. */
@@ -23,8 +37,8 @@ export interface MeshSourceFeatureOptions extends FeatureArrowBatchOptions {
 
 /** Extracts legacy batch tables or one decoded modern property table and validates geometry ownership. */
 export function extractMeshFeatures(
-  gltf: GLTFPostprocessed,
-  primitive: GLTFMeshPrimitivePostprocessed,
+  gltf: GLTFWithBuffers,
+  primitive: GLTFMeshPrimitive,
   payload: {
     batchTableJson?: Record<string, unknown>;
     header?: {batchLength?: number};
@@ -33,12 +47,16 @@ export function extractMeshFeatures(
   mesh: MeshGeometry,
   options?: MeshSourceFeatureOptions | MeshSourceSchemaOptions
 ): I3SMeshFeatures | undefined {
-  const declarations = primitive.extensions?.EXT_mesh_features?.featureIds;
-  const metadata = gltf.extensions?.EXT_structural_metadata;
+  const declarations = (
+    primitive.extensions?.EXT_mesh_features as GLTF_EXT_mesh_features | undefined
+  )?.featureIds;
+  const metadata = gltf.json.extensions?.EXT_structural_metadata as
+    | GLTF_EXT_structural_metadata_GLTF
+    | undefined;
   const legacy = primitive.attributes._BATCHID;
   if (
     !declarations &&
-    !legacy &&
+    legacy === undefined &&
     !metadata &&
     !Object.keys(payload.batchTableJson || {}).length &&
     !payload.header?.batchLength
@@ -60,13 +78,15 @@ export function extractMeshFeatures(
       'MESH_FEATURE_CLASS_REQUIRED',
       'Feature metadata class must be explicit'
     );
-  const mapping = 'schema' in options ? options : createMeshSourceFeatureOptions(gltf, options);
+  const mapping =
+    'schema' in options ? options : createMeshSourceFeatureOptions(gltf.json, options);
+  const propertyMappings = new Map<string, MeshSourcePropertyMapping>();
   let count: number;
-  let attribute = legacy;
+  let attributeReference = legacy;
   let properties: Record<string, ArrayLike<unknown>>;
   if (declarations) {
     if (
-      legacy ||
+      legacy !== undefined ||
       declarations.length !== 1 ||
       metadata?.propertyTables?.length !== 1 ||
       metadata.propertyTextures?.length ||
@@ -78,6 +98,7 @@ export function extractMeshFeatures(
       );
     const declaration = declarations[0];
     if (
+      typeof declaration.attribute !== 'number' ||
       !Number.isInteger(declaration.attribute) ||
       declaration.attribute < 0 ||
       declaration.propertyTable !== 0 ||
@@ -89,26 +110,27 @@ export function extractMeshFeatures(
         'MESH_FEATURE_MAPPING_UNSUPPORTED',
         'Features require an attribute and property table 0 without null/texture/implicit IDs'
       );
-    attribute = primitive.attributes[`_FEATURE_ID_${declaration.attribute}`];
+    attributeReference = primitive.attributes[`_FEATURE_ID_${declaration.attribute}`];
     const table = metadata.propertyTables[0];
-    if (table.class !== options.metadataClass || table.count !== declaration.featureCount)
+    if (
+      table.class !== options.metadataClass ||
+      !Number.isSafeInteger(declaration.featureCount) ||
+      declaration.featureCount <= 0 ||
+      declaration.featureCount > table.count
+    )
       throw new TileConversionError(
         'MESH_FEATURE_CLASS_MISMATCH',
-        'Feature class and declared table counts must agree'
+        'Feature class must agree and declared feature count must fit the property table'
       );
     count = table.count;
-    // Qualified mesh writers require every feature row to own geometry. Check before defaults allocate.
-    if (
-      !Number.isSafeInteger(count) ||
-      count <= 0 ||
-      count > mesh.attributes.POSITION.value.length / 3
-    ) {
+    // Source tables may be shared by primitives; dense output indices are uint32.
+    if (!Number.isSafeInteger(count) || count <= 0 || count > 0xffffffff) {
       throw new TileConversionError(
         'MESH_FEATURE_IDS_INVALID',
-        'Feature row count exceeds the available mesh vertices'
+        'Feature row count must fit uint32 indices'
       );
     }
-    properties = {};
+    properties = Object.create(null);
     const classProperties = metadata.schema?.classes?.[table.class]?.properties;
     if (!classProperties)
       throw new TileConversionError(
@@ -179,9 +201,10 @@ export function extractMeshFeatures(
         integer64 && property.default !== undefined
           ? BigInt(property.default as number)
           : (property.default ?? null);
-      const decoded = data ?? Array.from({length: count}, () => defaultValue);
+      const decoded = data;
       if (property.noData === undefined || data === undefined) {
-        properties[name] = decoded;
+        if (decoded !== undefined) properties[name] = decoded as ArrayLike<unknown>;
+        else propertyMappings.set(name, {defaultValue});
         continue;
       }
       const sentinel = property.noData;
@@ -200,9 +223,9 @@ export function extractMeshFeatures(
           `Property ${name} requires a valid decoded noData mapping`
         );
       const comparable = integer64 ? BigInt(sentinel as number) : sentinel;
-      properties[name] = Array.from(decoded as ArrayLike<unknown>, value =>
-        value === comparable ? defaultValue : value
-      );
+      const values = decoded as ArrayLike<unknown>;
+      properties[name] = values;
+      propertyMappings.set(name, {noData: comparable, defaultValue});
     }
   } else {
     if (metadata)
@@ -213,6 +236,15 @@ export function extractMeshFeatures(
     count = payload.header?.batchLength ?? Number(payload.featureTableJson?.BATCH_LENGTH);
     properties = (payload.batchTableJson as Record<string, ArrayLike<unknown>>) || {};
   }
+  const accessor =
+    attributeReference === undefined ? undefined : getGLTFAccessor(gltf, attributeReference);
+  const attribute = accessor
+    ? {
+        ...accessor,
+        components: accessor.type === 'SCALAR' ? 1 : Number(accessor.type.slice(3)),
+        value: getGLTFAccessorValue(gltf, accessor)
+      }
+    : undefined;
   const vertexCount = mesh.attributes.POSITION.value.length / 3;
   if (
     !Number.isSafeInteger(count) ||
@@ -220,15 +252,26 @@ export function extractMeshFeatures(
     !attribute ||
     attribute.components !== 1 ||
     attribute.normalized ||
-    attribute.value.length !== vertexCount ||
-    Array.from(attribute.value as ArrayLike<number>).some(
-      value => !Number.isSafeInteger(value) || value < 0 || value >= count
-    )
+    attribute.value.length !== vertexCount
   )
     throw new TileConversionError(
       'MESH_FEATURE_IDS_INVALID',
       'Feature IDs must be one valid property-table row index per vertex'
     );
+  const vertexRows = declarations ? new Set<number>() : undefined;
+  for (const value of attribute.value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value >= count)
+      throw new TileConversionError(
+        'MESH_FEATURE_IDS_INVALID',
+        'Feature IDs must reference valid property-table rows'
+      );
+    vertexRows?.add(Number(value));
+  }
+  if (declarations && vertexRows!.size !== declarations[0].featureCount)
+    throw new TileConversionError(
+      'MESH_FEATURE_IDS_INVALID',
+      'Declared feature count must match distinct vertex feature IDs'
+    );
   const selectedAttribute = declarations ? `_FEATURE_ID_${declarations[0].attribute}` : '_BATCHID';
   if (
     Object.keys(primitive.attributes).some(
@@ -247,45 +290,84 @@ export function extractMeshFeatures(
     )
       throw new TileConversionError(
         'MESH_FEATURE_PROPERTY_UNAVAILABLE',
-        `Property ${name} must be a decoded column matching the table count`
+        `Property ${name} must be a decoded column matching the feature row count`
       );
   }
   const sourceIdentifier = options.sourceFeatureIdProperty;
-  if (sourceIdentifier && !properties[sourceIdentifier])
+  if (sourceIdentifier && !properties[sourceIdentifier] && !propertyMappings.has(sourceIdentifier))
     throw new TileConversionError(
       'MESH_FEATURE_ID_PROPERTY_REQUIRED',
       'Stable source identifier property is missing'
     );
-  const batches = convertFeatureAttributesToArrowBatches(
-    Array.from({length: count}, (_, index) => ({
-      featureId: (sourceIdentifier ? properties[sourceIdentifier][index] : index) as
-        | string
-        | number
-        | bigint,
-      metadataClass: options.metadataClass,
-      properties: Object.fromEntries(
-        Object.entries(properties)
-          .filter(([name]) => name !== sourceIdentifier)
-          .map(([name, values]) => [name, values[index]])
-      )
-    })),
-    mapping
-  );
   const indices = mesh.indices?.value;
-  const triangleFeatureIndices = new Uint32Array((indices?.length ?? vertexCount) / 3);
-  for (let triangle = 0; triangle < triangleFeatureIndices.length; triangle++) {
-    const corners = [0, 1, 2].map(
-      corner => indices?.[triangle * 3 + corner] ?? triangle * 3 + corner
+  const cornerCount = indices?.length ?? vertexCount;
+  if (cornerCount % 3)
+    throw new TileConversionError(
+      'MESH_FEATURE_IDS_INVALID',
+      'Triangle geometry requires complete triples'
     );
-    const rows = corners.map(corner => attribute.value[corner]);
+  const triangleFeatureIndices = new Uint32Array(cornerCount / 3);
+  const referencedRows = new Set<number>();
+  /** Reads a validated triangle corner without allocating per-triangle arrays. */
+  const readFeatureRow = (corner: number): number => {
+    if (!Number.isSafeInteger(corner) || corner < 0 || corner >= vertexCount)
+      throw new TileConversionError(
+        'MESH_FEATURE_IDS_INVALID',
+        'Triangle indices must reference valid mesh vertices'
+      );
+    return Number(attribute.value[corner]);
+  };
+  for (let triangle = 0; triangle < triangleFeatureIndices.length; triangle++) {
+    const firstCorner = indices?.[triangle * 3] ?? triangle * 3;
+    const secondCorner = indices?.[triangle * 3 + 1] ?? triangle * 3 + 1;
+    const thirdCorner = indices?.[triangle * 3 + 2] ?? triangle * 3 + 2;
+    const firstRow = readFeatureRow(firstCorner);
+    const secondRow = readFeatureRow(secondCorner);
+    const thirdRow = readFeatureRow(thirdCorner);
     // Repeated-index strip connectors have no surface; retain the first corner's feature row.
-    if (rows.some(row => row !== rows[0]) && new Set(corners).size === 3)
+    if (
+      (firstRow !== secondRow || firstRow !== thirdRow) &&
+      firstCorner !== secondCorner &&
+      firstCorner !== thirdCorner &&
+      secondCorner !== thirdCorner
+    )
       throw new TileConversionError(
         'MESH_FEATURE_TRIANGLE_MIXED',
         'All vertices of a nondegenerate triangle must reference the same feature row'
       );
-    triangleFeatureIndices[triangle] = Number(rows[0]);
+    triangleFeatureIndices[triangle] = firstRow;
+    referencedRows.add(firstRow);
   }
+  // Sort once to retain source table order, then materialize only geometry-owned rows.
+  const selectedRows = [...referencedRows].sort((left, right) => left - right);
+  const denseRows = new Map(selectedRows.map((row, index) => [row, index]));
+  for (let triangle = 0; triangle < triangleFeatureIndices.length; triangle++) {
+    triangleFeatureIndices[triangle] = denseRows.get(triangleFeatureIndices[triangle])!;
+  }
+  /** Reads one referenced source value without expanding defaults or noData columns. */
+  const readProperty = (name: string, row: number): unknown => {
+    const values = properties[name];
+    const propertyMapping = propertyMappings.get(name);
+    if (!values) return propertyMapping?.defaultValue;
+    const value = values[row];
+    return propertyMapping && value === propertyMapping.noData
+      ? propertyMapping.defaultValue
+      : value;
+  };
+  const propertyNames = [
+    ...new Set([...Object.keys(properties), ...propertyMappings.keys()])
+  ].filter(name => name !== sourceIdentifier);
+  const batches = convertFeatureAttributesToArrowBatches(
+    selectedRows.map(row => ({
+      featureId: (sourceIdentifier ? readProperty(sourceIdentifier, row) : row) as
+        | string
+        | number
+        | bigint,
+      metadataClass: options.metadataClass,
+      properties: Object.fromEntries(propertyNames.map(name => [name, readProperty(name, row)]))
+    })),
+    mapping
+  );
   return {
     batches,
     triangleFeatureIndices,

package/src/v5/mesh-source-schema.ts

@@ -2,8 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {GLTFPostprocessed, GLTF_EXT_structural_metadata_ClassProperty} from '@loaders.gl/gltf';
-import type {DataType, Field} from '@loaders.gl/schema';
+import type {
+  GLTF,
+  GLTF_EXT_structural_metadata_ClassProperty,
+  GLTF_EXT_structural_metadata_GLTF
+} from '@loaders.gl/gltf';
+import type {DataType, Field} from '@loaders.gl/core/schema';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 import type {MeshSourceFeatureOptions} from './mesh-source-features.js';
 
@@ -32,10 +36,12 @@ const SCALAR_TYPES: Readonly<Record<string, DataType>> = {
  * This does not authorize destination type changes or loss of source class semantics.
  */
 export function createMeshSourceFeatureOptions(
-  gltf: GLTFPostprocessed,
+  gltf: GLTF,
   options: MeshSourceSchemaOptions
 ): MeshSourceFeatureOptions {
-  const metadata = gltf.extensions?.EXT_structural_metadata;
+  const metadata = gltf.extensions?.EXT_structural_metadata as
+    | GLTF_EXT_structural_metadata_GLTF
+    | undefined;
   const table = metadata?.propertyTables?.[0];
   const properties = metadata?.schema?.classes?.[options.metadataClass]?.properties;
   if (

package/src/v5/mesh-source-texture.ts

@@ -3,17 +3,20 @@
 // Copyright (c) vis.gl contributors
 
 import {getBinaryImageMetadata} from '@loaders.gl/images';
-import type {GLTFMaterialPostprocessed, GLTFImagePostprocessed} from '@loaders.gl/gltf';
+import type {GLTFMaterial, GLTFImage, GLTFWithBuffers} from '@loaders.gl/gltf';
+import {GLTFScenegraph} from '@loaders.gl/gltf';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 import type {MeshTileSampler, MeshTileTexture, MeshTileTextureTransform} from './mesh.js';
 
 /** Maps a buffer-view or base64 PNG/JPEG image, sampling and UV transform without decoding pixels. */
 export function mapMeshSourceTexture(
-  textureInfo: NonNullable<GLTFMaterialPostprocessed['pbrMetallicRoughness']>['baseColorTexture']
+  gltf: GLTFWithBuffers,
+  textureInfo: NonNullable<GLTFMaterial['pbrMetallicRoughness']>['baseColorTexture']
 ): MeshTileTexture {
-  const texture = textureInfo?.texture;
-  const image = texture?.source;
-  const sampler = texture?.sampler;
+  const texture = textureInfo ? gltf.json.textures?.[textureInfo.index] : undefined;
+  const image = texture?.source === undefined ? undefined : gltf.json.images?.[texture.source];
+  const sampler =
+    texture?.sampler === undefined ? undefined : gltf.json.samplers?.[texture.sampler];
   const extensions = textureInfo?.extensions || {};
   const hasTransform = Object.hasOwn(extensions, 'KHR_texture_transform');
   const transform = extensions.KHR_texture_transform;
@@ -43,8 +46,9 @@ export function mapMeshSourceTexture(
     (image.uri !== undefined && image.bufferView !== undefined) ||
     Object.keys(image.extensions || {}).length ||
     (image.uri === undefined &&
-      (!(image.bufferView?.data instanceof Uint8Array) ||
-        Object.keys(image.bufferView.extensions || {}).length ||
+      (image.bufferView === undefined ||
+        !gltf.json.bufferViews?.[image.bufferView] ||
+        Object.keys(gltf.json.bufferViews?.[image.bufferView!]?.extensions || {}).length ||
         !['image/png', 'image/jpeg'].includes(image.mimeType || ''))) ||
     (sampler &&
       (Object.keys(sampler.extensions || {}).length ||
@@ -77,7 +81,7 @@ export function mapMeshSourceTexture(
       } as MeshTileSampler)
     : undefined;
   return {
-    ...mapMeshSourceImage(image),
+    ...mapMeshSourceImage(gltf, image),
     ...(hasTransform
       ? {
           transform: {
@@ -95,10 +99,14 @@ export function mapMeshSourceTexture(
 
 /** Reads self-contained encoded bytes without fetch, pixel decoding, or Node APIs. */
 function mapMeshSourceImage(
-  image: GLTFImagePostprocessed
+  gltf: GLTFWithBuffers,
+  image: GLTFImage
 ): Pick<MeshTileTexture, 'data' | 'mimeType'> {
   if (image.uri === undefined) {
-    return {data: image.bufferView!.data, mimeType: image.mimeType as MeshTileTexture['mimeType']};
+    return {
+      data: new GLTFScenegraph(gltf).getTypedArrayForBufferView(image.bufferView!),
+      mimeType: image.mimeType as MeshTileTexture['mimeType']
+    };
   }
   const match =
     typeof image.uri === 'string'
@@ -124,16 +132,18 @@ function mapMeshSourceImage(
 
 /** Resolves one external encoded image through an explicitly supplied application reader. */
 export async function resolveMeshSourceTexture(
-  textureInfo: NonNullable<GLTFMaterialPostprocessed['pbrMetallicRoughness']>['baseColorTexture'],
+  gltf: GLTFWithBuffers,
+  textureInfo: NonNullable<GLTFMaterial['pbrMetallicRoughness']>['baseColorTexture'],
   readExternalResource:
     | ((uri: string, contentUri: string | undefined, signal?: AbortSignal) => Promise<Uint8Array>)
     | undefined,
   contentUri: string | undefined,
   signal?: AbortSignal
 ): Promise<MeshTileTexture> {
-  const image = textureInfo?.texture?.source;
+  const texture = textureInfo ? gltf.json.textures?.[textureInfo.index] : undefined;
+  const image = texture?.source === undefined ? undefined : gltf.json.images?.[texture.source];
   if (!image || image.uri === undefined || image.uri.startsWith('data:'))
-    return mapMeshSourceTexture(textureInfo);
+    return mapMeshSourceTexture(gltf, textureInfo);
   if (!readExternalResource || image.bufferView !== undefined)
     throw new TileConversionError(
       'MESH_SOURCE_TEXTURE_UNSUPPORTED',
@@ -158,12 +168,32 @@ export async function resolveMeshSourceTexture(
       'External images require matching PNG/JPEG headers'
     );
   // Select encoded bytes without decoding pixels or modifying the caller-owned glTF image.
-  const resolved = {
-    ...textureInfo,
-    texture: {
-      ...textureInfo!.texture,
-      source: {...image, uri: undefined, mimeType: metadata.mimeType, bufferView: {data}}
+  const resolvedImage = {
+    ...image,
+    uri: undefined,
+    mimeType: metadata.mimeType,
+    bufferView: (gltf.json.bufferViews || []).length
+  };
+  const resolved: GLTFWithBuffers = {
+    ...gltf,
+    buffers: [
+      ...gltf.buffers,
+      {
+        arrayBuffer: data.buffer as ArrayBuffer,
+        byteOffset: data.byteOffset,
+        byteLength: data.byteLength
+      }
+    ],
+    json: {
+      ...gltf.json,
+      images: gltf.json.images!.map((entry, index) =>
+        index === texture!.source ? resolvedImage : entry
+      ),
+      bufferViews: [
+        ...(gltf.json.bufferViews || []),
+        {buffer: gltf.buffers.length, byteLength: data.byteLength}
+      ]
     }
   };
-  return mapMeshSourceTexture(resolved as typeof textureInfo);
+  return mapMeshSourceTexture(resolved, textureInfo);
 }