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

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

@@ -0,0 +1,319 @@
+import type {Availability, BoundingVolume, Subtree} from '../../../types';
+import {Tile3DSubtreeLoader} from '../../../tile-3d-subtree-loader';
+import {load} from '@loaders.gl/core';
+
+const QUADTREE_DEVISION_COUNT = 4;
+const OCTREE_DEVISION_COUNT = 8;
+
+const SUBDIVISION_COUNT_MAP = {
+  QUADTREE: QUADTREE_DEVISION_COUNT,
+  OCTREE: OCTREE_DEVISION_COUNT
+};
+
+/**
+ * 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};
+}) {
+  const {
+    options,
+    parentData = {
+      mortonIndex: 0,
+      x: 0,
+      y: 0,
+      z: 0
+    },
+    childIndex = 0,
+    globalData = {
+      level: 0,
+      mortonIndex: 0,
+      x: 0,
+      y: 0,
+      z: 0
+    }
+  } = 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);
+
+  // TODO Remove after real implicit tileset will be tested.
+  // Degug data
+  // tile.level = level + globalData.level;
+  // tile.x = concatBits(globalData.x, childTileX);
+  // tile.y = concatBits(globalData.y, childTileY);
+  // tile.z = concatBits(globalData.z, childTileZ);
+  // tile.mortonIndex = childTileMortonIndex;
+  // End of debug data
+
+  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 currentTile = await parseImplicitTiles({
+      subtree,
+      options,
+      parentData: pData,
+      childIndex: index,
+      level: childTileLevel,
+      globalData
+    });
+
+    if (currentTile.contentUrl || currentTile.children.length) {
+      const globalLevel = lev + 1;
+      const childCoordinates = {childTileX, childTileY, childTileZ};
+      const formattedTile = formatTileData(currentTile, globalLevel, childCoordinates, options);
+      // @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
+) {
+  const {
+    basePath,
+    refine,
+    getRefine,
+    lodMetricType,
+    getTileType,
+    rootLodMetricValue,
+    rootBoundingVolume
+  } = options;
+  const uri = tile.contentUrl && tile.contentUrl.replace(`${basePath}/`, '');
+  const lodMetricValue = rootLodMetricValue / 2 ** level;
+  const boundingVolume = calculateBoundingVolumeForChildTile(
+    level,
+    rootBoundingVolume,
+    childCoordinates
+  );
+
+  return {
+    children: tile.children,
+    contentUrl: tile.contentUrl,
+    content: {uri},
+    id: tile.contentUrl,
+    refine: getRefine(refine),
+    type: getTileType(tile),
+    lodMetricType,
+    lodMetricValue,
+    boundingVolume
+    // Temp debug values. Remove when real implicit tileset will be tested.
+    // x: tile.x,
+    // y: tile.y,
+    // z: tile.z,
+    // level: tile.level
+  };
+}
+
+/**
+ * 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 | null {
+  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;
+    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]
+    };
+  }
+
+  // eslint-disable-next-line no-console
+  console.warn('Unsupported bounding volume type: ', rootBoundingVolume);
+  return null;
+}
+
+/**
+ * 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');
   }
 }

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

@@ -0,0 +1,105 @@
+import type {Subtree, ExplicitBitstream} from '../../../types';
+import {fetchFile} from '@loaders.gl/core';
+
+const SUBTREE_FILE_MAGIC = 0x74627573;
+const SUBTREE_FILE_VERSION = 1;
+
+/**
+ * Parse subtree file
+ * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling#subtree-file-format
+ * @param data
+ * @returns
+ */
+// eslint-disable-next-line max-statements
+export default async function parse3DTilesSubtree(data: ArrayBuffer): Promise<Subtree> {
+  const magic = new Uint32Array(data.slice(0, 4));
+
+  if (magic[0] !== SUBTREE_FILE_MAGIC) {
+    throw new Error('Wrong subtree file magic number');
+  }
+
+  const version = new Uint32Array(data.slice(4, 8));
+
+  if (version[0] !== SUBTREE_FILE_VERSION) {
+    throw new Error('Wrong subtree file verson, must be 1');
+  }
+
+  const jsonByteLength = parseUint64Value(data.slice(8, 16));
+  const stringAttribute = new Uint8Array(data, 24, jsonByteLength);
+
+  const textDecoder = new TextDecoder('utf8');
+  const string = textDecoder.decode(stringAttribute);
+  const subtree = JSON.parse(string);
+
+  const binaryByteLength = parseUint64Value(data.slice(16, 24));
+  let internalBinaryBuffer = new ArrayBuffer(0);
+
+  if (binaryByteLength) {
+    internalBinaryBuffer = data.slice(24 + jsonByteLength);
+  }
+
+  if ('bufferView' in subtree.tileAvailability) {
+    subtree.tileAvailability.explicitBitstream = await getExplicitBitstream(
+      subtree,
+      'tileAvailability',
+      internalBinaryBuffer
+    );
+  }
+
+  if ('bufferView' in subtree.contentAvailability) {
+    subtree.contentAvailability.explicitBitstream = await getExplicitBitstream(
+      subtree,
+      'contentAvailability',
+      internalBinaryBuffer
+    );
+  }
+
+  if ('bufferView' in subtree.childSubtreeAvailability) {
+    subtree.childSubtreeAvailability.explicitBitstream = await getExplicitBitstream(
+      subtree,
+      'childSubtreeAvailability',
+      internalBinaryBuffer
+    );
+  }
+
+  return subtree;
+}
+
+/**
+ * Get explicit bitstream for subtree availability data.
+ * @param subtree
+ * @param name
+ * @param internalBinaryBuffer
+ */
+async function getExplicitBitstream(
+  subtree: Subtree,
+  name: string,
+  internalBinaryBuffer: ArrayBuffer
+): Promise<ExplicitBitstream> {
+  const bufferViewIndex = subtree[name].bufferView;
+  const bufferView = subtree.bufferViews[bufferViewIndex];
+  const buffer = subtree.buffers[bufferView.buffer];
+
+  // External bitstream loading
+  if (buffer.uri) {
+    const response = await fetchFile(buffer.uri);
+    const data = await response.arrayBuffer();
+    // Return view of bitstream.
+    return new Uint8Array(data, bufferView.byteOffset, bufferView.byteLength);
+  }
+  // Return view of bitstream.
+  return new Uint8Array(internalBinaryBuffer, bufferView.byteOffset, bufferView.byteLength);
+}
+
+/**
+ * Parse buffer to return uint64 value
+ * @param buffer
+ * @returns 64-bit value until precision is lost after Number.MAX_SAFE_INTEGER
+ */
+function parseUint64Value(buffer: ArrayBuffer): number {
+  const dataView = new DataView(buffer);
+  const left = dataView.getUint32(0, true);
+  const right = dataView.getUint32(4, true);
+  // combine the two 32-bit values
+  return left + 2 ** 32 * right;
+}

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

@@ -4,7 +4,7 @@
 import {getStringFromArrayBuffer} from './parse-utils';
 
 const SIZEOF_UINT32 = 4;
-const DEPRECATION_WARNING = `b3dm tile in legacy format.`;
+const DEPRECATION_WARNING = 'b3dm tile in legacy format.';
 
 // eslint-disable-next-line max-statements
 export function parse3DTileTablesHeaderSync(tile, arrayBuffer, byteOffset) {

package/src/lib/parsers/parse-3d-tile-gltf.js

@@ -0,0 +1,16 @@
+import {GLTFLoader} from '@loaders.gl/gltf';
+
+export async function parseGltf3DTile(tile, arrayBuffer, options, context) {
+  // Set flags
+  // glTF models need to be rotated from Y to Z up
+  // https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#y-up-to-z-up
+  tile.rotateYtoZ = true;
+  // Save gltf up axis
+  tile.gltfUpAxis =
+    options['3d-tiles'] && options['3d-tiles'].assetGltfUpAxis
+      ? options['3d-tiles'].assetGltfUpAxis
+      : 'Y';
+
+  const {parse} = context;
+  tile.gltf = await parse(arrayBuffer, GLTFLoader, options, context);
+}

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

@@ -0,0 +1,152 @@
+import {Tile3DSubtreeLoader} from '../../tile-3d-subtree-loader';
+import {load} from '@loaders.gl/core';
+import {Tileset3D, LOD_METRIC_TYPE, TILE_REFINEMENT, TILE_TYPE} from '@loaders.gl/tiles';
+import {Subtree} from '../../types';
+import {parseImplicitTiles, replaceContentUrlTemplate} from './helpers/parse-3d-implicit-tiles';
+
+function getTileType(tile) {
+  if (!tile.contentUrl) {
+    return TILE_TYPE.EMPTY;
+  }
+
+  const contentUrl = tile.contentUrl;
+  const fileExtension = contentUrl.split('.').pop();
+  switch (fileExtension) {
+    case 'pnts':
+      return TILE_TYPE.POINTCLOUD;
+    case 'i3dm':
+    case 'b3dm':
+    case 'glb':
+    case 'gltf':
+      return TILE_TYPE.SCENEGRAPH;
+    default:
+      return fileExtension;
+  }
+}
+
+function getRefine(refine) {
+  switch (refine) {
+    case 'REPLACE':
+    case 'replace':
+      return TILE_REFINEMENT.REPLACE;
+    case 'ADD':
+    case 'add':
+      return TILE_REFINEMENT.ADD;
+    default:
+      return refine;
+  }
+}
+
+export function normalizeTileData(tile, options) {
+  if (!tile) {
+    return null;
+  }
+  if (tile.content) {
+    const contentUri = tile.content.uri || tile.content.url;
+    tile.contentUrl = `${options.basePath}/${contentUri}`;
+  }
+  tile.id = tile.contentUrl;
+  tile.lodMetricType = LOD_METRIC_TYPE.GEOMETRIC_ERROR;
+  tile.lodMetricValue = tile.geometricError;
+  tile.transformMatrix = tile.transform;
+  tile.type = getTileType(tile);
+  tile.refine = getRefine(tile.refine);
+
+  return tile;
+}
+
+// normalize tile headers
+export function normalizeTileHeaders(tileset) {
+  const basePath = tileset.basePath;
+  const root = normalizeTileData(tileset.root, tileset);
+
+  const stack: any[] = [];
+  stack.push(root);
+
+  while (stack.length > 0) {
+    const tile = stack.pop() || {};
+    const children = tile.children || [];
+    for (const childHeader of children) {
+      normalizeTileData(childHeader, {basePath});
+      stack.push(childHeader);
+    }
+  }
+
+  return root;
+}
+
+/**
+ * Do normalisation of implicit tile headers
+ * TODO Check if Tile3D class can be a return type here.
+ * @param tileset
+ */
+export async function normalizeImplicitTileHeaders(tileset: Tileset3D) {
+  if (!tileset.root) {
+    return null;
+  }
+
+  const basePath = tileset.basePath;
+  const implicitTilingExtension = tileset.root.extensions['3DTILES_implicit_tiling'];
+  const {
+    subdivisionScheme,
+    maximumLevel,
+    subtreeLevels,
+    subtrees: {uri: subtreesUriTemplate}
+  } = implicitTilingExtension;
+  const subtreeUrl = replaceContentUrlTemplate(subtreesUriTemplate, 0, 0, 0, 0);
+  const rootSubtreeUrl = `${basePath}/${subtreeUrl}`;
+  const rootSubtree = await load(rootSubtreeUrl, Tile3DSubtreeLoader);
+  const contentUrlTemplate = `${basePath}/${tileset.root.content.uri}`;
+  const refine = tileset.root.refine;
+  // @ts-ignore
+  const rootLodMetricValue = tileset.root.geometricError;
+  const rootBoundingVolume = tileset.root.boundingVolume;
+
+  const options = {
+    contentUrlTemplate,
+    subtreesUriTemplate,
+    subdivisionScheme,
+    subtreeLevels,
+    maximumLevel,
+    refine,
+    basePath,
+    lodMetricType: LOD_METRIC_TYPE.GEOMETRIC_ERROR,
+    rootLodMetricValue,
+    rootBoundingVolume,
+    getTileType,
+    getRefine
+  };
+
+  return await normalizeImplicitTileData(tileset.root, rootSubtree, options);
+}
+
+/**
+ * Do implicit data normalisation to create hierarchical tile structure
+ * @param tile
+ * @param rootSubtree
+ * @param options
+ * @returns
+ */
+export async function normalizeImplicitTileData(tile, rootSubtree: Subtree, options: any) {
+  if (!tile) {
+    return null;
+  }
+
+  tile.lodMetricType = LOD_METRIC_TYPE.GEOMETRIC_ERROR;
+  tile.lodMetricValue = tile.geometricError;
+  tile.transformMatrix = tile.transform;
+
+  const {children, contentUrl} = await parseImplicitTiles({subtree: rootSubtree, options});
+
+  if (contentUrl) {
+    tile.contentUrl = contentUrl;
+    tile.content = {uri: contentUrl.replace(`${options.basePath}/`, '')};
+  }
+
+  tile.refine = getRefine(tile.refine);
+  tile.type = getTileType(tile);
+  tile.children = children;
+  tile.id = tile.contentUrl;
+
+  return tile;
+}

package/src/lib/parsers/{parse-3d-tile-instanced-model.js → parse-3d-tile-instanced-model.ts}

@@ -146,6 +146,7 @@ function extractInstancedAttributes(tile, featureTable, batchTable, instancesLen
     }
 
     instancePosition.copy(position);
+    // @ts-expect-error
     instanceTranslationRotationScale.translation = instancePosition;
 
     // Get the instance rotation
@@ -203,6 +204,7 @@ function extractInstancedAttributes(tile, featureTable, batchTable, instancesLen
     }
 
     instanceQuaternion.fromMatrix3(instanceRotation);
+    // @ts-expect-error
     instanceTranslationRotationScale.rotation = instanceQuaternion;
 
     // Get the instance scale
@@ -216,6 +218,7 @@ function extractInstancedAttributes(tile, featureTable, batchTable, instancesLen
       instanceScale.scale(nonUniformScale);
     }
 
+    // @ts-expect-error
     instanceTranslationRotationScale.scale = instanceScale;
 
     // Get the batchId
@@ -225,12 +228,15 @@ function extractInstancedAttributes(tile, featureTable, batchTable, instancesLen
       batchId = i;
     }
 
+    // @ts-expect-error
     const rotationMatrix = new Matrix4().fromQuaternion(instanceTranslationRotationScale.rotation);
 
     // Create the model matrix and the instance
     instanceTransform.identity();
+    // @ts-expect-error
     instanceTransform.translate(instanceTranslationRotationScale.translation);
     instanceTransform.multiplyRight(rotationMatrix);
+    // @ts-expect-error
     instanceTransform.scale(instanceTranslationRotationScale.scale);
 
     const modelMatrix = instanceTransform.clone();

package/src/lib/parsers/{parse-3d-tile-point-cloud.js → parse-3d-tile-point-cloud.ts}

@@ -137,7 +137,7 @@ function parseNormals(tile, featureTable) {
 }
 
 function parseBatchIds(tile, featureTable) {
-  let batchTable = null;
+  let batchTable: Tile3DBatchTable | null = null;
   if (!tile.batchIds && featureTable.hasProperty('BATCH_ID')) {
     tile.batchIds = featureTable.getPropertyArray('BATCH_ID', GL.UNSIGNED_SHORT, 1);
 
@@ -250,7 +250,7 @@ export async function loadDraco(tile, dracoData, options, context) {
 
   tile.attributes = {
     positions: decodedPositions,
-    colors: normalize3DTileColorAttribute(tile, decodedColors),
+    colors: normalize3DTileColorAttribute(tile, decodedColors, undefined),
     normals: decodedNormals,
     batchIds: decodedBatchIds,
     ...batchTableAttributes