@loaders.gl/tiles 5.0.0-alpha.11 → 5.0.0-alpha.12

package/src/point-cloud-tile-source-loader-types.ts

@@ -0,0 +1,53 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {CoreAPI, SourceLoader} from '@loaders.gl/loader-utils';
+import type {PointCloudTileSource} from './point-cloud-tile-source';
+import type {
+  PointCloudTileSourceInput,
+  PointCloudTileSourceOptions
+} from './point-cloud-tile-source-types';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Loads the optional authoring runtime through an explicit package subpath. */
+async function preloadPointCloudTileSource(): Promise<
+  typeof import('./point-cloud-tile-source-loader').PointCloudTileSourceLoaderWithParser
+> {
+  const {PointCloudTileSourceLoaderWithParser} = await import(
+    '@loaders.gl/tiles/point-cloud-tile-source-loader'
+  );
+  return PointCloudTileSourceLoaderWithParser;
+}
+
+/** Metadata-only loader for creating an additive point source from decoded Mesh/Arrow input. */
+export const PointCloudTileSourceLoader = {
+  dataType: null as unknown as PointCloudTileSource,
+  batchType: null as never,
+  name: 'PointCloudTiler',
+  id: 'point-cloud-tiler',
+  module: 'tiles',
+  version: VERSION,
+  extensions: [],
+  mimeTypes: [],
+  type: 'point-cloud',
+  fromUrl: false,
+  fromBlob: false,
+  testURL: () => false,
+  options: {pointCloudTiler: {}},
+  defaultOptions: {pointCloudTiler: {}},
+  preload: preloadPointCloudTileSource,
+  /** Direct construction requires the runtime rather than this metadata export. */
+  createDataSource(
+    _input: PointCloudTileSourceInput | string | Blob,
+    _options: PointCloudTileSourceOptions = {},
+    _coreApi?: CoreAPI
+  ): PointCloudTileSource {
+    throw new Error(
+      'PointCloudTileSourceLoader requires preload() or @loaders.gl/tiles/point-cloud-tile-source-loader'
+    );
+  }
+} as const satisfies SourceLoader<PointCloudTileSource>;

package/src/point-cloud-tile-source-loader.ts

@@ -0,0 +1,32 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {CoreAPI, SourceLoader} from '@loaders.gl/loader-utils';
+import {PointCloudTileSource} from '@loaders.gl/tiles/point-cloud-tile-source';
+import {PointCloudTileSourceLoader} from './point-cloud-tile-source-loader-types';
+import type {
+  PointCloudTileSourceInput,
+  PointCloudTileSourceOptions
+} from './point-cloud-tile-source-types';
+
+const {
+  preload: _preload,
+  createDataSource: _createDataSource,
+  ...metadata
+} = PointCloudTileSourceLoader;
+
+/** Parser-bearing source factory for decoded point Mesh/Arrow data. */
+export const PointCloudTileSourceLoaderWithParser = {
+  ...metadata,
+  /** Creates a native-coordinate source with deferred child indexing. */
+  createDataSource(
+    input: PointCloudTileSourceInput | string | Blob,
+    options: PointCloudTileSourceOptions = {},
+    coreApi?: CoreAPI
+  ): PointCloudTileSource {
+    if (typeof input === 'string' || input instanceof Blob)
+      throw new Error('PointCloudTileSourceLoader requires decoded Mesh/Arrow input');
+    return new PointCloudTileSource(input, options, coreApi);
+  }
+} as const satisfies SourceLoader<PointCloudTileSource>;

package/src/point-cloud-tile-source-types.ts

@@ -0,0 +1,20 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DataSourceOptions} from '@loaders.gl/loader-utils';
+import type {Mesh, MeshArrowTable} from '@loaders.gl/schema';
+import type {PointCloudTilerOptions} from '@loaders.gl/schema-utils';
+import type {TilesetSpatialReference} from './spatial/spatial-types';
+
+/** Decoded points supplied to the dynamic point-cloud source. */
+export type PointCloudTileSourceInput = Mesh | MeshArrowTable;
+
+/** Options for native-coordinate, additive dynamic point tiling. */
+export type PointCloudTileSourceOptions = DataSourceOptions & {
+  /** Point indexing, output and lifetime controls. No CRS is inferred. */
+  pointCloudTiler?: PointCloudTilerOptions & {
+    /** Spatial metadata for the input coordinates; retained without reprojection. */
+    readonly spatialReference?: TilesetSpatialReference;
+  };
+};

package/src/point-cloud-tile-source.ts

@@ -0,0 +1,112 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {DataSource, type CoreAPI} from '@loaders.gl/loader-utils';
+import {
+  PointCloudTiler,
+  convertMeshToTable,
+  type PointCloudTilerNode
+} from '@loaders.gl/schema-utils';
+import type {
+  PointCloudTileContent,
+  PointCloudTileHeader,
+  PointCloudTilesetSource
+} from './point-cloud/types';
+import type {
+  PointCloudTileSourceInput,
+  PointCloudTileSourceOptions
+} from './point-cloud-tile-source-types';
+
+/**
+ * Dynamic counterpart to vector table tiling, usable by PointCloudTileset and converter traversal.
+ * Each point belongs to one additive node. It retains native coordinates and explicit CRS metadata.
+ * Geometry stays in memory; output tiles are gathered on request and are not cached by this source.
+ */
+export class PointCloudTileSource
+  extends DataSource<null, PointCloudTileSourceOptions>
+  implements PointCloudTilesetSource<null, PointCloudTileSourceOptions>
+{
+  /** Resolves after the root is indexed. */
+  readonly ready: Promise<void>;
+  /** Whether root indexing has completed successfully. */
+  isReady = false;
+  /** Shared portable index and ownership implementation. */
+  private readonly tiler: PointCloudTiler;
+
+  /** Creates a source from decoded points, without fetching or reprojecting input. */
+  constructor(
+    input: PointCloudTileSourceInput,
+    options: PointCloudTileSourceOptions = {},
+    coreApi?: CoreAPI
+  ) {
+    super(null, options, {pointCloudTiler: {}}, coreApi);
+    this.tiler = new PointCloudTiler(input, options.pointCloudTiler);
+    this.ready = this.tiler.getRootNode().then(() => {
+      this.isReady = true;
+    });
+    this.ready.catch(() => {});
+  }
+
+  /** Waits for one shared indexing operation. */
+  async initialize(): Promise<void> {
+    await this.ready;
+    await this.tiler.getRootNode();
+  }
+
+  /** Reports exact source count and the additive ownership contract. */
+  async getMetadata(): Promise<{pointCount: number; refinement: 'ADD'}> {
+    await this.initialize();
+    return {pointCount: this.tiler.pointCount, refinement: 'ADD'};
+  }
+
+  /** Returns the sampled root and its native bounds. */
+  async getRootTile(): Promise<PointCloudTileHeader> {
+    return this.createHeader(await this.tiler.getRootNode());
+  }
+
+  /** Discovers only the requested node's immediate children. */
+  async getChildren(tile: PointCloudTileHeader): Promise<PointCloudTileHeader[]> {
+    return (await this.tiler.getChildNodes(tile.id)).map(node => this.createHeader(node));
+  }
+
+  /** Gathers the requested point rows into a fresh Arrow tile, preserving attribute types. */
+  async loadTileContent(tile: PointCloudTileHeader): Promise<PointCloudTileContent | null> {
+    const mesh = await this.tiler.getTileMesh(tile.id);
+    if (!mesh.header!.vertexCount) return null;
+    return {
+      data: convertMeshToTable(mesh, 'arrow-table'),
+      pointCount: mesh.header!.vertexCount,
+      cartographicOrigin: [0, 0, 0],
+      coordinateSystem: 'cartesian',
+      spatialReference: this.options.pointCloudTiler.spatialReference,
+      spatialBoundingVolume: this.createHeader(await this.tiler.getNodeMetadata(tile.id))
+        .boundingVolume
+    };
+  }
+
+  /** Releases the input table, attributes and index; safe to repeat. */
+  close(): void {
+    this.tiler.close();
+    this.isReady = false;
+  }
+
+  /** Creates a conservative native-coordinate header without renderer projection math. */
+  private createHeader(node: PointCloudTilerNode): PointCloudTileHeader {
+    const center = node.bounds[0].map((value, axis) => value + (node.bounds[1][axis] - value) / 2);
+    const boundingVolume = {
+      cartographicBounds: node.bounds.map(corner => [...corner]) as [number[], number[]],
+      center,
+      radius: Math.hypot(...center.map((value, axis) => node.bounds[1][axis] - value)),
+      coordinateFrame: 'cartesian' as const
+    };
+    return {
+      id: node.id,
+      level: node.level,
+      pointCount: node.pointCount,
+      geometricError: node.geometricError,
+      boundingVolume,
+      spatialBoundingVolume: boundingVolume
+    };
+  }
+}

package/src/spatial/spatial-coordinate-transformer.ts

@@ -7,6 +7,7 @@ import {Vector3} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
 import type {ReadonlyCRSDefinition} from '@math.gl/crs';
 import type {Projection} from '@math.gl/projection';
+import {ProjectionBuffer} from '@math.gl/projection/bulk';
 import {getGeoidModel, getSpatialProjectionEngine} from './spatial-resource-registry';
 import {
   normalizeCrsIdentifier,
@@ -35,6 +36,9 @@ export class SpatialCoordinateTransformer {
   /** Projection from the source CRS directly to the requested horizontal target CRS. */
   private readonly horizontalProjection?: Projection;
 
+  /** Reusable packed xyz projection for horizontal-only coordinate batches. */
+  private readonly horizontalProjectionBuffer?: ProjectionBuffer;
+
   /** Projection from the source CRS to geographic longitude, latitude, and ellipsoidal height. */
   private readonly geographicProjection?: Projection;
 
@@ -83,6 +87,12 @@ export class SpatialCoordinateTransformer {
         to: getHorizontalProjectionDefinition(spatialReference.targetCrs),
         enforceAxis: false
       });
+      if (!requiresHeightTransformation(spatialReference)) {
+        this.horizontalProjectionBuffer = new ProjectionBuffer({
+          projection: this.horizontalProjection,
+          dimension: 3
+        });
+      }
     }
 
     if (
@@ -160,12 +170,22 @@ export class SpatialCoordinateTransformer {
     return result;
   }
 
-  /** Transform a packed sequence of xyz positions, preserving the input array type only when safe. */
+  /** Transform packed xyz positions into owned Float64 storage, batching finite horizontal transforms. */
   transformPositions(positions: ArrayLike<number>): Float64Array {
     if (positions.length % 3 !== 0) {
       throw new Error('Packed spatial positions must contain a multiple of three components');
     }
     const transformedPositions = new Float64Array(positions.length);
+    if (this.horizontalProjectionBuffer) {
+      transformedPositions.set(positions);
+      // The bulk API rejects nonfinite ordinates; preserve scalar behavior for those inputs.
+      if (transformedPositions.every(Number.isFinite)) {
+        return this.horizontalProjectionBuffer.projectFlatTo(
+          transformedPositions,
+          transformedPositions
+        );
+      }
+    }
     for (let index = 0; index < positions.length; index += 3) {
       const transformed = this.transformPosition([
         Number(positions[index]),

package/src/tileset-2d.ts

@@ -2,4 +2,28 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export * from './tileset-2d/index';
+export {
+  SharedTile2DHeader,
+  Tileset2D,
+  STRATEGY_DEFAULT,
+  STRATEGY_NEVER,
+  STRATEGY_REPLACE
+} from './tileset-2d/index';
+export type {
+  Bounds,
+  GeoBoundingBox,
+  NonGeoBoundingBox,
+  TileBoundingBox,
+  TileIndex,
+  TileLoadProps,
+  ZRange,
+  Tileset2DAdapter,
+  Tileset2DTileContext,
+  Tileset2DTraversalContext,
+  Tile2DLoadDataProps,
+  RefinementStrategy,
+  RefinementStrategyFunction,
+  Tileset2DBaseProps,
+  Tileset2DProps,
+  Tile2DListener
+} from './tileset-2d/index';

package/src/tileset-3d/common/tileset-3d.ts

@@ -41,6 +41,8 @@ import {
 export type {TilesetJSON} from './tileset-source';
 
 export type Tileset3DProps = {
+  /** Format options forwarded to I3S content requests, including source-coordinate decoding. */
+  i3s?: Record<string, unknown>;
   throttleRequests?: boolean;
   maxRequests?: number;
   loadOptions?: LoaderOptions;

package/src/tileset-3d/format-3d-tiles/implicit-tiling.ts

@@ -3,9 +3,6 @@
 // Copyright vis.gl contributors
 
 import {LOD_METRIC_TYPE, TILE_REFINEMENT, TILE_TYPE} from '../../constants';
-// TypeScript's legacy `node` resolution does not inspect package `exports`, but this public
-// subpath is resolved by the package at runtime and avoids loading unrelated DGGS decoders.
-// @ts-expect-error Conditional package subpath exports require a modern module resolver.
 import {getS2DescendantIndex, getS2IndexFromToken, getS2TokenFromIndex} from '@math.gl/dggs/s2';
 import {convertS2BoundingVolumeToOBB, type S2VolumeInfo} from '../helpers/s2-bounding-volume';
 

package/src/tileset-3d/helpers/s2-bounding-volume.ts

@@ -2,9 +2,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright vis.gl contributors
 
-// TypeScript's legacy `node` resolution does not inspect package `exports`, but this public
-// subpath is resolved by the package at runtime and avoids loading unrelated DGGS decoders.
-// @ts-expect-error Conditional package subpath exports require a modern module resolver.
 import {getS2Bounds} from '@math.gl/dggs/s2';
 import {Ellipsoid, makeOBBFromRegion} from '@math.gl/geospatial';