@cesium/engine 6.1.0 → 6.2.0

package/Source/Renderer/AutomaticUniforms.js

@@ -939,6 +939,59 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing the ellipsoid surface normal
+   * at the position below the eye (camera), in eye coordinates.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   */
+  czm_eyeEllipsoidNormalEC: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_VEC3,
+    getValue: function (uniformState) {
+      return uniformState.eyeEllipsoidNormalEC;
+    },
+  }),
+
+  /**
+   * An automatic GLSL uniform containing the ellipsoid radii of curvature at the camera position.
+   * The .x component is the prime vertical radius, .y is the meridional.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   */
+  czm_eyeEllipsoidCurvature: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_VEC2,
+    getValue: function (uniformState) {
+      return uniformState.eyeEllipsoidCurvature;
+    },
+  }),
+
+  /**
+   * An automatic GLSL uniform containing the transform from model coordinates
+   * to an east-north-up coordinate system centered at the position on the
+   * ellipsoid below the camera.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   */
+  czm_modelToEnu: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_MAT4,
+    getValue: function (uniformState) {
+      return uniformState.modelToEnu;
+    },
+  }),
+
+  /**
+   * An automatic GLSL uniform containing the the inverse of
+   * {@link AutomaticUniforms.czm_modelToEnu}.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   */
+  czm_enuToModel: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_MAT4,
+    getValue: function (uniformState) {
+      return uniformState.enuToModel;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform containing the near distance (<code>x</code>) and the far distance (<code>y</code>)
    * of the frustum defined by the camera.  This is the largest possible frustum, not an individual

package/Source/Renderer/UniformState.js

@@ -144,6 +144,10 @@ function UniformState() {
   this._frustum2DWidth = 0.0;
   this._eyeHeight = 0.0;
   this._eyeHeight2D = new Cartesian2();
+  this._eyeEllipsoidNormalEC = new Cartesian3();
+  this._eyeEllipsoidCurvature = new Cartesian2();
+  this._modelToEnu = new Matrix4();
+  this._enuToModel = new Matrix4();
   this._pixelRatio = 1.0;
   this._orthographicIn3D = false;
   this._backgroundColor = new Color();
@@ -696,6 +700,52 @@ Object.defineProperties(UniformState.prototype, {
     },
   },
 
+  /**
+   * The ellipsoid surface normal at the camera position, in model coordinates.
+   * @memberof UniformState.prototype
+   * @type {Cartesian3}
+   */
+  eyeEllipsoidNormalEC: {
+    get: function () {
+      return this._eyeEllipsoidNormalEC;
+    },
+  },
+
+  /**
+   * The ellipsoid radii of curvature at the camera position.
+   * The .x component is the prime vertical radius, .y is the meridional.
+   * @memberof UniformState.prototype
+   * @type {Cartesian2}
+   */
+  eyeEllipsoidCurvature: {
+    get: function () {
+      return this._eyeEllipsoidCurvature;
+    },
+  },
+
+  /**
+   * A transform from model coordinates to an east-north-up coordinate system
+   * centered at the position on the ellipsoid below the camera
+   * @memberof UniformState.prototype
+   * @type {Matrix4}
+   */
+  modelToEnu: {
+    get: function () {
+      return this._modelToEnu;
+    },
+  },
+
+  /**
+   * The inverse of {@link UniformState.prototype.modelToEnu}
+   * @memberof UniformState.prototype
+   * @type {Matrix4}
+   */
+  enuToModel: {
+    get: function () {
+      return this._enuToModel;
+    },
+  },
+
   /**
    * The sun position in 3D world coordinates at the current scene time.
    * @memberof UniformState.prototype
@@ -1068,20 +1118,88 @@ function setInfiniteProjection(uniformState, matrix) {
   uniformState._modelViewInfiniteProjectionDirty = true;
 }
 
+const surfacePositionScratch = new Cartesian3();
+const enuTransformScratch = new Matrix4();
+
 function setCamera(uniformState, camera) {
   Cartesian3.clone(camera.positionWC, uniformState._cameraPosition);
   Cartesian3.clone(camera.directionWC, uniformState._cameraDirection);
   Cartesian3.clone(camera.rightWC, uniformState._cameraRight);
   Cartesian3.clone(camera.upWC, uniformState._cameraUp);
 
+  const ellipsoid = uniformState._ellipsoid;
+  let surfacePosition;
+
   const positionCartographic = camera.positionCartographic;
   if (!defined(positionCartographic)) {
-    uniformState._eyeHeight = -uniformState._ellipsoid.maximumRadius;
+    uniformState._eyeHeight = -ellipsoid.maximumRadius;
+    if (Cartesian3.magnitude(camera.positionWC) > 0.0) {
+      uniformState._eyeEllipsoidNormalEC = Cartesian3.normalize(
+        camera.positionWC,
+        uniformState._eyeEllipsoidNormalEC
+      );
+    }
+    surfacePosition = ellipsoid.scaleToGeodeticSurface(
+      camera.positionWC,
+      surfacePositionScratch
+    );
   } else {
     uniformState._eyeHeight = positionCartographic.height;
+    uniformState._eyeEllipsoidNormalEC = ellipsoid.geodeticSurfaceNormalCartographic(
+      positionCartographic,
+      uniformState._eyeEllipsoidNormalEC
+    );
+    surfacePosition = Cartesian3.fromRadians(
+      positionCartographic.longitude,
+      positionCartographic.latitude,
+      0.0,
+      ellipsoid,
+      surfacePositionScratch
+    );
   }
 
   uniformState._encodedCameraPositionMCDirty = true;
+
+  if (!defined(surfacePosition)) {
+    return;
+  }
+
+  uniformState._eyeEllipsoidNormalEC = Matrix3.multiplyByVector(
+    uniformState._viewRotation,
+    uniformState._eyeEllipsoidNormalEC,
+    uniformState._eyeEllipsoidNormalEC
+  );
+
+  const enuToWorld = Transforms.eastNorthUpToFixedFrame(
+    surfacePosition,
+    ellipsoid,
+    enuTransformScratch
+  );
+  uniformState._enuToModel = Matrix4.multiplyTransformation(
+    uniformState.inverseModel,
+    enuToWorld,
+    uniformState._enuToModel
+  );
+  uniformState._modelToEnu = Matrix4.inverseTransformation(
+    uniformState._enuToModel,
+    uniformState._modelToEnu
+  );
+
+  if (
+    !CesiumMath.equalsEpsilon(
+      ellipsoid._radii.x,
+      ellipsoid._radii.y,
+      CesiumMath.EPSILON15
+    )
+  ) {
+    // Ellipsoid curvature calculations assume radii.x === radii.y as is true for WGS84
+    return;
+  }
+
+  uniformState._eyeEllipsoidCurvature = ellipsoid.getLocalCurvature(
+    surfacePosition,
+    uniformState._eyeEllipsoidCurvature
+  );
 }
 
 let transformMatrix = new Matrix3();

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPK72121c3f05244af285ad75999db084bfDGkWA0QECX6QWOdaQmarXC21i1ogkvj8XCctaZExrW8Hw1AT58yG7twH3VFzZl13";
+  "AAPK2b93071721df4cc78be0d8b3d79b1fd54YMocOcx2NxlbYTDkyO5gPk8XsDnguQgeMdFKepFwLwTgb8vHfPvSTdjy_KlMHlS";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/Cesium3DTile.js

@@ -43,6 +43,7 @@ import TileBoundingS2Cell from "./TileBoundingS2Cell.js";
 import TileBoundingSphere from "./TileBoundingSphere.js";
 import TileOrientedBoundingBox from "./TileOrientedBoundingBox.js";
 import Pass from "../Renderer/Pass.js";
+import VerticalExaggeration from "../Core/VerticalExaggeration.js";
 
 /**
  * A tile in a {@link Cesium3DTileset}.  When a tile is first created, its content is not loaded;
@@ -119,6 +120,9 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
    */
   this.metadata = findTileMetadata(tileset, header);
 
+  this._verticalExaggeration = 1.0;
+  this._verticalExaggerationRelativeHeight = 0.0;
+
   // Important: tile metadata must be parsed before this line so that the
   // metadata semantics TILE_BOUNDING_BOX, TILE_BOUNDING_REGION, or TILE_BOUNDING_SPHERE
   // can override header.boundingVolume (if necessary)
@@ -1018,7 +1022,7 @@ Cesium3DTile.prototype.updateVisibility = function (frameState) {
   const parentVisibilityPlaneMask = defined(parent)
     ? parent._visibilityPlaneMask
     : CullingVolume.MASK_INDETERMINATE;
-  this.updateTransform(parentTransform);
+  this.updateTransform(parentTransform, frameState);
   this._distanceToCamera = this.distanceToTile(frameState);
   this._centerZDepth = this.distanceToTileCenter(frameState);
   this._screenSpaceError = this.getScreenSpaceError(frameState, false);
@@ -1709,12 +1713,18 @@ function createRegion(region, transform, initialTransform, result) {
     );
   }
 
+  const rectangleRegion = Rectangle.unpack(region, 0, scratchRectangle);
+
   if (defined(result)) {
+    result.rectangle = Rectangle.clone(rectangleRegion, result.rectangle);
+    result.minimumHeight = region[4];
+    result.maximumHeight = region[5];
+    // The TileBoundingRegion was already constructed with the default
+    // WGS84 ellipsoid, so keep it consistent when updating.
+    result.computeBoundingVolumes(Ellipsoid.WGS84);
     return result;
   }
 
-  const rectangleRegion = Rectangle.unpack(region, 0, scratchRectangle);
-
   return new TileBoundingRegion({
     rectangle: rectangleRegion,
     minimumHeight: region[4],
@@ -1793,26 +1803,117 @@ Cesium3DTile.prototype.createBoundingVolume = function (
 
   const { box, region, sphere } = boundingVolumeHeader;
   if (defined(box)) {
-    return createBox(box, transform, result);
+    const tileOrientedBoundingBox = createBox(box, transform, result);
+    if (this._verticalExaggeration !== 1.0) {
+      exaggerateBoundingBox(
+        tileOrientedBoundingBox,
+        this._verticalExaggeration,
+        this._verticalExaggerationRelativeHeight
+      );
+    }
+    return tileOrientedBoundingBox;
   }
   if (defined(region)) {
-    return createRegion(region, transform, this._initialTransform, result);
+    const tileBoundingVolume = createRegion(
+      region,
+      transform,
+      this._initialTransform,
+      result
+    );
+    if (this._verticalExaggeration === 1.0) {
+      return tileBoundingVolume;
+    }
+    if (tileBoundingVolume instanceof TileOrientedBoundingBox) {
+      exaggerateBoundingBox(
+        tileBoundingVolume,
+        this._verticalExaggeration,
+        this._verticalExaggerationRelativeHeight
+      );
+    } else {
+      tileBoundingVolume.minimumHeight = VerticalExaggeration.getHeight(
+        tileBoundingVolume.minimumHeight,
+        this._verticalExaggeration,
+        this._verticalExaggerationRelativeHeight
+      );
+      tileBoundingVolume.maximumHeight = VerticalExaggeration.getHeight(
+        tileBoundingVolume.maximumHeight,
+        this._verticalExaggeration,
+        this._verticalExaggerationRelativeHeight
+      );
+      tileBoundingVolume.computeBoundingVolumes(Ellipsoid.WGS84);
+    }
+    return tileBoundingVolume;
   }
   if (defined(sphere)) {
-    return createSphere(sphere, transform, result);
+    const tileBoundingSphere = createSphere(sphere, transform, result);
+    if (this._verticalExaggeration !== 1.0) {
+      const exaggeratedCenter = VerticalExaggeration.getPosition(
+        tileBoundingSphere.center,
+        Ellipsoid.WGS84,
+        this._verticalExaggeration,
+        this._verticalExaggerationRelativeHeight,
+        scratchCenter
+      );
+      const exaggeratedRadius =
+        tileBoundingSphere.radius * this._verticalExaggeration;
+      tileBoundingSphere.update(exaggeratedCenter, exaggeratedRadius);
+    }
+    return tileBoundingSphere;
   }
   throw new RuntimeError(
     "boundingVolume must contain a sphere, region, or box"
   );
 };
 
+const scratchExaggeratedCorners = Cartesian3.unpackArray(
+  new Array(8 * 3).fill(0)
+);
+
+/**
+ * Exaggerates the bounding box of a tile based on the provided exaggeration factors.
+ *
+ * @private
+ * @param {TileOrientedBoundingBox} tileOrientedBoundingBox - The oriented bounding box of the tile.
+ * @param {number} exaggeration - The exaggeration factor to apply to the tile's bounding box.
+ * @param {number} exaggerationRelativeHeight - The height relative to which exaggeration will be applied.
+ */
+function exaggerateBoundingBox(
+  tileOrientedBoundingBox,
+  exaggeration,
+  exaggerationRelativeHeight
+) {
+  const exaggeratedCorners = tileOrientedBoundingBox.boundingVolume
+    .computeCorners(scratchExaggeratedCorners)
+    .map((corner) =>
+      VerticalExaggeration.getPosition(
+        corner,
+        Ellipsoid.WGS84,
+        exaggeration,
+        exaggerationRelativeHeight,
+        corner
+      )
+    );
+  const exaggeratedBox = OrientedBoundingBox.fromPoints(
+    exaggeratedCorners,
+    scratchOrientedBoundingBox
+  );
+  tileOrientedBoundingBox.update(
+    exaggeratedBox.center,
+    exaggeratedBox.halfAxes
+  );
+}
+
 /**
  * Update the tile's transform. The transform is applied to the tile's bounding volumes.
  *
  * @private
  * @param {Matrix4} parentTransform
+ * @param {FrameState} [frameState]
  */
-Cesium3DTile.prototype.updateTransform = function (parentTransform) {
+Cesium3DTile.prototype.updateTransform = function (
+  parentTransform,
+  frameState
+) {
   parentTransform = defaultValue(parentTransform, Matrix4.IDENTITY);
   const computedTransform = Matrix4.multiplyTransformation(
     parentTransform,
@@ -1823,12 +1924,23 @@ Cesium3DTile.prototype.updateTransform = function (parentTransform) {
     computedTransform,
     this.computedTransform
   );
+  const exaggerationChanged =
+    defined(frameState) &&
+    (this._verticalExaggeration !== frameState.verticalExaggeration ||
+      this._verticalExaggerationRelativeHeight !==
+        frameState.verticalExaggerationRelativeHeight);
 
-  if (!transformChanged) {
+  if (!transformChanged && !exaggerationChanged) {
     return;
   }
-
-  Matrix4.clone(computedTransform, this.computedTransform);
+  if (transformChanged) {
+    Matrix4.clone(computedTransform, this.computedTransform);
+  }
+  if (exaggerationChanged) {
+    this._verticalExaggeration = frameState.verticalExaggeration;
+    this._verticalExaggerationRelativeHeight =
+      frameState.verticalExaggerationRelativeHeight;
+  }
 
   // Update the bounding volumes
   const header = this._header;

package/Source/Scene/Cesium3DTileset.js

@@ -1902,7 +1902,7 @@ Object.defineProperties(Cesium3DTileset.prototype, {
  * used for streaming massive heterogeneous 3D geospatial datasets, from a Cesium ion asset ID.
  *
  * @param {number} assetId The Cesium ion asset id.
- * @param {Cesium3DTileset.ConstructorOptions} options An object describing initialization options
+ * @param {Cesium3DTileset.ConstructorOptions} [options] An object describing initialization options
  * @returns {Promise<Cesium3DTileset>}
  *
  * @exception {DeveloperError} The tileset must be 3D Tiles version 0.0 or 1.0.

package/Source/Scene/FrameState.js

@@ -275,18 +275,18 @@ function FrameState(context, creditDisplay, jobScheduler) {
   };
 
   /**
-   * A scalar used to exaggerate the terrain.
+   * A scalar used to vertically exaggerate the scene
    * @type {number}
    * @default 1.0
    */
-  this.terrainExaggeration = 1.0;
+  this.verticalExaggeration = 1.0;
 
   /**
-   * The height relative to which terrain is exaggerated.
+   * The height relative to which the scene is vertically exaggerated.
    * @type {number}
    * @default 0.0
    */
-  this.terrainExaggerationRelativeHeight = 0.0;
+  this.verticalExaggerationRelativeHeight = 0.0;
 
   /**
    * @typedef FrameState.ShadowState

package/Source/Scene/Globe.js

@@ -28,6 +28,7 @@ import ImageryLayerCollection from "./ImageryLayerCollection.js";
 import QuadtreePrimitive from "./QuadtreePrimitive.js";
 import SceneMode from "./SceneMode.js";
 import ShadowMode from "./ShadowMode.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 
 /**
  * The globe rendered in the scene, including its terrain ({@link Globe#terrainProvider})
@@ -340,25 +341,9 @@ function Globe(ellipsoid) {
    */
   this.atmosphereBrightnessShift = 0.0;
 
-  /**
-   * A scalar used to exaggerate the terrain. Defaults to <code>1.0</code> (no exaggeration).
-   * A value of <code>2.0</code> scales the terrain by 2x.
-   * A value of <code>0.0</code> makes the terrain completely flat.
-   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
-   * @type {number}
-   * @default 1.0
-   */
-  this.terrainExaggeration = 1.0;
-
-  /**
-   * The height from which terrain is exaggerated. Defaults to <code>0.0</code> (scaled relative to ellipsoid surface).
-   * Terrain that is above this height will scale upwards and terrain that is below this height will scale downwards.
-   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
-   * If {@link Globe#terrainExaggeration} is <code>1.0</code> this value will have no effect.
-   * @type {number}
-   * @default 0.0
-   */
-  this.terrainExaggerationRelativeHeight = 0.0;
+  this._terrainExaggerationChanged = false;
+  this._terrainExaggeration = 1.0;
+  this._terrainExaggerationRelativeHeight = 0.0;
 
   /**
    * Whether to show terrain skirts. Terrain skirts are geometry extending downwards from a tile's edges used to hide seams between neighboring tiles.
@@ -538,6 +523,68 @@ Object.defineProperties(Globe.prototype, {
       return this._terrainProviderChanged;
     },
   },
+  /**
+   * A scalar used to exaggerate the terrain. Defaults to <code>1.0</code> (no exaggeration).
+   * A value of <code>2.0</code> scales the terrain by 2x.
+   * A value of <code>0.0</code> makes the terrain completely flat.
+   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
+   *
+   * @memberof Globe.prototype
+   * @type {number}
+   * @default 1.0
+   *
+   * @deprecated
+   */
+  terrainExaggeration: {
+    get: function () {
+      deprecationWarning(
+        "Globe.terrainExaggeration",
+        "Globe.terrainExaggeration was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggeration instead."
+      );
+      return this._terrainExaggeration;
+    },
+    set: function (value) {
+      deprecationWarning(
+        "Globe.terrainExaggeration",
+        "Globe.terrainExaggeration was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggeration instead."
+      );
+      if (value !== this._terrainExaggeration) {
+        this._terrainExaggeration = value;
+        this._terrainExaggerationChanged = true;
+      }
+    },
+  },
+  /**
+   * The height from which terrain is exaggerated. Defaults to <code>0.0</code> (scaled relative to ellipsoid surface).
+   * Terrain that is above this height will scale upwards and terrain that is below this height will scale downwards.
+   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
+   * If {@link Globe#terrainExaggeration} is <code>1.0</code> this value will have no effect.
+   *
+   * @memberof Globe.prototype
+   * @type {number}
+   * @default 0.0
+   *
+   * @deprecated
+   */
+  terrainExaggerationRelativeHeight: {
+    get: function () {
+      deprecationWarning(
+        "Globe.terrainExaggerationRelativeHeight",
+        "Globe.terrainExaggerationRelativeHeight was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggerationRelativeHeight instead."
+      );
+      return this._terrainExaggerationRelativeHeight;
+    },
+    set: function (value) {
+      deprecationWarning(
+        "Globe.terrainExaggerationRelativeHeight",
+        "Globe.terrainExaggerationRelativeHeight was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggerationRelativeHeight instead."
+      );
+      if (value !== this._terrainExaggerationRelativeHeight) {
+        this._terrainExaggerationRelativeHeight = value;
+        this._terrainExaggerationChanged = true;
+      }
+    },
+  },
   /**
    * Gets an event that's raised when the length of the tile load queue has changed since the last render frame.  When the load queue is empty,
    * all terrain and imagery for the current view have been loaded.  The event passes the new length of the tile load queue.

package/Source/Scene/GlobeSurfaceTile.js

@@ -463,9 +463,9 @@ GlobeSurfaceTile.prototype.updateExaggeration = function (
   }
 
   // Check the tile's terrain encoding to see if it has been exaggerated yet
-  const exaggeration = frameState.terrainExaggeration;
+  const exaggeration = frameState.verticalExaggeration;
   const exaggerationRelativeHeight =
-    frameState.terrainExaggerationRelativeHeight;
+    frameState.verticalExaggerationRelativeHeight;
   const hasExaggerationScale = exaggeration !== 1.0;
 
   const encoding = mesh.encoding;
@@ -790,9 +790,9 @@ function transform(surfaceTile, frameState, terrainProvider, x, y, level) {
   createMeshOptions.x = x;
   createMeshOptions.y = y;
   createMeshOptions.level = level;
-  createMeshOptions.exaggeration = frameState.terrainExaggeration;
+  createMeshOptions.exaggeration = frameState.verticalExaggeration;
   createMeshOptions.exaggerationRelativeHeight =
-    frameState.terrainExaggerationRelativeHeight;
+    frameState.verticalExaggerationRelativeHeight;
   createMeshOptions.throttle = true;
 
   const terrainData = surfaceTile.terrainData;