@cesium/engine 2.1.0 → 2.2.0

package/Source/Core/createWorldTerrain.js

@@ -1,5 +1,6 @@
 import CesiumTerrainProvider from "./CesiumTerrainProvider.js";
 import defaultValue from "./defaultValue.js";
+import deprecationWarning from "./deprecationWarning.js";
 import IonResource from "./IonResource.js";
 
 /**
@@ -31,12 +32,29 @@ import IonResource from "./IonResource.js";
  *
  */
 function createWorldTerrain(options) {
+  deprecationWarning(
+    "createWorldTerrain",
+    "createWorldTerrain was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use createWorldTerrainAsync instead."
+  );
+
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
-  return new CesiumTerrainProvider({
-    url: IonResource.fromAssetId(1),
+  const provider = new CesiumTerrainProvider({
     requestVertexNormals: defaultValue(options.requestVertexNormals, false),
     requestWaterMask: defaultValue(options.requestWaterMask, false),
   });
+
+  // This is here in order to avoid throwing a second deprecation error
+  // by using the deprecated url parameter in the constructor above
+  provider._readyPromise = CesiumTerrainProvider._initializeReadyPromise(
+    {
+      url: IonResource.fromAssetId(1),
+      requestVertexNormals: defaultValue(options.requestVertexNormals, false),
+      requestWaterMask: defaultValue(options.requestWaterMask, false),
+    },
+    provider
+  );
+
+  return provider;
 }
 export default createWorldTerrain;

package/Source/Core/createWorldTerrainAsync.js

@@ -0,0 +1,48 @@
+import CesiumTerrainProvider from "./CesiumTerrainProvider.js";
+import defaultValue from "./defaultValue.js";
+
+/**
+ * Creates a {@link CesiumTerrainProvider} instance for the {@link https://cesium.com/content/#cesium-world-terrain|Cesium World Terrain}.
+ *
+ * @function
+ *
+ * @param {Object} [options] Object with the following properties:
+ * @param {Boolean} [options.requestVertexNormals=false] Flag that indicates if the client should request additional lighting information from the server if available.
+ * @param {Boolean} [options.requestWaterMask=false] Flag that indicates if the client should request per tile water masks from the server if available.
+ * @returns {Promise<CesiumTerrainProvider>} A promise that resolves to the created CesiumTerrainProvider
+ *
+ * @see Ion
+ *
+ * @example
+ * // Create Cesium World Terrain with default settings
+ * try {
+ *   const viewer = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.createWorldTerrainAsync();
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @example
+ * // Create Cesium World Terrain with water and normals.
+ * try {
+ *   const viewer1 = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.createWorldTerrainAsync({
+ *       requestWaterMask: true,
+ *       requestVertexNormals: true
+ *     });
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ */
+function createWorldTerrainAsync(options) {
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+
+  return CesiumTerrainProvider.fromIonAssetId(1, {
+    requestVertexNormals: defaultValue(options.requestVertexNormals, false),
+    requestWaterMask: defaultValue(options.requestWaterMask, false),
+  });
+}
+export default createWorldTerrainAsync;

package/Source/Core/sampleTerrain.js

@@ -26,27 +26,26 @@ import defined from "./defined.js";
  *
  * @example
  * // Query the terrain height of two Cartographic positions
- * const terrainProvider = Cesium.createWorldTerrain();
+ * const terrainProvider = await Cesium.createWorldTerrainAsync();
  * const positions = [
  *     Cesium.Cartographic.fromDegrees(86.925145, 27.988257),
  *     Cesium.Cartographic.fromDegrees(87.0, 28.0)
  * ];
- * const promise = Cesium.sampleTerrain(terrainProvider, 11, positions);
- * Promise.resolve(promise).then(function(updatedPositions) {
- *     // positions[0].height and positions[1].height have been updated.
- *     // updatedPositions is just a reference to positions.
- * });
+ * const updatedPositions = await Cesium.sampleTerrain(terrainProvider, 11, positions);
+ * // positions[0].height and positions[1].height have been updated.
+ * // updatedPositions is just a reference to positions.
  */
-function sampleTerrain(terrainProvider, level, positions) {
+async function sampleTerrain(terrainProvider, level, positions) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("terrainProvider", terrainProvider);
   Check.typeOf.number("level", level);
   Check.defined("positions", positions);
   //>>includeEnd('debug');
 
-  return terrainProvider.readyPromise.then(function () {
-    return doSampling(terrainProvider, level, positions);
-  });
+  // readyPromise has been deprecated; This is here for backwards compatibility
+  await terrainProvider._readyPromise;
+
+  return doSampling(terrainProvider, level, positions);
 }
 
 /**

package/Source/Core/sampleTerrainMostDetailed.js

@@ -17,18 +17,16 @@ const scratchCartesian2 = new Cartesian2();
  *
  * @example
  * // Query the terrain height of two Cartographic positions
- * const terrainProvider = Cesium.createWorldTerrain();
+ * const terrainProvider = await Cesium.createWorldTerrainAsync();
  * const positions = [
  *     Cesium.Cartographic.fromDegrees(86.925145, 27.988257),
  *     Cesium.Cartographic.fromDegrees(87.0, 28.0)
  * ];
- * const promise = Cesium.sampleTerrainMostDetailed(terrainProvider, positions);
- * Promise.resolve(promise).then(function(updatedPositions) {
- *     // positions[0].height and positions[1].height have been updated.
- *     // updatedPositions is just a reference to positions.
- * });
+ * const updatedPositions = await Cesium.sampleTerrainMostDetailed(terrainProvider, positions);
+ * // positions[0].height and positions[1].height have been updated.
+ * // updatedPositions is just a reference to positions.
  */
-function sampleTerrainMostDetailed(terrainProvider, positions) {
+async function sampleTerrainMostDetailed(terrainProvider, positions) {
   //>>includeStart('debug', pragmas.debug);
   if (!defined(terrainProvider)) {
     throw new DeveloperError("terrainProvider is required.");
@@ -38,80 +36,76 @@ function sampleTerrainMostDetailed(terrainProvider, positions) {
   }
   //>>includeEnd('debug');
 
-  return terrainProvider.readyPromise.then(function () {
-    const byLevel = [];
-    const maxLevels = [];
+  const byLevel = [];
+  const maxLevels = [];
 
-    const availability = terrainProvider.availability;
+  // readyPromise has been deprecated; This is here for backwards compatibility
+  await terrainProvider._readyPromise;
 
-    //>>includeStart('debug', pragmas.debug);
-    if (!defined(availability)) {
-      throw new DeveloperError(
-        "sampleTerrainMostDetailed requires a terrain provider that has tile availability."
+  const availability = terrainProvider.availability;
+
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(availability)) {
+    throw new DeveloperError(
+      "sampleTerrainMostDetailed requires a terrain provider that has tile availability."
+    );
+  }
+  //>>includeEnd('debug');
+
+  const promises = [];
+  for (let i = 0; i < positions.length; ++i) {
+    const position = positions[i];
+    const maxLevel = availability.computeMaximumLevelAtPosition(position);
+    maxLevels[i] = maxLevel;
+    if (maxLevel === 0) {
+      // This is a special case where we have a parent terrain and we are requesting
+      // heights from an area that isn't covered by the top level terrain at all.
+      // This will essentially trigger the loading of the parent terrains root tile
+      terrainProvider.tilingScheme.positionToTileXY(
+        position,
+        1,
+        scratchCartesian2
+      );
+      const promise = terrainProvider.loadTileDataAvailability(
+        scratchCartesian2.x,
+        scratchCartesian2.y,
+        1
       );
+      if (defined(promise)) {
+        promises.push(promise);
+      }
     }
-    //>>includeEnd('debug');
 
-    const promises = [];
-    for (let i = 0; i < positions.length; ++i) {
-      const position = positions[i];
-      const maxLevel = availability.computeMaximumLevelAtPosition(position);
-      maxLevels[i] = maxLevel;
-      if (maxLevel === 0) {
-        // This is a special case where we have a parent terrain and we are requesting
-        // heights from an area that isn't covered by the top level terrain at all.
-        // This will essentially trigger the loading of the parent terrains root tile
-        terrainProvider.tilingScheme.positionToTileXY(
-          position,
-          1,
-          scratchCartesian2
-        );
-        const promise = terrainProvider.loadTileDataAvailability(
-          scratchCartesian2.x,
-          scratchCartesian2.y,
-          1
-        );
-        if (defined(promise)) {
-          promises.push(promise);
-        }
-      }
+    let atLevel = byLevel[maxLevel];
+    if (!defined(atLevel)) {
+      byLevel[maxLevel] = atLevel = [];
+    }
+    atLevel.push(position);
+  }
 
-      let atLevel = byLevel[maxLevel];
-      if (!defined(atLevel)) {
-        byLevel[maxLevel] = atLevel = [];
+  await Promise.all(promises);
+  await Promise.all(
+    byLevel.map(function (positionsAtLevel, index) {
+      if (defined(positionsAtLevel)) {
+        return sampleTerrain(terrainProvider, index, positionsAtLevel);
       }
-      atLevel.push(position);
-    }
+    })
+  );
+  const changedPositions = [];
+  for (let i = 0; i < positions.length; ++i) {
+    const position = positions[i];
+    const maxLevel = availability.computeMaximumLevelAtPosition(position);
 
-    return Promise.all(promises)
-      .then(function () {
-        return Promise.all(
-          byLevel.map(function (positionsAtLevel, index) {
-            if (defined(positionsAtLevel)) {
-              return sampleTerrain(terrainProvider, index, positionsAtLevel);
-            }
-          })
-        );
-      })
-      .then(function () {
-        const changedPositions = [];
-        for (let i = 0; i < positions.length; ++i) {
-          const position = positions[i];
-          const maxLevel = availability.computeMaximumLevelAtPosition(position);
+    if (maxLevel !== maxLevels[i]) {
+      // Now that we loaded the max availability, a higher level has become available
+      changedPositions.push(position);
+    }
+  }
 
-          if (maxLevel !== maxLevels[i]) {
-            // Now that we loaded the max availability, a higher level has become available
-            changedPositions.push(position);
-          }
-        }
+  if (changedPositions.length > 0) {
+    await sampleTerrainMostDetailed(terrainProvider, changedPositions);
+  }
 
-        if (changedPositions.length > 0) {
-          return sampleTerrainMostDetailed(terrainProvider, changedPositions);
-        }
-      })
-      .then(function () {
-        return positions;
-      });
-  });
+  return positions;
 }
 export default sampleTerrainMostDetailed;

package/Source/DataSources/Cesium3DTilesetVisualizer.js

@@ -65,7 +65,7 @@ Cesium3DTilesetVisualizer.prototype.update = function (time) {
     const tilesetGraphics = entity._tileset;
 
     let resource;
-    let tilesetData = tilesetHash[entity.id];
+    const tilesetData = tilesetHash[entity.id];
     const show =
       entity.isShowing &&
       entity.isAvailable(time) &&
@@ -86,28 +86,21 @@ Cesium3DTilesetVisualizer.prototype.update = function (time) {
       continue;
     }
 
-    let tileset = defined(tilesetData)
+    const tileset = defined(tilesetData)
       ? tilesetData.tilesetPrimitive
       : undefined;
-    if (!defined(tileset) || resource.url !== tilesetData.url) {
+    if (!defined(tilesetData) || resource.url !== tilesetData.url) {
       if (defined(tileset)) {
         primitives.removeAndDestroy(tileset);
-        delete tilesetHash[entity.id];
       }
-      tileset = new Cesium3DTileset({
-        url: resource,
-      });
-      tileset.id = entity;
-      primitives.add(tileset);
-
-      tilesetData = {
-        tilesetPrimitive: tileset,
-        url: resource.url,
-        loadFail: false,
-      };
-      tilesetHash[entity.id] = tilesetData;
-
-      checkLoad(tileset, entity, tilesetHash);
+
+      delete tilesetHash[entity.id];
+
+      createTileset(resource, tilesetHash, entity, primitives);
+    }
+
+    if (!defined(tileset)) {
+      continue;
     }
 
     tileset.show = true;
@@ -180,12 +173,12 @@ Cesium3DTilesetVisualizer.prototype.getBoundingSphere = function (
   }
 
   const primitive = tilesetData.tilesetPrimitive;
-  if (!defined(primitive) || !primitive.show) {
-    return BoundingSphereState.FAILED;
+  if (!defined(primitive)) {
+    return BoundingSphereState.PENDING;
   }
 
-  if (!primitive.ready) {
-    return BoundingSphereState.PENDING;
+  if (!primitive.show) {
+    return BoundingSphereState.FAILED;
   }
 
   BoundingSphere.clone(primitive.boundingSphere, result);
@@ -235,15 +228,33 @@ Cesium3DTilesetVisualizer.prototype._onCollectionChanged = function (
 function removeTileset(visualizer, entity, tilesetHash, primitives) {
   const tilesetData = tilesetHash[entity.id];
   if (defined(tilesetData)) {
-    primitives.removeAndDestroy(tilesetData.tilesetPrimitive);
+    if (defined(tilesetData.tilesetPrimitive)) {
+      primitives.removeAndDestroy(tilesetData.tilesetPrimitive);
+    }
     delete tilesetHash[entity.id];
   }
 }
 
-function checkLoad(primitive, entity, tilesetHash) {
-  primitive.readyPromise.catch(function (error) {
+async function createTileset(resource, tilesetHash, entity, primitives) {
+  tilesetHash[entity.id] = {
+    url: resource.url,
+    loadFail: false,
+  };
+
+  try {
+    const tileset = await Cesium3DTileset.fromUrl(resource);
+    tileset.id = entity;
+    primitives.add(tileset);
+
+    if (!defined(tilesetHash[entity.id])) {
+      return;
+    }
+
+    tilesetHash[entity.id].tilesetPrimitive = tileset;
+  } catch (error) {
     console.error(error);
     tilesetHash[entity.id].loadFail = true;
-  });
+  }
 }
+
 export default Cesium3DTilesetVisualizer;

package/Source/DataSources/Entity.js

@@ -597,7 +597,12 @@ Entity.prototype.merge = function (source) {
     //While source is required by the API to be an Entity, we internally call this method from the
     //constructor with an options object to configure initial custom properties.
     //So we need to ignore reserved-non-property.
-    if (name === "parent" || name === "name" || name === "availability") {
+    if (
+      name === "parent" ||
+      name === "name" ||
+      name === "availability" ||
+      name === "children"
+    ) {
       continue;
     }
 

package/Source/DataSources/ModelVisualizer.js

@@ -36,6 +36,9 @@ const modelMatrixScratch = new Matrix4();
 const nodeMatrixScratch = new Matrix4();
 
 const scratchColor = new Color();
+const scratchArray = new Array(4);
+const scratchCartesian = new Cartesian3();
+
 /**
  * A {@link Visualizer} which maps {@link Entity#model} to a {@link Model}.
  * @alias ModelVisualizer
@@ -63,6 +66,52 @@ function ModelVisualizer(scene, entityCollection) {
   this._onCollectionChanged(entityCollection, entityCollection.values, [], []);
 }
 
+async function createModelPrimitive(
+  visualizer,
+  entity,
+  resource,
+  incrementallyLoadTextures
+) {
+  const primitives = visualizer._primitives;
+  const modelHash = visualizer._modelHash;
+
+  try {
+    const model = await Model.fromGltfAsync({
+      url: resource,
+      incrementallyLoadTextures: incrementallyLoadTextures,
+      scene: visualizer._scene,
+    });
+
+    if (visualizer.isDestroyed() || !defined(modelHash[entity.id])) {
+      return;
+    }
+
+    model.id = entity;
+    primitives.add(model);
+    modelHash[entity.id].modelPrimitive = model;
+    model.errorEvent.addEventListener((error) => {
+      if (!defined(modelHash[entity.id])) {
+        return;
+      }
+
+      console.log(error);
+
+      // Texture failures when incrementallyLoadTextures
+      // will not affect the ability to compute the bounding sphere
+      if (error.name !== "TextureError" && model.incrementallyLoadTextures) {
+        modelHash[entity.id].loadFailed = true;
+      }
+    });
+  } catch (error) {
+    if (visualizer.isDestroyed() || !defined(modelHash[entity.id])) {
+      return;
+    }
+
+    console.log(error);
+    modelHash[entity.id].loadFailed = true;
+  }
+}
+
 /**
  * Updates models created this visualizer to match their
  * Entity counterpart at the given time.
@@ -102,45 +151,44 @@ ModelVisualizer.prototype.update = function (time) {
     }
 
     if (!show) {
-      if (defined(modelData)) {
+      if (defined(modelData) && modelData.modelPrimitive) {
         modelData.modelPrimitive.show = false;
       }
       continue;
     }
 
-    let model = defined(modelData) ? modelData.modelPrimitive : undefined;
-    if (!defined(model) || resource.url !== modelData.url) {
-      if (defined(model)) {
-        primitives.removeAndDestroy(model);
+    if (!defined(modelData) || resource.url !== modelData.url) {
+      if (defined(modelData?.modelPrimitive)) {
+        primitives.removeAndDestroy(modelData.modelPrimitive);
         delete modelHash[entity.id];
       }
 
-      model = Model.fromGltf({
-        url: resource,
-        incrementallyLoadTextures: Property.getValueOrDefault(
-          modelGraphics._incrementallyLoadTextures,
-          time,
-          defaultIncrementallyLoadTextures
-        ),
-        scene: this._scene,
-      });
-      model.id = entity;
-      primitives.add(model);
-
       modelData = {
-        modelPrimitive: model,
+        modelPrimitive: undefined,
         url: resource.url,
         animationsRunning: false,
         nodeTransformationsScratch: {},
         articulationsScratch: {},
-        loadFail: false,
+        loadFailed: false,
+        modelUpdated: false,
         awaitingSampleTerrain: false,
         clampedBoundingSphere: undefined,
         sampleTerrainFailed: false,
       };
       modelHash[entity.id] = modelData;
 
-      checkModelLoad(model, entity, modelHash);
+      const incrementallyLoadTextures = Property.getValueOrDefault(
+        modelGraphics._incrementallyLoadTextures,
+        time,
+        defaultIncrementallyLoadTextures
+      );
+
+      createModelPrimitive(this, entity, resource, incrementallyLoadTextures);
+    }
+
+    const model = modelData.modelPrimitive;
+    if (!defined(model)) {
+      continue;
     }
 
     model.show = true;
@@ -214,15 +262,27 @@ ModelVisualizer.prototype.update = function (time) {
       time,
       defaultImageBasedLightingFactor
     );
-    model.lightColor = Property.getValueOrUndefined(
+    let lightColor = Property.getValueOrUndefined(
       modelGraphics._lightColor,
       time
     );
+
+    // Convert from Color to Cartesian3
+    if (defined(lightColor)) {
+      Color.pack(lightColor, scratchArray, 0);
+      lightColor = Cartesian3.unpack(scratchArray, 0, scratchCartesian);
+    }
+
+    model.lightColor = lightColor;
     model.customShader = Property.getValueOrUndefined(
       modelGraphics._customShader,
       time
     );
 
+    // It's possible for getBoundingSphere to run before
+    // model becomes ready and these properties are updated
+    modelHash[entity.id].modelUpdated = true;
+
     if (model.ready) {
       const runAnimations = Property.getValueOrDefault(
         modelGraphics._runAnimations,
@@ -365,18 +425,23 @@ ModelVisualizer.prototype.getBoundingSphere = function (entity, result) {
   //>>includeEnd('debug');
 
   const modelData = this._modelHash[entity.id];
-  if (!defined(modelData) || modelData.loadFail) {
+  if (!defined(modelData)) {
+    return BoundingSphereState.FAILED;
+  }
+
+  if (modelData.loadFailed) {
     return BoundingSphereState.FAILED;
   }
 
   const model = modelData.modelPrimitive;
   if (!defined(model) || !model.show) {
-    return BoundingSphereState.FAILED;
+    return BoundingSphereState.PENDING;
   }
 
-  if (!model.ready) {
+  if (!model.ready || !modelData.modelUpdated) {
     return BoundingSphereState.PENDING;
   }
+
   const scene = this._scene;
   const globe = scene.globe;
   const ellipsoid = globe.ellipsoid;
@@ -386,7 +451,8 @@ ModelVisualizer.prototype.getBoundingSphere = function (entity, result) {
   if (hasHeightReference) {
     // We cannot query the availability of the terrain provider till its ready, so the
     // bounding sphere state will remain pending till the terrain provider is ready.
-    if (!terrainProvider.ready) {
+    // ready is deprecated. This is here for backwards compatibility
+    if (!terrainProvider._ready) {
       return BoundingSphereState.PENDING;
     }
 
@@ -441,6 +507,10 @@ ModelVisualizer.prototype.getBoundingSphere = function (entity, result) {
           scratchCartographic,
         ])
           .then((result) => {
+            if (this.isDestroyed()) {
+              return;
+            }
+
             this._modelHash[entity.id].awaitingSampleTerrain = false;
 
             const updatedCartographic = result[0];
@@ -463,6 +533,10 @@ ModelVisualizer.prototype.getBoundingSphere = function (entity, result) {
             );
           })
           .catch((e) => {
+            if (this.isDestroyed()) {
+              return;
+            }
+
             this._modelHash[entity.id].sampleTerrainFailed = true;
             this._modelHash[entity.id].awaitingSampleTerrain = false;
           });
@@ -539,10 +613,4 @@ function clearNodeTransformationsArticulationsScratch(entity, modelHash) {
   }
 }
 
-function checkModelLoad(model, entity, modelHash) {
-  model.readyPromise.catch(function (error) {
-    console.error(error);
-    modelHash[entity.id].loadFail = true;
-  });
-}
 export default ModelVisualizer;

package/Source/DataSources/PolygonGraphics.js

@@ -21,7 +21,7 @@ function createPolygonHierarchyProperty(value) {
  * Initialization options for the PolygonGraphics constructor
  *
  * @property {Property | boolean} [show=true] A boolean Property specifying the visibility of the polygon.
- * @property {Property | PolygonHierarchy} [hierarchy] A Property specifying the {@link PolygonHierarchy}.
+ * @property {Property | PolygonHierarchy | Cartesian3[]} [hierarchy] A Property specifying the {@link PolygonHierarchy}.
  * @property {Property | number} [height=0] A numeric Property specifying the altitude of the polygon relative to the ellipsoid surface.
  * @property {Property | HeightReference} [heightReference=HeightReference.NONE] A Property specifying what the height is relative to.
  * @property {Property | number} [extrudedHeight] A numeric Property specifying the altitude of the polygon's extruded face relative to the ellipsoid surface.