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

package/src/v5/browser.ts

@@ -35,8 +35,14 @@ export type {
   BrowserTileConversionSourceOptions
 } from '@loaders.gl/tile-converter/v5/core';
 export {createBrowserTilesetConversionSource} from '@loaders.gl/tile-converter/v5/core';
-export {encodePointCloudTile} from '@loaders.gl/tile-converter/v5/adapters';
-export type {EncodePointCloudTileOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export {
+  encodePointCloudTile,
+  encodePointCloudTileWithMetadata
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  EncodePointCloudTileOptions,
+  EncodedPointCloudTile
+} from '@loaders.gl/tile-converter/v5/adapters';
 export {traversePointCloudSource} from '@loaders.gl/tile-converter/v5/core';
 export type {
   PointCloudSourceTile,
@@ -103,3 +109,76 @@ export type {
   I3SMeshConversionCodecOptions,
   SingleMeshI3SSink
 } from '@loaders.gl/tile-converter/v5/adapters';
+
+export {
+  createI3SMeshSink,
+  createTileConversionResourceFetcher
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  I3SMeshSink,
+  I3SMeshSinkOptions,
+  TileConversionResourceFetcherOptions,
+  MeshTileFeatures
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createPointCloudTilesetSink} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  PointCloudTilesetSink,
+  PointCloudTilesetSinkOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {transformPointCloudSourceTile} from '@loaders.gl/tile-converter/v5/adapters';
+export type {PointCloudSpatialOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export {createI3SConversionSpatialContext} from '@loaders.gl/tile-converter/v5/core';
+export type {I3SConversionSpatialContext} from '@loaders.gl/tile-converter/v5/core';
+
+export {createI3SMeshTilesetConversionSource} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  I3SMeshTilesetSourceOptions,
+  I3SMeshSourceFeatureOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {convertPointCloudToTileset} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  ConvertPointCloudToTilesetOptions,
+  ConvertedPointCloudTileset
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {
+  encodePotreeArchive,
+  openPointCloudFile,
+  extractMeshVertices
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  EncodePotreeArchiveOptions,
+  OpenPointCloudFileOptions,
+  OpenedPointCloudFile,
+  ExtractMeshVerticesOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createMeshSourceFeatureOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export type {MeshSourceSchemaOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export {convertPointCloudToPotree} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  ConvertPointCloudToPotreeOptions,
+  ConvertedPointCloudPotree
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {selectBrowserTilesetContent} from '@loaders.gl/tile-converter/v5/core';
+export type {
+  BrowserTilesetDocumentPlacement,
+  BrowserTilesetContentSelection
+} from '@loaders.gl/tile-converter/v5/core';
+
+export {
+  createSelectedMeshConversionSource,
+  measureMeshBytes,
+  SELECTED_MESH_LIMITS
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  SelectedMeshSourceOptions,
+  SelectedMeshConversionSource
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createMeshHierarchyTilesetSink} from '@loaders.gl/tile-converter/v5/adapters';
+export type {MeshHierarchyTilesetSinkOptions} from '@loaders.gl/tile-converter/v5/adapters';

package/src/v5/conversion-api.ts

@@ -111,6 +111,14 @@ export interface ConvertTilesetOptions<TInspection, TInput, TOutput> {
   readonly maxInputResourceBytes?: number;
   /** Reject any output resource larger than this configured byte limit. */
   readonly maxOutputResourceBytes?: number;
+  /** Maximum measured input bytes across this run; does not bound source allocations. */
+  readonly maxInputBytes?: number;
+  /** Maximum measured output bytes across this run, including checkpointed resources. */
+  readonly maxOutputBytes?: number;
+  /** Maximum input resources consumed by this run, including zero-byte resources. */
+  readonly maxInputResources?: number;
+  /** Maximum outputs processed by this run, including zero-byte and checkpointed resources. */
+  readonly maxOutputResources?: number;
   /** Cancel inspection, conversion, validation, or writes. */
   readonly signal?: AbortSignal;
   /** Receive progress updates after each resource transition. */
@@ -155,6 +163,7 @@ export async function inspectTileset<TInspection, TInput>(
  * This does not limit source decoding allocations or content retained by a source.
  * Writes are awaited one resource at a time, keeping queued output bytes bounded by the
  * largest emitted resource and the configured `maxOutputResourceBytes` limit.
+ * Cumulative byte/count limits bound measured work in this run, not total allocation memory.
  */
 export async function convertTileset<TInspection, TInput, TOutput>(
   options: ConvertTilesetOptions<TInspection, TInput, TOutput>
@@ -167,6 +176,10 @@ export async function convertTileset<TInspection, TInput, TOutput>(
     measureOutputBytes,
     maxInputResourceBytes = Number.POSITIVE_INFINITY,
     maxOutputResourceBytes = Number.POSITIVE_INFINITY,
+    maxInputBytes = Number.POSITIVE_INFINITY,
+    maxOutputBytes = Number.POSITIVE_INFINITY,
+    maxInputResources = Number.POSITIVE_INFINITY,
+    maxOutputResources = Number.POSITIVE_INFINITY,
     signal,
     onProgress
   } = options;
@@ -181,19 +194,26 @@ export async function convertTileset<TInspection, TInput, TOutput>(
   };
 
   try {
-    if (
-      maxInputResourceBytes !== Number.POSITIVE_INFINITY &&
-      (!Number.isSafeInteger(maxInputResourceBytes) || maxInputResourceBytes < 0)
-    ) {
-      throw new TileConversionError(
-        'INVALID_INPUT_RESOURCE_LIMIT',
-        'maxInputResourceBytes must be a nonnegative safe integer or Infinity'
-      );
+    for (const [name, limit, code] of [
+      ['maxInputResourceBytes', maxInputResourceBytes, 'INVALID_INPUT_RESOURCE_LIMIT'],
+      ['maxOutputResourceBytes', maxOutputResourceBytes, 'INVALID_OUTPUT_RESOURCE_LIMIT'],
+      ['maxInputBytes', maxInputBytes, 'INVALID_INPUT_BYTES_LIMIT'],
+      ['maxOutputBytes', maxOutputBytes, 'INVALID_OUTPUT_BYTES_LIMIT'],
+      ['maxInputResources', maxInputResources, 'INVALID_INPUT_COUNT_LIMIT'],
+      ['maxOutputResources', maxOutputResources, 'INVALID_OUTPUT_COUNT_LIMIT']
+    ] as const) {
+      if (limit !== Infinity && (!Number.isSafeInteger(limit) || limit < 0)) {
+        throw new TileConversionError(
+          code,
+          name + ' must be a nonnegative safe integer or Infinity'
+        );
+      }
     }
     reportProgress('inspect');
     const inspection = await inspectTileset(source, signal);
     for await (const inputResource of source.read(inspection, signal)) {
       throwIfAborted(signal);
+      checkConversionTotal(inputResources, 1, maxInputResources, 'INPUT_COUNT_LIMIT_EXCEEDED');
       const inputResourceBytes = measureInputBytes(inputResource);
       if (!Number.isSafeInteger(inputResourceBytes) || inputResourceBytes < 0) {
         throw new TileConversionError(
@@ -207,23 +227,41 @@ export async function convertTileset<TInspection, TInput, TOutput>(
           `Input resource is ${inputResourceBytes} bytes, exceeding the configured limit of ${maxInputResourceBytes} bytes`
         );
       }
+      checkConversionTotal(
+        inputBytes,
+        inputResourceBytes,
+        maxInputBytes,
+        'INPUT_BYTES_LIMIT_EXCEEDED'
+      );
       inputResources++;
       inputBytes += inputResourceBytes;
       reportProgress('convert');
       const convertedResources = await codec.convert(inputResource, inspection, signal);
       for await (const outputResource of convertedResources) {
         throwIfAborted(signal);
+        checkConversionTotal(outputResources, 1, maxOutputResources, 'OUTPUT_COUNT_LIMIT_EXCEEDED');
         reportProgress('validate');
         const resourceDiagnostics = (await codec.validateOutput?.(outputResource, signal)) || [];
         diagnostics.push(...resourceDiagnostics);
         const outputResourceBytes = measureOutputBytes(outputResource);
-        largestOutputResourceBytes = Math.max(largestOutputResourceBytes, outputResourceBytes);
+        if (!Number.isSafeInteger(outputResourceBytes) || outputResourceBytes < 0) {
+          throw new TileConversionError(
+            'INVALID_OUTPUT_RESOURCE_SIZE',
+            'measureOutputBytes must return a nonnegative safe integer'
+          );
+        }
         if (outputResourceBytes > maxOutputResourceBytes) {
           throw new TileConversionError(
             'OUTPUT_RESOURCE_TOO_LARGE',
             `Output resource is ${outputResourceBytes} bytes, exceeding the configured limit of ${maxOutputResourceBytes} bytes`
           );
         }
+        checkConversionTotal(
+          outputBytes,
+          outputResourceBytes,
+          maxOutputBytes,
+          'OUTPUT_BYTES_LIMIT_EXCEEDED'
+        );
         if (resourceDiagnostics.some(diagnostic => diagnostic.severity === 'error')) {
           throw new TileConversionError(
             'OUTPUT_VALIDATION_FAILED',
@@ -234,6 +272,7 @@ export async function convertTileset<TInspection, TInput, TOutput>(
         throwIfAborted(signal);
         await sink.write(outputResource, signal);
         throwIfAborted(signal);
+        largestOutputResourceBytes = Math.max(largestOutputResourceBytes, outputResourceBytes);
         outputResources++;
         outputBytes += outputResourceBytes;
         reportProgress('convert');
@@ -285,3 +324,24 @@ function throwIfAborted(signal?: AbortSignal): void {
     throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
   }
 }
+
+/** Checks a cumulative budget without overflowing safe integer accounting. */
+function checkConversionTotal(
+  current: number,
+  increment: number,
+  limit: number,
+  code: string
+): void {
+  if (increment > limit - current) {
+    throw new TileConversionError(
+      code,
+      `Conversion exceeds cumulative limit ${limit}: ${current} processed, next resource adds ${increment}`
+    );
+  }
+  if (increment > Number.MAX_SAFE_INTEGER - current) {
+    throw new TileConversionError(
+      'RESOURCE_TOTAL_OVERFLOW',
+      'Conversion totals must remain safe integers'
+    );
+  }
+}

package/src/v5/converter-cli.ts

@@ -0,0 +1,28 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {runTileConverterCLI} from './node-cli.js';
+
+/** Runs the Node process adapter and maps SIGINT into cooperative I/O cancellation. */
+async function main(): Promise<void> {
+  const controller = new AbortController();
+  /** Cancels the active operation; promise cleanup closes source and output handles. */
+  const cancelOperation = (): void =>
+    controller.abort(new Error('Tile conversion operation interrupted'));
+  process.on('SIGINT', cancelOperation);
+  try {
+    process.exitCode = await runTileConverterCLI(
+      process.argv.slice(2),
+      {
+        stdout: text => process.stdout.write(text),
+        stderr: text => process.stderr.write(text)
+      },
+      controller.signal
+    );
+  } finally {
+    process.removeListener('SIGINT', cancelOperation);
+  }
+}
+
+void main();

package/src/v5/core.ts

@@ -59,3 +59,9 @@ export type {
   BrowserTilesetResourceDescriptor,
   BrowserTilesetConversionInputResource
 } from './browser-tileset-source.js';
+
+export {selectBrowserTilesetContent} from './browser-tileset-source.js';
+export type {
+  BrowserTilesetDocumentPlacement,
+  BrowserTilesetContentSelection
+} from './browser-tileset-source.js';

package/src/v5/i3s-mesh-conversion.ts

@@ -2,11 +2,22 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {encodeI3SMeshLayer} from '@loaders.gl/i3s';
-import type {EncodedI3SMeshLayer, I3SMeshWriterOptions} from '@loaders.gl/i3s';
+import {
+  encodeI3SMeshLayer,
+  encodeI3SMeshLayerWithDraco,
+  preloadI3SMeshCompression
+} from '@loaders.gl/i3s';
+import type {
+  EncodedI3SMeshLayer,
+  I3SMeshWriterOptions,
+  I3SDracoLibraryOptions
+} from '@loaders.gl/i3s';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 import type {TileConversionCodec, TileConversionSink} from '@loaders.gl/tile-converter/v5/core';
-import type {Tiles3DConversionSpatialContext} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  Tiles3DConversionSpatialContext,
+  I3SConversionSpatialContext
+} from '@loaders.gl/tile-converter/v5/core';
 import type {MeshSourceResource} from './mesh-source.js';
 import {validateMeshGeometry} from './mesh.js';
 import {createBoundedMemoryTileConversionSink} from '@loaders.gl/tile-converter/v5/core';
@@ -16,19 +27,38 @@ import type {BrowserTileConversionFile} from '@loaders.gl/tile-converter/v5/core
 export interface I3SMeshConversionResource extends EncodedI3SMeshLayer {
   /** Source placement identifier used for diagnostics. */
   readonly id: string;
+  /** Original I3S layer type when authoring from an I3S source. */
+  readonly sourceLayerType?: '3DObject' | 'IntegratedMesh';
 }
 
 /** Spatial preparation and required authoring limits for the I3S codec. */
 export interface I3SMeshConversionCodecOptions
   extends Pick<I3SMeshWriterOptions, 'name' | 'maxPositionError' | 'maxResourceBytes'> {
   /** Shared source-to-ECEF context, applied exactly once before I3S geographic encoding. */
-  readonly spatialContext: Tiles3DConversionSpatialContext;
+  readonly spatialContext: Tiles3DConversionSpatialContext | I3SConversionSpatialContext;
+  /** I3S vector frame when using an I3S context; defaults to earth-centered. */
+  readonly normalReferenceFrame?: 'earth-centered' | 'vertex-reference-frame';
+  /** Lossless Edge Breaker geometry by default; false retains raw I3S geometry. */
+  readonly draco?: boolean;
+  /** Explicitly authorize IntegratedMesh input to become 3DObject output; omission rejects it. */
+  readonly integratedMeshPolicy?: 'as-3d-object';
+  /** Full Draco encoder/decoder runtime URLs or injected modules. */
+  readonly dracoLibraryOptions?: I3SDracoLibraryOptions;
 }
 
 /** Creates a portable source-mesh to I3S layer codec with explicit precision and feature diagnostics. */
 export function createI3SMeshConversionCodec<TInspection = unknown>(
   options: I3SMeshConversionCodecOptions
 ): TileConversionCodec<TInspection, MeshSourceResource, I3SMeshConversionResource> {
+  if (
+    options.integratedMeshPolicy !== undefined &&
+    options.integratedMeshPolicy !== 'as-3d-object'
+  ) {
+    throw new TileConversionError(
+      'I3S_LAYER_TYPE_POLICY_INVALID',
+      'Unknown IntegratedMesh conversion policy'
+    );
+  }
   const reference = options.spatialContext.spatialReference;
   const height =
     reference.targetHeightReference === 'native'
@@ -47,28 +77,52 @@ export function createI3SMeshConversionCodec<TInspection = unknown>(
       'I3S_MESH_FRAME_UNSUPPORTED',
       'I3S mesh authoring requires resolved ECEF coordinates and ellipsoidal heights'
     );
+  let objectIdOffset = 0;
   return {
     /** Places a source mesh in ECEF and authors one layer without modifying source arrays. */
     async *convert(resource, _inspection, signal) {
       signal?.throwIfAborted();
+      if (
+        resource.sourceLayerType === 'IntegratedMesh' &&
+        options.integratedMeshPolicy !== 'as-3d-object'
+      ) {
+        throw new TileConversionError(
+          'I3S_LAYER_TYPE_CHANGE_REQUIRED',
+          'IntegratedMesh to 3DObject conversion requires integratedMeshPolicy=as-3d-object'
+        );
+      }
       const mesh = validateMeshGeometry(resource.mesh, true);
       const positions = mesh.attributes.POSITION.value;
-      mesh.attributes.POSITION = {
-        value: options.spatialContext.transformPositions(positions),
-        size: 3
-      };
-      if (mesh.attributes.NORMAL)
-        mesh.attributes.NORMAL = {
-          value: options.spatialContext.transformNormals(mesh.attributes.NORMAL.value, positions),
-          size: 3
-        };
+      const context = options.spatialContext;
+      const transformed =
+        'transformGeometryAsync' in context
+          ? await context.transformGeometryAsync(
+              positions,
+              mesh.attributes.NORMAL?.value,
+              resource.normalReferenceFrame ?? options.normalReferenceFrame
+            )
+          : {
+              positions: context.transformPositions(positions),
+              normals: mesh.attributes.NORMAL
+                ? context.transformNormals(mesh.attributes.NORMAL.value, positions)
+                : undefined
+            };
+      signal?.throwIfAborted();
+      mesh.attributes.POSITION = {value: transformed.positions, size: 3};
+      if (mesh.attributes.NORMAL) mesh.attributes.NORMAL = {value: transformed.normals!, size: 3};
       let layer: EncodedI3SMeshLayer;
       try {
-        layer = encodeI3SMeshLayer(mesh, {
+        await preloadI3SMeshCompression();
+        const writerOptions = {
           ...options,
           material: resource.material,
-          features: resource.features
-        });
+          features: resource.features,
+          objectIdOffset
+        };
+        layer =
+          options.draco === false
+            ? encodeI3SMeshLayer(mesh, writerOptions)
+            : await encodeI3SMeshLayerWithDraco(mesh, writerOptions, options.dracoLibraryOptions);
       } catch (error) {
         throw new TileConversionError(
           'I3S_MESH_PROFILE_UNSUPPORTED',
@@ -76,11 +130,24 @@ export function createI3SMeshConversionCodec<TInspection = unknown>(
         );
       }
       signal?.throwIfAborted();
-      yield {id: resource.id, ...layer};
+      objectIdOffset +=
+        resource.features?.batches.reduce((total, batch) => total + batch.data.numRows, 0) ?? 1;
+      yield {id: resource.id, ...layer, sourceLayerType: resource.sourceLayerType};
     },
     /** Reports measured precision and explicitly authorized integer representation changes. */
     async validateOutput(resource) {
       return [
+        ...(resource.sourceLayerType === 'IntegratedMesh'
+          ? [
+              {
+                code: 'I3S_LAYER_TYPE_CHANGED',
+                message:
+                  'Explicitly authored IntegratedMesh geometry as I3S 1.7 3DObject; integrated surface layer semantics and source LOD are not preserved',
+                severity: 'warning' as const,
+                resourceId: resource.id
+              }
+            ]
+          : []),
         ...(resource.maximumPositionError > 0
           ? [
               {
@@ -104,7 +171,7 @@ export function createI3SMeshConversionCodec<TInspection = unknown>(
 
 /** Atomic bounded output for one authored I3S layer. */
 export interface SingleMeshI3SSink extends TileConversionSink<I3SMeshConversionResource> {
-  /** Compressed archive-relative files visible only after successful finalization. */
+  /** Archive-relative geometry, metadata and images visible only after successful finalization. */
   getFiles(): readonly BrowserTileConversionFile[];
 }
 
@@ -128,7 +195,18 @@ export function createSingleMeshI3SSink(options: {
         );
       state = 'writing';
       for (const [resourceId, bytes] of Object.entries(resource.files))
-        await memory.write({resourceId, parts: [bytes], contentType: 'application/gzip'}, signal);
+        await memory.write(
+          {
+            resourceId,
+            parts: [bytes],
+            contentType: resourceId.endsWith('.png')
+              ? 'image/png'
+              : resourceId.endsWith('.jpg')
+                ? 'image/jpeg'
+                : 'application/gzip'
+          },
+          signal
+        );
       state = 'written';
     },
     /** Commits a complete single-layer result. */