@loaders.gl/3d-tiles 4.0.0-alpha.4 → 4.0.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/3d-tiles",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
   "description": "3D Tiles, an open standard for streaming massive heterogeneous 3D geospatial datasets.",
   "license": "MIT",
   "publishConfig": {
@@ -20,9 +20,9 @@
     "point cloud",
     "pointcloud"
   ],
-  "types": "src/index.ts",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "main": "dist/es5/index.js",
+  "module": "dist/esm/index.js",
   "sideEffects": false,
   "files": [
     "src",
@@ -31,19 +31,20 @@
   ],
   "scripts": {
     "pre-build": "npm run build-bundle",
-    "build-bundle": "esbuild src/bundle.ts --bundle --outfile=dist/bundle.js"
+    "build-bundle": "esbuild src/bundle.ts --bundle --outfile=dist/dist.min.js"
   },
   "dependencies": {
-    "@loaders.gl/draco": "4.0.0-alpha.4",
-    "@loaders.gl/gltf": "4.0.0-alpha.4",
-    "@loaders.gl/loader-utils": "4.0.0-alpha.4",
-    "@loaders.gl/math": "4.0.0-alpha.4",
-    "@loaders.gl/tiles": "4.0.0-alpha.4",
+    "@loaders.gl/draco": "4.0.0-alpha.6",
+    "@loaders.gl/gltf": "4.0.0-alpha.6",
+    "@loaders.gl/loader-utils": "4.0.0-alpha.6",
+    "@loaders.gl/math": "4.0.0-alpha.6",
+    "@loaders.gl/tiles": "4.0.0-alpha.6",
     "@math.gl/core": "^3.5.1",
-    "@math.gl/geospatial": "^3.5.1"
+    "@math.gl/geospatial": "^3.5.1",
+    "long": "^5.2.1"
   },
   "peerDependencies": {
-    "@loaders.gl/core": "^3.0.0"
+    "@loaders.gl/core": "4.0.0-alpha.5"
   },
-  "gitHead": "53026061b3c8871f7e96d3a5826125cc6613bddc"
+  "gitHead": "acc1985050dfaa0f1f0c066f8da5bce7454a046c"
 }

package/src/cesium-ion-loader.ts

@@ -33,6 +33,7 @@ export const CesiumIonLoader: LoaderWithParser = {
   },
   options: {
     'cesium-ion': {
+      // @ts-expect-error
       ...Tiles3DLoader.options['3d-tiles'],
       accessToken: null
     }

package/src/index.ts

@@ -1,6 +1,7 @@
 // LOADERS
 export {Tiles3DLoader} from './tiles-3d-loader';
 export {CesiumIonLoader} from './cesium-ion-loader';
+export {Tile3DSubtreeLoader} from './tile-3d-subtree-loader';
 
 // WRITERS
 export {Tile3DWriter} from './tile-3d-writer';
@@ -12,4 +13,4 @@ export {default as Tile3DBatchTable} from './lib/classes/tile-3d-batch-table';
 // EXPERIMENTAL
 export {TILE3D_TYPE} from './lib/constants';
 export {getIonTilesetMetadata as _getIonTilesetMetadata} from './lib/ion/ion';
-export type {BatchTableJson, B3DMContent, Node3D} from './types';
+export type {FeatureTableJson, B3DMContent, Node3D, ImplicitTilingExtension} from './types';

package/src/lib/classes/{tile-3d-batch-table.js → tile-3d-batch-table.ts}

@@ -21,6 +21,16 @@ const IGNORED_PROPERTY_FIELDS = {
 
 // The size of this array equals the maximum instance count among all loaded tiles, which has the potential to be large.
 export default class Tile3DBatchTableParser {
+  json;
+  binary;
+  featureCount;
+  _extensions;
+  // Copy all top-level property fields from the json object, ignoring special fields
+  _properties;
+  _binaryProperties;
+  // TODO: hierarchy support is only partially implemented and not tested
+  _hierarchy;
+
   constructor(json, binary, featureCount, options = {}) {
     assert(featureCount >= 0);
     this.json = json || {};
@@ -49,11 +59,11 @@ export default class Tile3DBatchTableParser {
     return this.json && this.json.extensions && this.json.extensions[extensionName];
   }
 
-  memorySizeInBytes() {
+  memorySizeInBytes(): number {
     return 0;
   }
 
-  isClass(batchId, className) {
+  isClass(batchId, className: string): boolean {
     this._checkBatchId(batchId);
     assert(typeof className === 'string', className);
 
@@ -178,7 +188,7 @@ export default class Tile3DBatchTableParser {
   _checkBatchId(batchId) {
     const valid = batchId >= 0 && batchId < this.featureCount;
     if (!valid) {
-      throw new Error(`batchId not in range [0, featureCount - 1].`);
+      throw new Error('batchId not in range [0, featureCount - 1].');
     }
   }
 
@@ -191,7 +201,7 @@ export default class Tile3DBatchTableParser {
   }
 
   _initializeBinaryProperties() {
-    let binaryProperties = null;
+    let binaryProperties: Record<string, any> | null = null;
     for (const name in this._properties) {
       const property = this._properties[name];
       const binaryProperty = this._initializeBinaryProperty(name, property);

package/src/lib/classes/{tile-3d-feature-table.js → tile-3d-feature-table.ts}

@@ -6,11 +6,14 @@ import {GL, GLType} from '@loaders.gl/math';
 // Reference:
 // https://github.com/AnalyticalGraphicsInc/cesium/blob/1de96d087f0b17575eb1a3f736407b348c765d59/Source/Scene/Cesium3DTileFeatureTable.js
 export default class Tile3DFeatureTable {
+  json;
+  buffer;
+  featuresLength = 0;
+  _cachedTypedArrays = {};
+
   constructor(featureTableJson, featureTableBinary) {
     this.json = featureTableJson;
     this.buffer = featureTableBinary;
-    this.featuresLength = 0;
-    this._cachedTypedArrays = {};
   }
 
   getExtension(extensionName) {

package/src/lib/{constants.js → constants.ts}

@@ -6,7 +6,8 @@ export const TILE3D_TYPE = {
   BATCHED_3D_MODEL: 'b3dm',
   INSTANCED_3D_MODEL: 'i3dm',
   GEOMETRY: 'geom',
-  VECTOR: 'vect'
+  VECTOR: 'vect',
+  GLTF: 'glTF'
 };
 
 export const TILE3D_TYPES = Object.keys(TILE3D_TYPE);

package/src/lib/parsers/helpers/{normalize-3d-tile-colors.js → normalize-3d-tile-colors.ts}

@@ -1,7 +1,7 @@
 import {decodeRGB565, GL} from '@loaders.gl/math';
 
 /* eslint-disable complexity*/
-export function normalize3DTileColorAttribute(tile, colors, batchTable) {
+export function normalize3DTileColorAttribute(tile, colors, batchTable?) {
   // no colors defined
   if (!colors && (!tile || !tile.batchIds || !batchTable)) {
     return null;

package/src/lib/parsers/helpers/parse-3d-implicit-tiles.ts

@@ -0,0 +1,396 @@
+import type {Availability, BoundingVolume, Subtree} from '../../../types';
+import {Tile3DSubtreeLoader} from '../../../tile-3d-subtree-loader';
+import {load} from '@loaders.gl/core';
+
+import {getS2CellIdFromToken, getS2ChildCellId, getS2TokenFromCellId} from '../../utils/s2/index';
+import type {S2VolumeInfo} from '../../utils/obb/s2-corners-to-obb';
+import {convertS2BoundingVolumetoOBB} from '../../utils/obb/s2-corners-to-obb';
+import Long from 'long';
+
+const QUADTREE_DEVISION_COUNT = 4;
+const OCTREE_DEVISION_COUNT = 8;
+
+const SUBDIVISION_COUNT_MAP = {
+  QUADTREE: QUADTREE_DEVISION_COUNT,
+  OCTREE: OCTREE_DEVISION_COUNT
+};
+
+/**
+ *  S2VolumeBox is an extention of BoundingVolume of type "box"
+ */
+export type S2VolumeBox = {
+  /** BoundingVolume of type "box" has the "box" field. S2VolumeBox contains it as well. */
+  box: number[];
+  /** s2VolumeInfo provides additional info about the box - specifically the token, min and max height */
+  s2VolumeInfo: S2VolumeInfo;
+};
+
+function getChildS2VolumeBox(
+  s2VolumeBox: S2VolumeBox | undefined,
+  index: number,
+  subdivisionScheme: string
+): S2VolumeBox | undefined {
+  if (s2VolumeBox?.box) {
+    // Check if the BoundingVolume is of type "box"
+    const cellId: Long = getS2CellIdFromToken(s2VolumeBox.s2VolumeInfo.token);
+    const childCellId = getS2ChildCellId(cellId, index);
+    const childToken = getS2TokenFromCellId(childCellId);
+
+    // Clone object. Note, s2VolumeInfo is a plain object that doesn't contain any nested object.
+    // So, we can use the Spread Operator to make a shallow copy of the object.
+    const s2ChildVolumeInfo: S2VolumeInfo = {...s2VolumeBox.s2VolumeInfo};
+    s2ChildVolumeInfo.token = childToken; // replace the token with the child's one
+
+    // In case of QUADTREE the sizeZ should NOT be changed!
+    // https://portal.ogc.org/files/102132
+    // A quadtree divides space only on the x and y dimensions.
+    // It divides each tile into 4 smaller tiles where the x and y dimensions are halved.
+    // The quadtree z minimum and maximum remain unchanged.
+    switch (subdivisionScheme) {
+      case 'OCTREE':
+        const s2VolumeInfo: S2VolumeInfo = s2VolumeBox.s2VolumeInfo;
+        const delta = s2VolumeInfo.maximumHeight - s2VolumeInfo.minimumHeight;
+        const sizeZ: number = delta / 2.0; // It's a next level (a child)
+        const midZ: number = s2VolumeInfo.minimumHeight + delta / 2.0;
+        s2VolumeInfo.minimumHeight = midZ - sizeZ;
+        s2VolumeInfo.maximumHeight = midZ + sizeZ;
+        break;
+      default:
+        break;
+    }
+    const box = convertS2BoundingVolumetoOBB(s2ChildVolumeInfo);
+    const childS2VolumeBox: S2VolumeBox = {
+      box,
+      s2VolumeInfo: s2ChildVolumeInfo
+    };
+    return childS2VolumeBox;
+  }
+  return undefined;
+}
+
+/**
+ * Recursively parse implicit tiles tree
+ * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling
+ * TODO Check out do we able to use Tile3D class as return type here.
+ * @param subtree
+ * @param lodMetricValue
+ * @param options
+ * @param parentData
+ * @param childIndex
+ * @param level
+ * @param globalData
+ */
+// eslint-disable-next-line max-statements
+export async function parseImplicitTiles(params: {
+  subtree: Subtree;
+  options: any;
+  parentData?: {mortonIndex: number; x: number; y: number; z: number};
+  childIndex?: number;
+  level?: number;
+  globalData?: {level: number; mortonIndex: number; x: number; y: number; z: number};
+  s2VolumeBox?: S2VolumeBox;
+}) {
+  const {
+    options,
+    parentData = {
+      mortonIndex: 0,
+      x: 0,
+      y: 0,
+      z: 0
+    },
+    childIndex = 0,
+    globalData = {
+      level: 0,
+      mortonIndex: 0,
+      x: 0,
+      y: 0,
+      z: 0
+    },
+    s2VolumeBox
+  } = params;
+  let {subtree, level = 0} = params;
+  const {
+    subdivisionScheme,
+    subtreeLevels,
+    maximumLevel,
+    contentUrlTemplate,
+    subtreesUriTemplate,
+    basePath
+  } = options;
+
+  const tile = {children: [], lodMetricValue: 0, contentUrl: ''};
+
+  const childrenPerTile = SUBDIVISION_COUNT_MAP[subdivisionScheme];
+
+  const childX = childIndex & 0b01;
+  const childY = (childIndex >> 1) & 0b01;
+  const childZ = (childIndex >> 2) & 0b01;
+
+  const levelOffset = (childrenPerTile ** level - 1) / (childrenPerTile - 1);
+  let childTileMortonIndex = concatBits(parentData.mortonIndex, childIndex);
+  let tileAvailabilityIndex = levelOffset + childTileMortonIndex;
+
+  // Local tile coordinates
+  let childTileX = concatBits(parentData.x, childX);
+  let childTileY = concatBits(parentData.y, childY);
+  let childTileZ = concatBits(parentData.z, childZ);
+
+  let isChildSubtreeAvailable = false;
+
+  if (level + 1 > subtreeLevels) {
+    isChildSubtreeAvailable = getAvailabilityResult(
+      subtree.childSubtreeAvailability,
+      childTileMortonIndex
+    );
+  }
+
+  const x = concatBits(globalData.x, childTileX);
+  const y = concatBits(globalData.y, childTileY);
+  const z = concatBits(globalData.z, childTileZ);
+  const lev = level + globalData.level;
+
+  if (isChildSubtreeAvailable) {
+    const subtreePath = `${basePath}/${subtreesUriTemplate}`;
+    const childSubtreeUrl = replaceContentUrlTemplate(subtreePath, lev, x, y, z);
+    const childSubtree = await load(childSubtreeUrl, Tile3DSubtreeLoader);
+
+    subtree = childSubtree;
+
+    globalData.mortonIndex = childTileMortonIndex;
+    globalData.x = childTileX;
+    globalData.y = childTileY;
+    globalData.z = childTileZ;
+    globalData.level = level;
+
+    childTileMortonIndex = 0;
+    tileAvailabilityIndex = 0;
+    childTileX = 0;
+    childTileY = 0;
+    childTileZ = 0;
+    level = 0;
+  }
+
+  const isTileAvailable = getAvailabilityResult(subtree.tileAvailability, tileAvailabilityIndex);
+
+  if (!isTileAvailable || level > maximumLevel) {
+    return tile;
+  }
+
+  const isContentAvailable = getAvailabilityResult(
+    subtree.contentAvailability,
+    tileAvailabilityIndex
+  );
+
+  if (isContentAvailable) {
+    tile.contentUrl = replaceContentUrlTemplate(contentUrlTemplate, lev, x, y, z);
+  }
+
+  const childTileLevel = level + 1;
+  const pData = {mortonIndex: childTileMortonIndex, x: childTileX, y: childTileY, z: childTileZ};
+
+  for (let index = 0; index < childrenPerTile; index++) {
+    const childS2VolumeBox: S2VolumeBox | undefined = getChildS2VolumeBox(
+      s2VolumeBox,
+      index,
+      subdivisionScheme
+    );
+
+    // Recursive calling...
+    const childTileParsed = await parseImplicitTiles({
+      subtree,
+      options,
+      parentData: pData,
+      childIndex: index,
+      level: childTileLevel,
+      globalData,
+      s2VolumeBox: childS2VolumeBox
+    });
+
+    if (childTileParsed.contentUrl || childTileParsed.children.length) {
+      const globalLevel = lev + 1;
+      const childCoordinates = {childTileX, childTileY, childTileZ};
+      const formattedTile = formatTileData(
+        childTileParsed,
+        globalLevel,
+        childCoordinates,
+        options,
+        s2VolumeBox
+      );
+      // @ts-ignore
+      tile.children.push(formattedTile);
+    }
+  }
+
+  return tile;
+}
+
+function getAvailabilityResult(availabilityData: Availability, index: number): boolean {
+  if ('constant' in availabilityData) {
+    return Boolean(availabilityData.constant);
+  }
+
+  if (availabilityData.explicitBitstream) {
+    return getBooleanValueFromBitstream(index, availabilityData.explicitBitstream);
+  }
+
+  return false;
+}
+
+/**
+ * Do formatting of implicit tile data.
+ * TODO Check out do we able to use Tile3D class as type here.
+ * @param tile
+ * @param lodMetricValue
+ * @param options
+ * @returns
+ */
+function formatTileData(
+  tile,
+  level: number,
+  childCoordinates: {childTileX: number; childTileY: number; childTileZ: number},
+  options: any,
+  s2VolumeBox?: S2VolumeBox
+) {
+  const {
+    basePath,
+    refine,
+    getRefine,
+    lodMetricType,
+    getTileType,
+    rootLodMetricValue,
+    rootBoundingVolume
+  } = options;
+  const uri = tile.contentUrl && tile.contentUrl.replace(`${basePath}/`, '');
+  const lodMetricValue = rootLodMetricValue / 2 ** level;
+
+  const boundingVolume: BoundingVolume = s2VolumeBox?.box
+    ? {box: s2VolumeBox.box}
+    : rootBoundingVolume;
+
+  const boundingVolumeForChildTile = calculateBoundingVolumeForChildTile(
+    level,
+    boundingVolume,
+    childCoordinates
+  );
+
+  return {
+    children: tile.children,
+    contentUrl: tile.contentUrl,
+    content: {uri},
+    id: tile.contentUrl,
+    refine: getRefine(refine),
+    type: getTileType(tile),
+    lodMetricType,
+    lodMetricValue,
+    geometricError: lodMetricValue,
+    transform: tile.transform,
+    boundingVolume: boundingVolumeForChildTile
+  };
+}
+
+/**
+ * Calculate child bounding volume.
+ * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling#subdivision-rules
+ * @param level
+ * @param rootBoundingVolume
+ * @param childCoordinates
+ */
+function calculateBoundingVolumeForChildTile(
+  level: number,
+  rootBoundingVolume: BoundingVolume,
+  childCoordinates: {childTileX: number; childTileY: number; childTileZ: number}
+): BoundingVolume {
+  if (rootBoundingVolume.region) {
+    const {childTileX, childTileY, childTileZ} = childCoordinates;
+    const [west, south, east, north, minimumHeight, maximumHeight] = rootBoundingVolume.region;
+    const boundingVolumesCount = 2 ** level;
+
+    const sizeX = (east - west) / boundingVolumesCount;
+    const sizeY = (north - south) / boundingVolumesCount;
+
+    // TODO : Why is the subdivisionScheme not being checked here?
+
+    // In case of QUADTREE the sizeZ should NOT be changed!
+    // https://portal.ogc.org/files/102132
+    // A quadtree divides space only on the x and y dimensions. It divides each tile into 4 smaller tiles where the x and y dimensions are halved. The quadtree z minimum and maximum remain unchanged.
+
+    const sizeZ = (maximumHeight - minimumHeight) / boundingVolumesCount;
+
+    const [childWest, childEast] = [west + sizeX * childTileX, west + sizeX * (childTileX + 1)];
+    const [childSouth, childNorth] = [south + sizeY * childTileY, south + sizeY * (childTileY + 1)];
+    const [childMinimumHeight, childMaximumHeight] = [
+      minimumHeight + sizeZ * childTileZ,
+      minimumHeight + sizeZ * (childTileZ + 1)
+    ];
+
+    return {
+      region: [childWest, childSouth, childEast, childNorth, childMinimumHeight, childMaximumHeight]
+    };
+  }
+
+  if (rootBoundingVolume.box) {
+    return rootBoundingVolume;
+  }
+
+  throw new Error(`Unsupported bounding volume type ${rootBoundingVolume}`);
+}
+
+/**
+ * Do binary concatenation
+ * @param first
+ * @param second
+ */
+function concatBits(first: number, second: number): number {
+  return parseInt(first.toString(2) + second.toString(2), 2);
+}
+
+/**
+ * Replace implicit tile content url with real coordinates.
+ * @param templateUrl
+ * @param level
+ * @param x
+ * @param y
+ * @param z
+ */
+export function replaceContentUrlTemplate(
+  templateUrl: string,
+  level: number,
+  x: number,
+  y: number,
+  z: number
+): string {
+  const mapUrl = generateMapUrl({level, x, y, z});
+  return templateUrl.replace(/{level}|{x}|{y}|{z}/gi, (matched) => mapUrl[matched]);
+}
+
+/**
+ * Get Map object for content url generation
+ * @param items
+ */
+function generateMapUrl(items: {[key: string]: number}): {[key: string]: string} {
+  const mapUrl = {};
+
+  for (const key in items) {
+    mapUrl[`{${key}}`] = items[key];
+  }
+  return mapUrl;
+}
+
+/**
+ * Get boolean value from bistream by index
+ * A boolean value is encoded as a single bit, either 0 (false) or 1 (true).
+ * Multiple boolean values are packed tightly in the same buffer.
+ * These buffers of tightly-packed bits are sometimes referred to as bitstreams.
+ * Spec - https://github.com/CesiumGS/3d-tiles/tree/implicit-revisions/specification/Metadata#booleans
+ * @param availabilitiIndex
+ */
+function getBooleanValueFromBitstream(
+  availabilityIndex: number,
+  availabilityBuffer: Uint8Array
+): boolean {
+  const byteIndex = Math.floor(availabilityIndex / 8);
+  const bitIndex = availabilityIndex % 8;
+  const bitValue = (availabilityBuffer[byteIndex] >> bitIndex) & 1;
+
+  return bitValue === 1;
+}

package/src/lib/parsers/helpers/{parse-3d-tile-gltf-view.js → parse-3d-tile-gltf-view.ts}

@@ -90,6 +90,6 @@ function extractGLTFBufferOrURL(tile, gltfFormat, options) {
     case GLTF_FORMAT.EMBEDDED:
       break;
     default:
-      throw new Error(`b3dm: Illegal glTF format field`);
+      throw new Error('b3dm: Illegal glTF format field');
   }
 }