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

package/dist/v5/point-cloud-file.d.ts

@@ -0,0 +1,83 @@
+import type { COPCTileSource, COPCSourceLoaderOptions } from '@loaders.gl/copc';
+import { PotreeSourceLoader } from '@loaders.gl/potree';
+import type { PotreeDataset, PotreeWriterNode, PotreeWriterOptions, PotreeSourceLoaderOptions } from '@loaders.gl/potree';
+import type { Mesh, MeshArrowTable, MeshGeometry } from '@loaders.gl/schema';
+/** 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 declare function encodePotreeArchive(input: Mesh | MeshArrowTable | readonly PotreeWriterNode[], options: EncodePotreeArchiveOptions): Promise<Blob>;
+/** Packages already encoded Potree files without encoding or sampling points a second time. */
+export declare function encodePotreeDatasetArchive(dataset: PotreeDataset, maxArchiveBytes: number, signal?: AbortSignal): Promise<Blob>;
+/**
+ * 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 declare function openPointCloudFile(input: Blob, options: OpenPointCloudFileOptions): Promise<OpenedPointCloudFile>;
+/** 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 declare function extractMeshVertices(mesh: MeshGeometry, options: ExtractMeshVerticesOptions): Mesh;

package/dist/v5/point-cloud-potree.d.ts

@@ -0,0 +1,47 @@
+import type { Mesh, MeshArrowTable } from '@loaders.gl/schema';
+import { type PointCloudTilerOptions } from '@loaders.gl/schema-utils';
+import type { PotreeDataset, PotreeWriterOptions } from '@loaders.gl/potree';
+/** Bounded authoring of one decoded dataset in its already placed native coordinates. */
+export interface ConvertPointCloudToPotreeOptions {
+    /** Explicit CRS declaration written verbatim; coordinates are not reprojected. */
+    readonly projection: string;
+    /** Maximum bytes retained across all gathered node attribute buffers. */
+    readonly maxGatheredBytes: number;
+    /** Maximum complete encoded dataset bytes, including metadata and hierarchy. */
+    readonly maxOutputBytes: number;
+    /** Input, index, per-node and node-count limits of the shared dynamic tiler. */
+    readonly tiling?: Omit<PointCloudTilerOptions, 'signal'>;
+    /** Existing version, precision, spacing and hierarchy controls. */
+    readonly potree?: Omit<NonNullable<PotreeWriterOptions['potree']>, 'projection' | 'signal' | 'maxOutputBytes'>;
+    /** Also package the completed files as a loaders.gl STORE ZIP32 bundle. */
+    readonly archive?: {
+        readonly maxArchiveBytes: number;
+    };
+    /** Cooperative cancellation during indexing, gathering, writing and packaging. */
+    readonly signal?: AbortSignal;
+}
+/** Complete Potree files; no partial dataset is returned after a failure. */
+export interface ConvertedPointCloudPotree {
+    /** Exact input row count, emitted once across the additive octree. */
+    readonly pointCount: number;
+    /** Number of connected octree nodes, including an empty root for empty input. */
+    readonly nodeCount: number;
+    /** Metadata and encoded resources; applications own storage. */
+    readonly dataset: PotreeDataset;
+    /** Optional downloadable bundle; applications own object URL and saving lifetimes. */
+    readonly archive?: Blob;
+}
+/**
+ * Connects the portable point tiler to the existing Potree 1.x/2.0 dataset writer.
+ * Retains additive octree addresses and every source row exactly once, including terminal
+ * overflow. Input must be immutable, unindexed decoded points already placed in the declared
+ * CRS. No origins, transforms, reprojection, attribute mappings or surface sampling are inferred.
+ * The writer rejects attributes or precision that the selected version cannot represent.
+ * Gathered nodes are bounded separately from source buffers, indexes, encoded output and ZIP
+ * temporaries. This is in-memory authoring, not streaming ingestion or a peak-heap guarantee.
+ * The shared tiler's sample coverage bound is not a qualified viewer LOD/error contract.
+ * @param input - One decoded point Mesh or MeshArrowTable, including loader output.
+ * @param options - Explicit native CRS, resource budgets and existing writer controls.
+ * @returns A complete dataset and optional bundle after releasing the owned tiler.
+ */
+export declare function convertPointCloudToPotree(input: Mesh | MeshArrowTable, options: ConvertPointCloudToPotreeOptions): Promise<ConvertedPointCloudPotree>;

package/dist/v5/point-cloud-source-encoder.d.ts

@@ -1,21 +1,18 @@
 import type { PointCloudBoundingVolume, PointCloudCoordinateSystem, PointCloudTilesetSource, TilesetSpatialReference } from '@loaders.gl/tiles';
-import type { EncodePointCloudTileOptions } from './point-cloud.js';
+import type { PointCloudSpatialOptions } from './point-cloud-spatial.js';
+import type { EncodePointCloudTileOptions, EncodedPointCloudTile } from './point-cloud.js';
 import type { PointCloudSourceTile, TraversePointCloudSourceOptions } from '@loaders.gl/tile-converter/v5/core';
 /** Traversal and per-tile encoding options for a point-cloud source. */
-export type EncodePointCloudSourceOptions = TraversePointCloudSourceOptions & {
+export type EncodePointCloudSourceOptions = TraversePointCloudSourceOptions & Partial<Pick<PointCloudSpatialOptions, 'spatialContext' | 'normalReferenceFrame'>> & {
     /** 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 = {
+export type EncodedPointCloudSourceTile = EncodedPointCloudTile & {
     /** 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. */

package/dist/v5/point-cloud-spatial.d.ts

@@ -0,0 +1,22 @@
+import type { I3SConversionSpatialContext, PointCloudSourceTile } from '@loaders.gl/tile-converter/v5/core';
+/** 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 declare function transformPointCloudSourceTile(sourceTile: PointCloudSourceTile, options: PointCloudSpatialOptions): Promise<PointCloudSourceTile>;

package/dist/v5/point-cloud-tileset-sink.d.ts

@@ -0,0 +1,28 @@
+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 declare function createPointCloudTilesetSink(options: PointCloudTilesetSinkOptions): PointCloudTilesetSink;

package/dist/v5/point-cloud-tileset.d.ts

@@ -0,0 +1,44 @@
+import type { Mesh, MeshArrowTable } from '@loaders.gl/schema';
+import type { PointCloudTilerOptions } from '@loaders.gl/schema-utils';
+import type { TilesetSpatialReference } from '@loaders.gl/tiles';
+import type { BrowserTileConversionFile, TileConversionProgress, TileConversionReport } from '@loaders.gl/tile-converter/v5/core';
+import type { PointCloudTilesetSinkOptions } from './point-cloud-tileset-sink.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 declare function convertPointCloudToTileset(input: Mesh | MeshArrowTable, options: ConvertPointCloudToTilesetOptions): Promise<ConvertedPointCloudTileset>;

package/dist/v5/point-cloud.d.ts

@@ -1,13 +1,28 @@
-import type { Mesh, MeshArrowTable } from '@loaders.gl/schema';
+import type { Mesh, MeshArrowTable, MeshAttribute } from '@loaders.gl/schema';
 /** 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.
  *
@@ -22,3 +37,13 @@ export interface EncodePointCloudTileOptions {
  * @returns A 3D Tiles PNTS resource.
  */
 export declare function encodePointCloudTile(pointBatch: Mesh | MeshArrowTable, options?: EncodePointCloudTileOptions): ArrayBuffer;
+/**
+ * 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 declare function encodePointCloudTileWithMetadata(pointBatch: Mesh | MeshArrowTable, options?: EncodePointCloudTileOptions): EncodedPointCloudTile;
+/** Decodes packed point positions to doubles before applying a spatial operation. */
+export declare function decodePointCloudPositions(attribute: MeshAttribute | undefined): Float64Array;

package/dist/v5/resource-fetcher.d.ts

@@ -0,0 +1,18 @@
+/** One aggregate transport budget shared by selected contents and their dependencies. */
+export interface TileConversionResourceFetcherOptions {
+    /** Maximum total response bytes, including previously inspected root bytes. */
+    readonly maxInputBytes: number;
+    /** Previously consumed input bytes, such as the inspected tileset JSON. */
+    readonly initialInputBytes?: number;
+    /** Application transport; also enables archive-backed or hermetic resolution. */
+    readonly fetcher?: typeof fetch;
+    /** Conversion cancellation, forwarded to every dependency request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Wraps application fetch with a shared byte budget and conversion cancellation.
+ * Each requested resource is charged, including repeated requests; HTTP(S), Blob and embedded data
+ * URLs are accepted. Response streams are canceled on overflow or failure. The complete bounded
+ * response is retained for codecs; this does not bound their decoded allocations.
+ */
+export declare function createTileConversionResourceFetcher(options: TileConversionResourceFetcherOptions): typeof fetch;

package/dist/v5/resource-manifest.d.ts

@@ -32,6 +32,14 @@ export interface ManifestBackedTileConversionSinkOptions<TResource> {
     readonly sink: TileConversionSink<TResource>;
     /** Persistence adapter for snapshots written after each resource. */
     readonly manifestStore: TileResourceManifestStore;
+    /** Optional cap on unique checkpoint entries loaded or written; defaults to no cap. */
+    readonly maxResources?: number;
+    /**
+     * Checks destination bytes before skipping a matching checkpoint. Return true only when
+     * stored bytes match the entry's size and fingerprint; false rewrites the resource.
+     * Without this callback the caller guarantees checkpointed destination bytes remain intact.
+     */
+    readonly verifyResource?: (entry: TileResourceManifestEntry, signal?: AbortSignal) => Promise<boolean>;
     /** Stable profile-specific path or resource key. */
     readonly getResourceId: (resource: TResource) => string;
     /** Byte length used to detect changed content under an existing resource ID. */
@@ -50,7 +58,8 @@ export interface ManifestBackedTileConversionSinkOptions<TResource> {
  * including writes skipped because the matching resource was already present. A graceful abort
  * clears the manifest checkpoint before asking the destination to clean partial output, so the
  * next run starts cleanly. A process interruption that does not call `abort` can resume from its
- * last saved checkpoint.
+ * last saved checkpoint. Optional destination verification repairs missing or changed stored
+ * resources before treating them as complete. maxResources caps unique checkpoint entries.
  *
  * @param options - Destination, manifest store, stable IDs, byte measurement, and fingerprinting.
  * @returns A `TileConversionSink` with resumable per-resource progress.

package/dist/v5/selected-mesh-source.d.ts

@@ -0,0 +1,53 @@
+import type { DracoLibraryOptions } from '@loaders.gl/draco/bundled';
+import { createTiles3DConversionSpatialContext } from '@loaders.gl/tile-converter/v5/core';
+import type { BrowserTilesetConversionInspection, BrowserTilesetConversionInputResource, TileConversionSource } from '@loaders.gl/tile-converter/v5/core';
+import type { MeshSourceResource, MeshSourceFeatureOptions } from '@loaders.gl/tile-converter/v5/adapters';
+/** Required transport, decoded geometry, retained output, and archive budgets for this demo. */
+export declare const SELECTED_MESH_LIMITS: {
+    /** Root JSON plus selected content transport bytes; also the decoded geometry/image/feature byte gate. */
+    readonly maxInputBytes: number;
+    /** Maximum declared content placements inspected. */
+    readonly maxInputResources: 1000;
+    /** Maximum inspected root/external document placements. */
+    readonly maxTilesetDocuments: 32;
+    /** Maximum explicitly selected content placements in one partial archive. */
+    readonly maxSelectedResources: 64;
+    /** Maximum primitive placements authored across all selected contents. */
+    readonly maxMeshResources: 64;
+    /** Maximum retained file bytes and final archive bytes. */
+    readonly maxOutputBytes: number;
+    /** Maximum measured reconstruction error in meters. */
+    readonly maxPositionError: 0.01;
+};
+/** Injected transport and decoder assets for the bounded selected mesh profile. */
+export interface SelectedMeshSourceOptions {
+    /** Require a complete qualified explicit tree; pair with createMeshHierarchyTilesetSink. */
+    readonly preserveHierarchy?: boolean;
+    /** Inspected content placement identifiers; one to 64 distinct selections. */
+    readonly resourceIds: readonly string[];
+    /** Cancellation across qualification, raw reads and decoding. */
+    readonly signal: AbortSignal;
+    /** Application-owned decoder asset locations or modules. */
+    readonly dracoLibraryOptions: DracoLibraryOptions;
+    /** Transport for decoded buffers/images, confined by a platform adapter when local. */
+    readonly fetcher?: typeof fetch;
+    /** Optional source owning the raw input lifetime, such as a Node file/archive adapter. */
+    readonly source?: TileConversionSource<BrowserTilesetConversionInspection, BrowserTilesetConversionInputResource>;
+    /** Explicit feature mapping, or the qualified inline structural metadata profile. */
+    readonly features?: MeshSourceFeatureOptions;
+    /** Lower the shared 16 MiB transport and decoded mesh limit. */
+    readonly maxInputBytes?: number;
+}
+/** Qualified selected-mesh decoding and source error policy. */
+export interface SelectedMeshConversionSource {
+    /** Lazy source that releases each dedicated mesh runtime after use. */
+    readonly source: TileConversionSource<BrowserTilesetConversionInspection, MeshSourceResource>;
+    /** Native ECEF coordinate context, qualified before reading mesh content. */
+    readonly spatialContext: ReturnType<typeof createTiles3DConversionSpatialContext>;
+    /** Conservative metric source error plus the position reconstruction allowance. */
+    readonly geometricError: number;
+}
+/** Qualifies and constructs a lazy selected mesh source without platform I/O or output ownership. */
+export declare function createSelectedMeshConversionSource(inspection: BrowserTilesetConversionInspection, options: SelectedMeshSourceOptions): Promise<SelectedMeshConversionSource>;
+/** Charges geometry, encoded image bytes, triangle associations and Arrow columns after extraction. */
+export declare function measureMeshBytes(resource: MeshSourceResource): number;

package/dist/v5/spatial-conversion.d.ts

@@ -1,4 +1,4 @@
-import type { CreateTilesetSpatialReferenceOptions, I3SSpatialBounds, I3STransformedPositions, Tiles3DSpatialBoundingVolume, TilesetSpatialOptions, TilesetSpatialReference } from '@loaders.gl/tiles';
+import type { CreateTilesetSpatialReferenceOptions, I3SSpatialBounds, I3STransformedPositions, I3STransformedGeometry, Tiles3DSpatialBoundingVolume, TilesetSpatialOptions, TilesetSpatialReference } from '@loaders.gl/tiles';
 /** Portable coordinate operations and output metadata for a 3D Tiles conversion. */
 export interface Tiles3DConversionSpatialContext {
     /** Source and selected target CRS, height reference, units, and transformation state. */
@@ -16,6 +16,8 @@ export interface I3SConversionSpatialContext {
     readonly spatialReference: TilesetSpatialReference;
     /** Transform absolute I3S positions after applying declared height units and placement. */
     transformPositions(positions: ArrayLike<number>, sourceOrigin: ArrayLike<number>): I3STransformedPositions;
+    /** Transform absolute conversion geometry without intermediate float32 rounding. */
+    transformGeometryAsync(positions: ArrayLike<number>, normals?: ArrayLike<number>, normalReferenceFrame?: string): Promise<I3STransformedGeometry>;
     /** Transform absolute I3S positions when terrain or scene sampling is asynchronous. */
     transformPositionsAsync(positions: ArrayLike<number>, sourceOrigin: ArrayLike<number>): Promise<I3STransformedPositions>;
     /** Transform packed normals using the corresponding source positions. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/tile-converter",
-  "version": "5.0.0-alpha.10",
+  "version": "5.0.0-alpha.12",
   "description": "Converter",
   "license": "MIT",
   "type": "module",
@@ -44,12 +44,18 @@
       "types": "./dist/v5/adapters.d.ts",
       "import": "./dist/v5/adapters.js",
       "require": "./dist/v5/adapters.cjs"
+    },
+    "./v5/node": {
+      "types": "./dist/v5/node.d.ts",
+      "import": "./dist/v5/node.js",
+      "require": "./dist/v5/node.cjs"
     }
   },
   "sideEffects": false,
   "bin": {
     "i3s-server": "./bin/i3s-server.js",
-    "tile-converter": "./bin/converter.js"
+    "tile-converter": "./bin/converter.js",
+    "tile-converter-v5": "./bin/converter-v5.js"
   },
   "files": [
     "src",
@@ -71,30 +77,32 @@
     "build-converter-bundle": "esbuild src/v4/converter-cli.ts --outfile=dist/converter.min.cjs --platform=node --target=esnext,node14 --external:join-images --minify --bundle --define:__VERSION__=\\\"$npm_package_version\\\"",
     "build-i3s-server-bundle": "esbuild src/v4/i3s-server/bin/www.ts --outfile=dist/i3s-server/bin/i3s-server.min.cjs --platform=node --target=esnext,node14 --minify --bundle --define:__VERSION__=\\\"$npm_package_version\\\"",
     "copy-certificates": "cp -R src/v4/i3s-server/certs dist/i3s-server",
-    "build-v5-entrypoints": "esbuild src/v5/core.ts src/v5/adapters.ts src/v5/index.ts src/v5/browser.ts --bundle --packages=external --external:@loaders.gl/* --platform=browser --outdir=dist/v5 --format=esm && esbuild src/v5/core.ts src/v5/adapters.ts src/v5/index.ts src/v5/browser.ts --bundle --packages=external --external:@loaders.gl/* --platform=browser --outdir=dist/v5 --format=cjs --out-extension:.js=.cjs"
+    "build-v5-entrypoints": "esbuild src/v5/core.ts src/v5/adapters.ts src/v5/index.ts src/v5/browser.ts --bundle --packages=external --external:@loaders.gl/* --platform=browser --outdir=dist/v5 --format=esm && esbuild src/v5/core.ts src/v5/adapters.ts src/v5/index.ts src/v5/browser.ts --bundle --packages=external --external:@loaders.gl/* --platform=browser --outdir=dist/v5 --format=cjs --out-extension:.js=.cjs && esbuild src/v5/node.ts src/v5/converter-cli.ts --bundle --packages=external --external:@loaders.gl/* --platform=node --outdir=dist/v5 --format=esm && esbuild src/v5/node.ts --bundle --packages=external --external:@loaders.gl/* --platform=node --outdir=dist/v5 --format=cjs --out-extension:.js=.cjs"
   },
   "dependencies": {
-    "@loaders.gl/3d-tiles": "5.0.0-alpha.10",
-    "@loaders.gl/compression": "5.0.0-alpha.10",
-    "@loaders.gl/crypto": "5.0.0-alpha.10",
-    "@loaders.gl/draco": "5.0.0-alpha.10",
-    "@loaders.gl/gltf": "5.0.0-alpha.10",
-    "@loaders.gl/i3s": "5.0.0-alpha.10",
-    "@loaders.gl/images": "5.0.0-alpha.10",
-    "@loaders.gl/loader-utils": "5.0.0-alpha.10",
-    "@loaders.gl/polyfills": "5.0.0-alpha.10",
-    "@loaders.gl/schema": "5.0.0-alpha.10",
-    "@loaders.gl/schema-utils": "5.0.0-alpha.10",
-    "@loaders.gl/textures": "5.0.0-alpha.10",
-    "@loaders.gl/tiles": "5.0.0-alpha.10",
-    "@loaders.gl/worker-utils": "5.0.0-alpha.10",
-    "@loaders.gl/zip": "5.0.0-alpha.10",
-    "@math.gl/core": "5.0.0-alpha.13",
-    "@math.gl/crs": "5.0.0-alpha.13",
-    "@math.gl/culling": "5.0.0-alpha.13",
-    "@math.gl/geoid": "5.0.0-alpha.13",
-    "@math.gl/geometry-utils": "5.0.0-alpha.13",
-    "@math.gl/geospatial": "5.0.0-alpha.13",
+    "@loaders.gl/3d-tiles": "5.0.0-alpha.12",
+    "@loaders.gl/compression": "5.0.0-alpha.12",
+    "@loaders.gl/copc": "5.0.0-alpha.12",
+    "@loaders.gl/crypto": "5.0.0-alpha.12",
+    "@loaders.gl/draco": "5.0.0-alpha.12",
+    "@loaders.gl/gltf": "5.0.0-alpha.12",
+    "@loaders.gl/i3s": "5.0.0-alpha.12",
+    "@loaders.gl/images": "5.0.0-alpha.12",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.12",
+    "@loaders.gl/polyfills": "5.0.0-alpha.12",
+    "@loaders.gl/potree": "5.0.0-alpha.12",
+    "@loaders.gl/schema": "5.0.0-alpha.12",
+    "@loaders.gl/schema-utils": "5.0.0-alpha.12",
+    "@loaders.gl/textures": "5.0.0-alpha.12",
+    "@loaders.gl/tiles": "5.0.0-alpha.12",
+    "@loaders.gl/worker-utils": "5.0.0-alpha.12",
+    "@loaders.gl/zip": "5.0.0-alpha.12",
+    "@math.gl/core": "5.0.0-alpha.16",
+    "@math.gl/crs": "5.0.0-alpha.16",
+    "@math.gl/culling": "5.0.0-alpha.16",
+    "@math.gl/geoid": "5.0.0-alpha.16",
+    "@math.gl/geometry-utils": "5.0.0-alpha.16",
+    "@math.gl/geospatial": "5.0.0-alpha.16",
     "ajv": "^8.12.0",
     "archiver": "^5.0.0",
     "cors": "^2.8.5",
@@ -119,5 +127,5 @@
   "peerDependencies": {
     "@loaders.gl/core": "~5.0.0-alpha.0"
   },
-  "gitHead": "7cbfaef633e86356c946541dab4977b522745b6c"
+  "gitHead": "8cbff6cb3e55c4eb1305072743992af27ff0c171"
 }

package/src/index.ts

@@ -1 +1,4 @@
-export * from './v4/index.js';
+export {
+  I3SConverter,
+  Tiles3DConverter
+} from './v4/index.js';

package/src/v4/3d-tiles-converter/helpers/load-i3s.ts

@@ -8,7 +8,7 @@ import {
   parseSLPKArchive
 } from '@loaders.gl/i3s';
 import {NodeFile} from '@loaders.gl/loader-utils';
-import {ZipFileSystem, makeZipCDHeaderIterator} from '@loaders.gl/zip';
+import {ZipFileSystem} from '@loaders.gl/zip';
 
 export type SLPKUrlParts = {slpkFileName: string; internalFileName: string};
 
@@ -116,9 +116,7 @@ export async function getNodeCount(fileSystem: ZipFileSystem | null): Promise<nu
     return 0;
   }
   const nodeSet = new Set();
-  const filesIterator = makeZipCDHeaderIterator(fileSystem.file);
-  for await (const file of filesIterator) {
-    const filename = file.fileName;
+  for (const filename of await fileSystem.readdir()) {
     const nodeNumberSearchResult = /^nodes\/(\d+)\//.exec(filename);
     if (nodeNumberSearchResult) {
       nodeSet.add(nodeNumberSearchResult[1]);

package/src/v4/converter-cli.ts

@@ -11,7 +11,7 @@ import {
   getURLValue,
   validateOptionsWithEqual
 } from './lib/utils/cli-utils';
-import {addOneFile, composeHashFile, makeZipCDHeaderIterator} from '@loaders.gl/zip';
+import {addOneFile, composeHashFile, openZipArchive} from '@loaders.gl/zip';
 import {NodeFile} from '@loaders.gl/loader-utils';
 // @ts-ignore
 import {copyFile} from 'node:fs/promises';
@@ -141,7 +141,13 @@ async function main() {
     if (finalPath !== validatedOptions.tileset) {
       await copyFile(validatedOptions.tileset, finalPath);
     }
-    const hashTable = await composeHashFile(makeZipCDHeaderIterator(new NodeFile(finalPath)));
+    const archive = await openZipArchive(new NodeFile(finalPath));
+    let hashTable: ArrayBuffer;
+    try {
+      hashTable = await composeHashFile(archive.entries());
+    } finally {
+      await archive.close();
+    }
     await addOneFile(finalPath, hashTable, '@specialIndexFileHASH128@');
 
     return;

package/src/v4/i3s-converter/helpers/load-3d-tiles.ts

@@ -4,19 +4,11 @@ import type {
   Tiles3DTileJSONPostprocessed,
   Tiles3DTilesetJSONPostprocessed
 } from '@loaders.gl/3d-tiles';
-import {Tiles3DArchive} from '@loaders.gl/3d-tiles';
+import {parse3DTilesArchive} from '@loaders.gl/3d-tiles';
 import {LoaderWithParser, load} from '@loaders.gl/core';
 import type {ReadableFile} from '@loaders.gl/loader-utils';
 import {HttpFile, NodeFile, isBrowser} from '@loaders.gl/loader-utils';
-import {
-  CD_HEADER_SIGNATURE,
-  ZipFileSystem,
-  parseHashTable,
-  parseZipCDFileHeader,
-  parseZipLocalFileHeader,
-  searchFromTheEnd,
-  readRange
-} from '@loaders.gl/zip';
+import {ZipFileSystem} from '@loaders.gl/zip';
 
 /**
  * Load nested 3DTiles tileset. If the sourceTile is not nested tileset - do nothing
@@ -116,8 +108,7 @@ export async function loadFromArchive(
   if (filename) {
     const tz3Path = `${tz3UrlParts[0]}.3tz`;
     const fileProvider = createReadableFile(tz3Path);
-    const hashTable = await loadHashTable(fileProvider);
-    const archive = new Tiles3DArchive(fileProvider, hashTable, tz3Path);
+    const archive = await parse3DTilesArchive(fileProvider, undefined, tz3Path);
     const fileSystem = new ZipFileSystem(archive);
     const archiveLoadOptions = {
       ...loadOptions,
@@ -145,42 +136,3 @@ function createReadableFile(path: string): ReadableFile {
   }
   return isBrowser ? new HttpFile(path) : new NodeFile(path);
 }
-
-/**
- * Load hash file from 3TZ
- * @param fileProvider - binary reader of 3TZ
- * @returns hash table of the 3TZ file content or undefined if the hash file is not presented inside
- */
-async function loadHashTable(
-  fileProvider: ReadableFile
-): Promise<undefined | Record<string, bigint>> {
-  let hashTable: undefined | Record<string, bigint>;
-
-  const hashCDOffset = await searchFromTheEnd(fileProvider, CD_HEADER_SIGNATURE);
-
-  const cdFileHeader = await parseZipCDFileHeader(hashCDOffset, fileProvider);
-
-  // '@3dtilesIndex1@' is index file that must be the last in the archive. It allows
-  // to improve load and read performance when the archive contains a very large number
-  // of files.
-  if (cdFileHeader?.fileName === '@3dtilesIndex1@') {
-    const localFileHeader = await parseZipLocalFileHeader(
-      cdFileHeader.localHeaderOffset,
-      fileProvider
-    );
-    if (!localFileHeader) {
-      throw new Error('corrupted 3tz');
-    }
-
-    const fileDataOffset = localFileHeader.fileDataOffset;
-    const hashFile = await readRange(
-      fileProvider,
-      fileDataOffset,
-      fileDataOffset + localFileHeader.compressedSize
-    );
-
-    hashTable = parseHashTable(hashFile);
-  }
-
-  return hashTable;
-}