@cesium/engine 6.1.1 → 7.0.0

package/Source/Scene/Scene.js

@@ -18,6 +18,7 @@ import Event from "../Core/Event.js";
 import GeographicProjection from "../Core/GeographicProjection.js";
 import GeometryInstance from "../Core/GeometryInstance.js";
 import GeometryPipeline from "../Core/GeometryPipeline.js";
+import HeightReference from "./HeightReference.js";
 import Intersect from "../Core/Intersect.js";
 import JulianDate from "../Core/JulianDate.js";
 import CesiumMath from "../Core/Math.js";
@@ -37,6 +38,7 @@ import Context from "../Renderer/Context.js";
 import ContextLimits from "../Renderer/ContextLimits.js";
 import Pass from "../Renderer/Pass.js";
 import RenderState from "../Renderer/RenderState.js";
+import Atmosphere from "./Atmosphere.js";
 import BrdfLutGenerator from "./BrdfLutGenerator.js";
 import Camera from "./Camera.js";
 import Cesium3DTilePass from "./Cesium3DTilePass.js";
@@ -46,6 +48,7 @@ import DebugCameraPrimitive from "./DebugCameraPrimitive.js";
 import DepthPlane from "./DepthPlane.js";
 import DerivedCommand from "./DerivedCommand.js";
 import DeviceOrientationCameraController from "./DeviceOrientationCameraController.js";
+import DynamicAtmosphereLightingType from "./DynamicAtmosphereLightingType.js";
 import Fog from "./Fog.js";
 import FrameState from "./FrameState.js";
 import GlobeTranslucencyState from "./GlobeTranslucencyState.js";
@@ -164,6 +167,7 @@ function Scene(options) {
   this._groundPrimitives = new PrimitiveCollection();
 
   this._globeHeight = undefined;
+  this._globeHeightDirty = undefined;
   this._cameraUnderground = false;
 
   this._logDepthBuffer = context.fragmentDepth;
@@ -356,6 +360,24 @@ function Scene(options) {
    */
   this.nearToFarDistance2D = 1.75e6;
 
+  /**
+   * The vertical exaggeration of the scene.
+   * When set to 1.0, no exaggeration is applied.
+   *
+   * @type {number}
+   * @default 1.0
+   */
+  this.verticalExaggeration = 1.0;
+
+  /**
+   * The reference height for vertical exaggeration of the scene.
+   * When set to 0.0, the exaggeration is applied relative to the ellipsoid surface.
+   *
+   * @type {number}
+   * @default 0.0
+   */
+  this.verticalExaggerationRelativeHeight = 0.0;
+
   /**
    * This property is for debugging only; it is not for production use.
    * <p>
@@ -494,6 +516,14 @@ function Scene(options) {
    */
   this.cameraEventWaitTime = 500.0;
 
+  /**
+   * Settings for atmosphere lighting effects affecting 3D Tiles and model rendering. This is not to be confused with
+   * {@link Scene#skyAtmosphere} which is responsible for rendering the sky.
+   *
+   * @type {Atmosphere}
+   */
+  this.atmosphere = new Atmosphere();
+
   /**
    * Blends the atmosphere to geometry far from the camera for horizon views. Allows for additional
    * performance improvements by rendering less geometry and dispatching less terrain requests.
@@ -720,6 +750,11 @@ function updateGlobeListeners(scene, globe) {
         requestRenderAfterFrame(scene)
       )
     );
+    removeGlobeCallbacks.push(
+      globe.tileLoadProgressEvent.addEventListener(() => {
+        scene._globeHeightDirty = true;
+      })
+    );
   }
   scene._removeGlobeCallbacks = removeGlobeCallbacks;
 }
@@ -1880,10 +1915,17 @@ Scene.prototype.updateFrameState = function () {
   frameState.cameraUnderground = this._cameraUnderground;
   frameState.globeTranslucencyState = this._globeTranslucencyState;
 
-  if (defined(this.globe)) {
-    frameState.terrainExaggeration = this.globe.terrainExaggeration;
-    frameState.terrainExaggerationRelativeHeight = this.globe.terrainExaggerationRelativeHeight;
+  const { globe } = this;
+  if (defined(globe) && globe._terrainExaggerationChanged) {
+    // Honor a user-set value for the old deprecated globe.terrainExaggeration.
+    // This can be removed when Globe.terrainExaggeration is removed.
+    this.verticalExaggeration = globe._terrainExaggeration;
+    this.verticalExaggerationRelativeHeight =
+      globe._terrainExaggerationRelativeHeight;
+    globe._terrainExaggerationChanged = false;
   }
+  frameState.verticalExaggeration = this.verticalExaggeration;
+  frameState.verticalExaggerationRelativeHeight = this.verticalExaggerationRelativeHeight;
 
   if (
     defined(this._specularEnvironmentMapAtlas) &&
@@ -3142,6 +3184,7 @@ Scene.prototype.updateEnvironment = function () {
   const environmentState = this._environmentState;
   const renderPass = frameState.passes.render;
   const offscreenPass = frameState.passes.offscreen;
+  const atmosphere = this.atmosphere;
   const skyAtmosphere = this.skyAtmosphere;
   const globe = this.globe;
   const globeTranslucencyState = this._globeTranslucencyState;
@@ -3160,17 +3203,19 @@ Scene.prototype.updateEnvironment = function () {
   } else {
     if (defined(skyAtmosphere)) {
       if (defined(globe)) {
-        skyAtmosphere.setDynamicAtmosphereColor(
-          globe.enableLighting && globe.dynamicAtmosphereLighting,
-          globe.dynamicAtmosphereLightingFromSun
+        skyAtmosphere.setDynamicLighting(
+          DynamicAtmosphereLightingType.fromGlobeFlags(globe)
         );
         environmentState.isReadyForAtmosphere =
           environmentState.isReadyForAtmosphere ||
           !globe.show ||
           globe._surface._tilesToRender.length > 0;
       } else {
+        const dynamicLighting = atmosphere.dynamicLighting;
+        skyAtmosphere.setDynamicLighting(dynamicLighting);
         environmentState.isReadyForAtmosphere = true;
       }
+
       environmentState.skyAtmosphereCommand = skyAtmosphere.update(
         frameState,
         globe
@@ -3576,19 +3621,178 @@ function callAfterRenderFunctions(scene) {
 }
 
 function getGlobeHeight(scene) {
-  const globe = scene._globe;
+  if (scene.mode === SceneMode.MORPHING) {
+    return;
+  }
+
   const camera = scene.camera;
   const cartographic = camera.positionCartographic;
-  if (defined(globe) && globe.show && defined(cartographic)) {
-    return globe.getHeight(cartographic);
+  return scene.getHeight(cartographic);
+}
+
+/**
+ * Gets the height of the loaded surface at the cartographic position.
+ * @param {Cartographic} cartographic The cartographic position.
+ * @param {HeightReference} [heightReference=CLAMP_TO_GROUND] Based on the height reference value, determines whether to ignore heights from 3D Tiles or terrain.
+ * @private
+ */
+Scene.prototype.getHeight = function (cartographic, heightReference) {
+  if (!defined(cartographic)) {
+    return undefined;
+  }
+
+  const ignore3dTiles =
+    heightReference === HeightReference.CLAMP_TO_TERRAIN ||
+    heightReference === HeightReference.RELATIVE_TO_TERRAIN;
+
+  const ignoreTerrain =
+    heightReference === HeightReference.CLAMP_TO_3D_TILE ||
+    heightReference === HeightReference.RELATIVE_TO_3D_TILE;
+
+  if (!defined(cartographic)) {
+    return;
+  }
+
+  let maxHeight = Number.NEGATIVE_INFINITY;
+
+  if (!ignore3dTiles) {
+    const length = this.primitives.length;
+    for (let i = 0; i < length; ++i) {
+      const primitive = this.primitives.get(i);
+      if (
+        !primitive.isCesium3DTileset ||
+        !primitive.show ||
+        primitive.disableCollision
+      ) {
+        continue;
+      }
+
+      const result = primitive.getHeight(cartographic, this);
+      if (defined(result) && result > maxHeight) {
+        maxHeight = result;
+      }
+    }
   }
+
+  const globe = this._globe;
+  if (!ignoreTerrain && defined(globe) && globe.show) {
+    const result = globe.getHeight(cartographic);
+    if (result > maxHeight) {
+      maxHeight = result;
+    }
+  }
+
+  if (maxHeight > Number.NEGATIVE_INFINITY) {
+    return maxHeight;
+  }
+
   return undefined;
-}
+};
+
+const updateHeightScratchCartographic = new Cartographic();
+/**
+ * Calls the callback when a new tile is rendered that contains the given cartographic. The only parameter
+ * is the cartesian position on the tile.
+ *
+ * @private
+ *
+ * @param {Cartographic} cartographic The cartographic position.
+ * @param {Function} callback The function to be called when a new tile is loaded containing the updated cartographic.
+ * @param {HeightReference} [heightReference=CLAMP_TO_GROUND] Based on the height reference value, determines whether to ignore heights from 3D Tiles or terrain.
+ * @returns {Function} The function to remove this callback from the quadtree.
+ */
+Scene.prototype.updateHeight = function (
+  cartographic,
+  callback,
+  heightReference
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.func("callback", callback);
+  //>>includeEnd('debug');
+
+  const callbackWrapper = () => {
+    Cartographic.clone(cartographic, updateHeightScratchCartographic);
+
+    const height = this.getHeight(cartographic, heightReference);
+    if (defined(height)) {
+      updateHeightScratchCartographic.height = height;
+      callback(updateHeightScratchCartographic);
+    }
+  };
+
+  const ignore3dTiles =
+    heightReference === HeightReference.CLAMP_TO_TERRAIN ||
+    heightReference === HeightReference.RELATIVE_TO_TERRAIN;
+
+  const ignoreTerrain =
+    heightReference === HeightReference.CLAMP_TO_3D_TILE ||
+    heightReference === HeightReference.RELATIVE_TO_3D_TILE;
+
+  let terrainRemoveCallback;
+  if (!ignoreTerrain && defined(this.globe)) {
+    terrainRemoveCallback = this.globe._surface.updateHeight(
+      cartographic,
+      callbackWrapper
+    );
+  }
+
+  let tilesetRemoveCallbacks = {};
+  const ellipsoid = this.globe?.ellipsoid;
+  const createPrimitiveEventListener = (primitive) => {
+    if (
+      ignore3dTiles ||
+      !primitive.isCesium3DTileset ||
+      primitive.disableCollision
+    ) {
+      return;
+    }
+
+    const tilesetRemoveCallback = primitive.updateHeight(
+      cartographic,
+      callbackWrapper,
+      ellipsoid
+    );
+    tilesetRemoveCallbacks[primitive.id] = tilesetRemoveCallback;
+  };
+
+  if (!ignore3dTiles) {
+    const length = this.primitives.length;
+    for (let i = 0; i < length; ++i) {
+      const primitive = this.primitives.get(i);
+      createPrimitiveEventListener(primitive);
+    }
+  }
+
+  const removeAddedListener = this.primitives.primitiveAdded.addEventListener(
+    createPrimitiveEventListener
+  );
+  const removeRemovedListener = this.primitives.primitiveRemoved.addEventListener(
+    (primitive) => {
+      if (!primitive.isCesium3DTileset) {
+        return;
+      }
+
+      tilesetRemoveCallbacks[primitive.id]();
+      delete tilesetRemoveCallbacks[primitive.id];
+    }
+  );
+
+  const removeCallback = () => {
+    terrainRemoveCallback = terrainRemoveCallback && terrainRemoveCallback();
+    Object.values(tilesetRemoveCallbacks).forEach((tilesetRemoveCallback) =>
+      tilesetRemoveCallback()
+    );
+    tilesetRemoveCallbacks = {};
+    removeAddedListener();
+    removeRemovedListener();
+  };
+
+  return removeCallback;
+};
 
 function isCameraUnderground(scene) {
   const camera = scene.camera;
   const mode = scene._mode;
-  const globe = scene.globe;
   const cameraController = scene._screenSpaceCameraController;
   const cartographic = camera.positionCartographic;
 
@@ -3602,12 +3806,7 @@ function isCameraUnderground(scene) {
     return true;
   }
 
-  if (
-    !defined(globe) ||
-    !globe.show ||
-    mode === SceneMode.SCENE2D ||
-    mode === SceneMode.MORPHING
-  ) {
+  if (mode === SceneMode.SCENE2D || mode === SceneMode.MORPHING) {
     return false;
   }
 
@@ -3628,7 +3827,10 @@ Scene.prototype.initializeFrame = function () {
 
   this._tweens.update();
 
-  this._globeHeight = getGlobeHeight(this);
+  if (this._globeHeightDirty) {
+    this._globeHeight = getGlobeHeight(this);
+    this._globeHeightDirty = false;
+  }
   this._cameraUnderground = isCameraUnderground(this);
   this._globeTranslucencyState.update(this);
 
@@ -3715,6 +3917,7 @@ function render(scene) {
   }
   frameState.backgroundColor = backgroundColor;
 
+  frameState.atmosphere = scene.atmosphere;
   scene.fog.update(frameState);
 
   us.update(frameState);
@@ -3803,8 +4006,12 @@ Scene.prototype.render = function (time) {
     time = JulianDate.now();
   }
 
-  // Determine if shouldRender
   const cameraChanged = this._view.checkForCameraUpdates(this);
+  if (cameraChanged) {
+    this._globeHeightDirty = true;
+  }
+
+  // Determine if should render a new frame in request render mode
   let shouldRender =
     !this.requestRenderMode ||
     this._renderRequested ||

package/Source/Scene/ScreenSpaceCameraController.js

@@ -17,7 +17,7 @@ import OrthographicFrustum from "../Core/OrthographicFrustum.js";
 import Plane from "../Core/Plane.js";
 import Quaternion from "../Core/Quaternion.js";
 import Ray from "../Core/Ray.js";
-import TerrainExaggeration from "../Core/TerrainExaggeration.js";
+import VerticalExaggeration from "../Core/VerticalExaggeration.js";
 import Transforms from "../Core/Transforms.js";
 import CameraEventAggregator from "./CameraEventAggregator.js";
 import CameraEventType from "./CameraEventType.js";
@@ -2861,16 +2861,12 @@ function adjustHeightForTerrain(controller) {
   const mode = scene.mode;
   const globe = scene.globe;
 
-  if (
-    !defined(globe) ||
-    mode === SceneMode.SCENE2D ||
-    mode === SceneMode.MORPHING
-  ) {
+  if (mode === SceneMode.SCENE2D || mode === SceneMode.MORPHING) {
     return;
   }
 
   const camera = scene.camera;
-  const ellipsoid = globe.ellipsoid;
+  const ellipsoid = defaultValue(globe?.ellipsoid, Ellipsoid.WGS84);
   const projection = scene.mapProjection;
 
   let transform;
@@ -2948,9 +2944,7 @@ const scratchPreviousDirection = new Cartesian3();
  */
 ScreenSpaceCameraController.prototype.update = function () {
   const scene = this._scene;
-  const camera = scene.camera;
-  const globe = scene.globe;
-  const mode = scene.mode;
+  const { camera, globe, mode } = scene;
 
   if (!Matrix4.equals(camera.transform, Matrix4.IDENTITY)) {
     this._globe = undefined;
@@ -2962,26 +2956,21 @@ ScreenSpaceCameraController.prototype.update = function () {
       : scene.mapProjection.ellipsoid;
   }
 
-  const exaggeration = defined(this._globe)
-    ? this._globe.terrainExaggeration
-    : 1.0;
-  const exaggerationRelativeHeight = defined(this._globe)
-    ? this._globe.terrainExaggerationRelativeHeight
-    : 0.0;
-  this._minimumCollisionTerrainHeight = TerrainExaggeration.getHeight(
+  const { verticalExaggeration, verticalExaggerationRelativeHeight } = scene;
+  this._minimumCollisionTerrainHeight = VerticalExaggeration.getHeight(
     this.minimumCollisionTerrainHeight,
-    exaggeration,
-    exaggerationRelativeHeight
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
   );
-  this._minimumPickingTerrainHeight = TerrainExaggeration.getHeight(
+  this._minimumPickingTerrainHeight = VerticalExaggeration.getHeight(
     this.minimumPickingTerrainHeight,
-    exaggeration,
-    exaggerationRelativeHeight
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
   );
-  this._minimumTrackBallHeight = TerrainExaggeration.getHeight(
+  this._minimumTrackBallHeight = VerticalExaggeration.getHeight(
     this.minimumTrackBallHeight,
-    exaggeration,
-    exaggerationRelativeHeight
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
   );
 
   this._cameraUnderground = scene.cameraUnderground && defined(this._globe);

package/Source/Scene/SkyAtmosphere.js

@@ -217,14 +217,13 @@ Object.defineProperties(SkyAtmosphere.prototype, {
 });
 
 /**
+ * Set the dynamic lighting enum value for the shader
+ * @param {DynamicAtmosphereLightingType} lightingEnum The enum that determines the dynamic atmosphere light source
+ *
  * @private
  */
-SkyAtmosphere.prototype.setDynamicAtmosphereColor = function (
-  enableLighting,
-  useSunDirection
-) {
-  const lightEnum = enableLighting ? (useSunDirection ? 2.0 : 1.0) : 0.0;
-  this._radiiAndDynamicAtmosphereColor.z = lightEnum;
+SkyAtmosphere.prototype.setDynamicLighting = function (lightingEnum) {
+  this._radiiAndDynamicAtmosphereColor.z = lightingEnum;
 };
 
 const scratchModelMatrix = new Matrix4();

package/Source/Scene/Terrain.js

@@ -1,5 +1,6 @@
 import Check from "../Core/Check.js";
 import Event from "../Core/Event.js";
+import createWorldBathymetryAsync from "../Core/createWorldBathymetryAsync.js";
 import createWorldTerrainAsync from "../Core/createWorldTerrainAsync.js";
 
 /**
@@ -156,6 +157,54 @@ Terrain.fromWorldTerrain = function (options) {
   return new Terrain(createWorldTerrainAsync(options));
 };
 
+/**
+ * Creates a {@link Terrain} instance for {@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 {Terrain} An asynchronous helper object for a CesiumTerrainProvider
+ *
+ * @see Ion
+ * @see createWorldBathymetryAsync
+ *
+ * @example
+ * // Create Cesium World Bathymetry with default settings
+ * const viewer = new Cesium.Viewer("cesiumContainer", {
+ *   terrain: Cesium.Terrain.fromWorldBathymetry)
+ * });
+ *
+ * @example
+ * // Create Cesium World Terrain with normals.
+ * const viewer1 = new Cesium.Viewer("cesiumContainer", {
+ *   terrain: Cesium.Terrain.fromWorldBathymetry({
+ *      requestVertexNormals: true
+ *    });
+ * });
+ *
+ * @example
+ * // Handle loading events
+ * const bathymetry = Cesium.Terrain.fromWorldBathymetry();
+ *
+ * scene.setTerrain(bathymetry);
+ *
+ * bathymetry.readyEvent.addEventListener(provider => {
+ *   scene.globe.enableLighting = true;
+ *
+ *   bathymetry.provider.errorEvent.addEventListener(error => {
+ *     alert(`Encountered an error while loading bathymetric terrain tiles! ${error}`);
+ *   });
+ * });
+ *
+ * bathymetry.errorEvent.addEventListener(error => {
+ *   alert(`Encountered an error while creating bathymetric terrain! ${error}`);
+ * });
+ */
+Terrain.fromWorldBathymetry = function (options) {
+  return new Terrain(createWorldBathymetryAsync(options));
+};
+
 function handleError(errorEvent, error) {
   if (errorEvent.numberOfListeners > 0) {
     errorEvent.raiseEvent(error);

package/Source/Scene/TerrainFillMesh.js

@@ -830,9 +830,9 @@ function createFillMesh(tileProvider, frameState, tile, vertexArraysToDestroy) {
   const fill = surfaceTile.fill;
   const rectangle = tile.rectangle;
 
-  const exaggeration = frameState.terrainExaggeration;
+  const exaggeration = frameState.verticalExaggeration;
   const exaggerationRelativeHeight =
-    frameState.terrainExaggerationRelativeHeight;
+    frameState.verticalExaggerationRelativeHeight;
   const hasExaggeration = exaggeration !== 1.0;
 
   const ellipsoid = tile.tilingScheme.ellipsoid;

package/Source/Scene/TileBoundingS2Cell.js

@@ -330,7 +330,7 @@ Object.defineProperties(TileBoundingS2Cell.prototype, {
   /**
    * The underlying bounding volume.
    *
-   * @memberof TileOrientedBoundingBox.prototype
+   * @memberof TileBoundingS2Cell.prototype
    *
    * @type {object}
    * @readonly
@@ -343,7 +343,7 @@ Object.defineProperties(TileBoundingS2Cell.prototype, {
   /**
    * The underlying bounding sphere.
    *
-   * @memberof TileOrientedBoundingBox.prototype
+   * @memberof TileBoundingS2Cell.prototype
    *
    * @type {BoundingSphere}
    * @readonly

package/Source/Scene/TileOrientedBoundingBox.js

@@ -106,7 +106,7 @@ Object.defineProperties(TileOrientedBoundingBox.prototype, {
    *
    * @memberof TileOrientedBoundingBox.prototype
    *
-   * @type {object}
+   * @type {OrientedBoundingBox}
    * @readonly
    */
   boundingVolume: {

package/Source/Scene/Tileset3DTileContent.js

@@ -168,6 +168,10 @@ Tileset3DTileContent.prototype.applyStyle = function (style) {};
 
 Tileset3DTileContent.prototype.update = function (tileset, frameState) {};
 
+Tileset3DTileContent.prototype.pick = function (ray, frameState, result) {
+  return undefined;
+};
+
 Tileset3DTileContent.prototype.isDestroyed = function () {
   return false;
 };

package/Source/Scene/Vector3DTileContent.js

@@ -727,6 +727,10 @@ Vector3DTileContent.prototype.update = function (tileset, frameState) {
   }
 };
 
+Vector3DTileContent.prototype.pick = function (ray, frameState, result) {
+  return undefined;
+};
+
 Vector3DTileContent.prototype.getPolylinePositions = function (batchId) {
   const polylines = this._polylines;
   if (!defined(polylines)) {