@loaders.gl/tile-converter 4.5.3 → 5.0.0-alpha.10

package/src/v5/mesh-conversion.ts

@@ -0,0 +1,200 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getSpatialCoordinateFrame} from '@loaders.gl/tiles';
+import type {TilesetSpatialReference} from '@loaders.gl/tiles';
+import type {MeshGeometry} from '@loaders.gl/schema';
+import type {LoadLibraryOptions} from '@loaders.gl/worker-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {TileConversionCodec} from '@loaders.gl/tile-converter/v5/core';
+import type {Tiles3DConversionSpatialContext} from '@loaders.gl/tile-converter/v5/core';
+import {encodeMeshTile, validateMeshGeometry} from './mesh.js';
+import type {MeshTileMaterial} from './mesh.js';
+import {encodeDracoMeshTile} from './mesh-draco.js';
+
+/** Explicitly selected geometry, with positions already in the spatial context's source frame. */
+export interface MeshConversionInput {
+  /** Caller-owned resource identifier, forwarded to the output sink. */
+  readonly id: string;
+  /** Triangle geometry with absolute packed Float32 or Float64 source positions. */
+  readonly mesh: MeshGeometry;
+  /** Optional single material with an embedded base-color image, mapped explicitly by the source adapter. */
+  readonly material?: MeshTileMaterial;
+  /** Finite xyz origin in the target frame, subtracted before float32 encoding. */
+  readonly origin: readonly [number, number, number];
+}
+
+/** A completed GLB resource and the metadata needed to place its local geometry. */
+export interface EncodedMeshConversionResource {
+  /** Caller-owned resource identifier. */
+  readonly id: string;
+  /** Self-contained GLB with local positions and transformed normals. */
+  readonly glb: ArrayBuffer;
+  /** Target-frame translation to add to the encoded positions. */
+  readonly origin: readonly [number, number, number];
+  /** Target-frame bounds of the reconstructed encoded vertices, including float32 rounding. */
+  readonly boundingBox: readonly [readonly number[], readonly number[]];
+  /** Bounds of encoded local vertices before adding the origin, without absolute-coordinate cancellation. */
+  readonly localBoundingBox: readonly [readonly number[], readonly number[]];
+  /** Metadata describing the output coordinate operation and height reference. */
+  readonly spatialReference: TilesetSpatialReference;
+  /** Largest measured Euclidean reconstruction error in target coordinate units. */
+  readonly maximumPositionError: number;
+}
+
+/** Spatial policy used by the concrete mesh conversion codec. */
+export interface MeshConversionCodecOptions {
+  /** Shared context that accepts absolute source positions and returns absolute target positions. */
+  readonly spatialContext: Tiles3DConversionSpatialContext;
+  /** Maximum Euclidean reconstruction error per vertex, in target coordinate units. */
+  readonly maxPositionError: number;
+  /** Lossless Draco Edge Breaker is enabled by default; false emits uncompressed GLB geometry. */
+  readonly draco?: boolean;
+  /** Optional local/CDN library locations or injected Draco runtimes for compression and verification. */
+  readonly dracoLibraryOptions?: LoadLibraryOptions;
+}
+
+/**
+ * Creates a concrete mesh codec for `convertTileset`.
+ *
+ * Source adapters must select geometry and apply source placement before supplying absolute
+ * positions and matching normals. This codec applies the supplied spatial context once, rebases
+ * around each input's target origin, and rejects rounding above the explicit error budget.
+ * Lossless Draco Edge Breaker is enabled by default; decoded positions determine output bounds.
+ * Set draco to false for uncompressed geometry. Quantization is not enabled by this profile.
+ * Geographic and unknown output frames are rejected. The returned origin/bounds/reference are
+ * external placement metadata; applications own axis conventions, hierarchy, and packaging.
+ * Input arrays are not mutated. Core input/output byte gates, cancellation, awaited writes, and
+ * destination finalize/abort handling apply when used through `convertTileset`.
+ *
+ * @param options - Resolved spatial context and finite nonnegative target-unit precision budget.
+ * @returns One GLB and matching metadata per input geometry.
+ */
+export function createMeshConversionCodec<TInspection = unknown>(
+  options: MeshConversionCodecOptions
+): TileConversionCodec<TInspection, MeshConversionInput, EncodedMeshConversionResource> {
+  const {spatialContext, maxPositionError, draco = true, dracoLibraryOptions} = options;
+  if (typeof draco !== 'boolean') {
+    throw new TileConversionError('MESH_DRACO_OPTIONS_INVALID', 'draco must be a boolean');
+  }
+  if (!Number.isFinite(maxPositionError) || maxPositionError < 0) {
+    throw new TileConversionError(
+      'MESH_PRECISION_LIMIT_INVALID',
+      'maxPositionError must be finite and nonnegative'
+    );
+  }
+  const spatialReference = spatialContext.spatialReference;
+  const outputCrs = spatialReference.targetCrs || spatialReference.sourceCrs;
+  const outputFrame =
+    spatialReference.status === 'native'
+      ? spatialReference.coordinateFrame
+      : outputCrs
+        ? getSpatialCoordinateFrame(outputCrs)
+        : 'unknown';
+  if (
+    !['native', 'transformed'].includes(spatialReference.status) ||
+    !['projected', 'geocentric', 'local', 'cartesian'].includes(outputFrame)
+  ) {
+    throw new TileConversionError(
+      'MESH_OUTPUT_FRAME_UNSUPPORTED',
+      'Mesh output requires a resolved Cartesian coordinate frame'
+    );
+  }
+  return {
+    /** Prepares and encodes one geometry while honoring cancellation. */
+    async *convert(resource, _inspection, signal) {
+      signal?.throwIfAborted();
+      if ('features' in resource && resource.features) {
+        throw new TileConversionError(
+          'MESH_FEATURE_OUTPUT_UNSUPPORTED',
+          'The GLB codec requires an explicit feature metadata writer; use the I3S codec for supported feature-bearing meshes'
+        );
+      }
+      const geometry = validateMeshGeometry(resource.mesh, true);
+      const sourcePositions = geometry.attributes.POSITION.value;
+      const origin: [number, number, number] = [...resource.origin];
+      if (origin.length !== 3 || origin.some(value => !Number.isFinite(value))) {
+        throw new TileConversionError(
+          'MESH_ORIGIN_INVALID',
+          'Target origin must contain three finite coordinates'
+        );
+      }
+      const targetPositions = spatialContext.transformPositions(sourcePositions);
+      if (
+        targetPositions.length !== sourcePositions.length ||
+        targetPositions.some(value => !Number.isFinite(value))
+      ) {
+        throw new TileConversionError(
+          'MESH_TRANSFORM_INVALID',
+          'Spatial transformation must return one finite xyz position per vertex'
+        );
+      }
+      const localPositions = new Float32Array(targetPositions.length);
+      const minimum = [Infinity, Infinity, Infinity];
+      const maximum = [-Infinity, -Infinity, -Infinity];
+      const localMinimum = [Infinity, Infinity, Infinity];
+      const localMaximum = [-Infinity, -Infinity, -Infinity];
+      let maximumPositionError = 0;
+      for (let index = 0; index < targetPositions.length; index += 3) {
+        for (let axis = 0; axis < 3; axis++) {
+          localPositions[index + axis] = targetPositions[index + axis] - origin[axis];
+        }
+        const positionError = Math.hypot(
+          localPositions[index] + origin[0] - targetPositions[index],
+          localPositions[index + 1] + origin[1] - targetPositions[index + 1],
+          localPositions[index + 2] + origin[2] - targetPositions[index + 2]
+        );
+        if (!Number.isFinite(positionError) || positionError > maxPositionError) {
+          throw new TileConversionError(
+            'MESH_POSITION_PRECISION_EXCEEDED',
+            'Float32 mesh positions exceed the configured reconstruction error budget'
+          );
+        }
+        maximumPositionError = Math.max(maximumPositionError, positionError);
+      }
+      geometry.attributes.POSITION = {value: localPositions, size: 3};
+      if (geometry.attributes.NORMAL) {
+        geometry.attributes.NORMAL = {
+          value: spatialContext.transformNormals(geometry.attributes.NORMAL.value, sourcePositions),
+          size: 3
+        };
+      }
+      const appearance = {material: resource.material};
+      const encoded = draco
+        ? await encodeDracoMeshTile(geometry, appearance, dracoLibraryOptions)
+        : {glb: encodeMeshTile(geometry, appearance), positions: localPositions};
+      signal?.throwIfAborted();
+      for (let index = 0; index < encoded.positions.length; index++) {
+        const axis = index % 3;
+        const position = encoded.positions[index];
+        localMinimum[axis] = Math.min(localMinimum[axis], position);
+        localMaximum[axis] = Math.max(localMaximum[axis], position);
+        minimum[axis] = Math.min(minimum[axis], position + origin[axis]);
+        maximum[axis] = Math.max(maximum[axis], position + origin[axis]);
+      }
+      yield {
+        id: resource.id,
+        glb: encoded.glb,
+        origin,
+        boundingBox: [minimum, maximum],
+        localBoundingBox: [localMinimum, localMaximum],
+        spatialReference,
+        maximumPositionError
+      };
+    },
+    /** Reports position rounding authorized by the configured precision budget. */
+    async validateOutput(resource) {
+      return resource.maximumPositionError > 0
+        ? [
+            {
+              code: 'MESH_POSITION_ROUNDING',
+              message: `Encoded positions have up to ${resource.maximumPositionError} target-unit reconstruction error`,
+              severity: 'info' as const,
+              resourceId: resource.id
+            }
+          ]
+        : [];
+    }
+  };
+}

package/src/v5/mesh-draco.ts

@@ -0,0 +1,138 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {DracoLoader, encodeDraco, type DracoMesh} from '@loaders.gl/draco';
+import type {GLTFAccessor} from '@loaders.gl/gltf';
+import type {MeshGeometry} from '@loaders.gl/schema';
+import type {LoadLibraryOptions} from '@loaders.gl/worker-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import {
+  createMeshTileScenegraph,
+  finalizeMeshTileScenegraph,
+  type MeshTileOptions,
+  validateMeshGeometry
+} from './mesh.js';
+
+const DRACO_EXTENSION = 'KHR_draco_mesh_compression';
+
+/** Encodes the validated single-mesh profile with lossless Edge Breaker and no raw fallback. */
+export async function encodeDracoMeshTile(
+  geometry: MeshGeometry,
+  options: MeshTileOptions,
+  libraryOptions: LoadLibraryOptions = {}
+): Promise<{glb: ArrayBuffer; positions: Float32Array}> {
+  geometry = validateMeshGeometry(geometry);
+  // Draco requires explicit faces even when the input triangle list is non-indexed.
+  if (!geometry.indices) {
+    geometry.indices = {
+      size: 1,
+      value: Uint32Array.from(
+        {length: geometry.attributes.POSITION.value.length / 3},
+        (_, index) => index
+      )
+    };
+  }
+  const {modules, useLocalLibraries, CDN: contentDeliveryNetwork} = libraryOptions;
+  const runtimeOptions = {modules, core: {useLocalLibraries, CDN: contentDeliveryNetwork}};
+  const {scenegraph, materialIndex} = createMeshTileScenegraph(options, geometry);
+  const encoded = await encodeDraco(geometry, {
+    ...runtimeOptions,
+    draco: {method: 'MESH_EDGEBREAKER_ENCODING'}
+  });
+  const loaderOptions = {...runtimeOptions, draco: {shape: 'mesh' as const}};
+  const loader = await DracoLoader.preload('', loaderOptions);
+  const decoded = (await loader.parse!(encoded.data, loaderOptions)) as DracoMesh;
+  const positions = decoded.attributes.POSITION.value;
+  if (
+    !(positions instanceof Float32Array) ||
+    positions.length !== encoded.report.pointCount * 3 ||
+    encoded.report.pointCount === 0 ||
+    !decoded.indices ||
+    decoded.indices.value.length !== encoded.report.faceCount * 3 ||
+    encoded.report.faceCount * 3 !==
+      (geometry.indices?.value.length ?? geometry.attributes.POSITION.value.length / 3)
+  ) {
+    throw new TileConversionError(
+      'MESH_DRACO_ENCODING_INVALID',
+      'Draco must preserve the triangle count and emit finite positions'
+    );
+  }
+  // Lossy quantization is deliberately unavailable in this initial profile.
+  const inputPositions = geometry.attributes.POSITION.value;
+  const positionKeys = new Set<string>();
+  for (let index = 0; index < inputPositions.length; index += 3) {
+    positionKeys.add(getPositionKey(inputPositions, index));
+  }
+  for (let index = 0; index < positions.length; index += 3) {
+    if (!positionKeys.has(getPositionKey(positions, index))) {
+      throw new TileConversionError(
+        'MESH_DRACO_POSITION_CHANGED',
+        'Lossless Draco must preserve the encoded Float32 positions'
+      );
+    }
+  }
+  const bufferView = scenegraph.addBufferView(encoded.data);
+  const attributes: Record<string, number> = {};
+  const attributeIdentifiers: Record<string, number> = {};
+  scenegraph.json.accessors = [];
+  for (const [name, attribute] of Object.entries(geometry.attributes)) {
+    const decodedAttribute = decoded.attributes[name];
+    if (
+      !decodedAttribute ||
+      decodedAttribute.value.length !== encoded.report.pointCount * attribute.size
+    ) {
+      throw new TileConversionError('MESH_DRACO_ENCODING_INVALID', `Draco must preserve ${name}`);
+    }
+    const accessor: GLTFAccessor = {
+      componentType:
+        attribute.value instanceof Uint8Array
+          ? 5121
+          : attribute.value instanceof Uint16Array
+            ? 5123
+            : 5126,
+      count: encoded.report.pointCount,
+      type: attribute.size === 2 ? 'VEC2' : attribute.size === 3 ? 'VEC3' : 'VEC4',
+      ...(attribute.normalized ? {normalized: true} : {})
+    };
+    if (name === 'POSITION') {
+      const minimum = [Infinity, Infinity, Infinity];
+      const maximum = [-Infinity, -Infinity, -Infinity];
+      for (let index = 0; index < positions.length; index++) {
+        const axis = index % 3;
+        minimum[axis] = Math.min(minimum[axis], positions[index]);
+        maximum[axis] = Math.max(maximum[axis], positions[index]);
+      }
+      accessor.min = minimum;
+      accessor.max = maximum;
+    }
+    attributes[name] = scenegraph.json.accessors.push(accessor) - 1;
+    attributeIdentifiers[name] = encoded.report.attributes[name].id;
+  }
+  const indices =
+    scenegraph.json.accessors.push({
+      componentType: decoded.indices.value instanceof Uint16Array ? 5123 : 5125,
+      count: encoded.report.faceCount * 3,
+      type: 'SCALAR'
+    }) - 1;
+  scenegraph.json.meshes = [
+    {
+      primitives: [
+        {
+          attributes,
+          indices,
+          mode: 4,
+          ...(materialIndex === undefined ? {} : {material: materialIndex}),
+          extensions: {[DRACO_EXTENSION]: {bufferView, attributes: attributeIdentifiers}}
+        }
+      ]
+    }
+  ];
+  scenegraph.registerRequiredExtension(DRACO_EXTENSION);
+  return {glb: finalizeMeshTileScenegraph(scenegraph, 0), positions};
+}
+
+/** Identifies one exact finite Float32 position independently of Draco vertex ordering. */
+function getPositionKey(positions: ArrayLike<number>, index: number): string {
+  return `${positions[index]},${positions[index + 1]},${positions[index + 2]}`;
+}

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

@@ -0,0 +1,232 @@
+// loaders.gl
+// 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 {convertFeatureAttributesToArrowBatches} from './feature-arrow.js';
+import type {FeatureArrowBatchOptions} from './feature-arrow.js';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+
+/** 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. */
+  readonly metadataClass: string;
+  /** Optional source property providing stable identifiers; otherwise row indices are stable within the content. */
+  readonly sourceFeatureIdProperty?: string;
+  /** Explicit I3S representation for 64-bit integers; omission rejects those target fields. */
+  readonly integer64Encoding?: 'decimal-string';
+}
+
+/** Extracts legacy batch tables or one decoded modern property table and validates geometry ownership. */
+export function extractMeshFeatures(
+  gltf: GLTFPostprocessed,
+  primitive: GLTFMeshPrimitivePostprocessed,
+  payload: {
+    batchTableJson?: Record<string, unknown>;
+    header?: {batchLength?: number};
+    featureTableJson?: Record<string, unknown>;
+  },
+  mesh: MeshGeometry,
+  options?: MeshSourceFeatureOptions
+): I3SMeshFeatures | undefined {
+  const declarations = primitive.extensions?.EXT_mesh_features?.featureIds;
+  const metadata = gltf.extensions?.EXT_structural_metadata;
+  const legacy = primitive.attributes._BATCHID;
+  if (
+    !declarations &&
+    !legacy &&
+    !metadata &&
+    !Object.keys(payload.batchTableJson || {}).length &&
+    !payload.header?.batchLength
+  ) {
+    if (Object.keys(primitive.attributes).some(name => /^_FEATURE_ID_\d+$/.test(name)))
+      throw new TileConversionError(
+        'MESH_FEATURE_MAPPING_REQUIRED',
+        'Feature attributes require an EXT_mesh_features declaration'
+      );
+    return undefined;
+  }
+  if (!options)
+    throw new TileConversionError(
+      'MESH_FEATURE_SCHEMA_REQUIRED',
+      'Feature extraction requires an explicit Arrow schema and class mapping'
+    );
+  if (!options.metadataClass)
+    throw new TileConversionError(
+      'MESH_FEATURE_CLASS_REQUIRED',
+      'Feature metadata class must be explicit'
+    );
+  let count: number;
+  let attribute = legacy;
+  let properties: Record<string, ArrayLike<unknown>>;
+  if (declarations) {
+    if (
+      legacy ||
+      declarations.length !== 1 ||
+      metadata?.propertyTables?.length !== 1 ||
+      metadata.propertyTextures?.length ||
+      metadata.propertyAttributes?.length
+    )
+      throw new TileConversionError(
+        'MESH_FEATURE_MAPPING_UNSUPPORTED',
+        'Only one attribute-backed feature set and one property table are supported'
+      );
+    const declaration = declarations[0];
+    if (
+      !Number.isInteger(declaration.attribute) ||
+      declaration.attribute < 0 ||
+      declaration.propertyTable !== 0 ||
+      declaration.texture ||
+      declaration.implicit ||
+      declaration.nullFeatureId !== undefined
+    )
+      throw new TileConversionError(
+        'MESH_FEATURE_MAPPING_UNSUPPORTED',
+        'Features require an attribute and property table 0 without null/texture/implicit IDs'
+      );
+    attribute = primitive.attributes[`_FEATURE_ID_${declaration.attribute}`];
+    const table = metadata.propertyTables[0];
+    if (table.class !== options.metadataClass || table.count !== declaration.featureCount)
+      throw new TileConversionError(
+        'MESH_FEATURE_CLASS_MISMATCH',
+        'Feature class and declared table counts must agree'
+      );
+    count = table.count;
+    properties = {};
+    const classProperties = metadata.schema?.classes?.[table.class]?.properties;
+    if (!classProperties)
+      throw new TileConversionError(
+        'MESH_FEATURE_SCHEMA_REQUIRED',
+        'A decoded inline structural metadata class is required'
+      );
+    if (Object.keys(table.properties || {}).some(name => !Object.hasOwn(classProperties, name)))
+      throw new TileConversionError(
+        'MESH_FEATURE_PROPERTY_UNMAPPED',
+        'Property table columns must be declared in the metadata class'
+      );
+    for (const [name, property] of Object.entries(classProperties) as [
+      string,
+      {
+        type: string;
+        componentType?: string;
+        array?: boolean;
+        noData?: unknown;
+        default?: unknown;
+        normalized?: boolean;
+        offset?: unknown;
+        scale?: unknown;
+      }
+    ][]) {
+      const column = table.properties?.[name];
+      if (
+        !['SCALAR', 'STRING'].includes(property.type) ||
+        property.array ||
+        property.noData !== undefined ||
+        (['INT64', 'UINT64'].includes(property.componentType || '') &&
+          (property.normalized ||
+            property.offset !== undefined ||
+            property.scale !== undefined ||
+            column?.offset !== undefined ||
+            column?.scale !== undefined))
+      )
+        throw new TileConversionError(
+          'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+          `Property ${name} requires a separately qualified semantic mapping`
+        );
+      const data = column?.data;
+      if (data === undefined && property.default === undefined)
+        throw new TileConversionError(
+          'MESH_FEATURE_PROPERTY_UNAVAILABLE',
+          `Property ${name} has not been decoded`
+        );
+      properties[name] = data ?? Array.from({length: count}, () => property.default);
+    }
+  } else {
+    if (metadata)
+      throw new TileConversionError(
+        'MESH_FEATURE_MAPPING_UNSUPPORTED',
+        'Structural metadata requires an attribute-backed feature declaration'
+      );
+    count = payload.header?.batchLength ?? Number(payload.featureTableJson?.BATCH_LENGTH);
+    properties = (payload.batchTableJson as Record<string, ArrayLike<unknown>>) || {};
+  }
+  const vertexCount = mesh.attributes.POSITION.value.length / 3;
+  if (
+    !Number.isSafeInteger(count) ||
+    count <= 0 ||
+    !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
+    )
+  )
+    throw new TileConversionError(
+      'MESH_FEATURE_IDS_INVALID',
+      'Feature IDs must be one valid property-table row index per vertex'
+    );
+  const selectedAttribute = declarations ? `_FEATURE_ID_${declarations[0].attribute}` : '_BATCHID';
+  if (
+    Object.keys(primitive.attributes).some(
+      name => (name === '_BATCHID' || /^_FEATURE_ID_\d+$/.test(name)) && name !== selectedAttribute
+    )
+  )
+    throw new TileConversionError(
+      'MESH_FEATURE_MAPPING_UNSUPPORTED',
+      'Additional feature ID sets require separate mappings'
+    );
+  for (const [name, values] of Object.entries(properties)) {
+    if (
+      !values ||
+      (!Array.isArray(values) && !ArrayBuffer.isView(values)) ||
+      values.length !== count
+    )
+      throw new TileConversionError(
+        'MESH_FEATURE_PROPERTY_UNAVAILABLE',
+        `Property ${name} must be a decoded column matching the table count`
+      );
+  }
+  const sourceIdentifier = options.sourceFeatureIdProperty;
+  if (sourceIdentifier && !properties[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 rows = [0, 1, 2].map(
+      corner => attribute.value[indices?.[triangle * 3 + corner] ?? triangle * 3 + corner]
+    );
+    if (rows.some(row => row !== rows[0]))
+      throw new TileConversionError(
+        'MESH_FEATURE_TRIANGLE_MIXED',
+        'All vertices of a triangle must reference the same feature row'
+      );
+    triangleFeatureIndices[triangle] = Number(rows[0]);
+  }
+  return {
+    batches,
+    triangleFeatureIndices,
+    featureIdField: options.featureIdField || 'feature_id',
+    integer64Encoding: options.integer64Encoding
+  };
+}

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

@@ -0,0 +1,122 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFMaterialPostprocessed, GLTFImagePostprocessed} 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']
+): MeshTileTexture {
+  const texture = textureInfo?.texture;
+  const image = texture?.source;
+  const sampler = texture?.sampler;
+  const extensions = textureInfo?.extensions || {};
+  const hasTransform = Object.hasOwn(extensions, 'KHR_texture_transform');
+  const transform = extensions.KHR_texture_transform;
+  if (
+    !textureInfo ||
+    (textureInfo.texCoord !== undefined && textureInfo.texCoord !== 0) ||
+    Object.keys(extensions).some(name => name !== 'KHR_texture_transform') ||
+    (hasTransform &&
+      (!transform ||
+        typeof transform !== 'object' ||
+        Array.isArray(transform) ||
+        (transform.texCoord !== undefined && transform.texCoord !== 0) ||
+        Object.keys(transform.extensions || {}).length ||
+        Object.keys(transform).some(
+          name =>
+            !['offset', 'rotation', 'scale', 'texCoord', 'extensions', 'extras'].includes(name)
+        ))) ||
+    Object.keys(textureInfo).some(
+      name => !['id', 'index', 'texture', 'texCoord', 'extensions', 'extras'].includes(name)
+    ) ||
+    !texture ||
+    Object.keys(texture).some(
+      name => !['id', 'source', 'sampler', 'name', 'extensions', 'extras'].includes(name)
+    ) ||
+    Object.keys(texture.extensions || {}).length ||
+    !image ||
+    (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/png', 'image/jpeg'].includes(image.mimeType || ''))) ||
+    (sampler &&
+      (Object.keys(sampler.extensions || {}).length ||
+        Object.keys(sampler).some(
+          name =>
+            ![
+              'id',
+              'parameters',
+              'wrapS',
+              'wrapT',
+              'magFilter',
+              'minFilter',
+              'name',
+              'extensions',
+              'extras'
+            ].includes(name)
+        )))
+  ) {
+    throw new TileConversionError(
+      'MESH_SOURCE_TEXTURE_UNSUPPORTED',
+      'Base-color textures require a PNG/JPEG bufferView or base64 data URI, TEXCOORD_0, glTF sampling and an optional KHR_texture_transform on TEXCOORD_0'
+    );
+  }
+  const selectedSampler = sampler
+    ? ({
+        wrapS: sampler.wrapS,
+        wrapT: sampler.wrapT,
+        magFilter: sampler.magFilter,
+        minFilter: sampler.minFilter
+      } as MeshTileSampler)
+    : undefined;
+  return {
+    ...mapMeshSourceImage(image),
+    ...(hasTransform
+      ? {
+          transform: {
+            offset: transform.offset,
+            rotation: transform.rotation,
+            scale: transform.scale
+          } as MeshTileTextureTransform
+        }
+      : {}),
+    ...(selectedSampler && Object.values(selectedSampler).some(value => value !== undefined)
+      ? {sampler: selectedSampler}
+      : {})
+  };
+}
+
+/** Reads self-contained encoded bytes without fetch, pixel decoding, or Node APIs. */
+function mapMeshSourceImage(
+  image: GLTFImagePostprocessed
+): Pick<MeshTileTexture, 'data' | 'mimeType'> {
+  if (image.uri === undefined) {
+    return {data: image.bufferView!.data, mimeType: image.mimeType as MeshTileTexture['mimeType']};
+  }
+  const match =
+    typeof image.uri === 'string'
+      ? /^data:(image\/(?:png|jpeg));base64,([A-Za-z0-9+/]+={0,2})$/.exec(image.uri)
+      : null;
+  if (!match || (image.mimeType !== undefined && image.mimeType !== match[1])) {
+    throw new TileConversionError(
+      'MESH_SOURCE_TEXTURE_UNSUPPORTED',
+      'Inline images require a PNG/JPEG base64 data URI and matching optional mimeType'
+    );
+  }
+  let encodedBytes: string;
+  try {
+    encodedBytes = atob(match[2]);
+  } catch {
+    throw new TileConversionError('MESH_SOURCE_TEXTURE_UNSUPPORTED', 'Invalid inline image base64');
+  }
+  return {
+    data: Uint8Array.from(encodedBytes, character => character.charCodeAt(0)),
+    mimeType: match[1] as MeshTileTexture['mimeType']
+  };
+}