@loaders.gl/tiles 5.0.0-alpha.5 → 5.0.0-alpha.7

package/src/spatial/tiles-3d-spatial-transformer.ts

@@ -0,0 +1,206 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {SpatialCoordinateTransformer} from './spatial-coordinate-transformer';
+import {getSpatialCoordinateFrame} from './get-spatial-coordinate-frame';
+import {Matrix4} from '@math.gl/core';
+import {Ellipsoid} from '@math.gl/geospatial';
+import type {TilesetSpatialOptions, TilesetSpatialReference} from './spatial-types';
+
+/** Structural 3D Tiles volume shape used by the source adapter. */
+export type Tiles3DSpatialBoundingVolume = {
+  box?: number[];
+  sphere?: number[];
+  region?: number[];
+  [key: string]: unknown;
+};
+
+/**
+ * Applies nonlinear CRS operations to 3D Tiles geometry bounds.
+ *
+ * Bounds are rebuilt from conservative samples. This intentionally produces an axis-aligned box
+ * in the target frame; it is safe for culling and screen-space-error calculations even when the
+ * source volume is rotated or the projection is nonlinear.
+ */
+export class Tiles3DSpatialTransformer {
+  /** Normalized reference describing the completed operation. */
+  readonly spatialReference: TilesetSpatialReference;
+  private readonly coordinateTransformer: SpatialCoordinateTransformer;
+  private readonly geographicCoordinateTransformer: SpatialCoordinateTransformer;
+
+  /** Creates a 3D Tiles transformer for a requested target CRS. */
+  constructor(spatialReference: TilesetSpatialReference, options: TilesetSpatialOptions = {}) {
+    this.coordinateTransformer = new SpatialCoordinateTransformer(spatialReference, options);
+    // 3D Tiles regions are always encoded as WGS84 longitude/latitude radians, independently
+    // of the tileset's local CRS. Build a second pipeline for that fixed source frame.
+    const geographicSpatialReference = {
+      ...spatialReference,
+      sourceCrs: 'EPSG:4326' as const,
+      targetCrs: spatialReference.targetCrs || spatialReference.sourceCrs,
+      coordinateFrame: 'geographic' as const,
+      axisOrder: 'xy' as const
+    };
+    this.geographicCoordinateTransformer = new SpatialCoordinateTransformer(
+      geographicSpatialReference,
+      options
+    );
+    this.spatialReference = spatialReference;
+  }
+
+  /** Transform packed POSITION values into the target CRS. */
+  transformPositions(positions: ArrayLike<number>): Float64Array {
+    return this.coordinateTransformer.transformPositions(positions);
+  }
+
+  /** Transform packed NORMAL values using the corresponding source positions. */
+  transformNormals(normals: ArrayLike<number>, positions: ArrayLike<number>): Float32Array {
+    return this.coordinateTransformer.transformNormals(normals, positions);
+  }
+
+  /** Rebuild a conservative target-frame volume from a source volume. */
+  transformBoundingVolume(
+    volume: Tiles3DSpatialBoundingVolume,
+    sourceTransform?: ArrayLike<number>
+  ): Tiles3DSpatialBoundingVolume {
+    const transform = sourceTransform ? new Matrix4(Array.from(sourceTransform)) : undefined;
+    const samples = volume.region
+      ? getRegionSamples(volume.region)
+      : getVolumeSamples(volume).map(sample =>
+          transform ? Array.from(transform.transformAsPoint(sample)) : sample
+        );
+    if (!samples.length) {
+      return volume;
+    }
+    const transformed = volume.region
+      ? samples.map(sample => this.transformRegionSample(sample))
+      : samples.map(sample => this.coordinateTransformer.transformPosition(sample));
+    return {box: createAxisAlignedBox(transformed)};
+  }
+
+  /** Transforms one WGS84 region sample into the selected output frame. */
+  private transformRegionSample(sample: number[]): number[] {
+    const [longitudeDegrees, latitudeDegrees, height] = sample;
+    const targetCrs = this.spatialReference.targetCrs || this.spatialReference.sourceCrs;
+    if (targetCrs && getSpatialCoordinateFrame(targetCrs) === 'geocentric') {
+      const cartesian = Ellipsoid.WGS84.cartographicToCartesian([
+        longitudeDegrees,
+        latitudeDegrees,
+        height
+      ]);
+      return Array.from(cartesian);
+    }
+    return this.geographicCoordinateTransformer.transformPosition(sample);
+  }
+}
+
+/** Samples region corners, center lines, and both height planes in degrees/meters. */
+function getRegionSamples(region: number[]): number[][] {
+  if (region.length < 6 || region.some(value => !Number.isFinite(value))) {
+    return [];
+  }
+  const [west, south, east, north, minimumHeight, maximumHeight] = region;
+  const longitudeEnd = east < west ? east + Math.PI * 2 : east;
+  const longitudes = getIntervalSamples(west, longitudeEnd);
+  const latitudes = getIntervalSamples(south, north);
+  const samples: number[][] = [];
+  for (const longitude of longitudes) {
+    for (const latitude of latitudes) {
+      for (const height of [minimumHeight, maximumHeight]) {
+        samples.push([(longitude * 180) / Math.PI, (latitude * 180) / Math.PI, height]);
+      }
+    }
+  }
+  return samples;
+}
+
+/** Includes interval endpoints and every quarter-turn where ECEF axes reach an extremum. */
+function getIntervalSamples(start: number, end: number): number[] {
+  const samples = [start, (start + end) / 2, end];
+  const angularStep = Math.PI / 2;
+  const firstCriticalIndex = Math.ceil(start / angularStep);
+  const lastCriticalIndex = Math.floor(end / angularStep);
+  for (
+    let criticalIndex = firstCriticalIndex;
+    criticalIndex <= lastCriticalIndex;
+    criticalIndex++
+  ) {
+    samples.push(criticalIndex * angularStep);
+  }
+  return samples;
+}
+
+function getVolumeSamples(volume: Tiles3DSpatialBoundingVolume): number[][] {
+  if (volume.box && volume.box.length >= 12) {
+    const center = volume.box.slice(0, 3);
+    const axes = [volume.box.slice(3, 6), volume.box.slice(6, 9), volume.box.slice(9, 12)];
+    const samples: number[][] = [];
+    for (let firstIndex = 0; firstIndex <= 4; firstIndex++) {
+      for (let secondIndex = 0; secondIndex <= 4; secondIndex++) {
+        for (let thirdIndex = 0; thirdIndex <= 4; thirdIndex++) {
+          const first = firstIndex / 2 - 1;
+          const second = secondIndex / 2 - 1;
+          const third = thirdIndex / 2 - 1;
+          samples.push([
+            center[0] + first * axes[0][0] + second * axes[1][0] + third * axes[2][0],
+            center[1] + first * axes[0][1] + second * axes[1][1] + third * axes[2][1],
+            center[2] + first * axes[0][2] + second * axes[1][2] + third * axes[2][2]
+          ]);
+        }
+      }
+    }
+    return samples;
+  }
+  if (volume.sphere && volume.sphere.length >= 4) {
+    const [x, y, z, radius] = volume.sphere;
+    const samples = [
+      [x - radius, y, z],
+      [x + radius, y, z],
+      [x, y - radius, z],
+      [x, y + radius, z],
+      [x, y, z - radius],
+      [x, y, z + radius]
+    ];
+    for (let longitudeIndex = 0; longitudeIndex < 16; longitudeIndex++) {
+      const longitude = (longitudeIndex * Math.PI * 2) / 16;
+      samples.push([x + radius * Math.cos(longitude), y + radius * Math.sin(longitude), z]);
+    }
+    return samples;
+  }
+  // Regions are already WGS84 geographic volumes. Keep them unchanged until a dedicated
+  // geographic-region adapter can account for longitude wrapping and datum semantics.
+  return [];
+}
+
+function createAxisAlignedBox(samples: number[][]): number[] {
+  const minimum = [Infinity, Infinity, Infinity];
+  const maximum = [-Infinity, -Infinity, -Infinity];
+  for (const sample of samples) {
+    for (let axis = 0; axis < 3; axis++) {
+      minimum[axis] = Math.min(minimum[axis], sample[axis]);
+      maximum[axis] = Math.max(maximum[axis], sample[axis]);
+    }
+  }
+  const padding = [
+    Math.max((maximum[0] - minimum[0]) * 0.01, 1e-9),
+    Math.max((maximum[1] - minimum[1]) * 0.01, 1e-9),
+    Math.max((maximum[2] - minimum[2]) * 0.01, 1e-9)
+  ];
+  const center = [
+    (minimum[0] + maximum[0]) / 2,
+    (minimum[1] + maximum[1]) / 2,
+    (minimum[2] + maximum[2]) / 2
+  ];
+  return [
+    ...center,
+    (maximum[0] - minimum[0]) / 2 + padding[0],
+    0,
+    0,
+    0,
+    (maximum[1] - minimum[1]) / 2 + padding[1],
+    0,
+    0,
+    0,
+    (maximum[2] - minimum[2]) / 2 + padding[2]
+  ];
+}

package/src/tileset-3d/common/indexed-archive-tileset-source.ts

@@ -3,12 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {BlobFile, HttpFile, path} from '@loaders.gl/loader-utils';
-import type {
-  CoreAPI,
-  LoaderOptions,
-  LoaderWithParser,
-  ReadableFile
-} from '@loaders.gl/loader-utils';
+import type {CoreAPI, Loader, LoaderOptions, ReadableFile} from '@loaders.gl/loader-utils';
 import type {TilesetSourceResolver} from './tileset-source';
 
 /** Options for {@link IndexedArchiveTilesetSource}. */
@@ -63,7 +58,7 @@ export class IndexedArchiveTilesetSource<ArchiveT> implements TilesetSourceResol
    */
   async loadRoot<DataT>(
     url: string,
-    loader: LoaderWithParser<DataT>,
+    loader: Loader<DataT>,
     loadOptions: LoaderOptions
   ): Promise<DataT> {
     return await this.parseArchiveResource(
@@ -83,7 +78,7 @@ export class IndexedArchiveTilesetSource<ArchiveT> implements TilesetSourceResol
    */
   async loadResource<DataT>(
     url: string,
-    loader: LoaderWithParser<DataT>,
+    loader: Loader<DataT>,
     loadOptions: LoaderOptions
   ): Promise<DataT> {
     const pathInArchive = this.resolveArchivePath(url, url);
@@ -93,7 +88,7 @@ export class IndexedArchiveTilesetSource<ArchiveT> implements TilesetSourceResol
   private async parseArchiveResource<DataT>(
     resourceUrl: string,
     pathInArchive: string,
-    loader: LoaderWithParser<DataT>,
+    loader: Loader<DataT>,
     loadOptions: LoaderOptions,
     mode?: string
   ): Promise<DataT> {

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

@@ -0,0 +1,115 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Structural subset implemented by math.gl bounding volumes used by tile renderers. */
+export type Tile3DBoundingVolume = {
+  distanceSquaredTo?(point: unknown): number;
+  intersectPlane?(plane: unknown): number;
+};
+
+/** Renderer-neutral description of one ordered tile content entry. */
+export type Tile3DContent = {
+  /** Zero-based source order, stable across loading and unloading. */
+  index: number;
+  /** Resolved content URI when declared by the tileset. */
+  uri?: string;
+  /** Tileset group index declared by this content entry. */
+  group?: number;
+  /** Normalized tile content kind, when detected. */
+  type?: string;
+  /** Decoded payload, or null while unloaded/failed. */
+  payload: unknown;
+  /** Raw content metadata reference. */
+  metadata: Record<string, unknown> | null;
+  /** Transformed content volume, with tile-volume fallback. */
+  boundingVolume: Tile3DBoundingVolume | null;
+  /** Normalized feature-id declarations for this content. */
+  featureIds: Tile3DFeatureIdSet[];
+  /** Whether the payload can currently be rendered. */
+  renderable: boolean;
+};
+
+/** Renderer-neutral feature-id declaration from a tile content payload. */
+export type Tile3DFeatureIdSet = {
+  /** Source of the feature identifiers. */
+  source: 'attribute' | 'property-table' | 'constant' | 'texture' | 'implicit';
+  /** glTF attribute name for attribute-backed identifiers. */
+  attribute?: string;
+  /** Structural-metadata property-table index. */
+  propertyTable?: number;
+  /** Constant feature identifier. */
+  constant?: number;
+  /** Texture-backed identifier declaration, when present. */
+  texture?: Record<string, unknown>;
+  /** Implicit identifier declaration, when present. */
+  implicit?: Record<string, unknown>;
+  /** Decoded identifier values, when supplied by a content loader. */
+  values?: Uint32Array | Uint16Array | Uint8Array;
+  /** Unrecognized source fields preserved for forward compatibility. */
+  details?: Record<string, unknown>;
+};
+
+/** Raw metadata references inherited by a tile and its contents. */
+export type Tile3DMetadataContext = {
+  /** Tileset-level metadata entity. */
+  tileset?: Record<string, unknown> | null;
+  /** Group metadata entity selected for the tile's primary content. */
+  group?: Record<string, unknown> | null;
+  /** All tileset groups, used to resolve a selected content entry's group. */
+  groups?: readonly (Record<string, unknown> | null)[];
+  /** Tile metadata entity. */
+  tile?: Record<string, unknown> | null;
+  /** Content metadata entity. */
+  content?: Record<string, unknown> | null;
+  /** Implicit-subtree metadata entity. */
+  subtree?: Record<string, unknown> | null;
+};
+
+/** Extracts mesh-feature declarations from a decoded glTF-like payload. */
+export function getTile3DFeatureIdSets(payload: unknown): Tile3DFeatureIdSet[] {
+  const featureIdSets: Tile3DFeatureIdSet[] = [];
+  const visited = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') {
+      return;
+    }
+    if (visited.has(value as object)) {
+      return;
+    }
+    visited.add(value as object);
+    const record = value as Record<string, any>;
+    const declarations = record.extensions?.EXT_mesh_features?.featureIds;
+    if (Array.isArray(declarations)) {
+      for (const declaration of declarations) {
+        if (!declaration || typeof declaration !== 'object') {
+          continue;
+        }
+        const source = declaration.texture
+          ? 'texture'
+          : declaration.implicit
+            ? 'implicit'
+            : declaration.attribute !== undefined
+              ? 'attribute'
+              : declaration.propertyTable !== undefined
+                ? 'property-table'
+                : 'constant';
+        featureIdSets.push({
+          source,
+          attribute: declaration.attribute,
+          propertyTable: declaration.propertyTable,
+          constant: declaration.constant,
+          texture: declaration.texture,
+          implicit: declaration.implicit,
+          values: declaration.values,
+          details: declaration
+        });
+      }
+    }
+    for (const child of Object.values(record)) {
+      visit(child);
+    }
+  };
+  visit(payload);
+  return featureIdSets;
+}