Merge pull request #12000 from CesiumGS/ellipsoids

Ease of use for Non-WGS84 Ellipsoids
CesiumGS · Jun 11, 2024 · cbd13ce · cbd13ce
2 parents 3c4538b + 66d8580
commit cbd13ce
Show file tree

Hide file tree

Showing 116 changed files with 887 additions and 532 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -6,8 +6,31 @@
 
 ##### Additions :tada:
 
+- Added `Ellipsoid.default` to allow a central place to specify a default ellipsoid value to be used throughout the API where an ellipsoid is not otherwise specified. [#4245](https://github.com/CesiumGS/cesium/issues/4245)
+- Various defaults have been updated to adjust when `Ellipsoid.default` is changed to a value other than the WGS84 ellipsoid.
+- Added `Scene.ellipsoid`, `CesiumWidget.ellipsoid`, and `Viewer.ellipsoid` to set the default ellipsoid used for rendering.
+- Added `SkyBox.createEarthSkyBox` which creates a skybox instance with the default starmap for the Earth.
 - Added support for the `scale` property of a normal texture in a glTF material. [#12018](https://github.com/CesiumGS/cesium/pull/12018)
 
+##### Fixes :wrench:
+
+- Fixed issue where Entities would not use a custom ellipsoid. [#3543](https://github.com/CesiumGS/cesium/issues/3543)
+
+##### Breaking Changes :mega:
+
+- `CircleGeometry.unpack` now defaults to `Ellipsoid.default` rather than `Ellipsoid.UNIT_SPHERE`.
+
+##### Deprecated :hourglass_flowing_sand:
+
+- `SceneTransforms.wgs84ToDrawingBufferCoordinates` has been deprecated. It will be removed in 1.121. Use `SceneTransforms.worldToDrawingBufferCoordinates` instead.
+- `SceneTransforms.wgs84ToWindowCoordinates` has been deprecated. It will be removed in 1.21. Use `SceneTransforms.worldToWindowCoordinates` instead.
+
+#### @cesium/widgets
+
+##### Breaking Changes :mega:
+
+- `BaseLayerPicker` no longer overrides the default imagery or terrain unless `options.selectedImageryProviderViewModel` or `options.selectedTerrainProviderViewModel` is provided respectively.
+
 ### 1.118.2 - 2024-06-03
 
 This is an npm-only release to fix a dependency issue published in 1.118.1

diff --git a/packages/engine/Source/Core/ApproximateTerrainHeights.js b/packages/engine/Source/Core/ApproximateTerrainHeights.js
@@ -56,7 +56,7 @@ ApproximateTerrainHeights.initialize = function () {
 /**
  * Computes the minimum and maximum terrain heights for a given rectangle
  * @param {Rectangle} rectangle The bounding rectangle
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid
  * @return {{minimumTerrainHeight: number, maximumTerrainHeight: number}}
  */
 ApproximateTerrainHeights.getMinimumMaximumHeights = function (
@@ -71,7 +71,7 @@ ApproximateTerrainHeights.getMinimumMaximumHeights = function (
     );
   }
   //>>includeEnd('debug');
-  ellipsoid = defaultValue(ellipsoid, Ellipsoid.WGS84);
+  ellipsoid = defaultValue(ellipsoid, Ellipsoid.default);
 
   const xyLevel = getTileXYLevel(rectangle);
 
@@ -130,7 +130,7 @@ ApproximateTerrainHeights.getMinimumMaximumHeights = function (
 /**
  * Computes the bounding sphere based on the tile heights in the rectangle
  * @param {Rectangle} rectangle The bounding rectangle
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid
  * @return {BoundingSphere} The result bounding sphere
  */
 ApproximateTerrainHeights.getBoundingSphere = function (rectangle, ellipsoid) {
@@ -142,7 +142,7 @@ ApproximateTerrainHeights.getBoundingSphere = function (rectangle, ellipsoid) {
     );
   }
   //>>includeEnd('debug');
-  ellipsoid = defaultValue(ellipsoid, Ellipsoid.WGS84);
+  ellipsoid = defaultValue(ellipsoid, Ellipsoid.default);
 
   const xyLevel = getTileXYLevel(rectangle);
 

diff --git a/packages/engine/Source/Core/ArcGISTiledElevationTerrainProvider.js b/packages/engine/Source/Core/ArcGISTiledElevationTerrainProvider.js
@@ -27,9 +27,9 @@ const ALL_CHILDREN = 15;
  * Initialization options for the ArcGISTiledElevationTerrainProvider constructor
  *
  * @property {string} [token] The authorization token to use to connect to the service.
- * @property {Ellipsoid} [ellipsoid] The ellipsoid.  If the tilingScheme is specified,
+ * @property {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid.  If the tilingScheme is specified,
  *                    this parameter is ignored and the tiling scheme's ellipsoid is used instead.
- *                    If neither parameter is specified, the WGS84 ellipsoid is used.
+ *                    If neither parameter is specified, the default ellipsoid is used.
  */
 
 /**
@@ -41,7 +41,7 @@ const ALL_CHILDREN = 15;
  * @param {ArcGISTiledElevationTerrainProvider.ConstructorOptions} [options] An object describing initialization options.
  */
 function TerrainProviderBuilder(options) {
-  this.ellipsoid = defaultValue(options.ellipsoid, Ellipsoid.WGS84);
+  this.ellipsoid = defaultValue(options.ellipsoid, Ellipsoid.default);
 
   this.credit = undefined;
   this.tilingScheme = undefined;
@@ -446,7 +446,7 @@ ArcGISTiledElevationTerrainProvider.prototype.requestTileGeometry = function (
         encoding: that._encoding,
       });
     })
-    .catch(function (error) {
+    .catch(async function (error) {
       if (
         defined(availabilityRequest) &&
         availabilityRequest.state === RequestState.CANCELLED
@@ -455,10 +455,14 @@ ArcGISTiledElevationTerrainProvider.prototype.requestTileGeometry = function (
 
         // Don't reject the promise till the request is actually cancelled
         // Otherwise it will think the request failed, but it didn't.
-        return request.deferred.promise.finally(function () {
-          request.state = RequestState.CANCELLED;
-          return Promise.reject(error);
-        });
+        try {
+          await request.deferred?.promise;
+        } catch {
+          // Eat this error
+        }
+
+        request.state = RequestState.CANCELLED;
+        return Promise.reject(error);
       }
       return Promise.reject(error);
     });

diff --git a/packages/engine/Source/Core/BoundingRectangle.js b/packages/engine/Source/Core/BoundingRectangle.js
@@ -3,6 +3,7 @@ import Cartographic from "./Cartographic.js";
 import Check from "./Check.js";
 import defaultValue from "./defaultValue.js";
 import defined from "./defined.js";
+import Ellipsoid from "./Ellipsoid.js";
 import GeographicProjection from "./GeographicProjection.js";
 import Intersect from "./Intersect.js";
 import Rectangle from "./Rectangle.js";
@@ -177,6 +178,7 @@ BoundingRectangle.fromRectangle = function (rectangle, projection, result) {
     return result;
   }
 
+  defaultProjection._ellipsoid = Ellipsoid.default;
   projection = defaultValue(projection, defaultProjection);
 
   const lowerLeft = projection.project(

diff --git a/packages/engine/Source/Core/BoundingSphere.js b/packages/engine/Source/Core/BoundingSphere.js
@@ -275,6 +275,7 @@ BoundingSphere.fromRectangleWithHeights2D = function (
     return result;
   }
 
+  defaultProjection._ellipsoid = Ellipsoid.default;
   projection = defaultValue(projection, defaultProjection);
 
   Rectangle.southwest(rectangle, fromRectangle2DSouthwest);
@@ -311,7 +312,7 @@ const fromRectangle3DScratch = [];
  * on the ellipsoid and contained in the rectangle. It may not be accurate for all rectangles on all types of ellipsoids.
  *
  * @param {Rectangle} [rectangle] The valid rectangle used to create a bounding sphere.
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid used to determine positions of the rectangle.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid used to determine positions of the rectangle.
  * @param {number} [surfaceHeight=0.0] The height above the surface of the ellipsoid.
  * @param {BoundingSphere} [result] The object onto which to store the result.
  * @returns {BoundingSphere} The modified result parameter or a new BoundingSphere instance if none was provided.
@@ -322,7 +323,7 @@ BoundingSphere.fromRectangle3D = function (
   surfaceHeight,
   result
 ) {
-  ellipsoid = defaultValue(ellipsoid, Ellipsoid.WGS84);
+  ellipsoid = defaultValue(ellipsoid, Ellipsoid.default);
   surfaceHeight = defaultValue(surfaceHeight, 0.0);
 
   if (!defined(result)) {
@@ -1277,6 +1278,7 @@ BoundingSphere.projectTo2D = function (sphere, projection, result) {
   Check.typeOf.object("sphere", sphere);
   //>>includeEnd('debug');
 
+  projectTo2DProjection._ellipsoid = Ellipsoid.default;
   projection = defaultValue(projection, projectTo2DProjection);
 
   const ellipsoid = projection.ellipsoid;

diff --git a/packages/engine/Source/Core/Cartesian3.js b/packages/engine/Source/Core/Cartesian3.js
@@ -866,7 +866,7 @@ Cartesian3.midpoint = function (left, right, result) {
  * @param {number} longitude The longitude, in degrees
  * @param {number} latitude The latitude, in degrees
  * @param {number} [height=0.0] The height, in meters, above the ellipsoid.
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the position lies.
  * @param {Cartesian3} [result] The object onto which to store the result.
  * @returns {Cartesian3} The position
  *
@@ -892,7 +892,9 @@ Cartesian3.fromDegrees = function (
 
 let scratchN = new Cartesian3();
 let scratchK = new Cartesian3();
-const wgs84RadiiSquared = new Cartesian3(
+
+// To prevent a circular dependency, this value is overridden by Ellipsoid when Ellipsoid.default is set
+Cartesian3._ellipsoidRadiiSquared = new Cartesian3(
   6378137.0 * 6378137.0,
   6378137.0 * 6378137.0,
   6356752.3142451793 * 6356752.3142451793
@@ -904,7 +906,7 @@ const wgs84RadiiSquared = new Cartesian3(
  * @param {number} longitude The longitude, in radians
  * @param {number} latitude The latitude, in radians
  * @param {number} [height=0.0] The height, in meters, above the ellipsoid.
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the position lies.
  * @param {Cartesian3} [result] The object onto which to store the result.
  * @returns {Cartesian3} The position
  *
@@ -924,9 +926,10 @@ Cartesian3.fromRadians = function (
   //>>includeEnd('debug');
 
   height = defaultValue(height, 0.0);
-  const radiiSquared = defined(ellipsoid)
-    ? ellipsoid.radiiSquared
-    : wgs84RadiiSquared;
+
+  const radiiSquared = !defined(ellipsoid)
+    ? Cartesian3._ellipsoidRadiiSquared
+    : ellipsoid.radiiSquared;
 
   const cosLatitude = Math.cos(latitude);
   scratchN.x = cosLatitude * Math.cos(longitude);
@@ -949,7 +952,7 @@ Cartesian3.fromRadians = function (
  * Returns an array of Cartesian3 positions given an array of longitude and latitude values given in degrees.
  *
  * @param {number[]} coordinates A list of longitude and latitude values. Values alternate [longitude, latitude, longitude, latitude...].
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the coordinates lie.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the coordinates lie.
  * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  * @returns {Cartesian3[]} The array of positions.
  *
@@ -993,7 +996,7 @@ Cartesian3.fromDegreesArray = function (coordinates, ellipsoid, result) {
  * Returns an array of Cartesian3 positions given an array of longitude and latitude values given in radians.
  *
  * @param {number[]} coordinates A list of longitude and latitude values. Values alternate [longitude, latitude, longitude, latitude...].
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the coordinates lie.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the coordinates lie.
  * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  * @returns {Cartesian3[]} The array of positions.
  *
@@ -1037,7 +1040,7 @@ Cartesian3.fromRadiansArray = function (coordinates, ellipsoid, result) {
  * Returns an array of Cartesian3 positions given an array of longitude, latitude and height values where longitude and latitude are given in degrees.
  *
  * @param {number[]} coordinates A list of longitude, latitude and height values. Values alternate [longitude, latitude, height, longitude, latitude, height...].
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the position lies.
  * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  * @returns {Cartesian3[]} The array of positions.
  *
@@ -1082,7 +1085,7 @@ Cartesian3.fromDegreesArrayHeights = function (coordinates, ellipsoid, result) {
  * Returns an array of Cartesian3 positions given an array of longitude, latitude and height values where longitude and latitude are given in radians.
  *
  * @param {number[]} coordinates A list of longitude, latitude and height values. Values alternate [longitude, latitude, height, longitude, latitude, height...].
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the position lies.
  * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  * @returns {Cartesian3[]} The array of positions.
  *

diff --git a/packages/engine/Source/Core/Cartographic.js b/packages/engine/Source/Core/Cartographic.js
@@ -83,6 +83,7 @@ Cartographic.fromDegrees = function (longitude, latitude, height, result) {
   Check.typeOf.number("longitude", longitude);
   Check.typeOf.number("latitude", latitude);
   //>>includeEnd('debug');
+
   longitude = CesiumMath.toRadians(longitude);
   latitude = CesiumMath.toRadians(latitude);
 
@@ -92,37 +93,39 @@ Cartographic.fromDegrees = function (longitude, latitude, height, result) {
 const cartesianToCartographicN = new Cartesian3();
 const cartesianToCartographicP = new Cartesian3();
 const cartesianToCartographicH = new Cartesian3();
-const wgs84OneOverRadii = new Cartesian3(
+
+// To avoid circular dependencies, these are set by Ellipsoid when Ellipsoid.default is set.
+Cartographic._ellipsoidOneOverRadii = new Cartesian3(
   1.0 / 6378137.0,
   1.0 / 6378137.0,
   1.0 / 6356752.3142451793
 );
-const wgs84OneOverRadiiSquared = new Cartesian3(
+Cartographic._ellipsoidOneOverRadiiSquared = new Cartesian3(
   1.0 / (6378137.0 * 6378137.0),
   1.0 / (6378137.0 * 6378137.0),
   1.0 / (6356752.3142451793 * 6356752.3142451793)
 );
-const wgs84CenterToleranceSquared = CesiumMath.EPSILON1;
+Cartographic._ellipsoidCenterToleranceSquared = CesiumMath.EPSILON1;
 
 /**
  * Creates a new Cartographic instance from a Cartesian position. The values in the
  * resulting object will be in radians.
  *
  * @param {Cartesian3} cartesian The Cartesian position to convert to cartographic representation.
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the position lies.
  * @param {Cartographic} [result] The object onto which to store the result.
  * @returns {Cartographic} The modified result parameter, new Cartographic instance if none was provided, or undefined if the cartesian is at the center of the ellipsoid.
  */
 Cartographic.fromCartesian = function (cartesian, ellipsoid, result) {
   const oneOverRadii = defined(ellipsoid)
     ? ellipsoid.oneOverRadii
-    : wgs84OneOverRadii;
+    : Cartographic._ellipsoidOneOverRadii;
   const oneOverRadiiSquared = defined(ellipsoid)
     ? ellipsoid.oneOverRadiiSquared
-    : wgs84OneOverRadiiSquared;
+    : Cartographic._ellipsoidOneOverRadiiSquared;
   const centerToleranceSquared = defined(ellipsoid)
     ? ellipsoid._centerToleranceSquared
-    : wgs84CenterToleranceSquared;
+    : Cartographic._ellipsoidCenterToleranceSquared;
 
   //`cartesian is required.` is thrown from scaleToGeodeticSurface
   const p = scaleToGeodeticSurface(
@@ -165,7 +168,7 @@ Cartographic.fromCartesian = function (cartesian, ellipsoid, result) {
  * object should be in radians.
  *
  * @param {Cartographic} cartographic Input to be converted into a Cartesian3 output.
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the position lies.
  * @param {Cartesian3} [result] The object onto which to store the result.
  * @returns {Cartesian3} The position
  */

diff --git a/packages/engine/Source/Core/CesiumTerrainProvider.js b/packages/engine/Source/Core/CesiumTerrainProvider.js
@@ -5,6 +5,7 @@ import Check from "./Check.js";
 import Credit from "./Credit.js";
 import defaultValue from "./defaultValue.js";
 import defined from "./defined.js";
+import Ellipsoid from "./Ellipsoid.js";
 import Event from "./Event.js";
 import GeographicTilingScheme from "./GeographicTilingScheme.js";
 import WebMercatorTilingScheme from "./WebMercatorTilingScheme.js";
@@ -45,7 +46,7 @@ function LayerInformation(layer) {
  * @property {boolean} [requestVertexNormals=false] Flag that indicates if the client should request additional lighting information from the server, in the form of per vertex normals if available.
  * @property {boolean} [requestWaterMask=false] Flag that indicates if the client should request per tile water masks from the server, if available.
  * @property {boolean} [requestMetadata=true] Flag that indicates if the client should request per tile metadata from the server, if available.
- * @property {Ellipsoid} [ellipsoid] The ellipsoid.  If not specified, the WGS84 ellipsoid is used.
+ * @property {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid.  If not specified, the default ellipsoid is used.
  * @property {Credit|string} [credit] A credit for the data source, which is displayed on the canvas.
  */
 
@@ -61,7 +62,7 @@ function TerrainProviderBuilder(options) {
   this.requestVertexNormals = defaultValue(options.requestVertexNormals, false);
   this.requestWaterMask = defaultValue(options.requestWaterMask, false);
   this.requestMetadata = defaultValue(options.requestMetadata, true);
-  this.ellipsoid = options.ellipsoid;
+  this.ellipsoid = defaultValue(options.ellipsoid, Ellipsoid.default);
 
   this.heightmapWidth = 65;
   this.heightmapStructure = undefined;

diff --git a/packages/engine/Source/Core/CircleGeometry.js b/packages/engine/Source/Core/CircleGeometry.js
@@ -15,7 +15,7 @@ import VertexFormat from "./VertexFormat.js";
  * @param {object} options Object with the following properties:
  * @param {Cartesian3} options.center The circle's center point in the fixed frame.
  * @param {number} options.radius The radius in meters.
- * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84] The ellipsoid the circle will be on.
+ * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.default] The ellipsoid the circle will be on.
  * @param {number} [options.height=0.0] The distance in meters between the circle and the ellipsoid surface.
  * @param {number} [options.granularity=0.02] The angular distance between points on the circle in radians.
  * @param {VertexFormat} [options.vertexFormat=VertexFormat.DEFAULT] The vertex attributes to be computed.
@@ -90,7 +90,7 @@ const scratchEllipseGeometry = new EllipseGeometry({
 const scratchOptions = {
   center: new Cartesian3(),
   radius: undefined,
-  ellipsoid: Ellipsoid.clone(Ellipsoid.UNIT_SPHERE),
+  ellipsoid: Ellipsoid.clone(Ellipsoid.default),
   height: undefined,
   extrudedHeight: undefined,
   granularity: undefined,
@@ -123,6 +123,10 @@ CircleGeometry.unpack = function (array, startingIndex, result) {
     ellipseGeometry._ellipsoid,
     scratchOptions.ellipsoid
   );
+  scratchOptions.ellipsoid = Ellipsoid.clone(
+    ellipseGeometry._ellipsoid,
+    scratchEllipseGeometry._ellipsoid
+  );
   scratchOptions.height = ellipseGeometry._height;
   scratchOptions.extrudedHeight = ellipseGeometry._extrudedHeight;
   scratchOptions.granularity = ellipseGeometry._granularity;

diff --git a/packages/engine/Source/Core/CircleOutlineGeometry.js b/packages/engine/Source/Core/CircleOutlineGeometry.js
@@ -14,7 +14,7 @@ import Ellipsoid from "./Ellipsoid.js";
  * @param {object} options Object with the following properties:
  * @param {Cartesian3} options.center The circle's center point in the fixed frame.
  * @param {number} options.radius The radius in meters.
- * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84] The ellipsoid the circle will be on.
+ * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.default] The ellipsoid the circle will be on.
  * @param {number} [options.height=0.0] The distance in meters between the circle and the ellipsoid surface.
  * @param {number} [options.granularity=0.02] The angular distance between points on the circle in radians.
  * @param {number} [options.extrudedHeight=0.0] The distance in meters between the circle's extruded face and the ellipsoid surface.