@loaders.gl/tile-converter 5.0.0-alpha.7 → 5.0.0-alpha.8

package/src/v5/feature-arrow.ts

@@ -0,0 +1,427 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ArrowTableBuilder} from '@loaders.gl/schema-utils';
+import type {ArrowTableBatch, DataType, Field, Schema} from '@loaders.gl/schema';
+import {TileConversionError} from './conversion-api.js';
+
+const DEFAULT_FEATURE_ID_FIELD = 'feature_id';
+const FEATURE_CLASS_METADATA_KEY = 'loaders.gl:feature-class';
+
+/** Feature attributes and source identifier ready for Arrow normalization. */
+export interface TileFeatureAttributes {
+  /** Stable feature identifier decoded from the source's feature-ID descriptor. */
+  readonly featureId: string | number | bigint;
+  /** Property values interpreted from the source metadata class. */
+  readonly properties: Readonly<Record<string, unknown>>;
+  /** Original class or property-table name, kept distinct between output batches. */
+  readonly metadataClass: string;
+  /** Optional original encoded metadata bytes, preserved without interpretation. */
+  readonly rawMetadata?: Uint8Array;
+}
+
+/** Explicit Arrow mapping and bounded output size for feature attribute batches. */
+export interface FeatureArrowBatchOptions {
+  /** Declared output columns and types, including the feature-ID column. */
+  readonly schema: Schema;
+  /** Schema field receiving stable feature identifiers. Defaults to `feature_id`. */
+  readonly featureIdField?: string;
+  /** Optional binary field receiving source metadata bytes. */
+  readonly rawMetadataField?: string;
+  /** Maximum number of features in one emitted Arrow record batch. Defaults to 65,536. */
+  readonly batchSize?: number;
+}
+
+/**
+ * Converts decoded feature attributes to bounded Arrow batches using a caller-declared schema.
+ *
+ * Values retain their source primitive types; nested lists, structs, dictionary enums, and 64-bit
+ * identifiers use the corresponding schema field type. Missing schema fields and incompatible
+ * identifiers fail explicitly. Unknown properties are rejected so a class mapping cannot silently
+ * discard data. Separate metadata classes should be passed separately with their own schema.
+ *
+ * @param features - Features decoded from one source metadata class.
+ * @param options - Explicit Arrow schema and batch configuration.
+ * @returns Arrow table batches whose schema metadata records the source metadata class.
+ */
+export function convertFeatureAttributesToArrowBatches(
+  features: readonly TileFeatureAttributes[],
+  options: FeatureArrowBatchOptions
+): ArrowTableBatch[] {
+  const featureIdField = options.featureIdField || DEFAULT_FEATURE_ID_FIELD;
+  const batchSize = options.batchSize ?? 65_536;
+  if (!Number.isInteger(batchSize) || batchSize <= 0) {
+    throw new TileConversionError(
+      'INVALID_FEATURE_BATCH_SIZE',
+      'Feature Arrow batch size must be a positive integer'
+    );
+  }
+
+  const featureClasses = new Set(features.map(feature => feature.metadataClass));
+  if (featureClasses.size > 1) {
+    throw new TileConversionError(
+      'MULTIPLE_FEATURE_CLASSES',
+      'Build separate Arrow batches for each source metadata class'
+    );
+  }
+  const metadataClass = features[0]?.metadataClass;
+  const schema = makeFeatureSchema(
+    options.schema,
+    featureIdField,
+    options.rawMetadataField,
+    metadataClass
+  );
+  const fieldsByName = new Map(schema.fields.map(field => [field.name, field]));
+  const propertyFieldNames = new Set(
+    schema.fields
+      .filter(field => field.name !== featureIdField && field.name !== options.rawMetadataField)
+      .map(field => field.name)
+  );
+
+  for (const feature of features) {
+    validateFeatureIdentifier(feature.featureId, fieldsByName.get(featureIdField)?.type);
+    if (feature.rawMetadata && !options.rawMetadataField) {
+      throw new TileConversionError(
+        'RAW_METADATA_FIELD_REQUIRED',
+        'A rawMetadataField must be declared to preserve encoded source metadata'
+      );
+    }
+    for (const propertyName of Object.keys(feature.properties)) {
+      if (!propertyFieldNames.has(propertyName)) {
+        throw new TileConversionError(
+          'FEATURE_PROPERTY_NOT_MAPPED',
+          `Feature property "${propertyName}" is not declared in the Arrow schema`
+        );
+      }
+    }
+  }
+
+  const batches: ArrowTableBatch[] = [];
+  for (let batchStart = 0; batchStart < features.length; batchStart += batchSize) {
+    const tableBuilder = new ArrowTableBuilder(schema);
+    const batchFeatures = features.slice(batchStart, batchStart + batchSize);
+    for (const feature of batchFeatures) {
+      const row: Record<string, unknown> = {
+        ...feature.properties,
+        [featureIdField]: feature.featureId
+      };
+      if (options.rawMetadataField) {
+        row[options.rawMetadataField] = feature.rawMetadata || null;
+      }
+      for (const field of schema.fields) {
+        if (row[field.name] === undefined) {
+          row[field.name] = null;
+        }
+        validateFeatureValue(field, row[field.name], field.name);
+      }
+      tableBuilder.addObjectRow(row);
+    }
+    const batch = tableBuilder.finishBatch();
+    if (batch) {
+      batches.push(batch);
+    }
+  }
+  return batches;
+}
+
+/** Adds feature class metadata and validates the required ID and raw metadata mappings. */
+function makeFeatureSchema(
+  sourceSchema: Schema,
+  featureIdField: string,
+  rawMetadataField: string | undefined,
+  metadataClass: string | undefined
+): Schema {
+  const fieldsByName = new Map(sourceSchema.fields.map(field => [field.name, field]));
+  if (fieldsByName.size !== sourceSchema.fields.length) {
+    throw new TileConversionError(
+      'DUPLICATE_FEATURE_FIELDS',
+      'Arrow schema fields must have unique names'
+    );
+  }
+  for (const field of sourceSchema.fields) {
+    validateFeatureSchemaType(field);
+  }
+  const featureIdType = fieldsByName.get(featureIdField)?.type;
+  if (!featureIdType) {
+    throw new TileConversionError(
+      'FEATURE_ID_FIELD_REQUIRED',
+      `Arrow schema must declare the feature identifier field "${featureIdField}"`
+    );
+  }
+  if (rawMetadataField && !fieldsByName.has(rawMetadataField)) {
+    throw new TileConversionError(
+      'RAW_METADATA_FIELD_NOT_DECLARED',
+      `Arrow schema does not declare the raw metadata field "${rawMetadataField}"`
+    );
+  }
+  if (rawMetadataField === featureIdField) {
+    throw new TileConversionError(
+      'FEATURE_FIELDS_COLLIDE',
+      'The feature identifier and raw metadata require separate Arrow fields'
+    );
+  }
+  if (rawMetadataField && !isBinaryType(fieldsByName.get(rawMetadataField)?.type)) {
+    throw new TileConversionError(
+      'RAW_METADATA_FIELD_NOT_BINARY',
+      `Arrow schema field "${rawMetadataField}" must use binary or fixed-size-binary type`
+    );
+  }
+  return {
+    ...sourceSchema,
+    metadata: {
+      ...(sourceSchema.metadata || {}),
+      ...(metadataClass ? {[FEATURE_CLASS_METADATA_KEY]: metadataClass} : {})
+    }
+  };
+}
+
+/** Rejects identifier values that the declared Arrow type cannot preserve exactly. */
+function validateFeatureIdentifier(featureId: string | number | bigint, dataType?: DataType): void {
+  const isStringIdentifier = typeof featureId === 'string';
+  const isIntegerIdentifier = typeof featureId === 'bigint' || Number.isSafeInteger(featureId);
+  const isStringType = dataType === 'utf8' || dataType === 'utf8-view';
+  if (
+    (isStringIdentifier && isStringType) ||
+    (isIntegerIdentifier && isIntegerDataType(dataType))
+  ) {
+    return;
+  }
+  throw new TileConversionError(
+    'FEATURE_ID_TYPE_MISMATCH',
+    `Feature identifier ${String(featureId)} is not compatible with the declared Arrow type`
+  );
+}
+
+/** Rejects nulls, implicit coercions, and out-of-range values before Arrow writes a field. */
+function validateFeatureValue(field: Field, value: unknown, fieldPath: string): void {
+  if (value === null || value === undefined) {
+    if (field.nullable !== true) {
+      throw new TileConversionError(
+        'FEATURE_VALUE_REQUIRED',
+        `Required Arrow field "${fieldPath}" has no value`
+      );
+    }
+    return;
+  }
+
+  const dataType = field.type;
+  if (typeof dataType === 'object') {
+    if (dataType.type === 'dictionary') {
+      validateFeatureValue({...field, type: dataType.dictionary}, value, fieldPath);
+      return;
+    }
+    if (dataType.type === 'list' || dataType.type === 'large-list') {
+      if (!Array.isArray(value)) {
+        throw createFeatureValueTypeError(fieldPath, 'an array');
+      }
+      const childField = dataType.children[0];
+      for (let index = 0; index < value.length; index++) {
+        validateFeatureValue(childField, value[index], `${fieldPath}[${index}]`);
+      }
+      return;
+    }
+    if (dataType.type === 'fixed-size-list') {
+      if (!Array.isArray(value) || value.length !== dataType.listSize) {
+        throw createFeatureValueTypeError(fieldPath, `an array of length ${dataType.listSize}`);
+      }
+      const childField = dataType.children[0];
+      for (let index = 0; index < value.length; index++) {
+        validateFeatureValue(childField, value[index], `${fieldPath}[${index}]`);
+      }
+      return;
+    }
+    if (dataType.type === 'struct') {
+      if (!isRecord(value)) {
+        throw createFeatureValueTypeError(fieldPath, 'an object');
+      }
+      const childNames = new Set(dataType.children.map(childField => childField.name));
+      const unknownNames = Object.keys(value).filter(name => !childNames.has(name));
+      if (unknownNames.length > 0) {
+        throw new TileConversionError(
+          'FEATURE_PROPERTY_NOT_MAPPED',
+          `Nested feature properties "${unknownNames.join(', ')}" are not declared under "${fieldPath}"`
+        );
+      }
+      for (const childField of dataType.children) {
+        validateFeatureValue(childField, value[childField.name], `${fieldPath}.${childField.name}`);
+      }
+      return;
+    }
+    if (dataType.type === 'decimal') {
+      if (typeof value !== 'bigint') {
+        throw createFeatureValueTypeError(fieldPath, 'an unscaled bigint decimal value');
+      }
+      if (
+        value <= -(10n ** BigInt(dataType.precision)) ||
+        value >= 10n ** BigInt(dataType.precision)
+      ) {
+        throw new TileConversionError(
+          'FEATURE_VALUE_OUT_OF_RANGE',
+          `Value for Arrow decimal field "${fieldPath}" exceeds precision ${dataType.precision}`
+        );
+      }
+      return;
+    }
+    if (dataType.type === 'fixed-size-binary') {
+      const byteLength = getByteLength(value);
+      if (byteLength !== dataType.byteWidth) {
+        throw createFeatureValueTypeError(fieldPath, `exactly ${dataType.byteWidth} bytes`);
+      }
+      return;
+    }
+    // Keep future Arrow composites explicit until a lossless runtime mapping is defined.
+    throw new TileConversionError(
+      'FEATURE_VALUE_MAPPING_UNSUPPORTED',
+      `Arrow schema type "${dataType.type}" has no feature value mapping for "${fieldPath}"`
+    );
+  }
+
+  if (isIntegerDataType(dataType)) {
+    if (!isIntegerIdentifier(value)) {
+      throw createFeatureValueTypeError(fieldPath, 'an integer');
+    }
+    const [minimum, maximum] = getIntegerBounds(dataType);
+    const integerValue = typeof value === 'bigint' ? value : BigInt(value);
+    if (integerValue < minimum || integerValue > maximum) {
+      throw new TileConversionError(
+        'FEATURE_VALUE_OUT_OF_RANGE',
+        `Value for Arrow field "${fieldPath}" is outside the range of ${dataType}`
+      );
+    }
+    return;
+  }
+  if (dataType === 'utf8' || dataType === 'utf8-view') {
+    if (typeof value !== 'string') throw createFeatureValueTypeError(fieldPath, 'a string');
+    return;
+  }
+  if (dataType === 'bool') {
+    if (typeof value !== 'boolean') throw createFeatureValueTypeError(fieldPath, 'a boolean');
+    return;
+  }
+  if (dataType === 'binary' || dataType === 'binary-view') {
+    if (getByteLength(value) < 0) throw createFeatureValueTypeError(fieldPath, 'binary data');
+    return;
+  }
+  if (
+    dataType === 'float' ||
+    dataType === 'float16' ||
+    dataType === 'float32' ||
+    dataType === 'float64'
+  ) {
+    if (typeof value !== 'number') throw createFeatureValueTypeError(fieldPath, 'a number');
+    return;
+  }
+  if (dataType === 'null') {
+    throw createFeatureValueTypeError(fieldPath, 'null');
+  }
+  if (
+    dataType === 'date-day' ||
+    dataType === 'date-millisecond' ||
+    dataType.startsWith('timestamp-')
+  ) {
+    if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+      throw createFeatureValueTypeError(fieldPath, 'a valid Date');
+    }
+    return;
+  }
+  throw new TileConversionError(
+    'FEATURE_VALUE_MAPPING_UNSUPPORTED',
+    `Arrow schema type "${dataType}" has no feature value mapping for "${fieldPath}"`
+  );
+}
+
+/** Checks whether a feature identifier is exact enough for an integer Arrow field. */
+function isIntegerIdentifier(value: unknown): value is number | bigint {
+  return typeof value === 'bigint' || (typeof value === 'number' && Number.isSafeInteger(value));
+}
+
+/** Identifies all Arrow integer primitive types accepted for feature identifiers. */
+function isIntegerDataType(dataType?: DataType): boolean {
+  return (
+    dataType === 'int8' ||
+    dataType === 'int16' ||
+    dataType === 'int32' ||
+    dataType === 'int64' ||
+    dataType === 'uint8' ||
+    dataType === 'uint16' ||
+    dataType === 'uint32' ||
+    dataType === 'uint64'
+  );
+}
+
+/** Rejects generic integer types and nested mappings the Arrow table builder cannot materialize. */
+function validateFeatureSchemaType(field: Field): void {
+  const dataType = field.type;
+  if (dataType === 'int') {
+    throw new TileConversionError(
+      'FEATURE_INTEGER_TYPE_UNSUPPORTED',
+      `Arrow field "${field.name}" must declare an explicit integer width and signedness`
+    );
+  }
+  if (typeof dataType !== 'object') {
+    return;
+  }
+  let childFields: readonly Field[] = [];
+  if (dataType.type === 'dictionary' && dataType.indices) {
+    childFields = [{name: `${field.name} index`, type: dataType.indices, nullable: false}];
+  } else if ('children' in dataType) {
+    childFields = dataType.children;
+  }
+  for (const childField of childFields) {
+    validateFeatureSchemaType(childField);
+  }
+}
+
+/** Returns the inclusive numeric limits for the declared integer field. */
+function getIntegerBounds(dataType: DataType): [bigint, bigint] {
+  switch (dataType) {
+    case 'int8':
+      return [-128n, 127n];
+    case 'uint8':
+      return [0n, 255n];
+    case 'int16':
+      return [-32768n, 32767n];
+    case 'uint16':
+      return [0n, 65535n];
+    case 'int32':
+      return [-2147483648n, 2147483647n];
+    case 'uint32':
+      return [0n, 4294967295n];
+    case 'int64':
+      return [-(2n ** 63n), 2n ** 63n - 1n];
+    case 'uint64':
+      return [0n, 2n ** 64n - 1n];
+    default:
+      return [-(2n ** 31n), 2n ** 31n - 1n];
+  }
+}
+
+/** Creates a typed error that names the field whose schema mapping does not match its value. */
+function createFeatureValueTypeError(fieldPath: string, expected: string): TileConversionError {
+  return new TileConversionError(
+    'FEATURE_VALUE_TYPE_MISMATCH',
+    `Arrow field "${fieldPath}" requires ${expected}`
+  );
+}
+
+/** Checks whether a value is a property record rather than an array or scalar. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Returns the byte length for supported binary value containers. */
+function getByteLength(value: unknown): number {
+  if (value instanceof Uint8Array) return value.byteLength;
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  return -1;
+}
+
+/** Checks whether the schema type stores opaque bytes without coercion. */
+function isBinaryType(dataType?: DataType): boolean {
+  return (
+    dataType === 'binary' ||
+    dataType === 'binary-view' ||
+    (typeof dataType === 'object' && dataType.type === 'fixed-size-binary')
+  );
+}

package/src/v5/index.ts

@@ -0,0 +1,47 @@
+export {
+  convertTileset,
+  inspectTileset,
+  TileConversionError,
+  validateTileset
+} from './conversion-api.js';
+export type {
+  ConvertTilesetOptions,
+  TileConversionCodec,
+  TileConversionDiagnostic,
+  TileConversionProgress,
+  TileConversionReport,
+  TileConversionSink,
+  TileConversionSource,
+  TileValidationReport,
+  ValidateTilesetOptions
+} from './conversion-api.js';
+export {createTilesetConversionSource} from './tileset-source.js';
+export type {TilesetConversionSourceOptions} from './tileset-source.js';
+export {
+  createI3SConversionSpatialContext,
+  createTiles3DConversionSpatialContext
+} from './spatial-conversion.js';
+export type {
+  I3SConversionSpatialContext,
+  Tiles3DConversionSpatialContext
+} from './spatial-conversion.js';
+export {convertFeatureAttributesToArrowBatches} from './feature-arrow.js';
+export type {FeatureArrowBatchOptions, TileFeatureAttributes} from './feature-arrow.js';
+export {encodePointCloudTile} from './point-cloud.js';
+export type {EncodePointCloudTileOptions} from './point-cloud.js';
+export {traversePointCloudSource} from './point-cloud-source.js';
+export type {PointCloudSourceTile, TraversePointCloudSourceOptions} from './point-cloud-source.js';
+export {encodePointCloudSource, encodePointCloudSourceTile} from './point-cloud-source-encoder.js';
+export type {
+  EncodedPointCloudSourceTile,
+  EncodePointCloudSourceOptions
+} from './point-cloud-source-encoder.js';
+export {convertPointCloudSource} from './point-cloud-conversion.js';
+export type {ConvertPointCloudSourceOptions} from './point-cloud-conversion.js';
+export {createManifestBackedTileConversionSink} from './resource-manifest.js';
+export type {
+  ManifestBackedTileConversionSinkOptions,
+  TileResourceManifest,
+  TileResourceManifestEntry,
+  TileResourceManifestStore
+} from './resource-manifest.js';

package/src/v5/point-cloud-conversion.ts

@@ -0,0 +1,80 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PointCloudTilesetSource} from '@loaders.gl/tiles';
+import {convertTileset} from './conversion-api.js';
+import type {
+  TileConversionProgress,
+  TileConversionReport,
+  TileConversionSink
+} from './conversion-api.js';
+import {traversePointCloudSource} from './point-cloud-source.js';
+import type {PointCloudSourceTile} from './point-cloud-source.js';
+import {encodePointCloudSourceTile} from './point-cloud-source-encoder.js';
+import type {
+  EncodedPointCloudSourceTile,
+  EncodePointCloudSourceOptions
+} from './point-cloud-source-encoder.js';
+
+/** Point-cloud encoding options and an application-owned output destination. */
+export interface ConvertPointCloudSourceOptions extends EncodePointCloudSourceOptions {
+  /** Destination receiving PNTS resources and their source placement metadata. */
+  readonly sink: TileConversionSink<EncodedPointCloudSourceTile>;
+  /** Input byte accounting for each visited source tile, including tiles with null content. */
+  readonly measureInputBytes: (sourceTile: PointCloudSourceTile) => number;
+  /** Maximum caller-measured bytes in one decoded source tile, checked before PNTS encoding. */
+  readonly maxInputResourceBytes?: number;
+  /** Maximum bytes in one encoded PNTS resource. Defaults to no limit. */
+  readonly maxOutputResourceBytes?: number;
+  /** Receive conversion progress, including resource counts and caller-measured input bytes. */
+  readonly onProgress?: (progress: TileConversionProgress) => void;
+}
+
+/**
+ * Converts a point-cloud source to PNTS resources through the v5 output-sink lifecycle.
+ *
+ * Each write is awaited before reading the next source tile. The destination is finalized only
+ * after traversal and writes succeed, and aborted on read, encoding, write, or cancellation errors.
+ * Input resource counts include empty tiles; output counts and byte sizes describe emitted PNTS
+ * resources. Applications supply input byte accounting because source tiles contain decoded Arrow
+ * data rather than transport bytes. The caller retains ownership of the input source.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud source to initialize and traverse.
+ * @param options - Destination, byte accounting, traversal limits, and per-tile encoding options.
+ * @returns The shared v5 conversion report after destination finalization.
+ */
+export function convertPointCloudSource(
+  source: PointCloudTilesetSource,
+  options: ConvertPointCloudSourceOptions
+): Promise<TileConversionReport> {
+  return convertTileset({
+    source: {
+      async inspect() {
+        if (!source.isReady) {
+          await source.initialize();
+        }
+      },
+      read: (_inspection, signal) =>
+        traversePointCloudSource(source, {maxDepth: options.maxDepth, signal})
+    },
+    codec: {
+      async *convert(sourceTile) {
+        const encodingOptions = sourceTile.content
+          ? options.getTileEncodingOptions?.(sourceTile)
+          : undefined;
+        const encodedTile = encodePointCloudSourceTile(sourceTile, encodingOptions);
+        if (encodedTile) {
+          yield encodedTile;
+        }
+      }
+    },
+    sink: options.sink,
+    measureInputBytes: options.measureInputBytes,
+    measureOutputBytes: resource => resource.pnts.byteLength,
+    maxInputResourceBytes: options.maxInputResourceBytes,
+    maxOutputResourceBytes: options.maxOutputResourceBytes,
+    signal: options.signal,
+    onProgress: options.onProgress
+  });
+}

package/src/v5/point-cloud-source-encoder.ts

@@ -0,0 +1,102 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  PointCloudBoundingVolume,
+  PointCloudCoordinateSystem,
+  PointCloudTilesetSource,
+  TilesetSpatialReference
+} from '@loaders.gl/tiles';
+import {encodePointCloudTile} from './point-cloud.js';
+import type {EncodePointCloudTileOptions} from './point-cloud.js';
+import {traversePointCloudSource} from './point-cloud-source.js';
+import type {PointCloudSourceTile, TraversePointCloudSourceOptions} from './point-cloud-source.js';
+
+/** Traversal and per-tile encoding options for a point-cloud source. */
+export type EncodePointCloudSourceOptions = TraversePointCloudSourceOptions & {
+  /** Select encoder options for each source tile with content, using its header and decoded data. */
+  readonly getTileEncodingOptions?: (
+    sourceTile: PointCloudSourceTile
+  ) => EncodePointCloudTileOptions;
+};
+
+/** A PNTS resource paired with the source placement metadata needed to package its tile. */
+export type EncodedPointCloudSourceTile = {
+  /** Stable source tile identifier. */
+  readonly id: string;
+  /** Original source hierarchy and bounds. */
+  readonly header: PointCloudSourceTile['header'];
+  /** Encoded point-cloud tile content. */
+  readonly pnts: ArrayBuffer;
+  /** Number of point records encoded. */
+  readonly pointCount: number;
+  /** Coordinate system used by the returned point positions. */
+  readonly coordinateSystem: PointCloudCoordinateSystem;
+  /** Origin to add to source-relative point positions. */
+  readonly cartographicOrigin: readonly number[];
+  /** Optional placement transform supplied by the point-cloud source. */
+  readonly modelMatrix?: readonly number[];
+  /** Optional source or target CRS metadata. */
+  readonly spatialReference?: TilesetSpatialReference;
+  /** Optional output-frame tile bounds supplied by the source. */
+  readonly spatialBoundingVolume?: PointCloudBoundingVolume;
+};
+
+/**
+ * Encodes a point-cloud source as a stream of PNTS resources, one for each non-empty source tile.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud tileset source.
+ * @param options - Optional traversal depth limit, cancellation signal, and per-tile encoder options.
+ * @returns Encoded source tiles in deterministic depth-first order.
+ */
+export async function* encodePointCloudSource(
+  source: PointCloudTilesetSource,
+  options: EncodePointCloudSourceOptions = {}
+): AsyncIterableIterator<EncodedPointCloudSourceTile> {
+  for await (const sourceTile of traversePointCloudSource(source, options)) {
+    const encodingOptions = sourceTile.content
+      ? options.getTileEncodingOptions?.(sourceTile)
+      : undefined;
+    const encodedTile = encodePointCloudSourceTile(sourceTile, encodingOptions);
+    if (encodedTile) {
+      yield encodedTile;
+    }
+  }
+}
+
+/**
+ * Encodes one decoded source tile as PNTS and retains its hierarchy and placement metadata.
+ *
+ * Positions use the source coordinate system, with an optional RTC center subtracted before float32
+ * encoding and stored in the PNTS feature table. Source placement metadata is retained so callers
+ * can assemble the output tileset. This function does not transform the source CRS.
+ *
+ * @param sourceTile - Tile header and decoded Arrow point content from `traversePointCloudSource`.
+ * @param options - Optional RTC center, batch-table values, and constant color override.
+ * @returns An encoded source tile, or null when the source tile has no content.
+ */
+export function encodePointCloudSourceTile(
+  sourceTile: PointCloudSourceTile,
+  options: EncodePointCloudTileOptions = {}
+): EncodedPointCloudSourceTile | null {
+  const {header, content} = sourceTile;
+  if (!content) {
+    return null;
+  }
+
+  return {
+    id: header.id,
+    header,
+    pnts: encodePointCloudTile(content.data, {
+      ...options,
+      constantRGBA: options.constantRGBA ?? content.constantRGBA
+    }),
+    pointCount: content.pointCount,
+    coordinateSystem: content.coordinateSystem,
+    cartographicOrigin: [...content.cartographicOrigin],
+    modelMatrix: content.modelMatrix ? Array.from(content.modelMatrix) : undefined,
+    spatialReference: content.spatialReference,
+    spatialBoundingVolume: content.spatialBoundingVolume || header.spatialBoundingVolume
+  };
+}