@cesium/engine 6.2.0 → 8.0.0

package/Source/Scene/Atmosphere.js

@@ -0,0 +1,127 @@
+import Cartesian3 from "../Core/Cartesian3.js";
+import DynamicAtmosphereLightingType from "./DynamicAtmosphereLightingType.js";
+
+/**
+ * Common atmosphere settings used by 3D Tiles and models for rendering sky atmosphere, ground atmosphere, and fog.
+ *
+ * <p>
+ * This class is not to be confused with {@link SkyAtmosphere}, which is responsible for rendering the sky.
+ * </p>
+ * <p>
+ * While the atmosphere settings affect the color of fog, see {@link Fog} to control how fog is rendered.
+ * </p>
+ *
+ * @alias Atmosphere
+ * @constructor
+ *
+ * @example
+ * // Turn on dynamic atmosphere lighting using the sun direction
+ * scene.atmosphere.dynamicLighting = Cesium.DynamicAtmosphereLightingType.SUNLIGHT;
+ *
+ * @example
+ * // Turn on dynamic lighting using whatever light source is in the scene
+ * scene.light = new Cesium.DirectionalLight({
+ *   direction: new Cesium.Cartesian3(1, 0, 0)
+ * });
+ * scene.atmosphere.dynamicLighting = Cesium.DynamicAtmosphereLightingType.SCENE_LIGHT;
+ *
+ * @example
+ * // Adjust the color of the atmosphere effects.
+ * scene.atmosphere.hueShift = 0.4; // Cycle 40% around the color wheel
+ * scene.atmosphere.brightnessShift = 0.25; // Increase the brightness
+ * scene.atmosphere.saturationShift = -0.1; // Desaturate the colors
+ *
+ * @see SkyAtmosphere
+ * @see Globe
+ * @see Fog
+ */
+function Atmosphere() {
+  /**
+   * The intensity of the light that is used for computing the ground atmosphere color.
+   *
+   * @type {number}
+   * @default 10.0
+   */
+  this.lightIntensity = 10.0;
+
+  /**
+   * The Rayleigh scattering coefficient used in the atmospheric scattering equations for the ground atmosphere.
+   *
+   * @type {Cartesian3}
+   * @default Cartesian3(5.5e-6, 13.0e-6, 28.4e-6)
+   */
+  this.rayleighCoefficient = new Cartesian3(5.5e-6, 13.0e-6, 28.4e-6);
+
+  /**
+   * The Mie scattering coefficient used in the atmospheric scattering equations for the ground atmosphere.
+   *
+   * @type {Cartesian3}
+   * @default Cartesian3(21e-6, 21e-6, 21e-6)
+   */
+  this.mieCoefficient = new Cartesian3(21e-6, 21e-6, 21e-6);
+
+  /**
+   * The Rayleigh scale height used in the atmospheric scattering equations for the ground atmosphere, in meters.
+   *
+   * @type {number}
+   * @default 10000.0
+   */
+  this.rayleighScaleHeight = 10000.0;
+
+  /**
+   * The Mie scale height used in the atmospheric scattering equations for the ground atmosphere, in meters.
+   *
+   * @type {number}
+   * @default 3200.0
+   */
+  this.mieScaleHeight = 3200.0;
+
+  /**
+   * The anisotropy of the medium to consider for Mie scattering.
+   * <p>
+   * Valid values are between -1.0 and 1.0.
+   * </p>
+   *
+   * @type {number}
+   * @default 0.9
+   */
+  this.mieAnisotropy = 0.9;
+
+  /**
+   * The hue shift to apply to the atmosphere. Defaults to 0.0 (no shift).
+   * A hue shift of 1.0 indicates a complete rotation of the hues available.
+   *
+   * @type {number}
+   * @default 0.0
+   */
+  this.hueShift = 0.0;
+
+  /**
+   * The saturation shift to apply to the atmosphere. Defaults to 0.0 (no shift).
+   * A saturation shift of -1.0 is monochrome.
+   *
+   * @type {number}
+   * @default 0.0
+   */
+  this.saturationShift = 0.0;
+
+  /**
+   * The brightness shift to apply to the atmosphere. Defaults to 0.0 (no shift).
+   * A brightness shift of -1.0 is complete darkness, which will let space show through.
+   *
+   * @type {number}
+   * @default 0.0
+   */
+  this.brightnessShift = 0.0;
+
+  /**
+   * When not DynamicAtmosphereLightingType.NONE, the selected light source will
+   * be used for dynamically lighting all atmosphere-related rendering effects.
+   *
+   * @type {DynamicAtmosphereLightingType}
+   * @default DynamicAtmosphereLightingType.NONE
+   */
+  this.dynamicLighting = DynamicAtmosphereLightingType.NONE;
+}
+
+export default Atmosphere;

package/Source/Scene/Axis.js

@@ -1,5 +1,4 @@
 import Check from "../Core/Check.js";
-import CesiumMath from "../Core/Math.js";
 import Matrix3 from "../Core/Matrix3.js";
 import Matrix4 from "../Core/Matrix4.js";
 
@@ -41,7 +40,8 @@ const Axis = {
  * @constant
  */
 Axis.Y_UP_TO_Z_UP = Matrix4.fromRotationTranslation(
-  Matrix3.fromRotationX(CesiumMath.PI_OVER_TWO)
+  // Rotation about PI/2 around the X-axis
+  Matrix3.fromArray([1, 0, 0, 0, 0, 1, 0, -1, 0])
 );
 
 /**
@@ -51,7 +51,8 @@ Axis.Y_UP_TO_Z_UP = Matrix4.fromRotationTranslation(
  * @constant
  */
 Axis.Z_UP_TO_Y_UP = Matrix4.fromRotationTranslation(
-  Matrix3.fromRotationX(-CesiumMath.PI_OVER_TWO)
+  // Rotation about -PI/2 around the X-axis
+  Matrix3.fromArray([1, 0, 0, 0, 0, -1, 0, 1, 0])
 );
 
 /**
@@ -61,7 +62,8 @@ Axis.Z_UP_TO_Y_UP = Matrix4.fromRotationTranslation(
  * @constant
  */
 Axis.X_UP_TO_Z_UP = Matrix4.fromRotationTranslation(
-  Matrix3.fromRotationY(-CesiumMath.PI_OVER_TWO)
+  // Rotation about -PI/2 around the Y-axis
+  Matrix3.fromArray([0, 0, 1, 0, 1, 0, -1, 0, 0])
 );
 
 /**
@@ -71,7 +73,8 @@ Axis.X_UP_TO_Z_UP = Matrix4.fromRotationTranslation(
  * @constant
  */
 Axis.Z_UP_TO_X_UP = Matrix4.fromRotationTranslation(
-  Matrix3.fromRotationY(CesiumMath.PI_OVER_TWO)
+  // Rotation about PI/2 around the Y-axis
+  Matrix3.fromArray([0, 0, -1, 0, 1, 0, 1, 0, 0])
 );
 
 /**
@@ -81,7 +84,8 @@ Axis.Z_UP_TO_X_UP = Matrix4.fromRotationTranslation(
  * @constant
  */
 Axis.X_UP_TO_Y_UP = Matrix4.fromRotationTranslation(
-  Matrix3.fromRotationZ(CesiumMath.PI_OVER_TWO)
+  // Rotation about PI/2 around the Z-axis
+  Matrix3.fromArray([0, 1, 0, -1, 0, 0, 0, 0, 1])
 );
 
 /**
@@ -91,7 +95,8 @@ Axis.X_UP_TO_Y_UP = Matrix4.fromRotationTranslation(
  * @constant
  */
 Axis.Y_UP_TO_X_UP = Matrix4.fromRotationTranslation(
-  Matrix3.fromRotationZ(-CesiumMath.PI_OVER_TWO)
+  // Rotation about -PI/2 around the Z-axis
+  Matrix3.fromArray([0, -1, 0, 1, 0, 0, 0, 0, 1])
 );
 
 /**

package/Source/Scene/Billboard.js

@@ -10,10 +10,13 @@ import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import DistanceDisplayCondition from "../Core/DistanceDisplayCondition.js";
+import Ellipsoid from "../Core/Ellipsoid.js";
 import Matrix4 from "../Core/Matrix4.js";
 import NearFarScalar from "../Core/NearFarScalar.js";
 import Resource from "../Core/Resource.js";
-import HeightReference from "./HeightReference.js";
+import HeightReference, {
+  isHeightReferenceRelative,
+} from "./HeightReference.js";
 import HorizontalOrigin from "./HorizontalOrigin.js";
 import SceneMode from "./SceneMode.js";
 import SceneTransforms from "./SceneTransforms.js";
@@ -1056,15 +1059,13 @@ Billboard.prototype._updateClamping = function () {
 };
 
 const scratchCartographic = new Cartographic();
-const scratchPosition = new Cartesian3();
-
 Billboard._updateClamping = function (collection, owner) {
   const scene = collection._scene;
-  if (!defined(scene) || !defined(scene.globe)) {
+  if (!defined(scene)) {
     //>>includeStart('debug', pragmas.debug);
     if (owner._heightReference !== HeightReference.NONE) {
       throw new DeveloperError(
-        "Height reference is not supported without a scene and globe."
+        "Height reference is not supported without a scene."
       );
     }
     //>>includeEnd('debug');
@@ -1072,8 +1073,7 @@ Billboard._updateClamping = function (collection, owner) {
   }
 
   const globe = scene.globe;
-  const ellipsoid = globe.ellipsoid;
-  const surface = globe._surface;
+  const ellipsoid = defaultValue(globe?.ellipsoid, Ellipsoid.WGS84);
 
   const mode = scene.frameState.mode;
 
@@ -1096,45 +1096,48 @@ Billboard._updateClamping = function (collection, owner) {
     return;
   }
 
+  if (defined(owner._removeCallbackFunc)) {
+    owner._removeCallbackFunc();
+  }
+
   const position = ellipsoid.cartesianToCartographic(owner._position);
   if (!defined(position)) {
     owner._actualClampedPosition = undefined;
     return;
   }
 
-  if (defined(owner._removeCallbackFunc)) {
-    owner._removeCallbackFunc();
-  }
-
   function updateFunction(clampedPosition) {
-    if (owner._heightReference === HeightReference.RELATIVE_TO_GROUND) {
+    owner._clampedPosition = ellipsoid.cartographicToCartesian(
+      clampedPosition,
+      owner._clampedPosition
+    );
+
+    if (isHeightReferenceRelative(owner._heightReference)) {
       if (owner._mode === SceneMode.SCENE3D) {
-        const clampedCart = ellipsoid.cartesianToCartographic(
+        clampedPosition.height += position.height;
+        ellipsoid.cartographicToCartesian(
           clampedPosition,
-          scratchCartographic
+          owner._clampedPosition
         );
-        clampedCart.height += position.height;
-        ellipsoid.cartographicToCartesian(clampedCart, clampedPosition);
       } else {
-        clampedPosition.x += position.height;
+        owner._clampedPosition.x += position.height;
       }
     }
-    owner._clampedPosition = Cartesian3.clone(
-      clampedPosition,
-      owner._clampedPosition
-    );
   }
-  owner._removeCallbackFunc = surface.updateHeight(position, updateFunction);
+
+  owner._removeCallbackFunc = scene.updateHeight(
+    position,
+    updateFunction,
+    owner._heightReference
+  );
 
   Cartographic.clone(position, scratchCartographic);
-  const height = globe.getHeight(position);
+  const height = scene.getHeight(position, owner._heightReference);
   if (defined(height)) {
     scratchCartographic.height = height;
   }
 
-  ellipsoid.cartographicToCartesian(scratchCartographic, scratchPosition);
-
-  updateFunction(scratchPosition);
+  updateFunction(scratchCartographic);
 };
 
 Billboard.prototype._loadImage = function () {

package/Source/Scene/BillboardCollection.js

@@ -28,7 +28,7 @@ import BillboardCollectionVS from "../Shaders/BillboardCollectionVS.js";
 import Billboard from "./Billboard.js";
 import BlendingState from "./BlendingState.js";
 import BlendOption from "./BlendOption.js";
-import HeightReference from "./HeightReference.js";
+import HeightReference, { isHeightReferenceClamp } from "./HeightReference.js";
 import HorizontalOrigin from "./HorizontalOrigin.js";
 import SceneMode from "./SceneMode.js";
 import SDFSettings from "./SDFSettings.js";
@@ -1375,7 +1375,7 @@ function writeCompressedAttribute3(
 
   let disableDepthTestDistance = billboard.disableDepthTestDistance;
   const clampToGround =
-    billboard.heightReference === HeightReference.CLAMP_TO_GROUND &&
+    isHeightReferenceClamp(billboard.heightReference) &&
     frameState.context.depthTexture;
   if (!defined(disableDepthTestDistance)) {
     disableDepthTestDistance = clampToGround ? 5000.0 : 0.0;
@@ -1448,7 +1448,7 @@ function writeTextureCoordinateBoundsOrLabelTranslate(
   vafWriters,
   billboard
 ) {
-  if (billboard.heightReference === HeightReference.CLAMP_TO_GROUND) {
+  if (isHeightReferenceClamp(billboard.heightReference)) {
     const scene = billboardCollection._scene;
     const context = frameState.context;
     const globeTranslucent = frameState.globeTranslucencyState.translucent;

package/Source/Scene/Camera.js

@@ -197,7 +197,7 @@ function Camera(scene) {
   this.defaultZoomAmount = 100000.0;
   /**
    * If set, the camera will not be able to rotate past this axis in either direction.
-   * @type {Cartesian3}
+   * @type {Cartesian3 | undefined}
    * @default undefined
    */
   this.constrainedAxis = undefined;
@@ -217,6 +217,7 @@ function Camera(scene) {
   this._changedDirection = undefined;
   this._changedFrustum = undefined;
   this._changedHeading = undefined;
+  this._changedRoll = undefined;
 
   /**
    * The amount the camera has to change before the <code>changed</code> event is raised. The value is a percentage in the [0, 1] range.
@@ -380,25 +381,55 @@ Camera.prototype._updateCameraChanged = function () {
 
   const percentageChanged = camera.percentageChanged;
 
+  // check heading
   const currentHeading = camera.heading;
 
   if (!defined(camera._changedHeading)) {
     camera._changedHeading = currentHeading;
   }
 
-  let delta =
+  let headingDelta =
     Math.abs(camera._changedHeading - currentHeading) % CesiumMath.TWO_PI;
-  delta = delta > CesiumMath.PI ? CesiumMath.TWO_PI - delta : delta;
+  headingDelta =
+    headingDelta > CesiumMath.PI
+      ? CesiumMath.TWO_PI - headingDelta
+      : headingDelta;
 
   // Since delta is computed as the shortest distance between two angles
   // the percentage is relative to the half circle.
-  const headingChangedPercentage = delta / Math.PI;
+  const headingChangedPercentage = headingDelta / Math.PI;
 
   if (headingChangedPercentage > percentageChanged) {
-    camera._changed.raiseEvent(headingChangedPercentage);
     camera._changedHeading = currentHeading;
   }
 
+  // check roll
+  const currentRoll = camera.roll;
+
+  if (!defined(camera._changedRoll)) {
+    camera._changedRoll = currentRoll;
+  }
+
+  let rollDelta =
+    Math.abs(camera._changedRoll - currentRoll) % CesiumMath.TWO_PI;
+  rollDelta =
+    rollDelta > CesiumMath.PI ? CesiumMath.TWO_PI - rollDelta : rollDelta;
+
+  // Since delta is computed as the shortest distance between two angles
+  // the percentage is relative to the half circle.
+  const rollChangedPercentage = rollDelta / Math.PI;
+
+  if (rollChangedPercentage > percentageChanged) {
+    camera._changedRoll = currentRoll;
+  }
+  if (
+    rollChangedPercentage > percentageChanged ||
+    headingChangedPercentage > percentageChanged
+  ) {
+    camera._changed.raiseEvent(
+      Math.max(rollChangedPercentage, headingChangedPercentage)
+    );
+  }
   if (camera._mode === SceneMode.SCENE2D) {
     if (!defined(camera._changedFrustum)) {
       camera._changedPosition = Cartesian3.clone(
@@ -1233,6 +1264,11 @@ const scratchSetViewMatrix3 = new Matrix3();
 const scratchSetViewCartographic = new Cartographic();
 
 function setView3D(camera, position, hpr) {
+  //>>includeStart('debug', pragmas.debug);
+  if (isNaN(position.x) || isNaN(position.y) || isNaN(position.z)) {
+    throw new DeveloperError("position has a NaN component");
+  }
+  //>>includeEnd('debug');
   const currentTransform = Matrix4.clone(
     camera.transform,
     scratchSetViewTransform1
@@ -1473,6 +1509,12 @@ Camera.prototype.setView = function (options) {
       destination,
       scratchSetViewCartesian
     );
+    //>>includeStart('debug', pragmas.debug);
+    // destination.z may be null in 2D, but .x and .y should be numeric
+    if (isNaN(destination.x) || isNaN(destination.y)) {
+      throw new DeveloperError(`destination has a NaN component`);
+    }
+    //>>includeEnd('debug');
     convert = false;
   }
 

package/Source/Scene/Cesium3DTile.js

@@ -474,6 +474,7 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
   this._touchedFrame = 0;
   this._visitedFrame = 0;
   this._selectedFrame = 0;
+  this._wasSelectedLastFrame = false;
   this._requestedFrame = 0;
   this._ancestorWithContent = undefined;
   this._ancestorWithContentAvailable = undefined;

package/Source/Scene/Cesium3DTileContent.js

@@ -350,6 +350,20 @@ Cesium3DTileContent.prototype.update = function (tileset, frameState) {
   DeveloperError.throwInstantiationError();
 };
 
+/**
+ * Find an intersection between a ray and the tile content surface that was rendered. The ray must be given in world coordinates.
+ *
+ * @param {Ray} ray The ray to test for intersection.
+ * @param {FrameState} frameState The frame state.
+ * @param {Cartesian3|undefined} [result] The intersection or <code>undefined</code> if none was found.
+ * @returns {Cartesian3|undefined} The intersection or <code>undefined</code> if none was found.
+ *
+ * @private
+ */
+Cesium3DTileContent.prototype.pick = function (ray, frameState, result) {
+  DeveloperError.throwInstantiationError();
+};
+
 /**
  * Returns true if this object was destroyed; otherwise, false.
  * <br /><br />