@cesium/engine 14.0.0 → 16.0.0

package/Source/Scene/Vector3DTilePrimitive.js

@@ -1,7 +1,7 @@
 import Cartesian3 from "../Core/Cartesian3.js";
 import Color from "../Core/Color.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
-import defaultValue from "../Core/defaultValue.js";
+import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
 import IndexDatatype from "../Core/IndexDatatype.js";
@@ -51,7 +51,7 @@ import Vector3DTileBatch from "./Vector3DTileBatch.js";
  * @private
  */
 function Vector3DTilePrimitive(options) {
-  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  options = options ?? Frozen.EMPTY_OBJECT;
 
   this._batchTable = options.batchTable;
   this._batchIds = options.batchIds;
@@ -70,7 +70,7 @@ function Vector3DTilePrimitive(options) {
   this._boundingVolume = options.boundingVolume;
   this._boundingVolumes = options.boundingVolumes;
 
-  this._center = defaultValue(options.center, Cartesian3.ZERO);
+  this._center = options.center ?? Cartesian3.ZERO;
 
   this._va = undefined;
   this._sp = undefined;
@@ -127,10 +127,8 @@ function Vector3DTilePrimitive(options) {
    * @type {ClassificationType}
    * @default ClassificationType.BOTH
    */
-  this.classificationType = defaultValue(
-    options.classificationType,
-    ClassificationType.BOTH,
-  );
+  this.classificationType =
+    options.classificationType ?? ClassificationType.BOTH;
 
   // Hidden options
   this._vertexShaderSource = options._vertexShaderSource;
@@ -257,10 +255,8 @@ function createShaders(primitive, context) {
   }
 
   const batchTable = primitive._batchTable;
-  const attributeLocations = defaultValue(
-    primitive._attributeLocations,
-    defaultAttributeLocations,
-  );
+  const attributeLocations =
+    primitive._attributeLocations ?? defaultAttributeLocations;
 
   let pickId = primitive._pickId;
   const vertexShaderSource = primitive._vertexShaderSource;
@@ -769,7 +765,7 @@ function createColorCommands(primitive, context) {
 
   const vertexArray = primitive._va;
   const sp = primitive._sp;
-  const modelMatrix = defaultValue(primitive._modelMatrix, Matrix4.IDENTITY);
+  const modelMatrix = primitive._modelMatrix ?? Matrix4.IDENTITY;
   const uniformMap = primitive._uniformMap;
   const bv = primitive._boundingVolume;
 
@@ -876,7 +872,7 @@ function createPickCommands(primitive) {
   const vertexArray = primitive._va;
   const spStencil = primitive._spStencil;
   const spPick = primitive._spPick;
-  const modelMatrix = defaultValue(primitive._modelMatrix, Matrix4.IDENTITY);
+  const modelMatrix = primitive._modelMatrix ?? Matrix4.IDENTITY;
   const uniformMap = primitive._uniformMap;
 
   for (let j = 0; j < length; ++j) {

package/Source/Scene/VoxelBoxShape.js

@@ -5,7 +5,6 @@ import Check from "../Core/Check.js";
 import Matrix3 from "../Core/Matrix3.js";
 import Matrix4 from "../Core/Matrix4.js";
 import OrientedBoundingBox from "../Core/OrientedBoundingBox.js";
-import defaultValue from "../Core/defaultValue.js";
 
 /**
  * A box {@link VoxelShape}.
@@ -24,6 +23,7 @@ function VoxelBoxShape() {
   /**
    * An oriented bounding box containing the bounded shape.
    * The update function must be called before accessing this value.
+   * @private
    * @type {OrientedBoundingBox}
    * @readonly
    */
@@ -32,6 +32,7 @@ function VoxelBoxShape() {
   /**
    * A bounding sphere containing the bounded shape.
    * The update function must be called before accessing this value.
+   * @private
    * @type {BoundingSphere}
    * @readonly
    */
@@ -40,6 +41,7 @@ function VoxelBoxShape() {
   /**
    * A transformation matrix containing the bounded shape.
    * The update function must be called before accessing this value.
+   * @private
    * @type {Matrix4}
    * @readonly
    */
@@ -48,6 +50,7 @@ function VoxelBoxShape() {
   /**
    * A transformation matrix containing the shape, ignoring the bounds.
    * The update function must be called before accessing this value.
+   * @private
    * @type {Matrix4}
    * @readonly
    */
@@ -72,6 +75,7 @@ function VoxelBoxShape() {
   );
 
   /**
+   * @private
    * @type {Object<string, any>}
    * @readonly
    */
@@ -83,6 +87,7 @@ function VoxelBoxShape() {
   };
 
   /**
+   * @private
    * @type {Object<string, any>}
    * @readonly
    */
@@ -93,6 +98,7 @@ function VoxelBoxShape() {
 
   /**
    * The maximum number of intersections against the shape for any ray direction.
+   * @private
    * @type {number}
    * @readonly
    */
@@ -115,7 +121,7 @@ const transformLocalToUv = Matrix4.fromRotationTranslation(
 
 /**
  * Update the shape's state.
- *
+ * @private
  * @param {Matrix4} modelMatrix The model matrix.
  * @param {Cartesian3} minBounds The minimum bounds.
  * @param {Cartesian3} maxBounds The maximum bounds.
@@ -130,8 +136,8 @@ VoxelBoxShape.prototype.update = function (
   clipMinBounds,
   clipMaxBounds,
 ) {
-  clipMinBounds = defaultValue(clipMinBounds, VoxelBoxShape.DefaultMinBounds);
-  clipMaxBounds = defaultValue(clipMaxBounds, VoxelBoxShape.DefaultMaxBounds);
+  clipMinBounds = clipMinBounds ?? VoxelBoxShape.DefaultMinBounds;
+  clipMaxBounds = clipMaxBounds ?? VoxelBoxShape.DefaultMaxBounds;
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("modelMatrix", modelMatrix);
   Check.typeOf.object("minBounds", minBounds);
@@ -302,7 +308,7 @@ const scratchTileMaxBounds = new Cartesian3();
 /**
  * Computes an oriented bounding box for a specified tile.
  * The update function must be called before calling this function.
- *
+ * @private
  * @param {number} tileLevel The tile's level.
  * @param {number} tileX The tile's x coordinate.
  * @param {number} tileY The tile's y coordinate.
@@ -356,7 +362,7 @@ const sampleSizeScratch = new Cartesian3();
 /**
  * Computes an oriented bounding box for a specified sample within a specified tile.
  * The update function must be called before calling this function.
- *
+ * @private
  * @param {SpatialNode} spatialNode The spatial node containing the sample
  * @param {Cartesian3} tileDimensions The size of the tile in number of samples, before padding
  * @param {Cartesian3} tileUv The sample coordinate within the tile
@@ -429,7 +435,7 @@ VoxelBoxShape.prototype.computeOrientedBoundingBoxForSample = function (
 
 /**
  * Defines the minimum bounds of the shape. Corresponds to minimum X, Y, Z.
- *
+ * @private
  * @type {Cartesian3}
  * @constant
  * @readonly
@@ -440,7 +446,7 @@ VoxelBoxShape.DefaultMinBounds = Object.freeze(
 
 /**
  * Defines the maximum bounds of the shape. Corresponds to maximum X, Y, Z.
- *
+ * @private
  * @type {Cartesian3}
  * @constant
  * @readonly

package/Source/Scene/VoxelCell.js

@@ -71,8 +71,8 @@ VoxelCell.fromKeyframeNode = function (
   //>>includeEnd('debug');
 
   const voxelCell = new VoxelCell(primitive, tileIndex, sampleIndex);
-  const { spatialNode, metadata } = keyframeNode;
-  voxelCell._metadata = getMetadataForSample(primitive, metadata, sampleIndex);
+  const { spatialNode, content } = keyframeNode;
+  voxelCell._metadata = getMetadataForSample(primitive, content, sampleIndex);
   voxelCell._orientedBoundingBox = getOrientedBoundingBox(
     primitive,
     spatialNode,
@@ -85,15 +85,16 @@ VoxelCell.fromKeyframeNode = function (
 /**
  * @private
  * @param {VoxelPrimitive} primitive
- * @param {object} metadata
+ * @param {VoxelContent} content
  * @param {number} sampleIndex
  * @returns {object}
  */
-function getMetadataForSample(primitive, metadata, sampleIndex) {
-  if (!defined(metadata)) {
+function getMetadataForSample(primitive, content, sampleIndex) {
+  if (!defined(content) || !defined(content.metadata)) {
     return undefined;
   }
   const { names, types } = primitive.provider;
+  const { metadata } = content;
   const metadataMap = {};
   for (let i = 0; i < names.length; i++) {
     const name = names[i];

package/Source/Scene/VoxelContent.js

@@ -1,167 +1,231 @@
+import { destroyObject } from "@cesium/engine";
 import Check from "../Core/Check.js";
+import ComponentDatatype from "../Core/ComponentDatatype.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import defined from "../Core/defined.js";
-import getJsonFromTypedArray from "../Core/getJsonFromTypedArray.js";
-import MetadataTable from "./MetadataTable.js";
+import GltfLoader from "./GltfLoader.js";
+import MetadataComponentType from "./MetadataComponentType.js";
+import MetadataType from "./MetadataType.js";
 
 /**
+ * <div class="notice">
+ * To construct a VoxelContent, call {@link VoxelContent.fromMetadataArray} or {@link VoxelContent.fromGltf}. Do not call the constructor directly.
+ * </div>
  * An object representing voxel content for a {@link Cesium3DTilesVoxelProvider}.
  *
  * @alias VoxelContent
- * @constructor
+ * @internalConstructor
  *
- * @param {Resource} resource The resource for this voxel content. This is used for fetching external buffers as needed.
+ * @privateParam {object} options An object with the following properties:
+ * @privateParam {ResourceLoader} [options.loader] The loader used to load the voxel content.
+ * @privateParam {Int8Array[]|Uint8Array[]|Int16Array[]|Uint16Array[]|Int32Array[]|Uint32Array[]|Float32Array[]|Float64Array[]} [options.metadata] The metadata for this voxel content.
+ *
+ * @exception {DeveloperError} One of loader and metadata must be defined.
+ * @exception {DeveloperError} metadata must be an array of TypedArrays.
  *
- * @private
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
-function VoxelContent(resource) {
+function VoxelContent(options) {
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.object("resource", resource);
+  Check.typeOf.object("options", options);
+  if (!defined(options.loader)) {
+    if (!defined(options.metadata)) {
+      throw new DeveloperError("One of loader and metadata must be defined.");
+    }
+    if (!Array.isArray(options.metadata)) {
+      throw new DeveloperError("metadata must be an array of TypedArrays.");
+    }
+  }
   //>>includeEnd('debug');
 
-  this._resource = resource;
-  this._metadataTable = undefined;
+  const { loader, metadata } = options;
+
+  this._loader = loader;
+  this._metadata = metadata;
+  this._resourcesLoaded = false;
+  this._ready = false;
 }
 
 Object.defineProperties(VoxelContent.prototype, {
   /**
-   * The {@link MetadataTable} storing voxel property values.
+   * Returns true when the content is ready to render; otherwise false
+   *
+   * @memberof VoxelContent.prototype
    *
-   * @type {MetadataTable}
+   * @type {boolean}
    * @readonly
    * @private
    */
-  metadataTable: {
+  ready: {
+    get: function () {
+      return this._ready;
+    },
+  },
+
+  /**
+   * The metadata for this voxel content.
+   * The metadata is an array of typed arrays, one for each field.
+   * The data for one field is a flattened 3D array ordered by X, then Y, then Z.
+   * @type {Int8Array[]|Uint8Array[]|Int16Array[]|Uint16Array[]|Int32Array[]|Uint32Array[]|Float32Array[]|Float64Array[]}
+   * @readonly
+   */
+  metadata: {
     get: function () {
-      return this._metadataTable;
+      return this._metadata;
     },
   },
 });
 
 /**
- * Creates an object representing voxel content for a {@link Cesium3DTilesVoxelProvider}.
+ * Constructs a VoxelContent from an array of metadata.
+ *
+ * @param {Int8Array[]|Uint8Array[]|Int16Array[]|Uint16Array[]|Int32Array[]|Uint32Array[]|Float32Array[]|Float64Array[]} metadata The metadata to use for this voxel content.
+ * @returns {VoxelContent} A VoxelContent containing the specified metadata.
+ */
+VoxelContent.fromMetadataArray = function (metadata) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("metadata", metadata);
+  if (!Array.isArray(metadata)) {
+    throw new DeveloperError("metadata must be an array of TypedArrays.");
+  }
+  //>>includeEnd('debug');
+
+  return new VoxelContent({ metadata });
+};
+
+/**
+ * Constructs a VoxelContent from a glTF resource.
  *
- * @param {Resource} resource The resource for this voxel content. This is used for fetching external buffers as needed.
- * @param {object} [json] Voxel JSON contents. Mutually exclusive with binary.
- * @param {Uint8Array} [binary] Voxel binary contents. Mutually exclusive with json.
- * @param {MetadataSchema} metadataSchema The metadata schema used by property tables in the voxel content
- * @returns {Promise<VoxelContent>}
+ * @param {Resource} resource A Resource pointing to a glTF containing voxel content.
+ * @returns {Promise<VoxelContent>} A promise that resolves to the voxel content.
  *
- * @exception {DeveloperError} One of json and binary must be defined.
+ * @private
  */
-VoxelContent.fromJson = async function (
-  resource,
-  json,
-  binary,
-  metadataSchema,
-) {
+VoxelContent.fromGltf = async function (resource) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("resource", resource);
-  if (defined(json) === defined(binary)) {
-    throw new DeveloperError("One of json and binary must be defined.");
-  }
   //>>includeEnd('debug');
 
-  let chunks;
-  if (defined(json)) {
-    chunks = {
-      json: json,
-      binary: undefined,
-    };
-  } else {
-    chunks = parseVoxelChunks(binary);
+  // Construct the glTF loader
+  const loader = new GltfLoader({
+    gltfResource: resource,
+    releaseGltfJson: false,
+    loadAttributesAsTypedArray: true,
+  });
+
+  try {
+    // This loads the gltf JSON and ensures the gltf is valid
+    // Further resource loading is handled synchronously in loader.process()
+    // via voxelContent.update() as the frameState is needed
+    await loader.load();
+  } catch (error) {
+    loader.destroy();
+    throw error;
   }
 
-  const buffersU8 = await requestBuffers(resource, chunks.json, chunks.binary);
-  const bufferViewsU8 = {};
-  const bufferViewsLength = chunks.json.bufferViews.length;
-  for (let i = 0; i < bufferViewsLength; ++i) {
-    const bufferViewJson = chunks.json.bufferViews[i];
-    const start = bufferViewJson.byteOffset;
-    const end = start + bufferViewJson.byteLength;
-    const buffer = buffersU8[bufferViewJson.buffer];
-    const bufferView = buffer.subarray(start, end);
-    bufferViewsU8[i] = bufferView;
+  return new VoxelContent({ loader });
+};
+
+/**
+ * Updates the content until all resources are ready for rendering.
+ * @param {FrameState} frameState The frame state
+ * @private
+ */
+VoxelContent.prototype.update = function (primitive, frameState) {
+  const loader = this._loader;
+
+  if (this._ready) {
+    // Nothing to do
+    return;
   }
 
-  const propertyTableIndex = chunks.json.voxelTable;
-  const propertyTableJson = chunks.json.propertyTables[propertyTableIndex];
+  // Ensures frames continue to render in requestRender mode while resources are processing
+  frameState.afterRender.push(() => true);
 
-  const content = new VoxelContent(resource);
+  if (!defined(loader)) {
+    this._ready = true;
+    return;
+  }
 
-  content._metadataTable = new MetadataTable({
-    count: propertyTableJson.count,
-    properties: propertyTableJson.properties,
-    class: metadataSchema.classes[propertyTableJson.class],
-    bufferViews: bufferViewsU8,
-  });
+  if (this._resourcesLoaded) {
+    const { structuralMetadata, scene } = loader.components;
+    const { attributes } = scene.nodes[0].primitives[0];
+    this._metadata = processAttributes(
+      attributes,
+      structuralMetadata,
+      primitive,
+    );
+    this._ready = true;
+    return;
+  }
 
-  return content;
+  this._resourcesLoaded = loader.process(frameState);
 };
 
-function requestBuffers(resource, json, binary) {
-  const buffersLength = json.buffers.length;
-  const bufferPromises = new Array(buffersLength);
-  for (let i = 0; i < buffersLength; i++) {
-    const buffer = json.buffers[i];
-    if (defined(buffer.uri)) {
-      const baseResource = resource;
-      const bufferResource = baseResource.getDerivedResource({
-        url: buffer.uri,
-      });
-      bufferPromises[i] = bufferResource
-        .fetchArrayBuffer()
-        .then(function (arrayBuffer) {
-          return new Uint8Array(arrayBuffer);
-        });
-    } else {
-      bufferPromises[i] = Promise.resolve(binary);
+/**
+ * Processes the attributes from the glTF loader, reordering them into the order expected by the primitive.
+ *
+ * @param {ModelComponents.Attribute[]} attributes The attributes to process
+ * @param {StructuralMetadata} structuralMetadata Information from the glTF EXT_structural_metadata extension
+ * @param {VoxelPrimitive} primitive The primitive for which this voxel content will be used.
+ * @returns {Int8Array[]|Uint8Array[]|Int16Array[]|Uint16Array[]|Int32Array[]|Uint32Array[]|Float32Array[]|Float64Array[]} An array of typed arrays containing the attribute values
+ * @private
+ */
+function processAttributes(attributes, structuralMetadata, primitive) {
+  const { className, names, types, componentTypes } = primitive.provider;
+  const propertyAttribute = structuralMetadata.propertyAttributes.find(
+    (p) => p.class.id === className,
+  );
+  const { properties } = propertyAttribute;
+  const data = new Array(names.length);
+
+  for (let i = 0; i < attributes.length; i++) {
+    // Find the appropriate glTF attribute based on its name.
+    const name = properties[names[i]].attribute;
+    const attribute = attributes.find((a) => a.name === name);
+    if (!defined(attribute)) {
+      continue;
     }
+
+    const componentDatatype = MetadataComponentType.toComponentDatatype(
+      componentTypes[i],
+    );
+    const componentCount = MetadataType.getComponentCount(types[i]);
+    const totalCount = attribute.count * componentCount;
+    data[i] = ComponentDatatype.createArrayBufferView(
+      componentDatatype,
+      attribute.typedArray.buffer,
+      attribute.typedArray.byteOffset + attribute.byteOffset,
+      totalCount,
+    );
   }
 
-  return Promise.all(bufferPromises);
+  return data;
 }
 
 /**
- * A helper object for storing the two parts of the binary voxel content
+ * Returns true if this object was destroyed; otherwise, false.
+ * <br /><br />
+ * If this object was destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
+ *
+ * @returns {boolean} <code>true</code> if this object was destroyed; otherwise, <code>false</code>.
+ *
+ * @see VoxelContent#destroy
  *
- * @typedef {object} VoxelChunks
- * @property {object} json The json chunk of the binary voxel content
- * @property {Uint8Array} binary The binary chunk of the binary voxel content. This represents the internal buffer.
  * @private
  */
+VoxelContent.prototype.isDestroyed = function () {
+  return false;
+};
 
 /**
- * Given binary voxel content, split into JSON and binary chunks
- *
- * @param {Uint8Array} binaryView The binary voxel content
- * @returns {VoxelChunks} An object containing the JSON and binary chunks
+ * Frees the resources used by this object.
  * @private
  */
-function parseVoxelChunks(binaryView) {
-  // Parse the header
-  const littleEndian = true;
-  const reader = new DataView(binaryView.buffer, binaryView.byteOffset);
-  // Skip to the chunk lengths
-  let byteOffset = 8;
-
-  // Read the bottom 32 bits of the 64-bit byte length. This is ok for now because:
-  // 1) not all browsers have native 64-bit operations
-  // 2) the data is well under 4GB
-  const jsonByteLength = reader.getUint32(byteOffset, littleEndian);
-  byteOffset += 8;
-  const binaryByteLength = reader.getUint32(byteOffset, littleEndian);
-  byteOffset += 8;
-
-  const json = getJsonFromTypedArray(binaryView, byteOffset, jsonByteLength);
-  byteOffset += jsonByteLength;
-  const binary = binaryView.subarray(byteOffset, byteOffset + binaryByteLength);
-
-  return {
-    json: json,
-    binary: binary,
-  };
-}
+VoxelContent.prototype.destroy = function () {
+  this._loader = this._loader && this._loader.destroy();
+  return destroyObject(this);
+};
 
 export default VoxelContent;