@loaders.gl/tile-converter 5.0.0-alpha.6 → 5.0.0-alpha.8

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.6",
+  "version": "5.0.0-alpha.8",
   "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.6",
-    "@loaders.gl/compression": "5.0.0-alpha.6",
-    "@loaders.gl/crypto": "5.0.0-alpha.6",
-    "@loaders.gl/draco": "5.0.0-alpha.6",
-    "@loaders.gl/gltf": "5.0.0-alpha.6",
-    "@loaders.gl/i3s": "5.0.0-alpha.6",
-    "@loaders.gl/images": "5.0.0-alpha.6",
-    "@loaders.gl/loader-utils": "5.0.0-alpha.6",
-    "@loaders.gl/polyfills": "5.0.0-alpha.6",
-    "@loaders.gl/textures": "5.0.0-alpha.6",
-    "@loaders.gl/tiles": "5.0.0-alpha.6",
-    "@loaders.gl/worker-utils": "5.0.0-alpha.6",
-    "@loaders.gl/zip": "5.0.0-alpha.6",
-    "@math.gl/core": "5.0.0-alpha.5",
-    "@math.gl/culling": "5.0.0-alpha.5",
-    "@math.gl/geoid": "5.0.0-alpha.5",
-    "@math.gl/geometry-utils": "5.0.0-alpha.5",
-    "@math.gl/geospatial": "5.0.0-alpha.5",
+    "@loaders.gl/3d-tiles": "5.0.0-alpha.8",
+    "@loaders.gl/compression": "5.0.0-alpha.8",
+    "@loaders.gl/crypto": "5.0.0-alpha.8",
+    "@loaders.gl/draco": "5.0.0-alpha.8",
+    "@loaders.gl/gltf": "5.0.0-alpha.8",
+    "@loaders.gl/i3s": "5.0.0-alpha.8",
+    "@loaders.gl/images": "5.0.0-alpha.8",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.8",
+    "@loaders.gl/polyfills": "5.0.0-alpha.8",
+    "@loaders.gl/schema": "5.0.0-alpha.8",
+    "@loaders.gl/schema-utils": "5.0.0-alpha.8",
+    "@loaders.gl/textures": "5.0.0-alpha.8",
+    "@loaders.gl/tiles": "5.0.0-alpha.8",
+    "@loaders.gl/worker-utils": "5.0.0-alpha.8",
+    "@loaders.gl/zip": "5.0.0-alpha.8",
+    "@math.gl/core": "5.0.0-alpha.11",
+    "@math.gl/crs": "5.0.0-alpha.11",
+    "@math.gl/culling": "5.0.0-alpha.11",
+    "@math.gl/geoid": "5.0.0-alpha.11",
+    "@math.gl/geometry-utils": "5.0.0-alpha.11",
+    "@math.gl/geospatial": "5.0.0-alpha.11",
     "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": "9b9ea7738e0fe63e55c19c136283705f99e0b9bf"
+  "gitHead": "bdc4536ea5b7d074ea362e372704cbdb180126cc"
 }

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

package/src/v4/3d-tiles-converter/helpers/validate-i3s-spatial-reference.ts

@@ -0,0 +1,124 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import {parseWKTCRS, type WKTCRSNode} from '@math.gl/crs';
+import {getSpatialCoordinateFrame} from '@loaders.gl/tiles';
+
+/** Horizontal CRS declarations consumed by the legacy I3S converter. */
+export type I3SConversionSpatialReference = {
+  /** Layer-level horizontal coordinate reference system. */
+  spatialReference?: {
+    /** Original spatial reference identifier. */
+    wkid?: number;
+    /** Current spatial reference identifier. */
+    latestWkid?: number;
+    /** Custom spatial reference definition. */
+    wkt?: string;
+  };
+  /** Fallback CRS declaration on the layer extent. */
+  fullExtent?: {
+    /** Coordinate system shared by the extent and layer. */
+    spatialReference?: I3SConversionSpatialReference['spatialReference'];
+  };
+  /** Coordinate systems declared for node bounds and geometry. */
+  store?: {
+    /** Coordinate system used by node bounds. */
+    indexCRS?: string;
+    /** Coordinate system used by geometry positions. */
+    vertexCRS?: string;
+  };
+};
+
+/**
+ * Reject explicit horizontal CRS declarations that the legacy converter cannot transform.
+ * Undeclared CRS metadata retains the historical WGS-84 assumption.
+ * @param layer - Source layer metadata, before interpreting any coordinates as longitude/latitude.
+ */
+export function validateI3SConversionSpatialReference(layer: I3SConversionSpatialReference): void {
+  const spatialReferences = [layer.spatialReference, layer.fullExtent?.spatialReference];
+  const unsupportedSpatialReference = spatialReferences.find(spatialReference => {
+    if (!spatialReference) {
+      return false;
+    }
+    const identifier = spatialReference.latestWkid ?? spatialReference.wkid;
+    return (
+      (identifier !== undefined && identifier !== 4326 && identifier !== 4979) ||
+      (spatialReference.wkt !== undefined && !isWgs84GeographicWkt(spatialReference.wkt))
+    );
+  });
+  const declarations = [layer.store?.indexCRS, layer.store?.vertexCRS].filter(
+    (declaration): declaration is string => Boolean(declaration)
+  );
+  const unsupportedDeclaration = declarations.find(
+    declaration =>
+      !/^(?:EPSG:(?:4326|4979)|urn:ogc:def:crs:EPSG::(?:4326|4979)|https?:\/\/www\.opengis\.net\/def\/crs\/EPSG\/0\/(?:4326|4979)\/?)$/i.test(
+        declaration
+      )
+  );
+  if (unsupportedSpatialReference || unsupportedDeclaration) {
+    const identifier = unsupportedSpatialReference?.latestWkid ?? unsupportedSpatialReference?.wkid;
+    const description =
+      unsupportedDeclaration || (identifier !== undefined ? `EPSG:${identifier}` : 'custom WKT');
+    throw new Error(
+      `The legacy I3S-to-3D Tiles converter requires WGS-84 (EPSG:4326) input; received ${description}. Reproject the source I3S dataset to EPSG:4326 before conversion.`
+    );
+  }
+}
+
+/** Recognize geographic WGS-84 WKT with degree units and the Greenwich prime meridian. */
+function isWgs84GeographicWkt(wellKnownText: string): boolean {
+  try {
+    if (getSpatialCoordinateFrame(wellKnownText) !== 'geographic') {
+      return false;
+    }
+    const {root} = parseWKTCRS(wellKnownText);
+    const nodes = collectWktNodes(root);
+    const datum = root.values.find(
+      value =>
+        value.type === 'node' &&
+        ['DATUM', 'ENSEMBLE', 'GEODETICDATUM'].includes(value.keyword.toUpperCase())
+    );
+    if (datum?.type !== 'node' || datum.values[0]?.type !== 'string') {
+      return false;
+    }
+    const datumName = datum.values[0].value.toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (
+      ![
+        'wgs84',
+        'wgs1984',
+        'dwgs1984',
+        'worldgeodeticsystem1984',
+        'worldgeodeticsystem1984ensemble'
+      ].includes(datumName)
+    ) {
+      return false;
+    }
+    const angularUnits = nodes.filter(
+      node =>
+        ['UNIT', 'ANGLEUNIT'].includes(node.keyword.toUpperCase()) &&
+        (node === root || root.values.includes(node) || node.keyword.toUpperCase() === 'ANGLEUNIT')
+    );
+    const primeMeridian = nodes.find(node => node.keyword.toUpperCase() === 'PRIMEM');
+    return (
+      angularUnits.length > 0 &&
+      angularUnits.every(
+        node =>
+          node.values[1]?.type === 'number' &&
+          Math.abs(node.values[1].value - Math.PI / 180) < 1e-12
+      ) &&
+      (!primeMeridian ||
+        (primeMeridian.values[1]?.type === 'number' && primeMeridian.values[1].value === 0))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Collect WKT nodes for semantic checks without inspecting quoted text as syntax. */
+function collectWktNodes(node: WKTCRSNode): WKTCRSNode[] {
+  return [
+    node,
+    ...node.values.flatMap(value => (value.type === 'node' ? collectWktNodes(value) : []))
+  ];
+}

package/src/{deps-installer → v4/deps-installer}/deps-installer.ts

@@ -48,13 +48,13 @@ export class DepsInstaller {
     await this.installFromNpm('draco', 'draco-worker-node.js');
 
     console.log('Installing "Draco Writer" worker'); // eslint-disable-line no-console
-    await this.installFromNpm('draco', 'draco-writer-worker-node.js');
+    await this.installFromNpm('draco', 'draco-writer-worker-node.cjs');
 
     console.log('Installing "Basis Loader" worker'); // eslint-disable-line no-console
-    await this.installFromNpm('textures', 'basis-worker-node.js');
+    await this.installFromNpm('textures', 'basis-worker-node.cjs');
 
     console.log('Installing "KTX2 Basis Writer" worker'); // eslint-disable-line no-console
-    await this.installFromNpm('textures', 'ktx2-basis-writer-worker-node.js');
+    await this.installFromNpm('textures', 'ktx2-basis-writer-worker-node.cjs');
 
     console.log('Installing "Draco decoder" library'); // eslint-disable-line no-console
     await this.installFromUrl(
@@ -101,13 +101,16 @@ export class DepsInstaller {
     console.log('All dependencies were installed succesfully.'); // eslint-disable-line no-console
   }
 
+  /** Download a published worker or library into the converter's local resource directory. */
   private async installFromNpm(module: string, name: string, extraPath: string = '') {
-    const fileResponse = await fetchFile(
-      `https://unpkg.com/@loaders.gl/${module}@${VERSION}/dist/${extraPath}/${name}`
-    );
+    const resourcePath = ['dist', extraPath, name].filter(Boolean).join('/');
+    const resourceUrl = `https://unpkg.com/@loaders.gl/${module}@${VERSION}/${resourcePath}`;
+    const fileResponse = await fetchFile(resourceUrl);
 
     if (fileResponse.status < 200 || fileResponse.status >= 300) {
-      throw new Error(`Failed to load resource ${name}`);
+      throw new Error(
+        `Failed to load resource ${name} from ${resourceUrl}: HTTP ${fileResponse.status}`
+      );
     }
 
     const fileData = await fileResponse.arrayBuffer();

package/src/v4/i3s-converter/helpers/encode-string-attribute.ts

@@ -0,0 +1,23 @@
+/**
+ * Encodes I3S string attributes as little-endian counts followed by UTF-8 strings.
+ * Each string's byte count includes its trailing null byte. Values retain the
+ * converter's existing JavaScript string coercion, including null and undefined.
+ */
+export function encodeStringAttribute(values: readonly unknown[]): ArrayBuffer {
+  const textEncoder = new TextEncoder();
+  const encodedValues = Array.from(values, value => textEncoder.encode(`${String(value)}\0`));
+  const stringByteLength = encodedValues.reduce((total, value) => total + value.byteLength, 0);
+  const headerByteLength = (2 + values.length) * Uint32Array.BYTES_PER_ELEMENT;
+  const output = new Uint8Array(headerByteLength + stringByteLength);
+  const header = new DataView(output.buffer);
+  header.setUint32(0, values.length, true);
+  header.setUint32(4, stringByteLength, true);
+
+  let byteOffset = headerByteLength;
+  for (const [index, encodedValue] of encodedValues.entries()) {
+    header.setUint32(8 + index * Uint32Array.BYTES_PER_ELEMENT, encodedValue.byteLength, true);
+    output.set(encodedValue, byteOffset);
+    byteOffset += encodedValue.byteLength;
+  }
+  return output.buffer;
+}