@loaders.gl/3d-tiles 4.0.0-alpha.7 → 4.0.0-alpha.8

package/src/lib/parsers/parse-3d-tile-point-cloud.ts

@@ -14,13 +14,14 @@ import {normalize3DTileNormalAttribute} from './helpers/normalize-3d-tile-normal
 import {normalize3DTilePositionAttribute} from './helpers/normalize-3d-tile-positions';
 import {Tiles3DLoaderOptions} from '../../tiles-3d-loader';
 import {LoaderContext} from '@loaders.gl/loader-utils';
+import {Tiles3DTileContent} from '../../types';
 
 export async function parsePointCloud3DTile(
-  tile,
+  tile: Tiles3DTileContent,
   arrayBuffer: ArrayBuffer,
   byteOffset: number,
-  options: Tiles3DLoaderOptions,
-  context: LoaderContext
+  options?: Tiles3DLoaderOptions,
+  context?: LoaderContext
 ): Promise<number> {
   byteOffset = parse3DTileHeaderSync(tile, arrayBuffer, byteOffset);
   byteOffset = parse3DTileTablesHeaderSync(tile, arrayBuffer, byteOffset);
@@ -39,7 +40,7 @@ export async function parsePointCloud3DTile(
   return byteOffset;
 }
 
-function initializeTile(tile): void {
+function initializeTile(tile: Tiles3DTileContent): void {
   // Initialize point cloud tile defaults
   tile.attributes = {
     positions: null,
@@ -53,7 +54,7 @@ function initializeTile(tile): void {
   tile.isOctEncoded16P = false;
 }
 
-function parsePointCloudTables(tile): {
+function parsePointCloudTables(tile: Tiles3DTileContent): {
   featureTable: Tile3DFeatureTable;
   batchTable: Tile3DBatchTable | null;
 } {
@@ -77,10 +78,16 @@ function parsePointCloudTables(tile): {
 }
 
 function parsePositions(
-  tile,
+  tile: Tiles3DTileContent,
   featureTable: Tile3DFeatureTable,
-  options: Tiles3DLoaderOptions
+  options: Tiles3DLoaderOptions | undefined
 ): void {
+  tile.attributes = tile.attributes || {
+    positions: null,
+    colors: null,
+    normals: null,
+    batchIds: null
+  };
   if (!tile.attributes.positions) {
     if (featureTable.hasProperty('POSITION')) {
       tile.attributes.positions = featureTable.getPropertyArray('POSITION', GL.FLOAT, 3);
@@ -117,7 +124,17 @@ function parsePositions(
   }
 }
 
-function parseColors(tile, featureTable: Tile3DFeatureTable, batchTable: Tile3DBatchTable): void {
+function parseColors(
+  tile: Tiles3DTileContent,
+  featureTable: Tile3DFeatureTable,
+  batchTable: Tile3DBatchTable
+): void {
+  tile.attributes = tile.attributes || {
+    positions: null,
+    colors: null,
+    normals: null,
+    batchIds: null
+  };
   if (!tile.attributes.colors) {
     let colors = null;
     if (featureTable.hasProperty('RGBA')) {
@@ -138,7 +155,13 @@ function parseColors(tile, featureTable: Tile3DFeatureTable, batchTable: Tile3DB
   }
 }
 
-function parseNormals(tile, featureTable: Tile3DFeatureTable): void {
+function parseNormals(tile: Tiles3DTileContent, featureTable: Tile3DFeatureTable): void {
+  tile.attributes = tile.attributes || {
+    positions: null,
+    colors: null,
+    normals: null,
+    batchIds: null
+  };
   if (!tile.attributes.normals) {
     let normals = null;
     if (featureTable.hasProperty('NORMAL')) {
@@ -152,7 +175,10 @@ function parseNormals(tile, featureTable: Tile3DFeatureTable): void {
   }
 }
 
-function parseBatchIds(tile, featureTable: Tile3DFeatureTable): Tile3DBatchTable | null {
+function parseBatchIds(
+  tile: Tiles3DTileContent,
+  featureTable: Tile3DFeatureTable
+): Tile3DBatchTable | null {
   let batchTable: Tile3DBatchTable | null = null;
   if (!tile.batchIds && featureTable.hasProperty('BATCH_ID')) {
     tile.batchIds = featureTable.getPropertyArray('BATCH_ID', GL.UNSIGNED_SHORT, 1);
@@ -171,11 +197,11 @@ function parseBatchIds(tile, featureTable: Tile3DFeatureTable): Tile3DBatchTable
 
 // eslint-disable-next-line complexity
 async function parseDraco(
-  tile,
+  tile: Tiles3DTileContent,
   featureTable: Tile3DFeatureTable,
   batchTable,
-  options: Tiles3DLoaderOptions,
-  context: LoaderContext
+  options?: Tiles3DLoaderOptions,
+  context?: LoaderContext
 ) {
   let dracoBuffer;
   let dracoFeatureTableProperties;
@@ -197,7 +223,10 @@ async function parseDraco(
       throw new Error('Draco properties, byteOffset, and byteLength must be defined');
     }
 
-    dracoBuffer = tile.featureTableBinary.slice(dracoByteOffset, dracoByteOffset + dracoByteLength);
+    dracoBuffer = (tile.featureTableBinary || []).slice(
+      dracoByteOffset,
+      dracoByteOffset + dracoByteLength
+    );
 
     tile.hasPositions = Number.isFinite(dracoFeatureTableProperties.POSITION);
     tile.hasColors =
@@ -225,16 +254,19 @@ async function parseDraco(
 
 // eslint-disable-next-line complexity, max-statements
 export async function loadDraco(
-  tile,
+  tile: Tiles3DTileContent,
   dracoData,
-  options: Tiles3DLoaderOptions,
-  context: LoaderContext
-) {
+  options?: Tiles3DLoaderOptions,
+  context?: LoaderContext
+): Promise<void> {
+  if (!context) {
+    return;
+  }
   const {parse} = context;
   const dracoOptions = {
     ...options,
     draco: {
-      ...options.draco,
+      ...options?.draco,
       extraAttributes: dracoData.batchTableProperties || {}
     }
   };

package/src/lib/parsers/parse-3d-tile.ts

@@ -9,15 +9,21 @@ import {parseBatchedModel3DTile} from './parse-3d-tile-batched-model';
 import {parseInstancedModel3DTile} from './parse-3d-tile-instanced-model';
 import {parseComposite3DTile} from './parse-3d-tile-composite';
 import {parseGltf3DTile} from './parse-3d-tile-gltf';
+import {LoaderContext} from '@loaders.gl/loader-utils';
+import {Tiles3DLoaderOptions} from '../../tiles-3d-loader';
+import {Tiles3DTileContent} from '../../types';
 
 // Extracts
-export async function parse3DTile(arrayBuffer, byteOffset = 0, options, context, tile = {}) {
-  // @ts-expect-error
+export async function parse3DTile(
+  arrayBuffer: ArrayBuffer,
+  byteOffset = 0,
+  options: Tiles3DLoaderOptions | undefined,
+  context: LoaderContext | undefined,
+  tile: Tiles3DTileContent = {}
+) {
   tile.byteOffset = byteOffset;
-  // @ts-expect-error
   tile.type = getMagicString(arrayBuffer, byteOffset);
 
-  // @ts-expect-error
   switch (tile.type) {
     case TILE3D_TYPE.COMPOSITE:
       // Note: We pass this function as argument so that embedded tiles can be parsed recursively
@@ -43,7 +49,6 @@ export async function parse3DTile(arrayBuffer, byteOffset = 0, options, context,
       return await parsePointCloud3DTile(tile, arrayBuffer, byteOffset, options, context);
 
     default:
-      // @ts-expect-error
       throw new Error(`3DTileLoader: unknown type ${tile.type}`); // eslint-disable-line
   }
 }

package/src/tiles-3d-loader.ts

@@ -8,6 +8,7 @@ import {TILESET_TYPE, LOD_METRIC_TYPE} from '@loaders.gl/tiles';
 import {VERSION} from './lib/utils/version';
 import {parse3DTile} from './lib/parsers/parse-3d-tile';
 import {normalizeTileHeaders} from './lib/parsers/parse-3d-tile-header';
+import {Tiles3DTilesetJSON, Tiles3DTilesetJSONPostprocessed} from './types';
 
 export type Tiles3DLoaderOptions = LoaderOptions &
   // GLTFLoaderOptions & - TODO not yet exported
@@ -58,9 +59,7 @@ async function parse(data, options: Tiles3DLoaderOptions = {}, context?: LoaderC
     isTileset = loaderOptions.isTileset;
   }
 
-  return (await isTileset)
-    ? parseTileset(data, options, context)
-    : parseTile(data, options, context);
+  return isTileset ? parseTileset(data, options, context) : parseTile(data, options, context);
 }
 
 /** Parse a tileset */
@@ -68,25 +67,24 @@ async function parseTileset(
   data: ArrayBuffer,
   options?: Tiles3DLoaderOptions,
   context?: LoaderContext
-) {
-  const tilesetJson = JSON.parse(new TextDecoder().decode(data));
-
-  // eslint-disable-next-line no-use-before-define
-  tilesetJson.loader = options?.loader || Tiles3DLoader;
-  tilesetJson.url = context?.url || '';
-  tilesetJson.queryString = context?.queryString || '';
-
-  // base path that non-absolute paths in tileset are relative to.
-  tilesetJson.basePath = getBaseUri(tilesetJson);
-  // TODO - check option types in normalizeTileHeaders
-  tilesetJson.root = await normalizeTileHeaders(tilesetJson, options || {});
+): Promise<Tiles3DTilesetJSONPostprocessed> {
+  const tilesetJson: Tiles3DTilesetJSON = JSON.parse(new TextDecoder().decode(data));
 
-  tilesetJson.type = TILESET_TYPE.TILES3D;
-
-  tilesetJson.lodMetricType = LOD_METRIC_TYPE.GEOMETRIC_ERROR;
-  tilesetJson.lodMetricValue = tilesetJson.root?.lodMetricValue || 0;
-
-  return tilesetJson;
+  const tilesetUrl = context?.url || '';
+  const basePath = getBaseUri(tilesetUrl);
+  const normalizedRoot = await normalizeTileHeaders(tilesetJson, basePath, options || {});
+  const tilesetJsonPostprocessed: Tiles3DTilesetJSONPostprocessed = {
+    ...tilesetJson,
+    loader: Tiles3DLoader,
+    url: tilesetUrl,
+    queryString: context?.queryString || '',
+    basePath,
+    root: normalizedRoot || tilesetJson.root,
+    type: TILESET_TYPE.TILES3D,
+    lodMetricType: LOD_METRIC_TYPE.GEOMETRIC_ERROR,
+    lodMetricValue: tilesetJson.root?.geometricError || 0
+  };
+  return tilesetJsonPostprocessed;
 }
 
 /** Parse a tile */
@@ -106,6 +104,6 @@ async function parseTile(
 }
 
 /** Get base name */
-function getBaseUri(tileset) {
-  return path.dirname(tileset.url);
+function getBaseUri(tilesetUrl: string): string {
+  return path.dirname(tilesetUrl);
 }

package/src/types.ts

@@ -1,5 +1,7 @@
 import type {GLTFPostprocessed} from '@loaders.gl/gltf';
+import {LoaderWithParser} from '@loaders.gl/loader-utils';
 import {Matrix4, Vector3} from '@math.gl/core';
+import {TILESET_TYPE, LOD_METRIC_TYPE, TILE_TYPE, TILE_REFINEMENT} from '@loaders.gl/tiles';
 
 export type FeatureTableJson = {
   [key: string]: any[];
@@ -35,20 +37,259 @@ export type GLTFHeader = {
   featureTableJsonByteLength: number;
 };
 
-export type Node3D = {
-  boundingVolume: BoundingVolume;
-  children: any;
-  geometricError: number;
-  content?: {
-    uri: string;
-    boundingVolume: BoundingVolume;
+/**
+ * A 3D Tiles tileset JSON
+ * https://github.com/CesiumGS/3d-tiles/tree/main/specification#property-reference
+ */
+export type Tiles3DTilesetJSON = {
+  /** Metadata about the entire tileset.
+   * https://github.com/CesiumGS/3d-tiles/tree/main/specification#asset
+   */
+  asset: {
+    /** The 3D Tiles version. The version defines the JSON schema for the tileset JSON and the base set of tile formats. */
+    version: string;
+    /** Application-specific version of this tileset, e.g., for when an existing tileset is updated. */
+    tilesetVersion?: string;
+    /** Dictionary object with extension-specific objects. */
+    extensions?: object;
+    /** Application-specific data. */
+    extras?: any;
+    /** Not mentioned in 1.0 spec but some tilesets contain this option */
+    gltfUpAxis?: string;
   };
+  /** A dictionary object of metadata about per-feature properties. */
+  properties?: Record<string, TilesetProperty>;
+  /** The error, in meters, introduced if this tileset is not rendered. At runtime, the geometric error is used to compute screen space error (SSE), i.e., the error measured in pixels. */
+  geometricError: number;
+  /** A tile in a 3D Tiles tileset. */
+  root: Tiles3DTileJSON;
+  /** Names of 3D Tiles extensions used somewhere in this tileset. */
+  extensionsUsed?: string[];
+  /** Names of 3D Tiles extensions required to properly load this tileset. */
+  extensionsRequired?: string[];
+  /** Dictionary object with extension-specific objects. */
+  extensions?: object;
+  /** Application-specific data. */
+  extras?: any;
+};
+
+/** TilesetJSON postprocessed by Tiles3DLoader */
+export type Tiles3DTilesetJSONPostprocessed = Omit<Tiles3DTilesetJSON, 'root'> & {
+  /**
+   * Loader used
+   * @deprecated
+   */
+  loader: LoaderWithParser;
+  /** URL used to load a tileset resource */
+  url: string;
+  /** HTTP request query string */
+  queryString: string;
+  /** base path that non-absolute paths in tileset are relative to. */
+  basePath: string;
+  /** tileset type */
+  type: TILESET_TYPE.TILES3D;
+  /** LOD metric type */
+  lodMetricType: LOD_METRIC_TYPE.GEOMETRIC_ERROR;
+  /** LOD metric value */
+  lodMetricValue: number;
+  /** Postprocessed root */
+  root: Tiles3DTileJSONPostprocessed;
 };
 
-export type BoundingVolume = {
+/**
+ * A tile in a 3D Tiles tileset.
+ * https://github.com/CesiumGS/3d-tiles/tree/main/specification#tile
+ */
+export type Tiles3DTileJSON = {
+  /** A bounding volume that encloses a tile or its content. */
+  boundingVolume: Tile3DBoundingVolume;
+  /** A bounding volume that encloses a tile or its content. */
+  viewerRequestVolume?: object;
+  /** The error, in meters, introduced if this tile is rendered and its children are not. At runtime, the geometric error is used to compute screen space error (SSE), i.e., the error measured in pixels. */
+  geometricError: number;
+  /**
+   * Specifies if additive or replacement refinement is used when traversing the tileset for rendering. This property is required for the root tile of a tileset; it is optional for all other tiles.
+   * The default is to inherit from the parent tile.
+   */
+  refine?: string;
+  /** A floating-point 4x4 affine transformation matrix, stored in column-major order, that transforms the tile's content */
+  transform?: number[];
+  /** Metadata about the tile's content and a link to the content. */
+  content?: Tiles3DTileContentJSON;
+  /** An array of objects that define child tiles. */
+  children: Tiles3DTileJSON[];
+  /** Dictionary object with extension-specific objects. */
+  extensions?: object;
+  /** Application-specific data. */
+  extras?: any;
+
+  /** 3DTiles v1.1 properties
+   * https://github.com/CesiumGS/3d-tiles/blob/draft-1.1/specification/schema/tile.schema.json
+   */
+  /** This object allows a tile to be implicitly subdivided. Tile and content availability and metadata is stored in subtrees which are referenced externally. */
+  implicitTiling?: ImplicitTilingData;
+};
+
+export type Tiles3DTileJSONPostprocessed = Omit<Tiles3DTileJSON, 'refine' | 'children'> & {
+  /** Unique ID */
+  id?: string;
+  /** Content full URL */
+  contentUrl?: string;
+  /** LOD metric type */
+  lodMetricType?: LOD_METRIC_TYPE.GEOMETRIC_ERROR;
+  /** LOD metric value */
+  lodMetricValue?: number;
+  /** Duplicate of transform */
+  transformMatrix?: number[];
+  /** Type of tile */
+  type?: TILE_TYPE | string;
+  /**
+   * Specifies if additive or replacement refinement is used when traversing the tileset for rendering. This property is required for the root tile of a tileset; it is optional for all other tiles.
+   * The default is to inherit from the parent tile.
+   */
+  refine?: TILE_REFINEMENT | string;
+  /** An array of objects that define child tiles. */
+  children: Tiles3DTileJSONPostprocessed[];
+};
+
+/** Metadata about the tile's content and a link to the content. */
+export type Tiles3DTileContentJSON = {
+  /** A uri that points to the tile's content. When the uri is relative, it is relative to the referring tileset JSON file. */
+  uri: string;
+  /** url doesn't allign the spec but we support it same way as uri */
+  url?: string;
+  /** A bounding volume that encloses a tile or its content. At least one bounding volume property is required. Bounding volumes include box, region, or sphere. */
+  boundingVolume?: Tile3DBoundingVolume;
+  /** Dictionary object with extension-specific objects. */
+  extensions?: object;
+  /** Application-specific data. */
+  extras?: any;
+};
+
+/** A bounding volume that encloses a tile or its content.
+ * https://github.com/CesiumGS/3d-tiles/tree/main/specification#bounding-volume
+ */
+export type Tile3DBoundingVolume = {
+  /** An array of 12 numbers that define an oriented bounding box. The first three elements define the x, y, and z values for the center of the box.
+   * The next three elements (with indices 3, 4, and 5) define the x axis direction and half-length. The next three elements (indices 6, 7, and 8) define
+   * the y axis direction and half-length. The last three elements (indices 9, 10, and 11) define the z axis direction and half-length. */
   box?: number[];
+  /** An array of four numbers that define a bounding sphere. The first three elements define the x, y, and z values for the center of the sphere.
+   * The last element (with index 3) defines the radius in meters. */
   sphere?: number[];
+  /** An array of six numbers that define a bounding geographic region in EPSG:4979 coordinates with the order [west, south, east, north, minimum height, maximum height].
+   * Longitudes and latitudes are in radians, and heights are in meters above (or below) the WGS84 ellipsoid. */
   region?: number[];
+  /** Dictionary object with extension-specific objects. */
+  extensions?: object;
+  /** Application-specific data. */
+  extras?: any;
+};
+
+/**
+ * A dictionary object of metadata about per-feature properties.
+ * https://github.com/CesiumGS/3d-tiles/tree/main/specification#properties
+ */
+export type TilesetProperty = {
+  /** The maximum value of this property of all the features in the tileset. */
+  maximum: number;
+  /** The minimum value of this property of all the features in the tileset. */
+  minimum: number;
+  /** Dictionary object with extension-specific objects. */
+  extensions?: object;
+  /** Application-specific data. */
+  extras?: any;
+};
+
+export type Tiles3DTileContent = {
+  /** Common properties */
+  byteOffset?: number;
+  type?: string;
+  featureIds?: null;
+
+  /** 3DTile header */
+  magic?: number;
+  version?: number;
+  byteLength?: number;
+
+  /** 3DTile tables header */
+  header?: {
+    featureTableJsonByteLength?: number;
+    featureTableBinaryByteLength?: number;
+    batchTableJsonByteLength?: number;
+    batchTableBinaryByteLength?: number;
+    batchLength?: number;
+  };
+
+  /** 3DTile tables */
+  featureTableJson?:
+    | {
+        BATCH_LENGTH?: number;
+      }
+    | Record<string, any>;
+  featureTableBinary?: Uint8Array;
+  batchTableJson?: Record<string, (string | number)[]>;
+  batchTableBinary?: Uint8Array;
+  rtcCenter?: number[];
+
+  /** 3DTile glTF */
+  gltfArrayBuffer?: ArrayBuffer;
+  gltfByteOffset?: number;
+  gltfByteLength?: number;
+  rotateYtoZ?: boolean;
+  gltfUpAxis?: 'x' | 'X' | 'y' | 'Y' | 'z' | 'Z';
+  gltfUrl?: string;
+  gpuMemoryUsageInBytes?: number;
+  gltf?: GLTFPostprocessed;
+
+  /** For Composite tiles */
+  tilesLength?: number;
+  tiles?: Tiles3DTileContent[];
+
+  /** For Instances model and Pointcloud tiles */
+  featuresLength?: number;
+
+  /** For Instanced model tiles */
+  gltfFormat?: number;
+  eastNorthUp?: boolean;
+  normalUp?: number[];
+  normalRight?: number[];
+  hasCustomOrientation?: boolean;
+  octNormalUp?: number[];
+  octNormalRight?: number[];
+  instances?: {
+    modelMatrix: Matrix4;
+    batchId: number;
+  }[];
+
+  /** For Pointcloud tiles */
+  attributes?: {
+    positions: null | number[];
+    colors:
+      | null
+      | number[]
+      | {type: number; value: Uint8ClampedArray; size: number; normalized: boolean};
+    normals: null | number[] | {type: number; size: number; value: Float32Array};
+    batchIds: null | number[];
+  };
+  constantRGBA?: number[];
+  isQuantized?: boolean;
+  isTranslucent?: boolean;
+  isRGB565?: boolean;
+  isOctEncoded16P?: boolean;
+  pointsLength?: number;
+  pointCount?: number;
+  batchIds?: number[];
+  hasPositions?: boolean;
+  hasColors?: boolean;
+  hasNormals?: boolean;
+  hasBatchIds?: boolean;
+  quantizedVolumeScale?: Vector3;
+  quantizedVolumeOffset?: Vector3;
+  quantizedRange?: number;
+  isQuantizedDraco?: boolean;
+  octEncodedRange?: number;
+  isOctEncodedDraco?: boolean;
 };
 
 /**
@@ -92,14 +333,27 @@ type BufferView = {
 /**
  * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling
  */
-export type ImplicitTilingExtension = {
-  subdivisionScheme: 'QUADTREE' | 'OCTREE';
+export type ImplicitTilingExensionData = ImplicitTilingData & {
   maximumLevel?: number;
-  availableLevels: number;
-  subtreeLevels: number;
-  subtrees: SubtreeUri;
 };
 
-type SubtreeUri = {
-  uri: string;
+/** 3DTiles v1.1 types */
+
+/**
+ * This object allows a tile to be implicitly subdivided. Tile and content availability and metadata is stored in subtrees which are referenced externally.
+ * https://github.com/CesiumGS/3d-tiles/blob/draft-1.1/specification/schema/tile.implicitTiling.schema.json
+ * */
+type ImplicitTilingData = {
+  /** A string describing the subdivision scheme used within the tileset. */
+  subdivisionScheme: 'QUADTREE' | 'OCTREE' | string;
+  /** The number of distinct levels in each subtree. For example, a quadtree with `subtreeLevels = 2` will have subtrees with 5 nodes (one root and 4 children). */
+  subtreeLevels: number;
+  /** The numbers of the levels in the tree with available tiles. */
+  availableLevels: number;
+  /** An object describing the location of subtree files. */
+  subtrees: {
+    /** A template URI pointing to subtree files. A subtree is a fixed-depth (defined by `subtreeLevels`) portion of the tree to keep memory use bounded.
+     * The URI of each file is substituted with the subtree root's global level, x, and y. For subdivision scheme `OCTREE`, z shall also be given. Relative paths are relative to the tileset JSON. */
+    uri: string;
+  };
 };