@cesium/engine 6.1.1 → 7.0.0

package/Source/Core/VerticalExaggeration.js

@@ -0,0 +1,69 @@
+import Cartesian3 from "./Cartesian3.js";
+import DeveloperError from "./DeveloperError.js";
+import defined from "./defined.js";
+
+/**
+ * @private
+ */
+const VerticalExaggeration = {};
+
+/**
+ * Scales a height relative to an offset.
+ *
+ * @param {number} height The height.
+ * @param {number} scale A scalar used to exaggerate the terrain. If the value is 1.0 there will be no effect.
+ * @param {number} relativeHeight The height relative to which terrain is exaggerated. If the value is 0.0 terrain will be exaggerated relative to the ellipsoid surface.
+ */
+VerticalExaggeration.getHeight = function (height, scale, relativeHeight) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!Number.isFinite(scale)) {
+    throw new DeveloperError("scale must be a finite number.");
+  }
+  if (!Number.isFinite(relativeHeight)) {
+    throw new DeveloperError("relativeHeight must be a finite number.");
+  }
+  //>>includeEnd('debug')
+  return (height - relativeHeight) * scale + relativeHeight;
+};
+
+const scratchCartographic = new Cartesian3();
+
+/**
+ * Scales a position by exaggeration.
+ *
+ * @param {Cartesian3} position The position.
+ * @param {Ellipsoid} ellipsoid The ellipsoid.
+ * @param {number} verticalExaggeration A scalar used to exaggerate the terrain. If the value is 1.0 there will be no effect.
+ * @param {number} verticalExaggerationRelativeHeight The height relative to which terrain is exaggerated. If the value is 0.0 terrain will be exaggerated relative to the ellipsoid surface.
+ * @param {Cartesian3} [result] The object onto which to store the result.
+ */
+VerticalExaggeration.getPosition = function (
+  position,
+  ellipsoid,
+  verticalExaggeration,
+  verticalExaggerationRelativeHeight,
+  result
+) {
+  const cartographic = ellipsoid.cartesianToCartographic(
+    position,
+    scratchCartographic
+  );
+  // If the position is too near the center of the ellipsoid, exaggeration is undefined.
+  if (!defined(cartographic)) {
+    return Cartesian3.clone(position, result);
+  }
+  const newHeight = VerticalExaggeration.getHeight(
+    cartographic.height,
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
+  );
+  return Cartesian3.fromRadians(
+    cartographic.longitude,
+    cartographic.latitude,
+    newHeight,
+    ellipsoid,
+    result
+  );
+};
+
+export default VerticalExaggeration;

package/Source/Core/createWorldBathymetryAsync.js

@@ -0,0 +1,45 @@
+import CesiumTerrainProvider from "./CesiumTerrainProvider.js";
+import defaultValue from "./defaultValue.js";
+
+/**
+ * Creates a {@link CesiumTerrainProvider} instance for the {@link https://cesium.com/content/#cesium-world-bathymetry|Cesium World Bathymetry}.
+ *
+ * @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.
+ * @returns {Promise<CesiumTerrainProvider>} A promise that resolves to the created CesiumTerrainProvider
+ *
+ * @see Ion
+ *
+ * @example
+ * // Create Cesium World Bathymetry with default settings
+ * try {
+ *   const viewer = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.createWorldBathymetryAsync();
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @example
+ * // Create Cesium World Bathymetry with normals.
+ * try {
+ *   const viewer1 = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.createWorldBathymetryAsync({
+ *       requestVertexNormals: true
+ *     });
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ */
+function createWorldBathymetryAsync(options) {
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+
+  return CesiumTerrainProvider.fromIonAssetId(2426648, {
+    requestVertexNormals: defaultValue(options.requestVertexNormals, false),
+  });
+}
+export default createWorldBathymetryAsync;

package/Source/DataSources/EllipsoidGeometryUpdater.js

@@ -547,11 +547,10 @@ DynamicEllipsoidGeometryUpdater.prototype.update = function (time) {
     options.radii = Cartesian3.clone(in3D ? unitSphere : radii, options.radii);
     if (defined(innerRadii)) {
       if (in3D) {
-        const mag = Cartesian3.magnitude(radii);
         options.innerRadii = Cartesian3.fromElements(
-          innerRadii.x / mag,
-          innerRadii.y / mag,
-          innerRadii.z / mag,
+          innerRadii.x / radii.x,
+          innerRadii.y / radii.y,
+          innerRadii.z / radii.z,
           options.innerRadii
         );
       } else {

package/Source/DataSources/Entity.js

@@ -13,7 +13,9 @@ import Quaternion from "../Core/Quaternion.js";
 import Transforms from "../Core/Transforms.js";
 import GroundPolylinePrimitive from "../Scene/GroundPolylinePrimitive.js";
 import GroundPrimitive from "../Scene/GroundPrimitive.js";
-import HeightReference from "../Scene/HeightReference.js";
+import HeightReference, {
+  isHeightReferenceClamp,
+} from "../Scene/HeightReference.js";
 import BillboardGraphics from "./BillboardGraphics.js";
 import BoxGraphics from "./BoxGraphics.js";
 import ConstantPositionProperty from "./ConstantPositionProperty.js";
@@ -71,8 +73,8 @@ function createPropertyTypeDescriptor(name, Type) {
  * @property {boolean} [show] A boolean value indicating if the entity and its children are displayed.
  * @property {Property | string} [description] A string Property specifying an HTML description for this entity.
  * @property {PositionProperty | Cartesian3} [position] A Property specifying the entity position.
- * @property {Property} [orientation] A Property specifying the entity orientation.
- * @property {Property} [viewFrom] A suggested initial offset for viewing this object.
+ * @property {Property | Quaternion} [orientation=Transforms.eastNorthUpToFixedFrame(position)] A Property specifying the entity orientation in respect to Earth-fixed-Earth-centered (ECEF). If undefined, east-north-up at entity position is used.
+ * @property {Property | Cartesian3} [viewFrom] A suggested initial offset for viewing this object.
  * @property {Entity} [parent] A parent entity to associate with this entity.
  * @property {BillboardGraphics | BillboardGraphics.ConstructorOptions} [billboard] A billboard to associate with this entity.
  * @property {BoxGraphics | BoxGraphics.ConstructorOptions} [box] A box to associate with this entity.
@@ -413,7 +415,8 @@ Object.defineProperties(Entity.prototype, {
    */
   tileset: createPropertyTypeDescriptor("tileset", Cesium3DTilesetGraphics),
   /**
-   * Gets or sets the orientation.
+   * Gets or sets the orientation in respect to Earth-fixed-Earth-centered (ECEF).
+   * Defaults to east-north-up at entity position.
    * @memberof Entity.prototype
    * @type {Property|undefined}
    */
@@ -706,7 +709,7 @@ Entity.prototype.computeModelMatrixForHeightReference = function (
   }
 
   const carto = ellipsoid.cartesianToCartographic(position, cartoScratch);
-  if (heightReference === HeightReference.CLAMP_TO_GROUND) {
+  if (isHeightReferenceClamp(heightReference)) {
     carto.height = heightOffset;
   } else {
     carto.height += heightOffset;

package/Source/DataSources/EntityCollection.js

@@ -5,7 +5,6 @@ import DeveloperError from "../Core/DeveloperError.js";
 import Event from "../Core/Event.js";
 import Iso8601 from "../Core/Iso8601.js";
 import JulianDate from "../Core/JulianDate.js";
-import RuntimeError from "../Core/RuntimeError.js";
 import TimeInterval from "../Core/TimeInterval.js";
 import Entity from "./Entity.js";
 
@@ -281,7 +280,7 @@ EntityCollection.prototype.add = function (entity) {
   const id = entity.id;
   const entities = this._entities;
   if (entities.contains(id)) {
-    throw new RuntimeError(
+    throw new DeveloperError(
       `An entity with id ${id} already exists in this collection.`
     );
   }

package/Source/DataSources/GeometryUpdater.js

@@ -233,8 +233,7 @@ Object.defineProperties(GeometryUpdater.prototype, {
   },
   /**
    * Gets a value indicating if the geometry is time-varying.
-   * If true, all visualization is delegated to a DynamicGeometryUpdater
-   * returned by GeometryUpdater#createDynamicUpdater.
+   *
    * @memberof GeometryUpdater.prototype
    *
    * @type {boolean}

package/Source/DataSources/GroundGeometryUpdater.js

@@ -5,7 +5,9 @@ import DeveloperError from "../Core/DeveloperError.js";
 import GeometryOffsetAttribute from "../Core/GeometryOffsetAttribute.js";
 import oneTimeWarning from "../Core/oneTimeWarning.js";
 import GroundPrimitive from "../Scene/GroundPrimitive.js";
-import HeightReference from "../Scene/HeightReference.js";
+import HeightReference, {
+  isHeightReferenceClamp,
+} from "../Scene/HeightReference.js";
 import CallbackProperty from "./CallbackProperty.js";
 import ConstantProperty from "./ConstantProperty.js";
 import GeometryUpdater from "./GeometryUpdater.js";
@@ -164,9 +166,10 @@ GroundGeometryUpdater.getGeometryHeight = function (height, heightReference) {
     return;
   }
 
-  if (heightReference !== HeightReference.CLAMP_TO_GROUND) {
+  if (!isHeightReferenceClamp(heightReference)) {
     return height;
   }
+
   return 0.0;
 };
 
@@ -186,7 +189,7 @@ GroundGeometryUpdater.getGeometryExtrudedHeight = function (
     }
     return;
   }
-  if (extrudedHeightReference !== HeightReference.CLAMP_TO_GROUND) {
+  if (!isHeightReferenceClamp(extrudedHeightReference)) {
     return extrudedHeight;
   }
 

package/Source/DataSources/ModelVisualizer.js

@@ -4,19 +4,22 @@ import Cartesian2 from "../Core/Cartesian2.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Check from "../Core/Check.js";
 import Color from "../Core/Color.js";
+import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
+import Ellipsoid from "../Core/Ellipsoid.js";
 import Matrix4 from "../Core/Matrix4.js";
 import Resource from "../Core/Resource.js";
 import ColorBlendMode from "../Scene/ColorBlendMode.js";
-import HeightReference from "../Scene/HeightReference.js";
+import HeightReference, {
+  isHeightReferenceClamp,
+} from "../Scene/HeightReference.js";
 import Model from "../Scene/Model/Model.js";
 import ModelAnimationLoop from "../Scene/ModelAnimationLoop.js";
 import ShadowMode from "../Scene/ShadowMode.js";
 import BoundingSphereState from "./BoundingSphereState.js";
 import Property from "./Property.js";
-import sampleTerrainMostDetailed from "../Core/sampleTerrainMostDetailed.js";
 import Cartographic from "../Core/Cartographic.js";
 
 const defaultScale = 1.0;
@@ -172,9 +175,6 @@ ModelVisualizer.prototype.update = function (time) {
         articulationsScratch: {},
         loadFailed: false,
         modelUpdated: false,
-        awaitingSampleTerrain: false,
-        clampedBoundingSphere: undefined,
-        sampleTerrainFailed: false,
       };
       modelHash[entity.id] = modelData;
 
@@ -399,9 +399,6 @@ ModelVisualizer.prototype.destroy = function () {
   return destroyObject(this);
 };
 
-// Used for testing.
-ModelVisualizer._sampleTerrainMostDetailed = sampleTerrainMostDetailed;
-
 const scratchPosition = new Cartesian3();
 const scratchCartographic = new Cartographic();
 /**
@@ -445,106 +442,30 @@ ModelVisualizer.prototype.getBoundingSphere = function (entity, result) {
 
   const scene = this._scene;
   const globe = scene.globe;
+  const ellipsoid = defaultValue(globe?.ellipsoid, Ellipsoid.WGS84);
 
-  // cannot access a terrain provider if there is no globe; formally set to undefined
-  const terrainProvider = defined(globe) ? globe.terrainProvider : undefined;
   const hasHeightReference = model.heightReference !== HeightReference.NONE;
-  if (defined(globe) && hasHeightReference) {
-    const ellipsoid = globe.ellipsoid;
+  if (hasHeightReference) {
     const modelMatrix = model.modelMatrix;
     scratchPosition.x = modelMatrix[12];
     scratchPosition.y = modelMatrix[13];
     scratchPosition.z = modelMatrix[14];
-    const cartoPosition = ellipsoid.cartesianToCartographic(scratchPosition);
-
-    // For a terrain provider that does not have availability, like the EllipsoidTerrainProvider,
-    // we can directly assign the bounding sphere's center from model matrix's translation.
-    if (!defined(terrainProvider.availability)) {
-      // Regardless of what the original model's position is set to, for CLAMP_TO_GROUND, we reset it to 0
-      // when computing the position to zoom/fly to.
-      if (model.heightReference === HeightReference.CLAMP_TO_GROUND) {
-        cartoPosition.height = 0;
-      }
-
-      const scratchPosition = ellipsoid.cartographicToCartesian(cartoPosition);
-      BoundingSphere.clone(model.boundingSphere, result);
-      result.center = scratchPosition;
-
-      return BoundingSphereState.DONE;
-    }
-
-    // Otherwise, in the case of terrain providers with availability,
-    // since the model's bounding sphere may be clamped to a lower LOD tile if
-    // the camera is initially far away, we use sampleTerrainMostDetailed to estimate
-    // where the bounding sphere should be and set that as the target bounding sphere
-    // for the camera.
-    let clampedBoundingSphere = this._modelHash[entity.id]
-      .clampedBoundingSphere;
-
-    // Check if the sample terrain function has failed.
-    const sampleTerrainFailed = this._modelHash[entity.id].sampleTerrainFailed;
-    if (sampleTerrainFailed) {
-      this._modelHash[entity.id].sampleTerrainFailed = false;
-      return BoundingSphereState.FAILED;
-    }
+    const cartoPosition = ellipsoid.cartesianToCartographic(
+      scratchPosition,
+      scratchCartographic
+    );
 
-    if (!defined(clampedBoundingSphere)) {
-      clampedBoundingSphere = new BoundingSphere();
-
-      // Since this function is called per-frame, we set a flag when sampleTerrainMostDetailed
-      // is called and check for it to avoid calling it again.
-      const awaitingSampleTerrain = this._modelHash[entity.id]
-        .awaitingSampleTerrain;
-      if (!awaitingSampleTerrain) {
-        Cartographic.clone(cartoPosition, scratchCartographic);
-        this._modelHash[entity.id].awaitingSampleTerrain = true;
-        ModelVisualizer._sampleTerrainMostDetailed(terrainProvider, [
-          scratchCartographic,
-        ])
-          .then((result) => {
-            if (this.isDestroyed()) {
-              return;
-            }
-
-            this._modelHash[entity.id].awaitingSampleTerrain = false;
-
-            const updatedCartographic = result[0];
-            if (model.heightReference === HeightReference.RELATIVE_TO_GROUND) {
-              updatedCartographic.height += cartoPosition.height;
-            }
-            ellipsoid.cartographicToCartesian(
-              updatedCartographic,
-              scratchPosition
-            );
-
-            // Update the bounding sphere with the updated position.
-            BoundingSphere.clone(model.boundingSphere, clampedBoundingSphere);
-            clampedBoundingSphere.center = scratchPosition;
-
-            this._modelHash[
-              entity.id
-            ].clampedBoundingSphere = BoundingSphere.clone(
-              clampedBoundingSphere
-            );
-          })
-          .catch((e) => {
-            if (this.isDestroyed()) {
-              return;
-            }
-
-            this._modelHash[entity.id].sampleTerrainFailed = true;
-            this._modelHash[entity.id].awaitingSampleTerrain = false;
-          });
+    const height = scene.getHeight(cartoPosition, model.heightReference);
+    if (defined(height)) {
+      if (isHeightReferenceClamp(model.heightReference)) {
+        cartoPosition.height = height;
+      } else {
+        cartoPosition.height += height;
       }
-
-      // We will return the state as pending until the clamped bounding sphere is defined,
-      // which happens when the sampleTerrainMostDetailed promise returns.
-      return BoundingSphereState.PENDING;
     }
 
-    BoundingSphere.clone(clampedBoundingSphere, result);
-    // Reset the clamped bounding sphere.
-    this._modelHash[entity.id].clampedBoundingSphere = undefined;
+    BoundingSphere.clone(model.boundingSphere, result);
+    result.center = ellipsoid.cartographicToCartesian(cartoPosition);
     return BoundingSphereState.DONE;
   }
 

package/Source/DataSources/PolygonGeometryUpdater.js

@@ -418,8 +418,14 @@ PolygonGeometryUpdater.prototype._setStaticOptions = function (
     extrudedHeightReferenceValue
   );
   if (extrudedHeightValue === GroundGeometryUpdater.CLAMP_TO_GROUND) {
+    const rectangle = PolygonGeometry.computeRectangleFromPositions(
+      options.polygonHierarchy.positions,
+      options.ellipsoid,
+      options.arcType,
+      scratchRectangle
+    );
     extrudedHeightValue = ApproximateTerrainHeights.getMinimumMaximumHeights(
-      PolygonGeometry.computeRectangle(options, scratchRectangle)
+      rectangle
     ).minimumTerrainHeight;
   }
 
@@ -565,8 +571,14 @@ DyanmicPolygonGeometryUpdater.prototype._setOptions = function (
     extrudedHeightReferenceValue
   );
   if (extrudedHeightValue === GroundGeometryUpdater.CLAMP_TO_GROUND) {
+    const rectangle = PolygonGeometry.computeRectangleFromPositions(
+      options.polygonHierarchy.positions,
+      options.ellipsoid,
+      options.arcType,
+      scratchRectangle
+    );
     extrudedHeightValue = ApproximateTerrainHeights.getMinimumMaximumHeights(
-      PolygonGeometry.computeRectangle(options, scratchRectangle)
+      rectangle
     ).minimumTerrainHeight;
   }
 

package/Source/DataSources/PolylineGeometryUpdater.js

@@ -249,8 +249,7 @@ Object.defineProperties(PolylineGeometryUpdater.prototype, {
   },
   /**
    * Gets a value indicating if the geometry is time-varying.
-   * If true, all visualization is delegated to the {@link DynamicGeometryUpdater}
-   * returned by GeometryUpdater#createDynamicUpdater.
+   *
    * @memberof PolylineGeometryUpdater.prototype
    *
    * @type {boolean}
@@ -661,12 +660,13 @@ function getLine(dynamicGeometryUpdater) {
     return dynamicGeometryUpdater._line;
   }
 
-  const sceneId = dynamicGeometryUpdater._geometryUpdater._scene.id;
-  let polylineCollection = polylineCollections[sceneId];
   const primitives = dynamicGeometryUpdater._primitives;
+  const polylineCollectionId =
+    dynamicGeometryUpdater._geometryUpdater._scene.id + primitives._guid;
+  let polylineCollection = polylineCollections[polylineCollectionId];
   if (!defined(polylineCollection) || polylineCollection.isDestroyed()) {
     polylineCollection = new PolylineCollection();
-    polylineCollections[sceneId] = polylineCollection;
+    polylineCollections[polylineCollectionId] = polylineCollection;
     primitives.add(polylineCollection);
   } else if (!primitives.contains(polylineCollection)) {
     primitives.add(polylineCollection);
@@ -869,13 +869,14 @@ DynamicGeometryUpdater.prototype.isDestroyed = function () {
 
 DynamicGeometryUpdater.prototype.destroy = function () {
   const geometryUpdater = this._geometryUpdater;
-  const sceneId = geometryUpdater._scene.id;
-  const polylineCollection = polylineCollections[sceneId];
+  const polylineCollectionId =
+    geometryUpdater._scene.id + this._primitives._guid;
+  const polylineCollection = polylineCollections[polylineCollectionId];
   if (defined(polylineCollection)) {
     polylineCollection.remove(this._line);
     if (polylineCollection.length === 0) {
       this._primitives.removeAndDestroy(polylineCollection);
-      delete polylineCollections[sceneId];
+      delete polylineCollections[polylineCollectionId];
     }
   }
   if (defined(this._groundPolylinePrimitive)) {

package/Source/DataSources/TerrainOffsetProperty.js

@@ -6,12 +6,12 @@ import destroyObject from "../Core/destroyObject.js";
 import Event from "../Core/Event.js";
 import Iso8601 from "../Core/Iso8601.js";
 import CesiumMath from "../Core/Math.js";
-import HeightReference from "../Scene/HeightReference.js";
-import SceneMode from "../Scene/SceneMode.js";
+import HeightReference, {
+  isHeightReferenceRelative,
+} from "../Scene/HeightReference.js";
 import Property from "./Property.js";
 
 const scratchPosition = new Cartesian3();
-const scratchCarto = new Cartographic();
 
 /**
  * @private
@@ -118,40 +118,32 @@ TerrainOffsetProperty.prototype._updateClamping = function () {
   const globe = scene.globe;
   const position = this._position;
 
-  if (!defined(globe) || Cartesian3.equals(position, Cartesian3.ZERO)) {
+  if (Cartesian3.equals(position, Cartesian3.ZERO)) {
     this._terrainHeight = 0;
     return;
   }
   const ellipsoid = globe.ellipsoid;
-  const surface = globe._surface;
-
-  const that = this;
   const cartographicPosition = ellipsoid.cartesianToCartographic(
     position,
     this._cartographicPosition
   );
-  const height = globe.getHeight(cartographicPosition);
+
+  const height = scene.getHeight(cartographicPosition, this._heightReference);
   if (defined(height)) {
     this._terrainHeight = height;
   } else {
     this._terrainHeight = 0;
   }
 
-  function updateFunction(clampedPosition) {
-    if (scene.mode === SceneMode.SCENE3D) {
-      const carto = ellipsoid.cartesianToCartographic(
-        clampedPosition,
-        scratchCarto
-      );
-      that._terrainHeight = carto.height;
-    } else {
-      that._terrainHeight = clampedPosition.x;
-    }
-    that.definitionChanged.raiseEvent();
-  }
-  this._removeCallbackFunc = surface.updateHeight(
+  const updateFunction = (clampedPosition) => {
+    this._terrainHeight = clampedPosition.height;
+    this.definitionChanged.raiseEvent();
+  };
+
+  this._removeCallbackFunc = scene.updateHeight(
     cartographicPosition,
-    updateFunction
+    updateFunction,
+    this._heightReference
   );
 };
 
@@ -174,7 +166,7 @@ TerrainOffsetProperty.prototype.getValue = function (time, result) {
 
   if (
     heightReference === HeightReference.NONE &&
-    extrudedHeightReference !== HeightReference.RELATIVE_TO_GROUND
+    !isHeightReferenceRelative(extrudedHeightReference)
   ) {
     this._position = Cartesian3.clone(Cartesian3.ZERO, this._position);
     return Cartesian3.clone(Cartesian3.ZERO, result);