@cesium/engine 2.0.0 → 2.2.0

package/Source/Scene/Cesium3DTilesVoxelProvider.js

@@ -2,7 +2,7 @@ import Cartesian3 from "../Core/Cartesian3.js";
 import Check from "../Core/Check.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
-import DeveloperError from "../Core/DeveloperError.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
 import Matrix4 from "../Core/Matrix4.js";
 import OrientedBoundingBox from "../Core/OrientedBoundingBox.js";
@@ -28,14 +28,18 @@ import VoxelShapeType from "./VoxelShapeType.js";
  * <p>
  * Implements the {@link VoxelProvider} interface.
  * </p>
+ * <div class="notice">
+ * This object is normally not instantiated directly, use {@link Cesium3DTilesVoxelProvider.fromUrl}.
+ * </div>
  *
  * @alias Cesium3DTilesVoxelProvider
  * @constructor
  * @augments VoxelProvider
  *
- * @param {Object} options Object with the following properties:
- * @param {Resource|String|Promise<Resource>|Promise<String>} options.url The URL to a tileset JSON file.
+ * @param {object} options Object with the following properties:
+ * @param {Resource|string|Promise<Resource>|Promise<string>} [options.url] The URL to a tileset JSON file. Deprecated.
  *
+ * @see Cesium3DTilesVoxelProvider.fromUrl
  * @see VoxelProvider
  * @see VoxelPrimitive
  * @see VoxelShapeType
@@ -44,12 +48,7 @@ import VoxelShapeType from "./VoxelShapeType.js";
  */
 function Cesium3DTilesVoxelProvider(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
-  //>>includeStart('debug', pragmas.debug)
-  Check.defined("options.url", options.url);
-  //>>includeEnd('debug');
-
-  /** @inheritdoc */
-  this.ready = false;
+  this._ready = false;
 
   /** @inheritdoc */
   this.shapeTransform = undefined;
@@ -99,83 +98,202 @@ function Cesium3DTilesVoxelProvider(options) {
   const that = this;
   let tilesetJson;
 
-  this._readyPromise = Promise.resolve(options.url).then(function (url) {
-    const resource = Resource.createIfNeeded(url);
-    return resource
-      .fetchJson()
-      .then(function (tileset) {
-        tilesetJson = tileset;
-        validate(tilesetJson);
-        return getMetadataSchemaLoader(tilesetJson, resource).promise;
-      })
-      .then(function (schemaLoader) {
-        const root = tilesetJson.root;
-        const voxel = root.content.extensions["3DTILES_content_voxels"];
-        const className = voxel.class;
-
-        const metadataJson = hasExtension(tilesetJson, "3DTILES_metadata")
-          ? tilesetJson.extensions["3DTILES_metadata"]
-          : tilesetJson;
-
-        const metadataSchema = schemaLoader.schema;
-        const metadata = new Cesium3DTilesetMetadata({
-          metadataJson: metadataJson,
-          schema: metadataSchema,
-        });
+  if (defined(options.url)) {
+    deprecationWarning(
+      "Cesium3DTilesVoxelProvider options.url",
+      "Cesium3DTilesVoxelProvider constructor parameter options.url was deprecated in CesiumJS 1.104. It will be removed in 1.107. Use Cesium3DTilesVoxelProvider.fromUrl instead."
+    );
 
-        addAttributeInfo(that, metadata, className);
+    this._readyPromise = Promise.resolve(options.url).then(function (url) {
+      const resource = Resource.createIfNeeded(url);
+      return resource
+        .fetchJson()
+        .then(function (tileset) {
+          tilesetJson = tileset;
+          validate(tilesetJson);
+          const schemaLoader = getMetadataSchemaLoader(tilesetJson, resource);
+          return schemaLoader.load();
+        })
+        .then(function (schemaLoader) {
+          const root = tilesetJson.root;
+          const voxel = root.content.extensions["3DTILES_content_voxels"];
+          const className = voxel.class;
+
+          const metadataJson = hasExtension(tilesetJson, "3DTILES_metadata")
+            ? tilesetJson.extensions["3DTILES_metadata"]
+            : tilesetJson;
+
+          const metadataSchema = schemaLoader.schema;
+          const metadata = new Cesium3DTilesetMetadata({
+            metadataJson: metadataJson,
+            schema: metadataSchema,
+          });
+
+          addAttributeInfo(that, metadata, className);
+
+          const implicitTileset = new ImplicitTileset(
+            resource,
+            root,
+            metadataSchema
+          );
+
+          const {
+            shape,
+            minBounds,
+            maxBounds,
+            shapeTransform,
+            globalTransform,
+          } = getShape(root);
+
+          that.shape = shape;
+          that.minBounds = minBounds;
+          that.maxBounds = maxBounds;
+          that.dimensions = Cartesian3.unpack(voxel.dimensions);
+          that.shapeTransform = shapeTransform;
+          that.globalTransform = globalTransform;
+          that.maximumTileCount = getTileCount(metadata);
+
+          let paddingBefore;
+          let paddingAfter;
+
+          if (defined(voxel.padding)) {
+            paddingBefore = Cartesian3.unpack(voxel.padding.before);
+            paddingAfter = Cartesian3.unpack(voxel.padding.after);
+          }
+
+          that.paddingBefore = paddingBefore;
+          that.paddingAfter = paddingAfter;
+
+          that._implicitTileset = implicitTileset;
+
+          ResourceCache.unload(schemaLoader);
+
+          that._ready = true;
+          return that;
+        });
+    });
+  }
+}
 
-        const implicitTileset = new ImplicitTileset(
-          resource,
-          root,
-          metadataSchema
-        );
+Object.defineProperties(Cesium3DTilesVoxelProvider.prototype, {
+  /**
+   * Gets the promise that will be resolved when the provider is ready for use.
+   *
+   * @memberof Cesium3DTilesVoxelProvider.prototype
+   * @type {Promise<Cesium3DTilesVoxelProvider>}
+   * @readonly
+   * @deprecated
+   */
+  readyPromise: {
+    get: function () {
+      deprecationWarning(
+        "Cesium3DTilesVoxelProvider.readyPromise",
+        "Cesium3DTilesVoxelProvider.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Use Cesium3DTilesVoxelProvider.fromUrl instead."
+      );
+      return this._readyPromise;
+    },
+  },
 
-        const {
-          shape,
-          minBounds,
-          maxBounds,
-          shapeTransform,
-          globalTransform,
-        } = getShape(root);
+  /**
+   * Gets a value indicating whether or not the provider is ready for use.
+   *
+   * @memberof Cesium3DTilesVoxelProvider.prototype
+   * @type {boolean}
+   * @readonly
+   * @deprecated
+   */
+  ready: {
+    get: function () {
+      deprecationWarning(
+        "Cesium3DTilesVoxelProvider.ready",
+        "Cesium3DTilesVoxelProvider.ready was deprecated in CesiumJS 1.104. It will be removed in 1.107. Use Cesium3DTilesVoxelProvider.fromUrl instead."
+      );
+      return this._ready;
+    },
+  },
+});
 
-        that.shape = shape;
-        that.minBounds = minBounds;
-        that.maxBounds = maxBounds;
-        that.dimensions = Cartesian3.unpack(voxel.dimensions);
-        that.shapeTransform = shapeTransform;
-        that.globalTransform = globalTransform;
-        that.maximumTileCount = getTileCount(metadata);
+/**
+ * Creates a {@link VoxelProvider} that fetches voxel data from a 3D Tiles tileset.
+ *
+ * @param {Resource|string} url The URL to a tileset JSON file
+ * @returns {Promise<Cesium3DTilesVoxelProvider>} The created provider
+ *
+ * @exception {RuntimeException} Root must have content
+ * @exception {RuntimeException} Root tile content must have 3DTILES_content_voxels extension
+ * @exception {RuntimeException} Root tile must have implicit tiling
+ * @exception {RuntimeException} Tileset must have a metadata schema
+ * @exception {RuntimeException} Only box, region and 3DTILES_bounding_volume_cylinder are supported in Cesium3DTilesVoxelProvider
+ */
+Cesium3DTilesVoxelProvider.fromUrl = async function (url) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("url", url);
+  //>>includeEnd('debug');
 
-        let paddingBefore;
-        let paddingAfter;
+  const resource = Resource.createIfNeeded(url);
+  const tilesetJson = await resource.fetchJson();
 
-        if (defined(voxel.padding)) {
-          paddingBefore = Cartesian3.unpack(voxel.padding.before);
-          paddingAfter = Cartesian3.unpack(voxel.padding.after);
-        }
+  validate(tilesetJson);
 
-        that.paddingBefore = paddingBefore;
-        that.paddingAfter = paddingAfter;
+  const schemaLoader = getMetadataSchemaLoader(tilesetJson, resource);
+  await schemaLoader.load();
 
-        that._implicitTileset = implicitTileset;
+  const root = tilesetJson.root;
+  const voxel = root.content.extensions["3DTILES_content_voxels"];
+  const className = voxel.class;
 
-        ResourceCache.unload(schemaLoader);
+  const metadataJson = hasExtension(tilesetJson, "3DTILES_metadata")
+    ? tilesetJson.extensions["3DTILES_metadata"]
+    : tilesetJson;
 
-        that.ready = true;
-        return that;
-      });
+  const metadataSchema = schemaLoader.schema;
+  const metadata = new Cesium3DTilesetMetadata({
+    metadataJson: metadataJson,
+    schema: metadataSchema,
   });
-}
 
-Object.defineProperties(Cesium3DTilesVoxelProvider.prototype, {
-  /** @inheritdoc */
-  readyPromise: {
-    get: function () {
-      return this._readyPromise;
-    },
-  },
-});
+  const provider = new Cesium3DTilesVoxelProvider();
+
+  addAttributeInfo(provider, metadata, className);
+
+  const implicitTileset = new ImplicitTileset(resource, root, metadataSchema);
+
+  const {
+    shape,
+    minBounds,
+    maxBounds,
+    shapeTransform,
+    globalTransform,
+  } = getShape(root);
+
+  provider.shape = shape;
+  provider.minBounds = minBounds;
+  provider.maxBounds = maxBounds;
+  provider.dimensions = Cartesian3.unpack(voxel.dimensions);
+  provider.shapeTransform = shapeTransform;
+  provider.globalTransform = globalTransform;
+  provider.maximumTileCount = getTileCount(metadata);
+
+  let paddingBefore;
+  let paddingAfter;
+
+  if (defined(voxel.padding)) {
+    paddingBefore = Cartesian3.unpack(voxel.padding.before);
+    paddingAfter = Cartesian3.unpack(voxel.padding.after);
+  }
+
+  provider.paddingBefore = paddingBefore;
+  provider.paddingAfter = paddingAfter;
+
+  provider._implicitTileset = implicitTileset;
+
+  ResourceCache.unload(schemaLoader);
+
+  provider._ready = true;
+  provider._readyPromise = Promise.resolve(provider);
+
+  return provider;
+};
 
 function getTileCount(metadata) {
   if (!defined(metadata.tileset)) {
@@ -306,9 +424,9 @@ function getCylinderShape(cylinder, tileTransform) {
 function getMetadataSchemaLoader(tilesetJson, resource) {
   const { schemaUri, schema } = tilesetJson;
   if (!defined(schemaUri)) {
-    return ResourceCache.loadSchema({ schema });
+    return ResourceCache.getSchemaLoader({ schema });
   }
-  return ResourceCache.loadSchema({
+  return ResourceCache.getSchemaLoader({
     resource: resource.getDerivedResource({
       url: schemaUri,
     }),
@@ -356,7 +474,7 @@ function copyArray(values, length) {
   return Array.from({ length }, (v, i) => valuesArray[i]);
 }
 
-function getVoxelPromise(implicitTileset, tileCoordinates) {
+async function getVoxelContent(implicitTileset, tileCoordinates) {
   const voxelRelative = implicitTileset.contentUriTemplates[0].getDerivedResource(
     {
       templateValues: tileCoordinates.getTemplateValues(),
@@ -366,29 +484,28 @@ function getVoxelPromise(implicitTileset, tileCoordinates) {
     url: voxelRelative.url,
   });
 
-  return voxelResource.fetchArrayBuffer().then(function (arrayBuffer) {
-    const preprocessed = preprocess3DTileContent(arrayBuffer);
+  const arrayBuffer = await voxelResource.fetchArrayBuffer();
+  const preprocessed = preprocess3DTileContent(arrayBuffer);
 
-    const voxelContent = new VoxelContent(
-      voxelResource,
-      preprocessed.jsonPayload,
-      preprocessed.binaryPayload,
-      implicitTileset.metadataSchema
-    );
+  const voxelContent = await VoxelContent.fromJson(
+    voxelResource,
+    preprocessed.jsonPayload,
+    preprocessed.binaryPayload,
+    implicitTileset.metadataSchema
+  );
 
-    return voxelContent.readyPromise;
-  });
+  return voxelContent;
 }
 
-function getSubtreePromise(provider, subtreeCoord) {
+async function getSubtreePromise(provider, subtreeCoord) {
   const implicitTileset = provider._implicitTileset;
   const subtreeCache = provider._subtreeCache;
 
   // First load the subtree to check if the tile is available.
   // If the subtree has been requested previously it might still be in the cache
-  const subtree = subtreeCache.find(subtreeCoord);
+  let subtree = subtreeCache.find(subtreeCoord);
   if (defined(subtree)) {
-    return subtree.readyPromise;
+    return subtree;
   }
 
   const subtreeRelative = implicitTileset.subtreeUriTemplate.getDerivedResource(
@@ -400,38 +517,29 @@ function getSubtreePromise(provider, subtreeCoord) {
     url: subtreeRelative.url,
   });
 
-  return subtreeResource.fetchArrayBuffer().then(function (arrayBuffer) {
-    // Check one more time if the subtree is in the cache.
-    // This could happen if there are two in-flight tile requests from the same
-    // subtree and one finishes before the other.
-    let subtree = subtreeCache.find(subtreeCoord);
-    if (defined(subtree)) {
-      return subtree.readyPromise;
-    }
+  const arrayBuffer = await subtreeResource.fetchArrayBuffer();
+  // Check one more time if the subtree is in the cache.
+  // This could happen if there are two in-flight tile requests from the same
+  // subtree and one finishes before the other.
+  subtree = subtreeCache.find(subtreeCoord);
+  if (defined(subtree)) {
+    return subtree;
+  }
 
-    const preprocessed = preprocess3DTileContent(arrayBuffer);
-    subtree = new ImplicitSubtree(
-      subtreeResource,
-      preprocessed.jsonPayload,
-      preprocessed.binaryPayload,
-      implicitTileset,
-      subtreeCoord
-    );
-    subtreeCache.addSubtree(subtree);
-    return subtree.readyPromise;
-  });
+  const preprocessed = preprocess3DTileContent(arrayBuffer);
+  subtree = await ImplicitSubtree.fromSubtreeJson(
+    subtreeResource,
+    preprocessed.jsonPayload,
+    preprocessed.binaryPayload,
+    implicitTileset,
+    subtreeCoord
+  );
+  subtreeCache.addSubtree(subtree);
+  return subtree;
 }
 
 /** @inheritdoc */
 Cesium3DTilesVoxelProvider.prototype.requestData = function (options) {
-  //>>includeStart('debug', pragmas.debug);
-  if (!this.ready) {
-    throw new DeveloperError(
-      "The provider is not ready. Use Cesium3DTilesVoxelProvider.readyPromise or wait for Cesium3DTilesVoxelProvider.ready to be true."
-    );
-  }
-  //>>includeEnd('debug');
-
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
   const tileLevel = defaultValue(options.tileLevel, 0);
   const tileX = defaultValue(options.tileX, 0);
@@ -482,7 +590,7 @@ Cesium3DTilesVoxelProvider.prototype.requestData = function (options) {
         return Promise.reject("Tile is not available");
       }
 
-      return getVoxelPromise(implicitTileset, tileCoordinates);
+      return getVoxelContent(implicitTileset, tileCoordinates);
     })
     .then(function (voxelContent) {
       return names.map(function (name) {