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

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

@@ -0,0 +1,289 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {COPCWriter, type COPCWriterOptions} from '@loaders.gl/tiles-3d/copc';
+import type {Mesh, MeshArrowTable} from '@loaders.gl/core/schema';
+import {TileConversionError, type TileConversionCodec} from '@loaders.gl/tile-converter/v5/core';
+import {
+  getPointCloudMesh,
+  mapPointCloudAttributes,
+  type PointCloudAttributeMapping
+} from './point-cloud-attributes.js';
+
+/** Bounded, explicitly placed COPC batch authoring. */
+export interface EncodePointCloudCOPCOptions {
+  /** All attribute aliases and semantic omissions must be explicit. */
+  readonly mapping: PointCloudAttributeMapping;
+  /** LAS axis scales; positions must already be absolute coordinates in the declared CRS. */
+  readonly scale: readonly [number, number, number];
+  /** LAS axis offsets used for signed int32 quantization. */
+  readonly offset: readonly [number, number, number];
+  /** Explicit OGC WKT CRS declaration; no inference or reprojection is performed. */
+  readonly wkt: string;
+  /** Maximum Euclidean quantization error in source units. */
+  readonly maxPositionError: number;
+  /** Maximum distinct retained source buffer bytes; default 64 MiB. */
+  readonly maxInputBytes?: number;
+  /** Maximum rows in one batch; default 1000000. */
+  readonly maxPoints?: number;
+  /** Maximum completed encoded bytes; default 128 MiB. Writer temporary memory is additional. */
+  readonly maxOutputBytes?: number;
+  /** Explicit LAS Extra Bytes names for custom typed attributes, including exact 64-bit IDs. */
+  readonly extraBytes?: NonNullable<COPCWriterOptions['copc']>['extraBytes'];
+  /** Optional octree organization forwarded to the owning COPC writer. */
+  readonly organization?: Pick<
+    NonNullable<COPCWriterOptions['copc']>,
+    'nodePointLimit' | 'maximumDepth' | 'hierarchyPageDepth' | 'spacing'
+  >;
+  /** Cancellation before validation and before/after synchronous writer execution. */
+  readonly signal?: AbortSignal;
+}
+
+/** A complete COPC file and its explicit precision/loss report. */
+export interface EncodedPointCloudCOPC {
+  /** Range-readable COPC 1.0 / LAZ 1.4 bytes. */
+  readonly copc: ArrayBuffer;
+  /** Exact encoded point count. */
+  readonly pointCount: number;
+  /** Maximum reconstructed Euclidean position error. */
+  readonly maximumPositionError: number;
+  /** Authorized attribute omissions and reasons. */
+  readonly droppedAttributes: Readonly<Record<string, string>>;
+}
+
+/** Standard scalar attributes qualified for PDRF 6/7/8, with integer bounds. */
+const SCALAR_RANGES: Readonly<Record<string, readonly [number, number]>> = {
+  intensity: [0, 65535],
+  classification: [0, 255],
+  nir: [0, 65535],
+  gpsTime: [-Infinity, Infinity],
+  scanAngle: [-32768, 32767],
+  userData: [0, 255],
+  pointSourceId: [0, 65535],
+  returnNumber: [1, 15],
+  numberOfReturns: [1, 15],
+  scannerChannel: [0, 3],
+  scanDirectionFlag: [0, 1],
+  edgeOfFlightLine: [0, 1],
+  synthetic: [0, 1],
+  keyPoint: [0, 1],
+  withheld: [0, 1],
+  overlap: [0, 1]
+};
+
+/** Encodes one decoded point batch as COPC with explicit mappings, CRS and precision gates. */
+export async function encodePointCloudCOPC(
+  input: Mesh | MeshArrowTable,
+  options: EncodePointCloudCOPCOptions
+): Promise<EncodedPointCloudCOPC> {
+  const maxInputBytes = options.maxInputBytes ?? 64 * 1024 * 1024;
+  const maxPoints = options.maxPoints ?? 1000000;
+  const maxOutputBytes = options.maxOutputBytes ?? 128 * 1024 * 1024;
+  if (
+    [maxInputBytes, maxPoints, maxOutputBytes].some(
+      value => !Number.isSafeInteger(value) || value < 1
+    ) ||
+    options.scale.length !== 3 ||
+    options.scale.some(value => !Number.isFinite(value) || value <= 0) ||
+    options.offset.length !== 3 ||
+    options.offset.some(value => !Number.isFinite(value)) ||
+    typeof options.wkt !== 'string' ||
+    !options.wkt.trim() ||
+    !Number.isFinite(options.maxPositionError) ||
+    options.maxPositionError < 0
+  )
+    throw new TileConversionError(
+      'POINT_CLOUD_COPC_OPTIONS_INVALID',
+      'COPC requires explicit finite scale, offset, CRS, precision and positive budgets'
+    );
+  options.signal?.throwIfAborted();
+  const source = getPointCloudMesh(input, maxInputBytes);
+  const {mesh, droppedAttributes} = mapPointCloudAttributes(source, options.mapping);
+  const position = mesh.attributes.POSITION;
+  const pointCount = mesh.header?.vertexCount ?? position.value.length / 3;
+  if (!Number.isSafeInteger(pointCount) || pointCount < 1 || pointCount > maxPoints)
+    throw new TileConversionError(
+      'POINT_CLOUD_POINT_BUDGET',
+      'COPC requires a nonempty batch within the point limit'
+    );
+  if (
+    !(position.value instanceof Float32Array || position.value instanceof Float64Array) ||
+    position.size !== 3 ||
+    position.normalized
+  )
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_INVALID',
+      'COPC requires decoded floating XYZ'
+    );
+  const extraNames = new Set(options.extraBytes?.map(field => field.attribute) || []);
+  const descriptorNames = new Set(
+    options.extraBytes?.map(field => field.name || field.attribute) || []
+  );
+  if (
+    extraNames.size !== (options.extraBytes?.length || 0) ||
+    descriptorNames.size !== extraNames.size ||
+    options.extraBytes?.some(field => {
+      const name = field.name || field.attribute;
+      const description = field.description || '';
+      return (
+        !mesh.attributes[field.attribute] ||
+        !field.attribute ||
+        !name.length ||
+        name.length > 32 ||
+        description.length > 32 ||
+        /[^\x20-\x7e]/.test(name) ||
+        /[^\x20-\x7e]/.test(description)
+      );
+    })
+  )
+    throw new TileConversionError(
+      'POINT_CLOUD_EXTRA_BYTES_INVALID',
+      'Extra Bytes descriptors require unique mapped attributes and names/descriptions within 32 printable ASCII bytes'
+    );
+  for (const name of extraNames)
+    if (name === 'POSITION' || name === 'COLOR_0' || Object.hasOwn(SCALAR_RANGES, name))
+      throw new TileConversionError(
+        'POINT_CLOUD_EXTRA_BYTES_INVALID',
+        'Map standard attributes directly instead of duplicating them as Extra Bytes'
+      );
+  for (const [name, attribute] of Object.entries(mesh.attributes)) {
+    const color = name === 'COLOR_0';
+    const extra = extraNames.has(name);
+    if (name !== 'POSITION' && !color && !extra && !Object.hasOwn(SCALAR_RANGES, name))
+      throw new TileConversionError(
+        'POINT_CLOUD_ATTRIBUTE_UNSUPPORTED',
+        `COPC cannot preserve ${name}; supply an explicit supported mapping or drop reason`
+      );
+    if (
+      attribute.transform ||
+      attribute.byteOffset ||
+      attribute.byteStride ||
+      attribute.componentType === 'float16' ||
+      attribute.value.length !== pointCount * attribute.size ||
+      (!color && attribute.normalized) ||
+      (name !== 'POSITION' &&
+        !color &&
+        (extra ? ![1, 3].includes(attribute.size) : attribute.size !== 1))
+    )
+      throw new TileConversionError(
+        'POINT_CLOUD_ATTRIBUTE_INVALID',
+        `COPC requires packed decoded attributes: ${name}`
+      );
+    if (color) {
+      if (
+        attribute.size !== 3 ||
+        !(attribute.value instanceof Uint8Array || attribute.value instanceof Uint16Array)
+      )
+        throw new TileConversionError(
+          'POINT_CLOUD_COLOR_INVALID',
+          'COPC requires explicitly mapped uint8/uint16 RGB'
+        );
+    } else if (extra) {
+      for (const value of attribute.value)
+        if (typeof value !== 'bigint' && !Number.isFinite(value))
+          throw new TileConversionError(
+            'POINT_CLOUD_ATTRIBUTE_RANGE',
+            `Nonfinite Extra Bytes value: ${name}`
+          );
+    } else if (name !== 'POSITION') {
+      const [minimum, maximum] = SCALAR_RANGES[name];
+      for (const value of attribute.value) {
+        if (
+          typeof value !== 'number' ||
+          !Number.isFinite(value) ||
+          value < minimum ||
+          value > maximum ||
+          (name !== 'gpsTime' && !Number.isInteger(value))
+        )
+          throw new TileConversionError(
+            'POINT_CLOUD_ATTRIBUTE_RANGE',
+            `COPC value outside the qualified range: ${name}`
+          );
+      }
+    }
+  }
+  let maximumPositionError = 0;
+  const minimum = [Infinity, Infinity, Infinity];
+  const maximum = [-Infinity, -Infinity, -Infinity];
+  const errors = [0, 0, 0];
+  for (let row = 0; row < pointCount; row++) {
+    for (let axis = 0; axis < 3; axis++) {
+      const value = position.value[row * 3 + axis];
+      const encoded = Math.round((value - options.offset[axis]) / options.scale[axis]);
+      if (
+        !Number.isFinite(value) ||
+        !Number.isSafeInteger(encoded) ||
+        encoded < -2147483648 ||
+        encoded > 2147483647
+      )
+        throw new TileConversionError(
+          'POINT_CLOUD_POSITION_RANGE',
+          'COPC position exceeds signed int32 quantization'
+        );
+      minimum[axis] = Math.min(minimum[axis], value);
+      maximum[axis] = Math.max(maximum[axis], value);
+      errors[axis] = encoded * options.scale[axis] + options.offset[axis] - value;
+    }
+    maximumPositionError = Math.max(maximumPositionError, Math.hypot(...errors));
+    if (maximumPositionError > options.maxPositionError)
+      throw new TileConversionError(
+        'POINT_CLOUD_PRECISION_EXCEEDED',
+        'COPC position rounding exceeds the declared error gate'
+      );
+    if (row % 16384 === 0) {
+      await new Promise<void>(resolve => setTimeout(resolve, 0));
+      options.signal?.throwIfAborted();
+    }
+  }
+  const width = Math.max(...maximum.map((value, axis) => value - minimum[axis]), ...options.scale);
+  const radius = width / 2;
+  if (
+    !Number.isFinite(Math.hypot(radius, radius, radius)) ||
+    minimum.some((value, axis) => {
+      const center = value + (maximum[axis] - value) / 2;
+      return (
+        !Number.isFinite(value + maximum[axis]) ||
+        !Number.isFinite(center - radius) ||
+        !Number.isFinite(center + radius)
+      );
+    })
+  )
+    throw new TileConversionError('POINT_CLOUD_BOUNDS_INVALID', 'COPC coordinate extent overflow');
+  // The owning writer executes synchronously; cancellation cannot interrupt its compression call.
+  options.signal?.throwIfAborted();
+  const color = mesh.attributes.COLOR_0;
+  const copc = COPCWriter.encodeSync(mesh, {
+    copc: {
+      ...options.organization,
+      scale: [...options.scale],
+      offset: [...options.offset],
+      wkt: options.wkt,
+      pointDataRecordFormat: mesh.attributes.nir ? 8 : color ? 7 : 6,
+      colorDepth: color?.value instanceof Uint16Array ? 16 : 8,
+      extraBytes: options.extraBytes
+    }
+  });
+  options.signal?.throwIfAborted();
+  if (copc.byteLength > maxOutputBytes)
+    throw new TileConversionError(
+      'POINT_CLOUD_OUTPUT_BUDGET',
+      'Completed COPC output exceeds the byte budget'
+    );
+  return {copc, pointCount, maximumPositionError, droppedAttributes};
+}
+
+/** Creates a v5 codec for one independently authored COPC file per decoded input batch. */
+export function createCOPCConversionCodec(
+  options: EncodePointCloudCOPCOptions
+): TileConversionCodec<unknown, Mesh | MeshArrowTable, EncodedPointCloudCOPC> {
+  return {
+    async *convert(input, _inspection, signal) {
+      const combinedSignal =
+        options.signal && signal
+          ? AbortSignal.any([options.signal, signal])
+          : options.signal || signal;
+      yield await encodePointCloudCOPC(input, {...options, signal: combinedSignal});
+    }
+  };
+}

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

@@ -0,0 +1,306 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {COPCSourceLoader} from '@loaders.gl/tiles-3d/copc';
+import type {COPCTileSource, COPCSourceLoaderOptions} from '@loaders.gl/tiles-3d/copc';
+import {PotreeSourceLoader, encodePotreeDataset} from '@loaders.gl/tiles-3d/potree';
+import type {
+  PotreeDataset,
+  PotreeWriterNode,
+  PotreeWriterOptions,
+  PotreeSourceLoaderOptions
+} from '@loaders.gl/tiles-3d/potree';
+import type {Mesh, MeshArrowTable, MeshGeometry} from '@loaders.gl/core/schema';
+import {deduceMeshSchema} from '@loaders.gl/core/schema-utils';
+import {encodeZip, openZipArchive} from '@loaders.gl/archives/zip';
+import type {ZipArchive, ZipEntry} from '@loaders.gl/archives/zip';
+
+/** Explicit local-file input; no format is inferred from an extension. */
+export type OpenPointCloudFileOptions = {
+  /** Maximum retained input Blob size. This does not bound decoded heap. */
+  readonly maxFileBytes: number;
+  /** Cancellation before/after initialization and during archived resource reads. */
+  readonly signal?: AbortSignal;
+} & (
+  | {
+      /** COPC is a native single LAZ file. */
+      readonly format: 'copc';
+      /** Existing COPC source coordinate and decoder controls. */
+      readonly sourceOptions?: COPCSourceLoaderOptions;
+    }
+  | {
+      /** A loaders.gl STORE ZIP convention, not a native Potree archive standard. */
+      readonly format: 'potree-zip';
+      /** Maximum ZIP entry count, including metadata; default 100000. */
+      readonly maxEntries?: number;
+      /** Maximum requested ZIP resource/range bytes; default 64 MiB. */
+      readonly maxResourceBytes?: number;
+      /** Explicit metadata path when it is not at the ZIP root. */
+      readonly metadataPath?: string;
+      /** Existing Potree parser controls; the bundle owns its isolated fetch transport. */
+      readonly sourceOptions?: PotreeSourceLoaderOptions;
+    }
+);
+
+/** An initialized source with an owned local file lifetime. */
+export interface OpenedPointCloudFile {
+  /** Lazy node access through the existing unified source APIs. */
+  readonly source: ReturnType<typeof PotreeSourceLoader.createDataSource> | COPCTileSource;
+  /** Closes the source and rejects subsequent bundle reads; idempotent. */
+  readonly close: () => Promise<void>;
+}
+
+/** Complete Potree dataset packaging controls. */
+export interface EncodePotreeArchiveOptions {
+  /** Existing dataset version, precision, hierarchy and encoded-byte limits. */
+  readonly potree?: PotreeWriterOptions['potree'];
+  /** Maximum completed STORE ZIP32 bytes, checked before archive allocation. */
+  readonly maxArchiveBytes: number;
+}
+
+/**
+ * Writes a complete Potree 1.x/2.0 dataset to a deterministic uncompressed ZIP32 Blob.
+ * This is a loaders.gl bundle convention, not a native Potree archive standard. Metadata sits
+ * at the root with original relative resource paths. Writer version/attribute/precision gates
+ * apply. Inputs, dataset bytes, ZIP temporaries and the returned Blob are separate memory.
+ * @param input - Decoded points or caller-organized additive nodes; no LOD sampling is inferred.
+ * @param options - Dataset writer controls and final archive budget.
+ * @returns A downloadable ZIP Blob that openPointCloudFile can read incrementally.
+ */
+export async function encodePotreeArchive(
+  input: Mesh | MeshArrowTable | readonly PotreeWriterNode[],
+  options: EncodePotreeArchiveOptions
+): Promise<Blob> {
+  validateLimit(options.maxArchiveBytes);
+  const dataset = await encodePotreeDataset(input, {potree: options.potree});
+  return encodePotreeDatasetArchive(dataset, options.maxArchiveBytes, options.potree?.signal);
+}
+
+/** Packages already encoded Potree files without encoding or sampling points a second time. */
+export async function encodePotreeDatasetArchive(
+  dataset: PotreeDataset,
+  maxArchiveBytes: number,
+  signal?: AbortSignal
+): Promise<Blob> {
+  validateLimit(maxArchiveBytes);
+  for (const path of dataset.files.keys()) validatePath(path);
+  signal?.throwIfAborted();
+  const archive = await encodeZip(Object.fromEntries(dataset.files), {
+    compression: 'store',
+    zip64: 'never',
+    maxEntries: 65535,
+    maxArchiveBytes: BigInt(maxArchiveBytes),
+    signal
+  });
+  signal?.throwIfAborted();
+  return new Blob([archive], {type: 'application/zip'});
+}
+
+/**
+ * Opens a COPC Blob or a Potree STORE ZIP without extracting the complete dataset.
+ * ZIP directory/local headers are checked before constructing the Potree source; modern node
+ * requests slice only their archived byte ranges. DEFLATE, encrypted entries, ambiguous
+ * metadata and noncanonical paths fail explicitly. Partial reads do not verify whole-entry CRCs.
+ * Legacy Potree retains its existing coordinate behavior; modern Potree retains native coordinates.
+ * COPC uses its existing source coordinate policy. Applications own CRS preparation and conversion.
+ * @param input - Immutable local file/Blob, bounded by maxFileBytes.
+ * @param options - Explicit format, source controls and archive transport limits.
+ * @returns An initialized lazy source; close it when conversion finishes.
+ */
+export async function openPointCloudFile(
+  input: Blob,
+  options: OpenPointCloudFileOptions
+): Promise<OpenedPointCloudFile> {
+  validateLimit(options.maxFileBytes);
+  if (input.size > options.maxFileBytes) throw new RangeError('Point file input budget exceeded');
+  options.signal?.throwIfAborted();
+  if (options.format === 'copc') {
+    const source = COPCSourceLoader.createDataSource(input, options.sourceOptions || {});
+    try {
+      await source.metadata;
+      options.signal?.throwIfAborted();
+      return {source, close: () => source.close()};
+    } catch (error) {
+      await source.close();
+      throw error;
+    }
+  }
+  if (options.format !== 'potree-zip') throw new TypeError('Unsupported point file format');
+  const maxEntries = options.maxEntries ?? 100000;
+  const maxResourceBytes = options.maxResourceBytes ?? 64 * 1024 * 1024;
+  validateLimit(maxEntries);
+  validateLimit(maxResourceBytes);
+  const controller = new AbortController();
+  const signals = [controller.signal, options.signal, options.sourceOptions?.potree?.signal].filter(
+    (value): value is AbortSignal => Boolean(value)
+  );
+  const signal = AbortSignal.any(signals);
+  let archive: ZipArchive | undefined;
+  const entries = new Map<string, ZipEntry>();
+  let source: ReturnType<typeof PotreeSourceLoader.createDataSource> | undefined;
+  try {
+    archive = await openZipArchive(input, {
+      maxArchiveBytes: BigInt(options.maxFileBytes),
+      maxEntries,
+      maxReadBytes: Math.max(65557, maxResourceBytes),
+      maxCompressedBytes: BigInt(maxResourceBytes),
+      maxDecodedBytes: BigInt(maxResourceBytes),
+      signal
+    });
+    for await (const entry of archive.entries()) {
+      if (entry.directory) continue;
+      validatePath(entry.path);
+      if (entry.compression !== 'store')
+        throw new Error('Potree bundles require unencrypted STORE entries');
+      entries.set(entry.path, entry);
+    }
+    const candidates = ['metadata.json', 'cloud.js'].filter(path => entries.has(path));
+    const metadataPath = options.metadataPath || (candidates.length === 1 ? candidates[0] : '');
+    validatePath(metadataPath);
+    if (!entries.has(metadataPath) || !/(^|\/)(metadata\.json|cloud\.js)$/.test(metadataPath))
+      throw new Error('Potree ZIP requires one metadata entry or an explicit metadataPath');
+    const prefix = 'https://point-bundle.loaders.gl.invalid/';
+    /** Isolated archive transport; it never falls back to network access. */
+    const fetchResource = async (
+      resource: string,
+      request: RequestInit = {}
+    ): Promise<Response> => {
+      signal.throwIfAborted();
+      request.signal?.throwIfAborted();
+      const url = new URL(resource);
+      if (url.origin !== new URL(prefix).origin || url.search || url.hash)
+        throw new Error('Resource outside the Potree bundle');
+      const path = decodeURIComponent(url.pathname.slice(1));
+      validatePath(path);
+      const entry = entries.get(path);
+      if (!entry) throw new Error(`Missing Potree bundle resource: ${path}`);
+      const range = new Headers(request.headers).get('range');
+      const match = range?.match(/^bytes=(\d+)-(\d+)$/);
+      if (range && !match) throw new RangeError('Unsupported Potree bundle byte range');
+      const begin = match ? Number(match[1]) : 0;
+      const end = match ? Number(match[2]) + 1 : Number(entry.size);
+      if (
+        !Number.isSafeInteger(begin) ||
+        !Number.isSafeInteger(end) ||
+        begin < 0 ||
+        end < begin ||
+        BigInt(end) > entry.size ||
+        end - begin > maxResourceBytes
+      )
+        throw new RangeError('Potree bundle resource/range budget exceeded');
+      const headers = new Headers({
+        'content-length': String(end - begin),
+        'accept-ranges': 'bytes'
+      });
+      if (match) headers.set('content-range', `bytes ${begin}-${end - 1}/${entry.size}`);
+      const bytes = match
+        ? await archive!.readRange(entry, {
+            start: BigInt(begin),
+            end: BigInt(end),
+            signal: request.signal ?? undefined
+          })
+        : await archive!.read(entry, {signal: request.signal ?? undefined});
+      const response = new Response(bytes, {
+        status: match ? 206 : 200,
+        headers
+      });
+      Object.defineProperty(response, 'url', {value: url.href});
+      signal.throwIfAborted();
+      return response;
+    };
+    source = PotreeSourceLoader.createDataSource(`${prefix}${metadataPath}`, {
+      ...options.sourceOptions,
+      core: {...options.sourceOptions?.core, fetch: fetchResource},
+      potree: {...options.sourceOptions?.potree, signal}
+    });
+    await source.initialize();
+    signal.throwIfAborted();
+    return {
+      source,
+      async close() {
+        controller.abort();
+        source?.close();
+        await archive?.close();
+      }
+    };
+  } catch (error) {
+    controller.abort();
+    source?.close();
+    await archive?.close();
+    throw error;
+  }
+}
+
+/** Explicit opt-in mesh-to-point selection. */
+export interface ExtractMeshVerticesOptions {
+  /** Attribute names to retain in addition to POSITION; all other semantics are omitted explicitly. */
+  readonly attributes: readonly string[];
+  /** Maximum stored vertices, not expanded triangle corners. */
+  readonly maxPoints: number;
+}
+
+/**
+ * Harvests one point per stored vertex from already placed triangle geometry.
+ * Does not expand indices, deduplicate coincident vertices or sample triangle interiors. Output
+ * shares immutable attribute arrays. Materials, features, topology and unselected attributes are
+ * discarded by this explicit opt-in; select compatible attributes before destination encoding.
+ * For tiles, use the mesh source adapters first so node/RTC/tile transforms are applied once.
+ * @param mesh - Decoded triangle geometry in the desired absolute coordinate frame.
+ * @param options - Explicit retained attributes and stored-vertex count budget.
+ * @returns An unindexed point Mesh ready for point-cloud writers or the dynamic tiler.
+ */
+export function extractMeshVertices(mesh: MeshGeometry, options: ExtractMeshVerticesOptions): Mesh {
+  validateLimit(options.maxPoints);
+  const position = mesh.attributes.POSITION;
+  const pointCount = position?.value.length / 3;
+  if (
+    mesh.topology !== 'triangle-list' ||
+    mesh.mode !== 4 ||
+    !position ||
+    position.size !== 3 ||
+    position.normalized ||
+    position.transform ||
+    position.byteStride ||
+    position.byteOffset ||
+    !(position.value instanceof Float32Array || position.value instanceof Float64Array) ||
+    !Number.isSafeInteger(pointCount) ||
+    pointCount > options.maxPoints ||
+    position.value.some(value => !Number.isFinite(value))
+  )
+    throw new Error(
+      'Mesh vertex harvesting requires packed finite triangle XYZ within the point budget'
+    );
+  const attributes: MeshGeometry['attributes'] = {POSITION: position};
+  for (const name of options.attributes) {
+    const attribute = mesh.attributes[name];
+    if (
+      !attribute ||
+      attribute.transform ||
+      attribute.byteStride ||
+      attribute.byteOffset ||
+      !Number.isSafeInteger(attribute.size) ||
+      attribute.size < 1 ||
+      attribute.value.length !== pointCount * attribute.size
+    )
+      throw new Error(`Invalid selected mesh vertex attribute: ${name}`);
+    attributes[name] = attribute;
+  }
+  return {topology: 'point-list', mode: 0, attributes, schema: deduceMeshSchema(attributes)};
+}
+
+/** Rejects unsafe or unsupported archive paths before URL resolution. */
+function validatePath(path: string): void {
+  if (
+    !path ||
+    !/^[A-Za-z0-9_.\/-]+$/.test(path) ||
+    path.split('/').some(part => !part || part === '.' || part === '..')
+  )
+    throw new Error('Potree bundle paths must be canonical relative ASCII paths');
+}
+
+/** Validates caller budgets before file reads or output allocation. */
+function validateLimit(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 1)
+    throw new RangeError('Point file limits must be positive safe integers');
+}