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

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

@@ -0,0 +1,55 @@
+import type { TilesetSpatialReference } from '@loaders.gl/tiles';
+import type { MeshGeometry } from '@loaders.gl/schema';
+import type { TileConversionCodec } from './conversion-api.js';
+import type { Tiles3DConversionSpatialContext } from './spatial-conversion.js';
+import type { MeshTileMaterial } from './mesh.js';
+/** Explicitly selected geometry, with positions already in the spatial context's source frame. */
+export interface MeshConversionInput {
+    /** Caller-owned resource identifier, forwarded to the output sink. */
+    readonly id: string;
+    /** Triangle geometry with absolute packed Float32 or Float64 source positions. */
+    readonly mesh: MeshGeometry;
+    /** Optional single material with an embedded base-color image, mapped explicitly by the source adapter. */
+    readonly material?: MeshTileMaterial;
+    /** Finite xyz origin in the target frame, subtracted before float32 encoding. */
+    readonly origin: readonly [number, number, number];
+}
+/** A completed GLB resource and the metadata needed to place its local geometry. */
+export interface EncodedMeshConversionResource {
+    /** Caller-owned resource identifier. */
+    readonly id: string;
+    /** Self-contained GLB with local positions and transformed normals. */
+    readonly glb: ArrayBuffer;
+    /** Target-frame translation to add to the encoded positions. */
+    readonly origin: readonly [number, number, number];
+    /** Target-frame bounds of the reconstructed encoded vertices, including float32 rounding. */
+    readonly boundingBox: readonly [readonly number[], readonly number[]];
+    /** Bounds of encoded local vertices before adding the origin, without absolute-coordinate cancellation. */
+    readonly localBoundingBox: readonly [readonly number[], readonly number[]];
+    /** Metadata describing the output coordinate operation and height reference. */
+    readonly spatialReference: TilesetSpatialReference;
+    /** Largest measured Euclidean reconstruction error in target coordinate units. */
+    readonly maximumPositionError: number;
+}
+/** Spatial policy used by the concrete mesh conversion codec. */
+export interface MeshConversionCodecOptions {
+    /** Shared context that accepts absolute source positions and returns absolute target positions. */
+    readonly spatialContext: Tiles3DConversionSpatialContext;
+    /** Maximum Euclidean reconstruction error per vertex, in target coordinate units. */
+    readonly maxPositionError: number;
+}
+/**
+ * Creates a concrete mesh codec for `convertTileset`.
+ *
+ * Source adapters must select geometry and apply source placement before supplying absolute
+ * positions and matching normals. This codec applies the supplied spatial context once, rebases
+ * around each input's target origin, and rejects rounding above the explicit error budget.
+ * Geographic and unknown output frames are rejected. The returned origin/bounds/reference are
+ * external placement metadata; applications own axis conventions, hierarchy, and packaging.
+ * Input arrays are not mutated. Core input/output byte gates, cancellation, awaited writes, and
+ * destination finalize/abort handling apply when used through `convertTileset`.
+ *
+ * @param options - Resolved spatial context and finite nonnegative target-unit precision budget.
+ * @returns One GLB and matching metadata per input geometry.
+ */
+export declare function createMeshConversionCodec<TInspection = unknown>(options: MeshConversionCodecOptions): TileConversionCodec<TInspection, MeshConversionInput, EncodedMeshConversionResource>;

package/dist/v5/mesh-tileset-archive.d.ts

@@ -0,0 +1,16 @@
+import type { BrowserTileConversionFile } from './browser-sink.js';
+/** Output-size budget for a single-mesh 3TZ archive. */
+export interface SingleMeshTilesetArchiveOptions {
+    /** Maximum final archive bytes, including ZIP headers and index; not peak serialization memory. */
+    readonly maxArchiveBytes: number;
+}
+/**
+ * Packages the two unmodified files from a finalized single-mesh sink as a downloadable 3TZ Blob.
+ * The writer checks the complete archive budget before reading either Blob. Applications own
+ * object-URL creation/revocation and download UI. Retained input Blobs and transient ZIP buffers
+ * are additional memory. SLPK requires separately authored I3S scene-layer resources.
+ * @param files - Files returned by a successfully finalized createSingleMeshTilesetSink.
+ * @param options - Required final archive-size budget.
+ * @returns An indexed 3TZ Blob; save with the .3tz extension.
+ */
+export declare function createSingleMeshTilesetArchive(files: readonly BrowserTileConversionFile[], options: SingleMeshTilesetArchiveOptions): Promise<Blob>;

package/dist/v5/mesh-tileset-sink.d.ts

@@ -0,0 +1,31 @@
+import type { TileConversionSink } from './conversion-api.js';
+import type { BrowserTileConversionFile } from './browser-sink.js';
+import type { EncodedMeshConversionResource } from './mesh-conversion.js';
+/** Limits and fidelity policy for one ECEF mesh tileset. */
+export interface SingleMeshTilesetSinkOptions {
+    /** Maximum combined UTF-8 tileset JSON and GLB Blob bytes retained by the sink. */
+    readonly maxTotalBytes: number;
+    /** Explicit geometric error in meters, including source error and position rounding. */
+    readonly geometricError: number;
+}
+/** A single-tile output package retained as two named browser-native Blobs. */
+export interface SingleMeshTilesetSink extends TileConversionSink<EncodedMeshConversionResource> {
+    /** Returns mesh.glb and tileset.json only after successful finalization; empty after abort. */
+    getFiles(): readonly BrowserTileConversionFile[];
+}
+/**
+ * Packages exactly one `createMeshConversionCodec` output as a 3D Tiles 1.1 tileset.
+ *
+ * Requires resolved EPSG:4978 output identified by the compact string, with ellipsoidal heights.
+ * The tile transform cancels the standard glTF y-up to z-up rotation and adds the ECEF origin.
+ * Bounds come from encoded local vertices, avoiding subtraction of large absolute coordinates.
+ * Fixed relative names keep the package deterministic. Save both files together or pass them to
+ * createSingleMeshTilesetArchive for 3TZ packaging. Applications own downloads, workers, and
+ * source-scene extraction.
+ * The byte limit bounds retained Blobs, not peak conversion/serialization memory. Input GLB and
+ * local bounds must be unmodified codec outputs; this sink does not independently validate GLB.
+ *
+ * @param options - Required retained-output budget and geometric error in meters.
+ * @returns A bounded sink that exposes files on finalization and clears them on abort.
+ */
+export declare function createSingleMeshTilesetSink(options: SingleMeshTilesetSinkOptions): SingleMeshTilesetSink;

package/dist/v5/mesh.d.ts

@@ -0,0 +1,73 @@
+import type { MeshGeometry } from '@loaders.gl/schema';
+/** 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 {
+    /** 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;
+/** Validates the shared mesh profile; spatial preparation may retain Float64 positions internally. */
+export declare function validateMeshGeometry(mesh: MeshGeometry, allowFloat64Positions?: boolean): MeshGeometry;

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 './conversion-api.js';
+import type { PointCloudSourceTile } from './point-cloud-source.js';
+import type { EncodedPointCloudSourceTile, EncodePointCloudSourceOptions } from './point-cloud-source-encoder.js';
+/** Point-cloud encoding options and an application-owned output destination. */
+export interface ConvertPointCloudSourceOptions extends EncodePointCloudSourceOptions {
+    /** Destination receiving PNTS resources and their source placement metadata. */
+    readonly sink: TileConversionSink<EncodedPointCloudSourceTile>;
+    /** Input byte accounting for each visited source tile, including tiles with null content. */
+    readonly measureInputBytes: (sourceTile: PointCloudSourceTile) => number;
+    /** Maximum caller-measured bytes in one decoded source tile, checked before PNTS encoding. */
+    readonly maxInputResourceBytes?: number;
+    /** Maximum bytes in one encoded PNTS resource. Defaults to no limit. */
+    readonly maxOutputResourceBytes?: number;
+    /** Receive conversion progress, including resource counts and caller-measured input bytes. */
+    readonly onProgress?: (progress: TileConversionProgress) => void;
+}
+/**
+ * Converts a point-cloud source to PNTS resources through the v5 output-sink lifecycle.
+ *
+ * Each write is awaited before reading the next source tile. The destination is finalized only
+ * after traversal and writes succeed, and aborted on read, encoding, write, or cancellation errors.
+ * Input resource counts include empty tiles; output counts and byte sizes describe emitted PNTS
+ * resources. Applications supply input byte accounting because source tiles contain decoded Arrow
+ * data rather than transport bytes. The caller retains ownership of the input source.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud source to initialize and traverse.
+ * @param options - Destination, byte accounting, traversal limits, and per-tile encoding options.
+ * @returns The shared v5 conversion report after destination finalization.
+ */
+export declare function convertPointCloudSource(source: PointCloudTilesetSource, options: ConvertPointCloudSourceOptions): Promise<TileConversionReport>;

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

@@ -0,0 +1,49 @@
+import type { PointCloudBoundingVolume, PointCloudCoordinateSystem, PointCloudTilesetSource, TilesetSpatialReference } from '@loaders.gl/tiles';
+import type { EncodePointCloudTileOptions } from './point-cloud.js';
+import type { PointCloudSourceTile, TraversePointCloudSourceOptions } from './point-cloud-source.js';
+/** Traversal and per-tile encoding options for a point-cloud source. */
+export type EncodePointCloudSourceOptions = TraversePointCloudSourceOptions & {
+    /** Select encoder options for each source tile with content, using its header and decoded data. */
+    readonly getTileEncodingOptions?: (sourceTile: PointCloudSourceTile) => EncodePointCloudTileOptions;
+};
+/** A PNTS resource paired with the source placement metadata needed to package its tile. */
+export type EncodedPointCloudSourceTile = {
+    /** Stable source tile identifier. */
+    readonly id: string;
+    /** Original source hierarchy and bounds. */
+    readonly header: PointCloudSourceTile['header'];
+    /** Encoded point-cloud tile content. */
+    readonly pnts: ArrayBuffer;
+    /** Number of point records encoded. */
+    readonly pointCount: number;
+    /** Coordinate system used by the returned point positions. */
+    readonly coordinateSystem: PointCloudCoordinateSystem;
+    /** Origin to add to source-relative point positions. */
+    readonly cartographicOrigin: readonly number[];
+    /** Optional placement transform supplied by the point-cloud source. */
+    readonly modelMatrix?: readonly number[];
+    /** Optional source or target CRS metadata. */
+    readonly spatialReference?: TilesetSpatialReference;
+    /** Optional output-frame tile bounds supplied by the source. */
+    readonly spatialBoundingVolume?: PointCloudBoundingVolume;
+};
+/**
+ * Encodes a point-cloud source as a stream of PNTS resources, one for each non-empty source tile.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud tileset source.
+ * @param options - Optional traversal depth limit, cancellation signal, and per-tile encoder options.
+ * @returns Encoded source tiles in deterministic depth-first order.
+ */
+export 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.d.ts

@@ -0,0 +1,24 @@
+import type { Mesh, MeshArrowTable } 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];
+    /** 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)[]>>;
+}
+/**
+ * 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;

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,59 @@
+import type { CreateTilesetSpatialReferenceOptions, I3SSpatialBounds, I3STransformedPositions, 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 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.7",
+  "version": "5.0.0-alpha.9",
   "description": "Converter",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,16 @@
       "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"
     }
   },
   "sideEffects": false,
@@ -45,30 +55,35 @@
     "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 && esbuild src/v5/index.ts --bundle --packages=external --platform=node --format=esm --outfile=dist/v5/index.js && esbuild src/v5/index.ts --bundle --packages=external --platform=node --format=cjs --outfile=dist/v5/index.cjs && esbuild src/v5/browser.ts --bundle --packages=external --platform=browser --format=esm --outfile=dist/v5/browser.js && esbuild src/v5/browser.ts --bundle --packages=external --platform=browser --format=cjs --outfile=dist/v5/browser.cjs && npm run build-v5-declarations",
+    "build-v5-declarations": "tsc --ignoreConfig --declaration --emitDeclarationOnly --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext --rootDir src/v5 --outDir dist/v5 src/v5/index.ts src/v5/browser.ts",
+    "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"
   },
   "dependencies": {
-    "@loaders.gl/3d-tiles": "5.0.0-alpha.7",
-    "@loaders.gl/compression": "5.0.0-alpha.7",
-    "@loaders.gl/crypto": "5.0.0-alpha.7",
-    "@loaders.gl/draco": "5.0.0-alpha.7",
-    "@loaders.gl/gltf": "5.0.0-alpha.7",
-    "@loaders.gl/i3s": "5.0.0-alpha.7",
-    "@loaders.gl/images": "5.0.0-alpha.7",
-    "@loaders.gl/loader-utils": "5.0.0-alpha.7",
-    "@loaders.gl/polyfills": "5.0.0-alpha.7",
-    "@loaders.gl/textures": "5.0.0-alpha.7",
-    "@loaders.gl/tiles": "5.0.0-alpha.7",
-    "@loaders.gl/worker-utils": "5.0.0-alpha.7",
-    "@loaders.gl/zip": "5.0.0-alpha.7",
-    "@math.gl/core": "5.0.0-alpha.9",
-    "@math.gl/culling": "5.0.0-alpha.9",
-    "@math.gl/geoid": "5.0.0-alpha.9",
-    "@math.gl/geometry-utils": "5.0.0-alpha.9",
-    "@math.gl/geospatial": "5.0.0-alpha.9",
+    "@loaders.gl/3d-tiles": "5.0.0-alpha.9",
+    "@loaders.gl/compression": "5.0.0-alpha.9",
+    "@loaders.gl/crypto": "5.0.0-alpha.9",
+    "@loaders.gl/draco": "5.0.0-alpha.9",
+    "@loaders.gl/gltf": "5.0.0-alpha.9",
+    "@loaders.gl/i3s": "5.0.0-alpha.9",
+    "@loaders.gl/images": "5.0.0-alpha.9",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.9",
+    "@loaders.gl/polyfills": "5.0.0-alpha.9",
+    "@loaders.gl/schema": "5.0.0-alpha.9",
+    "@loaders.gl/schema-utils": "5.0.0-alpha.9",
+    "@loaders.gl/textures": "5.0.0-alpha.9",
+    "@loaders.gl/tiles": "5.0.0-alpha.9",
+    "@loaders.gl/worker-utils": "5.0.0-alpha.9",
+    "@loaders.gl/zip": "5.0.0-alpha.9",
+    "@math.gl/core": "5.0.0-alpha.12",
+    "@math.gl/crs": "5.0.0-alpha.12",
+    "@math.gl/culling": "5.0.0-alpha.12",
+    "@math.gl/geoid": "5.0.0-alpha.12",
+    "@math.gl/geometry-utils": "5.0.0-alpha.12",
+    "@math.gl/geospatial": "5.0.0-alpha.12",
     "ajv": "^8.12.0",
     "archiver": "^5.0.0",
     "cors": "^2.8.5",
@@ -77,7 +92,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 +102,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": "e1e6174f9e66f4f3e695e8778f769429508342f1"
+  "gitHead": "c3be3766791d30e79a9aa1d9b326962f264cbbe7"
 }

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);