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

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

@@ -2,13 +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. */
@@ -21,22 +37,26 @@ 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};
     featureTableJson?: Record<string, unknown>;
   },
   mesh: MeshGeometry,
-  options?: MeshSourceFeatureOptions
+  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
@@ -51,19 +71,22 @@ export function extractMeshFeatures(
   if (!options)
     throw new TileConversionError(
       'MESH_FEATURE_SCHEMA_REQUIRED',
-      'Feature extraction requires an explicit Arrow schema and class mapping'
+      'Feature extraction requires a class selection and a declared Arrow or inline source schema'
     );
   if (!options.metadataClass)
     throw new TileConversionError(
       'MESH_FEATURE_CLASS_REQUIRED',
       'Feature metadata class must be explicit'
     );
+  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 ||
@@ -75,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 ||
@@ -86,15 +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;
-    properties = {};
+    // 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 must fit uint32 indices'
+      );
+    }
+    properties = Object.create(null);
     const classProperties = metadata.schema?.classes?.[table.class]?.properties;
     if (!classProperties)
       throw new TileConversionError(
@@ -110,6 +146,7 @@ export function extractMeshFeatures(
       string,
       {
         type: string;
+        required?: boolean;
         componentType?: string;
         array?: boolean;
         noData?: unknown;
@@ -141,18 +178,36 @@ export function extractMeshFeatures(
           `Property ${name} requires a separately qualified semantic mapping`
         );
       const data = column?.data;
-      if (data === undefined && property.default === undefined)
+      if (
+        (column !== undefined && (data === undefined || data === null)) ||
+        (data === undefined && property.required === true)
+      )
         throw new TileConversionError(
           'MESH_FEATURE_PROPERTY_UNAVAILABLE',
           `Property ${name} has not been decoded`
         );
-      const decoded = data ?? Array.from({length: count}, () => property.default);
+      const integer64 = ['INT64', 'UINT64'].includes(property.componentType || '');
+      if (
+        integer64 &&
+        property.default !== undefined &&
+        (typeof property.default !== 'number' || !Number.isSafeInteger(property.default))
+      ) {
+        throw new TileConversionError(
+          'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+          `Property ${name} requires an exact 64-bit default`
+        );
+      }
+      const defaultValue =
+        integer64 && property.default !== undefined
+          ? BigInt(property.default as number)
+          : (property.default ?? null);
+      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;
-      const integer64 = ['INT64', 'UINT64'].includes(property.componentType || '');
       if (
         (property.type === 'STRING'
           ? typeof sentinel !== 'string'
@@ -168,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 ? (property.default ?? null) : value
-      );
+      const values = decoded as ArrayLike<unknown>;
+      properties[name] = values;
+      propertyMappings.set(name, {noData: comparable, defaultValue});
     }
   } else {
     if (metadata)
@@ -181,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) ||
@@ -188,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(
@@ -215,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]])
-      )
-    })),
-    options
-  );
   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

@@ -0,0 +1,140 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+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';
+
+/** Class and identifier selection for a mapping derived from an inline glTF schema. */
+export type MeshSourceSchemaOptions = Omit<MeshSourceFeatureOptions, 'schema' | 'rawMetadataField'>;
+
+/** Declared scalar storage widths; no property values participate in type selection. */
+const SCALAR_TYPES: Readonly<Record<string, DataType>> = {
+  INT8: 'int8',
+  UINT8: 'uint8',
+  INT16: 'int16',
+  UINT16: 'uint16',
+  INT32: 'int32',
+  UINT32: 'uint32',
+  INT64: 'int64',
+  UINT64: 'uint64',
+  FLOAT32: 'float32',
+  FLOAT64: 'float64'
+};
+
+/**
+ * Builds an explicit Arrow mapping from one inline structural-metadata class and property table.
+ * Scalar widths, strings and optional/default/noData declarations are retained. The caller selects
+ * the class and stable identifier property; otherwise identifiers are uint32 table row indices.
+ * Arrays, enums, vectors, transformed numeric properties and external schemas fail explicitly.
+ * This does not authorize destination type changes or loss of source class semantics.
+ */
+export function createMeshSourceFeatureOptions(
+  gltf: GLTF,
+  options: MeshSourceSchemaOptions
+): MeshSourceFeatureOptions {
+  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 (
+    !options.metadataClass ||
+    metadata?.propertyTables?.length !== 1 ||
+    table?.class !== options.metadataClass ||
+    !properties ||
+    !Number.isSafeInteger(table.count) ||
+    table.count < 1 ||
+    table.count > 0xffffffff ||
+    metadata.propertyTextures?.length ||
+    metadata.propertyAttributes?.length
+  ) {
+    throw new TileConversionError(
+      'MESH_FEATURE_SCHEMA_REQUIRED',
+      'Schema mapping requires one inline class, one matching property table and a positive uint32 row count'
+    );
+  }
+  if (Object.keys(table.properties || {}).some(name => !Object.hasOwn(properties, name))) {
+    throw new TileConversionError(
+      'MESH_FEATURE_PROPERTY_UNMAPPED',
+      'Property table columns must be declared in the selected class'
+    );
+  }
+  const fields: Field[] = Object.entries(properties).map(([name, property]) => {
+    const declaration = property as GLTF_EXT_structural_metadata_ClassProperty;
+    const column = table.properties?.[name];
+    if (
+      declaration.array ||
+      !['SCALAR', 'STRING'].includes(declaration.type) ||
+      declaration.normalized ||
+      declaration.offset !== undefined ||
+      declaration.scale !== undefined ||
+      column?.offset !== undefined ||
+      column?.scale !== undefined ||
+      (declaration.required &&
+        (declaration.noData !== undefined || declaration.default !== undefined))
+    ) {
+      throw new TileConversionError(
+        'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+        `Property ${name} requires an explicit separately qualified mapping`
+      );
+    }
+    const type =
+      declaration.type === 'STRING'
+        ? 'utf8'
+        : Object.hasOwn(SCALAR_TYPES, declaration.componentType || '')
+          ? SCALAR_TYPES[declaration.componentType!]
+          : undefined;
+    if (!type) {
+      throw new TileConversionError(
+        'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+        `Property ${name} has no supported declared scalar width`
+      );
+    }
+    return {
+      name,
+      type,
+      nullable: declaration.required !== true,
+      metadata: {'loaders.gl:structural-property': JSON.stringify(declaration)}
+    };
+  });
+  const identifierName = options.featureIdField || 'feature_id';
+  const sourceIdentifier = options.sourceFeatureIdProperty;
+  const sourceField = sourceIdentifier
+    ? fields.find(field => field.name === sourceIdentifier)
+    : undefined;
+  if (
+    (sourceIdentifier && !sourceField) ||
+    fields.some(field => field.name === identifierName && field !== sourceField) ||
+    (sourceField &&
+      !['utf8', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', 'uint64'].includes(
+        String(sourceField.type)
+      ))
+  ) {
+    throw new TileConversionError(
+      'MESH_FEATURE_ID_PROPERTY_REQUIRED',
+      'Select a declared string/integer identifier and a distinct output identifier name'
+    );
+  }
+  return {
+    ...options,
+    schema: {
+      fields: [
+        {
+          ...sourceField,
+          name: identifierName,
+          type: sourceField?.type || 'uint32',
+          nullable: false
+        },
+        ...fields.filter(field => field !== sourceField)
+      ],
+      metadata: {'loaders.gl:source-schema': JSON.stringify(metadata.schema)}
+    }
+  };
+}

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);
 }