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

package/dist/v5/mesh.d.ts

@@ -0,0 +1,86 @@
+import { GLTFScenegraph } from '@loaders.gl/gltf';
+import type { MeshAttribute, MeshGeometry } from '@loaders.gl/schema';
+import { type MeshTileFeatures } from './mesh-features.js';
+/** Explicit glTF wrapping and filtering for the selected base-color image. */
+export interface MeshTileSampler {
+    /** Horizontal wrapping: CLAMP_TO_EDGE, MIRRORED_REPEAT, or REPEAT; omitted values use REPEAT. */
+    readonly wrapS?: 33071 | 33648 | 10497;
+    /** Vertical wrapping: CLAMP_TO_EDGE, MIRRORED_REPEAT, or REPEAT; omitted values use REPEAT. */
+    readonly wrapT?: 33071 | 33648 | 10497;
+    /** Magnification: NEAREST or LINEAR; omission leaves filtering to the renderer. */
+    readonly magFilter?: 9728 | 9729;
+    /** Minification: NEAREST, LINEAR, or a glTF mipmap filter; omission leaves filtering to the renderer. */
+    readonly minFilter?: 9728 | 9729 | 9984 | 9985 | 9986 | 9987;
+}
+/** Selected KHR_texture_transform controls for TEXCOORD_0. */
+export interface MeshTileTextureTransform {
+    /** Finite UV translation; omitted values use [0, 0]. */
+    readonly offset?: readonly [number, number];
+    /** Finite counterclockwise rotation in radians around the UV origin; omission uses 0. */
+    readonly rotation?: number;
+    /** Finite UV scale; zero and negative values are allowed, and omission uses [1, 1]. */
+    readonly scale?: readonly [number, number];
+}
+/** One already encoded base-color image using TEXCOORD_0. */
+export interface MeshTileTexture {
+    /** Encoded PNG/JPEG bytes; a typed array subview selects only its own bytes. */
+    readonly data: Uint8Array;
+    /** Declared image format, checked against the encoded header. */
+    readonly mimeType: 'image/png' | 'image/jpeg';
+    /** Optional wrapping/filtering; omission retains glTF's implicit sampler. */
+    readonly sampler?: MeshTileSampler;
+    /** Optional UV transform, preserved as a required KHR_texture_transform extension. */
+    readonly transform?: MeshTileTextureTransform;
+}
+/** One glTF metallic-roughness material, shared by every triangle in the mesh. */
+export interface MeshTileMaterial {
+    /** Linear RGBA base-color multiplier; components must be finite in [0, 1]. */
+    readonly baseColorFactor?: readonly [number, number, number, number];
+    /** Optional embedded image, multiplied by baseColorFactor and COLOR_0; requires TEXCOORD_0. */
+    readonly baseColorTexture?: MeshTileTexture;
+    /** Metallic weight in [0, 1]; omitted values use the glTF default of 1. */
+    readonly metallicFactor?: number;
+    /** Roughness weight in [0, 1]; omitted values use the glTF default of 1. */
+    readonly roughnessFactor?: number;
+    /** Alpha interpretation; omitted values use OPAQUE. */
+    readonly alphaMode?: 'OPAQUE' | 'MASK' | 'BLEND';
+    /** Finite nonnegative threshold, allowed only with MASK; omitted values use 0.5. */
+    readonly alphaCutoff?: number;
+    /** Whether both sides are rendered; omitted values use false. */
+    readonly doubleSided?: boolean;
+}
+/** Optional appearance for the single-mesh GLB profile. */
+export interface MeshTileOptions {
+    /** One explicit Arrow feature table with a row index per triangle. */
+    readonly features?: MeshTileFeatures;
+    /** Explicitly selected material; other texture maps and material extensions are unsupported. */
+    readonly material?: MeshTileMaterial;
+}
+/**
+ * Encodes one triangle mesh as a self-contained glTF 2.0 GLB resource.
+ *
+ * POSITION and optional NORMAL must contain packed finite Float32 xyz triples. COLOR_0 accepts
+ * packed Float32 linear RGB/RGBA in [0, 1] or normalized Uint8/Uint16 colors per vertex.
+ * Normals must have unit length within 0.0001. TEXCOORD_0 accepts packed finite Float32
+ * or normalized Uint8/Uint16 UV pairs per vertex. Optional indices use packed unsigned
+ * 8-, 16-, or 32-bit values.
+ * Unsupported attributes, layouts, and encoded transforms fail rather than being discarded.
+ * Coordinates are preserved: callers own CRS conversion, local origins, placement, source material mapping,
+ * feature mappings, and tileset packaging. Input arrays are never modified.
+ *
+ * @param mesh - Triangle-list geometry in the caller's selected local coordinate frame.
+ * @param options - Optional single material with an already encoded base-color image.
+ * @returns An embedded-buffer GLB containing one mesh, node, and default scene.
+ */
+export declare function encodeMeshTile(mesh: MeshGeometry, options?: MeshTileOptions): ArrayBuffer;
+/** Creates the shared material/image scene without allocating uncompressed geometry buffers. */
+export declare function createMeshTileScenegraph(options: MeshTileOptions, geometry: MeshGeometry): {
+    scenegraph: GLTFScenegraph;
+    materialIndex: number | undefined;
+};
+/** Adds placement-neutral nodes and serializes the single-mesh scene as GLB. */
+export declare function finalizeMeshTileScenegraph(scenegraph: GLTFScenegraph, meshIndex: number): ArrayBuffer;
+/** Validates the shared mesh profile; spatial preparation may retain Float64 positions internally. */
+export declare function validateMeshGeometry(mesh: MeshGeometry, allowFloat64Positions?: boolean): MeshGeometry;
+/** Validates packed indices for triangle lists or strips, including glTF primitive-restart rules. */
+export declare function validateMeshIndices(attribute: MeshAttribute | undefined, vertexCount: number, primitiveMode?: 4 | 5): Uint8Array | Uint16Array | Uint32Array | undefined;

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

@@ -0,0 +1,31 @@
+import type { PointCloudTilesetSource } from '@loaders.gl/tiles';
+import type { TileConversionProgress, TileConversionReport, TileConversionSink } from '@loaders.gl/tile-converter/v5/core';
+import type { PointCloudSourceTile } from '@loaders.gl/tile-converter/v5/core';
+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 declare function convertPointCloudSource(source: PointCloudTilesetSource, options: ConvertPointCloudSourceOptions): Promise<TileConversionReport>;

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

@@ -0,0 +1,46 @@
+import type { PointCloudBoundingVolume, PointCloudCoordinateSystem, PointCloudTilesetSource, TilesetSpatialReference } from '@loaders.gl/tiles';
+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 & 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 = EncodedPointCloudTile & {
+    /** Stable source tile identifier. */
+    readonly id: string;
+    /** Original source hierarchy and bounds. */
+    readonly header: PointCloudSourceTile['header'];
+    /** 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 declare function encodePointCloudSource(source: PointCloudTilesetSource, options?: EncodePointCloudSourceOptions): AsyncIterableIterator<EncodedPointCloudSourceTile>;
+/**
+ * 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 declare function encodePointCloudSourceTile(sourceTile: PointCloudSourceTile, options?: EncodePointCloudTileOptions): EncodedPointCloudSourceTile | null;

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

@@ -0,0 +1,25 @@
+import type { PointCloudTileContent, PointCloudTileHeader, PointCloudTilesetSource } from '@loaders.gl/tiles';
+/** A source tile and its decoded point content, including null content when no payload exists. */
+export type PointCloudSourceTile = {
+    /** Header with the source tile's hierarchy, bounds, and LOD metadata. */
+    readonly header: PointCloudTileHeader;
+    /** Arrow point data and its coordinate metadata, or null for an empty tile. */
+    readonly content: PointCloudTileContent | null;
+};
+/** Options for camera-independent point-cloud source traversal. */
+export type TraversePointCloudSourceOptions = {
+    /** Stop descending after this source tile level. Defaults to the complete hierarchy. */
+    readonly maxDepth?: number;
+    /** Cancel traversal between source operations. */
+    readonly signal?: AbortSignal;
+};
+/**
+ * Reads a point-cloud source in deterministic depth-first order, independent of a render camera.
+ * Each yielded value retains its tile header and Arrow content metadata so callers can apply the
+ * source coordinate frame and placement when encoding output tiles.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud tileset source.
+ * @param options - Optional depth limit and cancellation signal.
+ * @returns One header and decoded payload for each reachable source tile.
+ */
+export declare function traversePointCloudSource(source: PointCloudTilesetSource, options?: TraversePointCloudSourceOptions): AsyncIterableIterator<PointCloudSourceTile>;

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

@@ -0,0 +1,49 @@
+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.
+ *
+ * The input position field must be named `POSITION` and contain xyz values. `COLOR_0` or `COLOR`
+ * is written when present; `constantRGBA` supplies a fallback PNTS `CONSTANT_RGBA` feature-table
+ * property. `NORMAL` and `BATCH_ID` are also written when present. Arrow batches should be passed
+ * one at a time so callers can bound memory and apply their own tiling and output policy.
+ * Unsupported attributes, including a second color attribute, fail instead of being discarded.
+ *
+ * @param pointBatch - Point data produced by a LAS, COPC, I3S, or other point source.
+ * @param options - Optional RTC center and batch-table values.
+ * @returns A 3D Tiles PNTS resource.
+ */
+export 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

@@ -0,0 +1,58 @@
+import type { TileConversionReport, TileConversionSink } from './conversion-api.js';
+/** Durable record for one successfully written, deterministic output resource. */
+export interface TileResourceManifestEntry {
+    /** Stable resource identifier supplied by the output profile. */
+    readonly resourceId: string;
+    /** Byte length of the output resource. */
+    readonly byteLength: number;
+    /** Stable caller-computed content fingerprint, such as a SHA-256 digest. */
+    readonly fingerprint: string;
+}
+/** Versioned progress record used to resume deterministic output packaging. */
+export interface TileResourceManifest {
+    /** Manifest format version. */
+    readonly version: 1;
+    /** True only after the destination and report have been finalized successfully. */
+    readonly complete: boolean;
+    /** Resources durably written before interruption or completion. */
+    readonly resources: readonly TileResourceManifestEntry[];
+    /** Conversion summary saved after successful destination finalization. */
+    readonly report?: TileConversionReport;
+}
+/** Application-owned persistence for a conversion manifest. */
+export interface TileResourceManifestStore {
+    /** Loads the previous manifest, or returns null when starting a new conversion. */
+    load(): Promise<TileResourceManifest | null>;
+    /** Atomically replaces the saved manifest with the supplied snapshot. */
+    save(manifest: TileResourceManifest): Promise<void>;
+}
+/** Options for decorating a resource sink with restart-safe manifest tracking. */
+export interface ManifestBackedTileConversionSinkOptions<TResource> {
+    /** Output destination with deterministic, idempotent resource writes. */
+    readonly sink: TileConversionSink<TResource>;
+    /** Persistence adapter for snapshots written after each resource. */
+    readonly manifestStore: TileResourceManifestStore;
+    /** Stable profile-specific path or resource key. */
+    readonly getResourceId: (resource: TResource) => string;
+    /** Byte length used to detect changed content under an existing resource ID. */
+    readonly measureResourceBytes: (resource: TResource) => number;
+    /** Stable fingerprint used to detect changed content under an existing resource ID. */
+    readonly fingerprintResource: (resource: TResource) => string;
+}
+/**
+ * Creates a sink that skips matching checkpointed resources when a process restarts.
+ *
+ * The destination must write resources idempotently by the ID returned from `getResourceId`.
+ * The manifest is persisted after every successful write; the store should replace snapshots
+ * atomically. Existing IDs must retain their byte length and fingerprint or the resumed job fails
+ * rather than silently mixing output from different conversion inputs. Writes are serialized even
+ * when callers issue them concurrently. Reports count resources processed by the current run,
+ * 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.
+ *
+ * @param options - Destination, manifest store, stable IDs, byte measurement, and fingerprinting.
+ * @returns A `TileConversionSink` with resumable per-resource progress.
+ */
+export declare function createManifestBackedTileConversionSink<TResource>(options: ManifestBackedTileConversionSinkOptions<TResource>): Promise<TileConversionSink<TResource>>;

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

@@ -0,0 +1,61 @@
+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. */
+    readonly spatialReference: TilesetSpatialReference;
+    /** Transform packed absolute xyz positions using double precision output. */
+    transformPositions(positions: ArrayLike<number>): Float64Array;
+    /** Transform packed normals using the corresponding source positions. */
+    transformNormals(normals: ArrayLike<number>, positions: ArrayLike<number>): Float32Array;
+    /** Rebuild a conservative bound in the selected target coordinate frame. */
+    transformBoundingVolume(volume: Tiles3DSpatialBoundingVolume, sourceTransform?: ArrayLike<number>): Tiles3DSpatialBoundingVolume;
+}
+/** Portable coordinate operations and output metadata for an I3S conversion. */
+export interface I3SConversionSpatialContext {
+    /** Source and selected target CRS, height reference, units, and transformation state. */
+    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. */
+    transformNormals(normals: ArrayLike<number>, positions: ArrayLike<number>, normalReferenceFrame?: string): Float32Array;
+    /** Rebuild a conservative I3S bound in the selected target frame. */
+    transformBoundingVolume(bounds: I3SSpatialBounds): I3SSpatialBounds | {
+        box?: number[];
+        region?: number[];
+    };
+    /** Rebuild a bound when terrain or scene sampling is asynchronous. */
+    transformBoundingVolumeAsync(bounds: I3SSpatialBounds): Promise<I3SSpatialBounds | {
+        box?: number[];
+        region?: number[];
+    }>;
+}
+/**
+ * Creates the shared spatial operations used to write 3D Tiles in a selected CRS and height frame.
+ *
+ * Source discovery remains format-specific and should use `get3DTilesSpatialReference` or the
+ * initialized source's spatial metadata. Target choices on a normalized, transformable reference
+ * are retained unless overridden in `options`. Do not reuse a reference already marked
+ * `transformed`; that would apply the operation twice. The returned reference is the metadata to
+ * publish with transformed output; unresolved requests fail instead of guessing a CRS or height datum.
+ *
+ * @param discovered - Source CRS, units, coordinate epoch, and height metadata.
+ * @param options - Target CRS, height reference, and explicitly supplied geoid resources.
+ * @returns Shared position, normal, and bound operations with matching output metadata.
+ */
+export declare function createTiles3DConversionSpatialContext(discovered: CreateTilesetSpatialReferenceOptions | TilesetSpatialReference, options?: TilesetSpatialOptions): Tiles3DConversionSpatialContext;
+/**
+ * Creates the shared spatial operations used to write I3S in a selected CRS and height frame.
+ *
+ * I3S height units, vertical datum, elevation placement, and bounds use the same transformer as
+ * the source-backed tile runtime. Terrain or scene elevation providers are explicit application
+ * inputs and may make position and bound operations asynchronous.
+ *
+ * @param discovered - Source CRS, vertical units, height reference, and elevation mode.
+ * @param options - Target CRS, height reference, geoid, or explicit elevation providers.
+ * @returns Shared position, normal, bound, and output-metadata operations.
+ */
+export declare function createI3SConversionSpatialContext(discovered: CreateTilesetSpatialReferenceOptions | TilesetSpatialReference, options?: TilesetSpatialOptions): I3SConversionSpatialContext;

package/dist/v5/tileset-source.d.ts

@@ -0,0 +1,21 @@
+import type { Tileset3D, TilesetContentTraversalItem, TilesetSourceMetadata, TraverseTilesetContentsOptions } from '@loaders.gl/tiles';
+import type { TileConversionSource } from './conversion-api.js';
+/** Decoded-content lifetime options for source-backed conversion. */
+export type TilesetConversionSourceOptions = Pick<TraverseTilesetContentsOptions, 'unloadContent'>;
+/**
+ * Adapts a source-backed tileset to the portable v5 conversion source contract.
+ *
+ * Inspection waits for initialization and returns the source's normalized metadata. Reading uses
+ * camera-independent shared traversal, retaining each placement and its ordered decoded contents.
+ * Source adapters own content, subtree, node-page, nested tileset, and archive resolution.
+ *
+ * Enable `unloadContent` on a dedicated runtime to release newly loaded payloads after the codec
+ * and awaited writes finish, or iteration closes on failure. Preloaded payloads remain attached.
+ * Applications own tileset destruction, format codecs, byte accounting, and output packaging.
+ * This adapter does not impose an aggregate input memory limit or transform coordinates.
+ *
+ * @param tileset - An initializing or initialized runtime backed by a 3D Tiles or I3S source.
+ * @param options - Optional cleanup of content loaded during conversion.
+ * @returns A source accepted by `inspectTileset` and `convertTileset`.
+ */
+export declare function createTilesetConversionSource(tileset: Tileset3D, options?: TilesetConversionSourceOptions): TileConversionSource<TilesetSourceMetadata, TilesetContentTraversalItem>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/tile-converter",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.11",
   "description": "Converter",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./v5": {
+      "types": "./dist/v5/index.d.ts",
+      "import": "./dist/v5/index.js",
+      "require": "./dist/v5/index.cjs"
+    },
+    "./v5/browser": {
+      "types": "./dist/v5/browser.d.ts",
+      "import": "./dist/v5/browser.js",
+      "require": "./dist/v5/browser.cjs"
+    },
+    "./v5/core": {
+      "types": "./dist/v5/core.d.ts",
+      "import": "./dist/v5/core.js",
+      "require": "./dist/v5/core.cjs"
+    },
+    "./v5/adapters": {
+      "types": "./dist/v5/adapters.d.ts",
+      "import": "./dist/v5/adapters.js",
+      "require": "./dist/v5/adapters.cjs"
     }
   },
   "sideEffects": false,
@@ -45,30 +65,36 @@
     "process": false
   },
   "scripts": {
-    "pre-build": "npm run build-converter-bundle && npm run build-i3s-server-bundle && npm run copy-certificates",
-    "build-converter-bundle": "esbuild src/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/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/i3s-server/certs dist/i3s-server"
+    "pre-build": "npm run build-package-entrypoints && npm run build-converter-bundle && npm run build-i3s-server-bundle && npm run copy-certificates",
+    "build-package-entrypoints": "esbuild src/index.ts --bundle --packages=external --platform=node --format=esm --outfile=dist/index.js && esbuild src/index.ts --bundle --packages=external --platform=node --format=cjs --outfile=dist/index.cjs && npm run build-v5-entrypoints && npm run build-v5-declarations",
+    "build-v5-declarations": "tsc --project tsconfig.v5.json",
+    "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"
   },
   "dependencies": {
-    "@loaders.gl/3d-tiles": "5.0.0-alpha.1",
-    "@loaders.gl/compression": "5.0.0-alpha.1",
-    "@loaders.gl/crypto": "5.0.0-alpha.1",
-    "@loaders.gl/draco": "5.0.0-alpha.1",
-    "@loaders.gl/gltf": "5.0.0-alpha.1",
-    "@loaders.gl/i3s": "5.0.0-alpha.1",
-    "@loaders.gl/images": "5.0.0-alpha.1",
-    "@loaders.gl/loader-utils": "5.0.0-alpha.1",
-    "@loaders.gl/math": "5.0.0-alpha.1",
-    "@loaders.gl/polyfills": "5.0.0-alpha.1",
-    "@loaders.gl/textures": "5.0.0-alpha.1",
-    "@loaders.gl/tiles": "5.0.0-alpha.1",
-    "@loaders.gl/worker-utils": "5.0.0-alpha.1",
-    "@loaders.gl/zip": "5.0.0-alpha.1",
-    "@math.gl/core": "^4.1.0",
-    "@math.gl/culling": "^4.1.0",
-    "@math.gl/geoid": "^4.1.0",
-    "@math.gl/geospatial": "^4.1.0",
+    "@loaders.gl/3d-tiles": "5.0.0-alpha.11",
+    "@loaders.gl/compression": "5.0.0-alpha.11",
+    "@loaders.gl/crypto": "5.0.0-alpha.11",
+    "@loaders.gl/draco": "5.0.0-alpha.11",
+    "@loaders.gl/gltf": "5.0.0-alpha.11",
+    "@loaders.gl/i3s": "5.0.0-alpha.11",
+    "@loaders.gl/images": "5.0.0-alpha.11",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.11",
+    "@loaders.gl/polyfills": "5.0.0-alpha.11",
+    "@loaders.gl/schema": "5.0.0-alpha.11",
+    "@loaders.gl/schema-utils": "5.0.0-alpha.11",
+    "@loaders.gl/textures": "5.0.0-alpha.11",
+    "@loaders.gl/tiles": "5.0.0-alpha.11",
+    "@loaders.gl/worker-utils": "5.0.0-alpha.11",
+    "@loaders.gl/zip": "5.0.0-alpha.11",
+    "@math.gl/core": "5.0.0-alpha.15",
+    "@math.gl/crs": "5.0.0-alpha.15",
+    "@math.gl/culling": "5.0.0-alpha.15",
+    "@math.gl/geoid": "5.0.0-alpha.15",
+    "@math.gl/geometry-utils": "5.0.0-alpha.15",
+    "@math.gl/geospatial": "5.0.0-alpha.15",
     "ajv": "^8.12.0",
     "archiver": "^5.0.0",
     "cors": "^2.8.5",
@@ -77,7 +103,6 @@
     "express": "~4.19.2",
     "inquirer": "^8.0.0",
     "json-map-transform": "^1.2.6",
-    "jszip": "^3.5.0",
     "md5": "^2.3.0",
     "morgan": "~1.9.1",
     "uuid": "^9.0.0"
@@ -88,10 +113,11 @@
   },
   "devDependencies": {
     "@types/express": "^4.17.17",
-    "@types/inquirer": "^9.0.7"
+    "@types/inquirer": "^9.0.7",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@loaders.gl/core": "~5.0.0-alpha.0"
   },
-  "gitHead": "77a55028e8204e09df1258f10cb61ed35353b258"
+  "gitHead": "e9694544adb0bc7dac68a35adbc8bdae35f64dae"
 }

package/src/common/README.md

@@ -0,0 +1,5 @@
+# Shared tile-converter code
+
+Place code here when it is intentionally shared by multiple converter versions.
+Version-specific implementations belong in `v4/` or `v5/` so their APIs and
+runtime requirements remain independent.

package/src/index.ts

@@ -1,2 +1 @@
-export {default as I3SConverter} from './i3s-converter/i3s-converter';
-export {default as Tiles3DConverter} from './3d-tiles-converter/3d-tiles-converter';
+export * from './v4/index.js';

package/src/{3d-tiles-converter → v4/3d-tiles-converter}/3d-tiles-converter.ts

@@ -14,6 +14,7 @@ import {load, isBrowser} from '@loaders.gl/core';
 import {I3SLoader, I3SAttributeLoader, COORDINATE_SYSTEM} from '@loaders.gl/i3s';
 import {Geoid} from '@math.gl/geoid';
 
+import {validateI3SConversionSpatialReference} from './helpers/validate-i3s-spatial-reference';
 import {PGMLoader} from '../pgm-loader';
 import {i3sObbTo3dTilesObb} from './helpers/i3s-obb-to-3d-tiles-obb';
 import {convertScreenThresholdToGeometricError} from '../lib/utils/lod-conversion-utils';
@@ -134,8 +135,6 @@ export default class Tiles3DConverter {
       }
     }
 
-    this.progress.startMonitoring();
-
     this.sourceTileset = await loadFromArchive(
       inputUrl,
       I3SLoader,
@@ -151,6 +150,18 @@ export default class Tiles3DConverter {
       return undefined;
     }
 
+    try {
+      validateI3SConversionSpatialReference(this.sourceTileset);
+    } catch (error) {
+      try {
+        await this.slpkFilesystem?.destroy();
+      } finally {
+        this.slpkFilesystem = null;
+      }
+      throw error;
+    }
+    this.progress.startMonitoring();
+
     const rootNode = this.sourceTileset?.root;
     if (!rootNode.obb) {
       rootNode.obb = createObbFromMbs(rootNode.mbs);