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

package/src/v5/point-cloud-tileset-sink.ts

@@ -0,0 +1,234 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  createBoundedMemoryTileConversionSink,
+  TileConversionError
+} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  BrowserTileConversionFile,
+  TileConversionSink
+} from '@loaders.gl/tile-converter/v5/core';
+import type {EncodedPointCloudSourceTile} from './point-cloud-source-encoder.js';
+
+/** Output limits and geometric error for independent ECEF point tiles. */
+export interface PointCloudTilesetSinkOptions {
+  /** Maximum retained PNTS and tileset JSON bytes, excluding peak serialization memory. */
+  readonly maxTotalBytes: number;
+  /** Maximum independent tile placements retained by the sink. */
+  readonly maxTiles: number;
+  /** Leaf error in meters, including source sampling error and measured position rounding. */
+  readonly geometricError: number;
+}
+
+/** Atomic flat 3D Tiles package suitable for the existing 3TZ archive adapter. */
+export interface PointCloudTilesetSink extends TileConversionSink<EncodedPointCloudSourceTile> {
+  /** Returns named PNTS files and tileset.json after successful finalization; empty after abort. */
+  getFiles(): readonly BrowserTileConversionFile[];
+}
+
+/**
+ * Packages independent point tiles as a bounded 3D Tiles 1.0 collection with an ADD root.
+ * Requires unmodified encoder outputs in declared EPSG:4978 xyz meters and ellipsoidal heights,
+ * cartesian positions, zero source origin and no additional placement transform. PNTS RTC_CENTER
+ * is already encoded and is applied once to bounds. Geographic/projected/offset source frames
+ * must be converted before this sink. This authors a flat partial dataset, not source LOD;
+ * callers must select independent, non-overlapping samples and supply their sampling error.
+ * Use createTileConversionArchive with format 3tz to package the finalized files.
+ * @param options - Retained byte/tile limits and explicit leaf geometric error.
+ * @returns A sink exposing the completed package atomically.
+ */
+export function createPointCloudTilesetSink(
+  options: PointCloudTilesetSinkOptions
+): PointCloudTilesetSink {
+  const {maxTiles, geometricError} = options;
+  if (
+    !Number.isSafeInteger(maxTiles) ||
+    maxTiles < 1 ||
+    !Number.isFinite(geometricError) ||
+    geometricError < 0
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_TILESET_OPTIONS_INVALID',
+      'Positive maxTiles and finite nonnegative geometricError are required'
+    );
+  }
+  const memory = createBoundedMemoryTileConversionSink(options);
+  const children: {
+    boundingVolume: {box: number[]};
+    geometricError: number;
+    content: {uri: string};
+  }[] = [];
+  const identifiers = new Set<string>();
+  const minimum = [Infinity, Infinity, Infinity];
+  const maximum = [-Infinity, -Infinity, -Infinity];
+  let state: 'open' | 'writing' | 'closed' = 'open';
+  let completed = false;
+
+  return {
+    /** Exposes finalized files without exposing a partial package. */
+    getFiles: () => (completed ? memory.getFiles() : []),
+    /** Captures one validated placement and encoded PNTS resource. */
+    async write(resource, signal) {
+      signal?.throwIfAborted();
+      if (state !== 'open')
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_SINK_UNAVAILABLE',
+          'Point sink is busy or closed'
+        );
+      if (!resource.id || identifiers.has(resource.id) || children.length >= maxTiles) {
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_PLACEMENT_INVALID',
+          'Placements require unique nonempty identifiers within maxTiles'
+        );
+      }
+      const [lower, upper] = getPointTileBounds(resource, geometricError);
+      const resourceId = `points/${children.length}.pnts`;
+      state = 'writing';
+      await memory.write(
+        {resourceId, parts: [resource.pnts], contentType: 'application/octet-stream'},
+        signal
+      );
+      if (state !== 'writing')
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_SINK_UNAVAILABLE',
+          'Point sink was aborted during writing'
+        );
+      children.push({
+        boundingVolume: {box: createPointBoundsBox(lower, upper)},
+        geometricError,
+        content: {uri: resourceId}
+      });
+      identifiers.add(resource.id);
+      for (let axis = 0; axis < 3; axis++) {
+        minimum[axis] = Math.min(minimum[axis], lower[axis]);
+        maximum[axis] = Math.max(maximum[axis], upper[axis]);
+      }
+      state = 'open';
+    },
+    /** Serializes the enclosing root after all placements have completed. */
+    async finalize(report) {
+      if (state !== 'open' || !children.length)
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_SINK_INCOMPLETE',
+          'Finalization requires successfully written point tiles'
+        );
+      state = 'writing';
+      const rootError = Math.max(
+        geometricError,
+        Math.hypot(...minimum.map((value, axis) => maximum[axis] - value))
+      );
+      if (!Number.isFinite(rootError))
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_BOUNDS_INVALID',
+          'Enclosing bounds must have a finite diagonal'
+        );
+      const json = JSON.stringify({
+        asset: {version: '1.0'},
+        geometricError: rootError,
+        root: {
+          boundingVolume: {box: createPointBoundsBox(minimum, maximum)},
+          geometricError: rootError,
+          refine: 'ADD',
+          children
+        }
+      });
+      await memory.write({
+        resourceId: 'tileset.json',
+        parts: [json],
+        contentType: 'application/json'
+      });
+      if (state !== 'writing')
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_SINK_UNAVAILABLE',
+          'Point sink was aborted during finalization'
+        );
+      await memory.finalize(report);
+      if (state !== 'writing')
+        throw new TileConversionError(
+          'POINT_CLOUD_TILESET_SINK_UNAVAILABLE',
+          'Point sink was aborted during finalization'
+        );
+      state = 'closed';
+      completed = true;
+    },
+    /** Clears resource and hierarchy storage on failure or cancellation. */
+    async abort(error) {
+      state = 'closed';
+      completed = false;
+      children.length = 0;
+      identifiers.clear();
+      await memory.abort(error);
+    }
+  };
+}
+
+/** Validates the declared frame and returns bounds reconstructed from trusted encoded positions. */
+function getPointTileBounds(resource: EncodedPointCloudSourceTile, geometricError: number) {
+  const reference = resource.spatialReference;
+  const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+  if (
+    !reference ||
+    !['native', 'transformed'].includes(reference.status) ||
+    (reference.targetCrs || reference.sourceCrs) !== 'EPSG:4978' ||
+    (reference.targetHeightReference === 'native'
+      ? reference.heightReference
+      : reference.targetHeightReference) !== 'ellipsoidal' ||
+    resource.coordinateSystem !== 'cartesian' ||
+    resource.cartographicOrigin.length !== 3 ||
+    resource.cartographicOrigin.some(value => value !== 0) ||
+    (resource.modelMatrix &&
+      (resource.modelMatrix.length !== 16 ||
+        resource.modelMatrix.some((value, index) => value !== identity[index]))) ||
+    (reference.status === 'native' &&
+      (reference.coordinateFrame !== 'geocentric' ||
+        reference.axisOrder !== 'xyz' ||
+        reference.verticalUnitScale !== 1 ||
+        reference.units?.some(unit => unit !== 'meter')))
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_TILESET_FRAME_UNSUPPORTED',
+      'Point tiles require declared EPSG:4978 xyz meters, ellipsoidal heights and no additional source placement'
+    );
+  }
+  if (
+    !Number.isFinite(resource.maximumPositionError) ||
+    resource.maximumPositionError < 0 ||
+    resource.maximumPositionError > geometricError
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_GEOMETRIC_ERROR_INVALID',
+      'geometricError must include measured position reconstruction error'
+    );
+  }
+  const [minimum, maximum] = resource.localBoundingBox;
+  const center = resource.rtcCenter;
+  if (
+    center.length !== 3 ||
+    minimum.length !== 3 ||
+    maximum.length !== 3 ||
+    [...center, ...minimum, ...maximum].some(value => !Number.isFinite(value)) ||
+    minimum.some((value, axis) => value > maximum[axis])
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_TILESET_BOUNDS_INVALID',
+      'RTC center and encoded xyz bounds must be finite and ordered'
+    );
+  }
+  const lower = minimum.map((value, axis) => value + center[axis]);
+  const upper = maximum.map((value, axis) => value + center[axis]);
+  if ([...lower, ...upper].some(value => !Number.isFinite(value)))
+    throw new TileConversionError(
+      'POINT_CLOUD_TILESET_BOUNDS_INVALID',
+      'Reconstructed ECEF bounds must be finite'
+    );
+  return [lower, upper] as const;
+}
+
+/** Creates an axis-aligned 3D Tiles box in the PNTS position frame without glTF axis rotation. */
+function createPointBoundsBox(minimum: readonly number[], maximum: readonly number[]): number[] {
+  const center = minimum.map((value, axis) => value / 2 + maximum[axis] / 2);
+  const halfSize = minimum.map((value, axis) => maximum[axis] / 2 - value / 2);
+  return [center[0], center[1], center[2], halfSize[0], 0, 0, 0, halfSize[1], 0, 0, 0, halfSize[2]];
+}

package/src/v5/point-cloud.ts

@@ -0,0 +1,398 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Tile3DWriter, TILE3D_TYPE} from '@loaders.gl/3d-tiles';
+import type {
+  Mesh,
+  MeshArrowTable,
+  MeshAttribute,
+  MeshAttributeQuantizationTransform
+} from '@loaders.gl/schema';
+import {convertTableToMesh} from '@loaders.gl/schema-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+
+/** Options for encoding one Arrow or mesh point batch as a 3D Tiles point tile. */
+export interface EncodePointCloudTileOptions {
+  /** Optional origin subtracted from absolute positions and stored as the PNTS RTC_CENTER. */
+  readonly rtcCenter?: readonly [number, number, number];
+  /** Maximum Euclidean position reconstruction error in source units; omission permits float32 rounding. */
+  readonly maxPositionError?: number;
+  /** Optional source-wide RGBA color stored as the PNTS CONSTANT_RGBA property. */
+  readonly constantRGBA?: readonly number[];
+  /** Optional per-point values indexed by the tile's `BATCH_ID` attribute. */
+  readonly batchTableJson?: Readonly<Record<string, readonly (string | number)[]>>;
+}
+
+/** Encoded PNTS and measured placement information from its float32 POSITION stream. */
+export interface EncodedPointCloudTile {
+  /** Self-contained PNTS payload. */
+  readonly pnts: ArrayBuffer;
+  /** Actual number of encoded points. */
+  readonly pointCount: number;
+  /** RTC center added to encoded positions; zero when no RTC center was selected. */
+  readonly rtcCenter: readonly [number, number, number];
+  /** Axis-aligned bounds of encoded positions before adding the RTC center. */
+  readonly localBoundingBox: readonly [readonly number[], readonly number[]];
+  /** Maximum Euclidean error after reconstructing absolute positions, in source units. */
+  readonly maximumPositionError: number;
+}
+
+/**
+ * Encodes one mesh or Mesh Arrow point batch as a PNTS resource.
+ *
+ * The input position field must be named `POSITION` and contain xyz values. `COLOR_0` or `COLOR`
+ * is written when present; `constantRGBA` supplies a fallback PNTS `CONSTANT_RGBA` feature-table
+ * property. `NORMAL` and `BATCH_ID` are also written when present. Arrow batches should be passed
+ * one at a time so callers can bound memory and apply their own tiling and output policy.
+ * Unsupported attributes, including a second color attribute, fail instead of being discarded.
+ *
+ * @param pointBatch - Point data produced by a LAS, COPC, I3S, or other point source.
+ * @param options - Optional RTC center and batch-table values.
+ * @returns A 3D Tiles PNTS resource.
+ */
+export function encodePointCloudTile(
+  pointBatch: Mesh | MeshArrowTable,
+  options: EncodePointCloudTileOptions = {}
+): ArrayBuffer {
+  return encodePointCloudTileWithMetadata(pointBatch, options).pnts;
+}
+
+/**
+ * Encodes a point batch and measures its decoded float32 bounds and position rounding.
+ * The optional error gate runs before PNTS serialization. Source arrays remain unchanged.
+ * @param pointBatch - One mesh or Arrow point batch.
+ * @param options - RTC center, precision gate, appearance and batch metadata.
+ * @returns PNTS bytes paired with bounds, RTC placement and maximum position error.
+ */
+export function encodePointCloudTileWithMetadata(
+  pointBatch: Mesh | MeshArrowTable,
+  options: EncodePointCloudTileOptions = {}
+): EncodedPointCloudTile {
+  const mesh = 'attributes' in pointBatch ? pointBatch : convertTableToMesh(pointBatch);
+  validatePointAttributes(mesh.attributes);
+  const positionAttribute = mesh.attributes.POSITION;
+  validatePointCloudPosition(positionAttribute);
+  const placement = encodePointPositions(positionAttribute, options);
+  const {positions} = placement;
+  const pointCount = positions.length / 3;
+  const colors = getColorAttribute(mesh.attributes.COLOR_0 || mesh.attributes.COLOR, pointCount);
+  const constantRGBA = colors ? null : getConstantRgba(options.constantRGBA);
+  const normals = getNormalAttribute(mesh.attributes.NORMAL, pointCount);
+  const batchIds = getBatchIds(mesh.attributes.BATCH_ID, pointCount);
+  const batchTableJson = validateBatchTable(options.batchTableJson, batchIds);
+
+  const pnts = Tile3DWriter.encodeSync(
+    {
+      type: TILE3D_TYPE.POINT_CLOUD,
+      featureTableJson:
+        options.rtcCenter || constantRGBA
+          ? {
+              ...(options.rtcCenter ? {RTC_CENTER: [...options.rtcCenter]} : {}),
+              ...(constantRGBA ? {CONSTANT_RGBA: constantRGBA} : {})
+            }
+          : undefined,
+      batchTableJson,
+      attributes: {positions, colors, normals, batchIds}
+    },
+    {}
+  );
+  return {
+    pnts,
+    pointCount,
+    rtcCenter: placement.rtcCenter,
+    localBoundingBox: placement.localBoundingBox,
+    maximumPositionError: placement.maximumPositionError
+  };
+}
+
+/** Rejects attributes that this PNTS encoder would otherwise silently discard. */
+function validatePointAttributes(attributes: Mesh['attributes']): void {
+  const supportedAttributes = new Set([
+    'POSITION',
+    'NORMAL',
+    'BATCH_ID',
+    attributes.COLOR_0 ? 'COLOR_0' : 'COLOR'
+  ]);
+  const unsupportedAttributes = Object.keys(attributes).filter(
+    name => !supportedAttributes.has(name)
+  );
+  if (unsupportedAttributes.length > 0) {
+    throw new TileConversionError(
+      'POINT_CLOUD_ATTRIBUTE_UNSUPPORTED',
+      `PNTS encoding does not support these point attributes: ${unsupportedAttributes.join(', ')}`
+    );
+  }
+}
+
+/** Validates an optional source-wide PNTS RGBA color. */
+function getConstantRgba(
+  constantRGBA?: readonly number[]
+): [number, number, number, number] | null {
+  if (!constantRGBA) {
+    return null;
+  }
+  if (
+    constantRGBA.length !== 4 ||
+    constantRGBA.some(value => !Number.isInteger(value) || value < 0 || value > 255)
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_CONSTANT_RGBA_INVALID',
+      'Point cloud constantRGBA must contain four unsigned byte values'
+    );
+  }
+  return [constantRGBA[0], constantRGBA[1], constantRGBA[2], constantRGBA[3]];
+}
+
+/** Validates packed point positions and their optional quantization descriptor. */
+function validatePointCloudPosition(
+  attribute: MeshAttribute | undefined
+): asserts attribute is MeshAttribute & {transform?: MeshAttributeQuantizationTransform} {
+  if (
+    !attribute ||
+    attribute.size !== 3 ||
+    attribute.byteOffset ||
+    attribute.byteStride ||
+    attribute.normalized ||
+    attribute.componentType
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_REQUIRED',
+      'Point cloud batches must contain packed, non-normalized three-component POSITION values'
+    );
+  }
+
+  if (!attribute.value.length || attribute.value.length % 3) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_COUNT_INVALID',
+      'Point cloud POSITION must contain one or more xyz triples'
+    );
+  }
+  const transform = attribute.transform;
+  if (
+    transform &&
+    (transform.type !== 'quantization' ||
+      !Number.isInteger(transform.bits) ||
+      transform.bits < 1 ||
+      transform.bits > 32 ||
+      transform.origin.length !== 3 ||
+      transform.origin.some(value => !Number.isFinite(value)) ||
+      !Number.isFinite(transform.range) ||
+      transform.range < 0)
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_TRANSFORM_INVALID',
+      'Position quantization requires finite xyz origin, nonnegative range and 1–32 bits'
+    );
+  }
+}
+
+/** Decodes packed point positions to doubles before applying a spatial operation. */
+export function decodePointCloudPositions(attribute: MeshAttribute | undefined): Float64Array {
+  validatePointCloudPosition(attribute);
+  const transform = attribute.transform;
+  return Float64Array.from(attribute.value, (value, index) =>
+    transform
+      ? transform.origin[index % 3] + (value / (2 ** transform.bits - 1)) * transform.range
+      : value
+  );
+}
+
+/** Decodes source positions, rebases them and measures the actual float32 output. */
+function encodePointPositions(
+  attribute: MeshAttribute & {transform?: MeshAttributeQuantizationTransform},
+  options: EncodePointCloudTileOptions
+) {
+  const {rtcCenter = [0, 0, 0], maxPositionError = Infinity} = options;
+  if (rtcCenter.length !== 3 || rtcCenter.some(value => !Number.isFinite(value))) {
+    throw new TileConversionError(
+      'POINT_CLOUD_RTC_CENTER_INVALID',
+      'Point cloud RTC_CENTER must contain three finite values'
+    );
+  }
+  if (
+    options.maxPositionError !== undefined &&
+    (!Number.isFinite(maxPositionError) || maxPositionError < 0)
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_PRECISION_INVALID',
+      'maxPositionError must be finite and nonnegative'
+    );
+  }
+  const values = attribute.value;
+  const positions = new Float32Array(values.length);
+  const minimum = [Infinity, Infinity, Infinity];
+  const maximum = [-Infinity, -Infinity, -Infinity];
+  let maximumPositionError = 0;
+  const transform = attribute.transform;
+  const errors = [0, 0, 0];
+  for (let point = 0; point < values.length; point += 3) {
+    for (let axis = 0; axis < 3; axis++) {
+      const value = values[point + axis];
+      const absoluteValue = transform
+        ? transform.origin[axis] + (value / (2 ** transform.bits - 1)) * transform.range
+        : value;
+      const relativeValue = absoluteValue - rtcCenter[axis];
+      positions[point + axis] = relativeValue;
+      const encodedValue = positions[point + axis];
+      const reconstructed = encodedValue + rtcCenter[axis];
+      if (
+        !Number.isFinite(absoluteValue) ||
+        !Number.isFinite(relativeValue) ||
+        !Number.isFinite(encodedValue) ||
+        !Number.isFinite(reconstructed)
+      ) {
+        throw new TileConversionError(
+          'POINT_CLOUD_POSITION_INVALID',
+          'Point positions and their float32 reconstruction must be finite'
+        );
+      }
+      errors[axis] = reconstructed - absoluteValue;
+      minimum[axis] = Math.min(minimum[axis], encodedValue);
+      maximum[axis] = Math.max(maximum[axis], encodedValue);
+    }
+    maximumPositionError = Math.max(maximumPositionError, Math.hypot(...errors));
+  }
+  if (!Number.isFinite(maximumPositionError) || maximumPositionError > maxPositionError) {
+    throw new TileConversionError(
+      'POINT_CLOUD_PRECISION_EXCEEDED',
+      'Float32 position reconstruction exceeds maxPositionError; select a closer RTC center'
+    );
+  }
+  return {
+    positions,
+    rtcCenter: [...rtcCenter] as [number, number, number],
+    localBoundingBox: [minimum, maximum] as const,
+    maximumPositionError
+  };
+}
+
+/** Converts an optional mesh color attribute into the byte colors accepted by PNTS. */
+function getColorAttribute(
+  attribute: MeshAttribute | undefined,
+  pointCount: number
+): {type: number; value: Uint8Array; size: number; normalized: boolean} | null {
+  if (!attribute) {
+    return null;
+  }
+  if (attribute.size !== 3 && attribute.size !== 4) {
+    throw new TileConversionError(
+      'POINT_CLOUD_COLOR_SIZE_UNSUPPORTED',
+      'Point cloud color attributes must contain three or four components'
+    );
+  }
+  if (attribute.value.length !== pointCount * attribute.size) {
+    throw new TileConversionError(
+      'POINT_CLOUD_COLOR_COUNT_MISMATCH',
+      'Point cloud color count does not match the POSITION count'
+    );
+  }
+
+  const colors = new Uint8Array(attribute.value.length);
+  const maximum = getIntegerColorMaximum(attribute.value);
+  for (let index = 0; index < attribute.value.length; index++) {
+    const value = attribute.value[index];
+    const scaledValue = maximum ? (value / maximum) * 255 : value <= 1 ? value * 255 : value;
+    if (!Number.isFinite(scaledValue) || scaledValue < 0 || scaledValue > 255) {
+      throw new TileConversionError(
+        'POINT_CLOUD_COLOR_VALUE_INVALID',
+        'Point cloud color components must be finite values from 0 through 255'
+      );
+    }
+    colors[index] = Math.round(scaledValue);
+  }
+  return {type: 5121, value: colors, size: attribute.size, normalized: false};
+}
+
+/** Returns the maximum value represented by an integer color component array. */
+function getIntegerColorMaximum(values: ArrayLike<number>): number | null {
+  if (values instanceof Uint8Array || values instanceof Uint8ClampedArray) {
+    return 255;
+  }
+  if (values instanceof Uint16Array) {
+    return 65_535;
+  }
+  if (values instanceof Uint32Array) {
+    return 4_294_967_295;
+  }
+  return null;
+}
+
+/** Returns float normals and rejects unsupported component shapes. */
+function getNormalAttribute(
+  attribute: MeshAttribute | undefined,
+  pointCount: number
+): {type: number; value: Float32Array; size: number} | null {
+  if (!attribute) {
+    return null;
+  }
+  if (attribute.size !== 3 || attribute.value.length !== pointCount * 3) {
+    throw new TileConversionError(
+      'POINT_CLOUD_NORMAL_COUNT_MISMATCH',
+      'Point cloud normals must contain one xyz triple per position'
+    );
+  }
+  return {type: 5126, value: Float32Array.from(attribute.value), size: 3};
+}
+
+/** Validates optional stable feature IDs for the PNTS uint16 batch-ID field. */
+function getBatchIds(attribute: MeshAttribute | undefined, pointCount: number): Uint16Array | null {
+  if (!attribute) {
+    return null;
+  }
+  if (attribute.size !== 1 || attribute.value.length !== pointCount) {
+    throw new TileConversionError(
+      'POINT_CLOUD_BATCH_ID_COUNT_MISMATCH',
+      'Point cloud BATCH_ID must contain one value per position'
+    );
+  }
+  const batchIds = new Uint16Array(pointCount);
+  for (let index = 0; index < pointCount; index++) {
+    const batchId = attribute.value[index];
+    if (!Number.isInteger(batchId) || batchId < 0 || batchId > 65_535) {
+      throw new TileConversionError(
+        'POINT_CLOUD_BATCH_ID_OUT_OF_RANGE',
+        'Point cloud BATCH_ID values must be unsigned 16-bit integers'
+      );
+    }
+    batchIds[index] = batchId;
+  }
+  return batchIds;
+}
+
+/** Checks that each batch-table property is indexable by the batch IDs used by this tile. */
+function validateBatchTable(
+  batchTableJson: EncodePointCloudTileOptions['batchTableJson'],
+  batchIds: Uint16Array | null
+): Record<string, (string | number)[]> | undefined {
+  if (!batchTableJson) {
+    if (batchIds) {
+      throw new TileConversionError(
+        'POINT_CLOUD_BATCH_TABLE_REQUIRED',
+        'BATCH_ID values require matching batchTableJson properties'
+      );
+    }
+    return undefined;
+  }
+  if (!batchIds) {
+    throw new TileConversionError(
+      'POINT_CLOUD_BATCH_ID_REQUIRED',
+      'batchTableJson requires a BATCH_ID attribute'
+    );
+  }
+  let batchLength = 0;
+  for (const batchId of batchIds) {
+    batchLength = Math.max(batchLength, batchId + 1);
+  }
+  const normalizedBatchTable: Record<string, (string | number)[]> = {};
+  for (const [name, values] of Object.entries(batchTableJson)) {
+    if (values.length !== batchLength) {
+      throw new TileConversionError(
+        'POINT_CLOUD_BATCH_TABLE_LENGTH_MISMATCH',
+        `Batch table property "${name}" must contain ${batchLength} values`
+      );
+    }
+    normalizedBatchTable[name] = [...values];
+  }
+  return normalizedBatchTable;
+}