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

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

@@ -0,0 +1,280 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import {getSpatialCoordinateFrame, createTilesetSpatialReference} from '@loaders.gl/tiles';
+import {convertTableToMesh, makeMeshArrowTable} from '@loaders.gl/schema-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  I3SConversionSpatialContext,
+  PointCloudSourceTile
+} from '@loaders.gl/tile-converter/v5/core';
+import {decodePointCloudPositions} from './point-cloud.js';
+
+/** Explicit spatial preparation for source point positions before PNTS encoding. */
+export interface PointCloudSpatialOptions {
+  /** Context for the decoded content's source CRS, units and elevation placement. */
+  readonly spatialContext: I3SConversionSpatialContext;
+  /** Required for point normals; prevents guessing their I3S vector basis. */
+  readonly normalReferenceFrame?: 'earth-centered' | 'vertex-reference-frame';
+  /** Cancellation checked before and after application-owned elevation sampling. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Resolves renderer placement and transforms one point batch to absolute target coordinates.
+ * Cartesian affine placement and longitude/latitude offsets are applied before the shared CRS
+ * operation. Ambiguous default/meter-offset representations and repeated source transforms fail
+ * explicitly. The caller declares source metadata through the context; metadata on content must
+ * agree. Source arrays and traversal headers remain unchanged. Output bounds describe decoded
+ * points, not the source LOD volume; archive sinks rebuild their bounds from encoded points.
+ * @param sourceTile - A decoded source tile with packed Arrow positions.
+ * @param options - Source spatial policy, optional normal frame and cancellation.
+ * @returns Prepared target-frame point content, or the unchanged empty tile.
+ */
+export async function transformPointCloudSourceTile(
+  sourceTile: PointCloudSourceTile,
+  options: PointCloudSpatialOptions
+): Promise<PointCloudSourceTile> {
+  options.signal?.throwIfAborted();
+  const {content} = sourceTile;
+  if (!content) return sourceTile;
+  const reference = options.spatialContext.spatialReference;
+  const contentReference = content.spatialReference;
+  // Already transformed ECEF sources can still expose renderer-relative positions. A native
+  // context for their effective frame resolves placement without repeating the source operation.
+  const retainTransformedEcef =
+    contentReference?.status === 'transformed' &&
+    (contentReference.targetCrs || contentReference.sourceCrs) === 'EPSG:4978' &&
+    reference.status === 'native' &&
+    reference.sourceCrs === 'EPSG:4978' &&
+    reference.verticalUnitScale === 1 &&
+    (reference.units?.every(unit => unit === 'meter') ?? true);
+  const sourceReference = retainTransformedEcef
+    ? createTilesetSpatialReference({
+        sourceCrs: 'EPSG:4978',
+        coordinateFrame: 'geocentric',
+        axisOrder: 'xyz',
+        units: reference.units,
+        coordinateEpoch: contentReference.coordinateEpoch,
+        heightReference:
+          contentReference.targetHeightReference === 'native'
+            ? contentReference.heightReference
+            : contentReference.targetHeightReference
+      })
+    : contentReference;
+  if (
+    sourceReference &&
+    (sourceReference.status === 'transformed' ||
+      sourceReference.status === 'unresolved' ||
+      JSON.stringify(sourceReference.sourceCrs) !== JSON.stringify(reference.sourceCrs) ||
+      sourceReference.heightReference !== reference.heightReference ||
+      sourceReference.verticalUnitScale !== reference.verticalUnitScale ||
+      sourceReference.coordinateEpoch !== reference.coordinateEpoch ||
+      JSON.stringify(sourceReference.units) !== JSON.stringify(reference.units) ||
+      sourceReference.elevationMode !== reference.elevationMode ||
+      sourceReference.elevationOffset !== reference.elevationOffset ||
+      sourceReference.elevationUnitScale !== reference.elevationUnitScale)
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_SPATIAL_REFERENCE_MISMATCH',
+      'Point content and context must agree on the input CRS, units, height reference and epoch'
+    );
+  }
+  const sourceFrame =
+    reference.coordinateFrame === 'unknown' && reference.sourceCrs
+      ? getSpatialCoordinateFrame(reference.sourceCrs)
+      : reference.coordinateFrame;
+  const geographic = sourceFrame === 'geographic';
+  if (
+    !['xy', 'xyz', 'unknown'].includes(reference.axisOrder) ||
+    (geographic
+      ? !['lnglat', 'lnglat-offsets'].includes(content.coordinateSystem)
+      : content.coordinateSystem !== 'cartesian' ||
+        !['projected', 'geocentric', 'cartesian', 'local'].includes(sourceFrame))
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_SOURCE_FRAME_UNSUPPORTED',
+      'Spatial preparation requires explicit Cartesian or longitude/latitude positions in source xyz order'
+    );
+  }
+  if (
+    content.cartographicOrigin.length !== 3 ||
+    content.cartographicOrigin.some(value => !Number.isFinite(value)) ||
+    (content.coordinateSystem !== 'lnglat-offsets' &&
+      content.cartographicOrigin.some(value => value !== 0))
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_SOURCE_ORIGIN_INVALID',
+      'Only longitude/latitude offsets use a nonzero cartographic origin'
+    );
+  }
+  if (
+    content.modelMatrix &&
+    (content.modelMatrix.length !== 16 ||
+      Array.from(content.modelMatrix).some(value => !Number.isFinite(value)))
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_SOURCE_PLACEMENT_UNSUPPORTED',
+      'Point placement must contain sixteen finite matrix values'
+    );
+  }
+  const matrix = new Matrix4(content.modelMatrix ? Array.from(content.modelMatrix) : undefined);
+  const determinant = matrix.determinant();
+  if (
+    matrix[3] !== 0 ||
+    matrix[7] !== 0 ||
+    matrix[11] !== 0 ||
+    matrix[15] !== 1 ||
+    !Number.isFinite(determinant) ||
+    determinant === 0 ||
+    (geographic && !matrix.equals(new Matrix4()))
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_SOURCE_PLACEMENT_UNSUPPORTED',
+      'Cartesian placement must be finite, affine and invertible; geographic placement must be identity'
+    );
+  }
+  const mesh = convertTableToMesh(content.data);
+  const positionAttribute = mesh.attributes.POSITION;
+  const declaredTransform = mesh.schema?.fields.find(field => field.name === 'POSITION')
+    ?.metadata?.['loaders.gl.transform'];
+  if (declaredTransform && !positionAttribute?.transform) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_TRANSFORM_INVALID',
+      'Arrow position transform metadata is unsupported or invalid'
+    );
+  }
+  const sourcePositions = decodePointCloudPositions(positionAttribute);
+  if (sourcePositions.some(value => !Number.isFinite(value))) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_INVALID',
+      'Decoded point positions must be finite'
+    );
+  }
+  const translationOnly = Array.from(matrix).every(
+    (value, index) => (index >= 12 && index <= 14) || value === (index % 5 === 0 ? 1 : 0)
+  );
+  for (let index = 0; index < sourcePositions.length; index += 3) {
+    if (geographic || translationOnly) {
+      for (let axis = 0; axis < 3; axis++) {
+        sourcePositions[index + axis] += geographic
+          ? content.cartographicOrigin[axis]
+          : matrix[12 + axis];
+      }
+    } else {
+      sourcePositions.set(
+        matrix.transformAsPoint(Array.from(sourcePositions.subarray(index, index + 3))),
+        index
+      );
+    }
+  }
+  const normalAttribute = mesh.attributes.NORMAL;
+  let normals: Float32Array | undefined;
+  if (normalAttribute) {
+    if (
+      !options.normalReferenceFrame ||
+      normalAttribute.size !== 3 ||
+      normalAttribute.value.length !== sourcePositions.length ||
+      normalAttribute.transform ||
+      normalAttribute.normalized ||
+      normalAttribute.byteOffset ||
+      normalAttribute.byteStride ||
+      normalAttribute.componentType ||
+      !translationOnly
+    ) {
+      throw new TileConversionError(
+        'POINT_CLOUD_NORMAL_FRAME_REQUIRED',
+        'Spatial point normals require a declared vector frame and packed xyz values'
+      );
+    }
+    normals = new Float32Array(normalAttribute.value.length);
+    for (let index = 0; index < normals.length; index += 3) {
+      const normal = Array.from(normalAttribute.value.slice(index, index + 3));
+      const length = Math.hypot(...normal);
+      if (!Number.isFinite(length) || length === 0) {
+        throw new TileConversionError(
+          'POINT_CLOUD_NORMAL_INVALID',
+          'Spatial point normals must be finite and nonzero'
+        );
+      }
+      normals.set(
+        normal.map(value => value / length),
+        index
+      );
+    }
+  }
+  const transformed = await options.spatialContext.transformGeometryAsync(
+    sourcePositions,
+    normals,
+    options.normalReferenceFrame
+  );
+  options.signal?.throwIfAborted();
+  if (transformed.positions.length !== sourcePositions.length) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_INVALID',
+      'Spatial conversion must return one xyz triple per point'
+    );
+  }
+  const minimum = [Infinity, Infinity, Infinity];
+  const maximum = [-Infinity, -Infinity, -Infinity];
+  for (let index = 0; index < transformed.positions.length; index++) {
+    const value = transformed.positions[index];
+    if (!Number.isFinite(value)) {
+      throw new TileConversionError(
+        'POINT_CLOUD_POSITION_INVALID',
+        'Transformed point positions must be finite'
+      );
+    }
+    const axis = index % 3;
+    minimum[axis] = Math.min(minimum[axis], value);
+    maximum[axis] = Math.max(maximum[axis], value);
+  }
+  const center = minimum.map((value, axis) => value / 2 + maximum[axis] / 2);
+  const targetFrame =
+    reference.status === 'native'
+      ? sourceFrame
+      : getSpatialCoordinateFrame(reference.targetCrs || reference.sourceCrs!);
+  const targetIsGeographic = targetFrame === 'geographic';
+  const attributes = {
+    ...mesh.attributes,
+    POSITION: {value: transformed.positions, size: 3},
+    ...(transformed.normals ? {NORMAL: {value: transformed.normals, size: 3}} : {})
+  };
+  return {
+    header: sourceTile.header,
+    content: {
+      ...content,
+      data: makeMeshArrowTable(attributes, {
+        topology: 'point-list',
+        boundingBox: [minimum, maximum],
+        schema: mesh.schema
+          ? {
+              ...mesh.schema,
+              metadata: {
+                ...mesh.schema.metadata,
+                topology: 'point-list',
+                boundingBox: JSON.stringify([minimum, maximum])
+              },
+              fields: mesh.schema.fields.map(field =>
+                field.name === 'POSITION' || (transformed.normals && field.name === 'NORMAL')
+                  ? {...field, metadata: {}}
+                  : field
+              )
+            }
+          : undefined
+      }),
+      coordinateSystem: targetIsGeographic ? 'lnglat' : 'cartesian',
+      cartographicOrigin: [0, 0, 0],
+      modelMatrix: undefined,
+      spatialReference: reference,
+      spatialBoundingVolume: {
+        cartographicBounds: [minimum, maximum],
+        coordinateFrame: targetIsGeographic ? 'geographic' : 'cartesian',
+        center,
+        radius: Math.hypot(...maximum.map((value, axis) => value - center[axis]))
+      }
+    }
+  };
+}

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-tileset.ts

@@ -0,0 +1,137 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Mesh, MeshArrowTable} from '@loaders.gl/schema';
+import type {PointCloudTilerOptions} from '@loaders.gl/schema-utils';
+import type {TilesetSpatialReference} from '@loaders.gl/tiles';
+import {PointCloudTileSource} from '@loaders.gl/tiles/point-cloud-tile-source';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  BrowserTileConversionFile,
+  TileConversionProgress,
+  TileConversionReport
+} from '@loaders.gl/tile-converter/v5/core';
+import {convertPointCloudSource} from './point-cloud-conversion.js';
+import {createPointCloudTilesetSink} from './point-cloud-tileset-sink.js';
+import type {PointCloudTilesetSinkOptions} from './point-cloud-tileset-sink.js';
+import {createTileConversionArchive} from './conversion-archive.js';
+import type {TileConversionArchiveOptions} from './conversion-archive.js';
+
+/** Bounded authoring of a complete decoded ECEF point dataset. */
+export interface ConvertPointCloudToTilesetOptions extends PointCloudTilesetSinkOptions {
+  /** Explicit native EPSG:4978 XYZ meters with ellipsoidal heights. No CRS is inferred. */
+  readonly spatialReference: TilesetSpatialReference;
+  /** In-memory input, index, gathered-tile and node limits; defaults belong to PointCloudTiler. */
+  readonly tiling?: Omit<PointCloudTilerOptions, 'signal'>;
+  /** Also create an indexed 3TZ Blob within this final archive-size budget. */
+  readonly archive?: Pick<TileConversionArchiveOptions, 'maxArchiveBytes'>;
+  /** Cooperative cancellation during indexing, traversal, encoding and packaging. */
+  readonly signal?: AbortSignal;
+  /** PNTS conversion progress; excludes tileset JSON and optional archive packaging. */
+  readonly onProgress?: (progress: TileConversionProgress) => void;
+}
+
+/** Completed point authoring result; no partial files are returned on failure. */
+export interface ConvertedPointCloudTileset {
+  /** Exact number of input points, each emitted once across the complete collection. */
+  readonly pointCount: number;
+  /** PNTS resource counts and bytes; input bytes count gathered Arrow column buffers. */
+  readonly report: TileConversionReport;
+  /** PNTS resources and tileset.json, including JSON in the retained output byte budget. */
+  readonly files: readonly BrowserTileConversionFile[];
+  /** Optional indexed 3TZ Blob. Applications own saving and object URL lifetimes. */
+  readonly archive?: Blob;
+}
+
+/**
+ * Tiles decoded point Mesh/Arrow data and authors a flat additive 3D Tiles 1.0 collection.
+ * All input rows are emitted once, including remaining rows at the tiler's maximum depth.
+ * Per-tile RTC centers reduce float32 rounding; geometricError gates measured reconstruction error.
+ * The flat collection does not preserve octree LOD or provide a sampling-error guarantee.
+ * Input must remain immutable until completion. Arrow normalization can copy buffers; retained
+ * input, row indexes, gathered tiles, output Blobs and optional ZIP temporaries are separate memory.
+ * This is bounded in-memory authoring, not streaming ingestion or an out-of-core converter.
+ * Unsupported PNTS attributes fail; callers must explicitly map or remove them beforehand.
+ * @param input - One decoded unindexed point-list with finite floating-point XYZ positions.
+ * @param options - Explicit ECEF frame, precision and resource limits, and optional 3TZ packaging.
+ * @returns Completed files and report after releasing the privately owned dynamic source.
+ */
+export async function convertPointCloudToTileset(
+  input: Mesh | MeshArrowTable,
+  options: ConvertPointCloudToTilesetOptions
+): Promise<ConvertedPointCloudTileset> {
+  const reference = options.spatialReference;
+  if (
+    !reference ||
+    reference.status !== 'native' ||
+    reference.sourceCrs !== 'EPSG:4978' ||
+    (reference.targetCrs && reference.targetCrs !== 'EPSG:4978') ||
+    reference.coordinateFrame !== 'geocentric' ||
+    reference.axisOrder !== 'xyz' ||
+    reference.heightReference !== 'ellipsoidal' ||
+    reference.verticalUnitScale !== 1 ||
+    reference.units?.some(unit => unit !== 'meter')
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_TILESET_FRAME_UNSUPPORTED',
+      'Point authoring requires explicit native EPSG:4978 xyz meters and ellipsoidal heights'
+    );
+  }
+  if (
+    options.archive &&
+    (!Number.isSafeInteger(options.archive.maxArchiveBytes) || options.archive.maxArchiveBytes < 0)
+  ) {
+    throw new TileConversionError(
+      'INVALID_ARCHIVE_BYTE_LIMIT',
+      'Archive byte limit must be a non-negative safe integer'
+    );
+  }
+  options.signal?.throwIfAborted();
+  const sink = createPointCloudTilesetSink(options);
+  let source: PointCloudTileSource | undefined;
+  try {
+    source = new PointCloudTileSource(input, {
+      pointCloudTiler: {...options.tiling, signal: options.signal, spatialReference: reference}
+    });
+    const {pointCount} = await source.getMetadata();
+    const report = await convertPointCloudSource(source, {
+      sink,
+      signal: options.signal,
+      onProgress: options.onProgress,
+      measureInputBytes: tile => {
+        const table = tile.content?.data.data;
+        return table
+          ? table.schema.fields.reduce(
+              (bytes, _field, index) => bytes + (table.getChildAt(index)?.byteLength ?? 0),
+              0
+            )
+          : 0;
+      },
+      getTileEncodingOptions: tile => ({
+        rtcCenter: [
+          tile.header.boundingVolume.center[0],
+          tile.header.boundingVolume.center[1],
+          tile.header.boundingVolume.center[2]
+        ],
+        maxPositionError: options.geometricError
+      })
+    });
+    options.signal?.throwIfAborted();
+    const files = sink.getFiles();
+    const archive = options.archive
+      ? await createTileConversionArchive(files, {
+          format: '3tz',
+          maxArchiveBytes: options.archive.maxArchiveBytes,
+          signal: options.signal
+        })
+      : undefined;
+    options.signal?.throwIfAborted();
+    return {pointCount, report, files, archive};
+  } catch (error) {
+    await sink.abort(error);
+    throw error;
+  } finally {
+    source?.close();
+  }
+}