@cesium/engine 2.1.0 → 2.3.0

package/Source/Core/Credit.js

@@ -17,7 +17,7 @@ const creditToId = {};
  * @exception {DeveloperError} html is required.
  *
  * @example
- * //Create a credit with a tooltip, image and link
+ * // Create a credit with a tooltip, image and link
  * const credit = new Cesium.Credit('<a href="https://cesium.com/" target="_blank"><img src="/images/cesium_logo.png" title="Cesium"/></a>');
  */
 function Credit(html, showOnScreen) {

package/Source/Core/CustomHeightmapTerrainProvider.js

@@ -2,6 +2,7 @@ import Check from "./Check.js";
 import Credit from "./Credit.js";
 import defaultValue from "./defaultValue.js";
 import defined from "./defined.js";
+import deprecationWarning from "./deprecationWarning.js";
 import Ellipsoid from "./Ellipsoid.js";
 import Event from "./Event.js";
 import GeographicTilingScheme from "./GeographicTilingScheme.js";
@@ -89,6 +90,7 @@ function CustomHeightmapTerrainProvider(options) {
   }
   this._credit = credit;
 
+  this._ready = true;
   this._readyPromise = Promise.resolve(true);
 }
 
@@ -137,9 +139,14 @@ Object.defineProperties(CustomHeightmapTerrainProvider.prototype, {
    * @memberof CustomHeightmapTerrainProvider.prototype
    * @type {boolean}
    * @readonly
+   * @deprecated
    */
   ready: {
     get: function () {
+      deprecationWarning(
+        "CustomHeightmapTerrainProvider.ready",
+        "CustomHeightmapTerrainProvider.ready was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107."
+      );
       return true;
     },
   },
@@ -149,9 +156,14 @@ Object.defineProperties(CustomHeightmapTerrainProvider.prototype, {
    * @memberof CustomHeightmapTerrainProvider.prototype
    * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "CustomHeightmapTerrainProvider.readyPromise",
+        "CustomHeightmapTerrainProvider.readyPromise was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107."
+      );
       return this._readyPromise;
     },
   },

package/Source/Core/EllipsoidTerrainProvider.js

@@ -1,5 +1,6 @@
 import defaultValue from "./defaultValue.js";
 import defined from "./defined.js";
+import deprecationWarning from "./deprecationWarning.js";
 import Ellipsoid from "./Ellipsoid.js";
 import Event from "./Event.js";
 import GeographicTilingScheme from "./GeographicTilingScheme.js";
@@ -42,6 +43,7 @@ function EllipsoidTerrainProvider(options) {
   );
 
   this._errorEvent = new Event();
+  this._ready = true;
   this._readyPromise = Promise.resolve(true);
 }
 
@@ -62,7 +64,7 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
 
   /**
    * Gets the credit to display when this terrain provider is active.  Typically this is used to credit
-   * the source of the terrain.  This function should not be called before {@link EllipsoidTerrainProvider#ready} returns true.
+   * the source of the terrain.
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {Credit}
    * @readonly
@@ -74,8 +76,7 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
   },
 
   /**
-   * Gets the tiling scheme used by this provider.  This function should
-   * not be called before {@link EllipsoidTerrainProvider#ready} returns true.
+   * Gets the tiling scheme used by this provider.
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {GeographicTilingScheme}
    * @readonly
@@ -91,9 +92,14 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {boolean}
    * @readonly
+   * @deprecated
    */
   ready: {
     get: function () {
+      deprecationWarning(
+        "EllipsoidTerrainProvider.ready",
+        "EllipsoidTerrainProvider.ready was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107."
+      );
       return true;
     },
   },
@@ -103,9 +109,14 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "EllipsoidTerrainProvider.readyPromise",
+        "EllipsoidTerrainProvider.readyPromise was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107."
+      );
       return this._readyPromise;
     },
   },
@@ -113,8 +124,7 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
   /**
    * Gets a value indicating whether or not the provider includes a water mask.  The water mask
    * indicates which areas of the globe are water rather than land, so they can be rendered
-   * as a reflective surface with animated waves.  This function should not be
-   * called before {@link EllipsoidTerrainProvider#ready} returns true.
+   * as a reflective surface with animated waves.
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {boolean}
    * @readonly
@@ -127,7 +137,6 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
 
   /**
    * Gets a value indicating whether or not the requested tiles include vertex normals.
-   * This function should not be called before {@link EllipsoidTerrainProvider#ready} returns true.
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {boolean}
    * @readonly
@@ -139,8 +148,7 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
   },
   /**
    * Gets an object that can be used to determine availability of terrain from this provider, such as
-   * at points and in rectangles.  This function should not be called before
-   * {@link TerrainProvider#ready} returns true.  This property may be undefined if availability
+   * at points and in rectangles. This property may be undefined if availability
    * information is not available.
    * @memberof EllipsoidTerrainProvider.prototype
    * @type {TileAvailability}
@@ -154,8 +162,7 @@ Object.defineProperties(EllipsoidTerrainProvider.prototype, {
 });
 
 /**
- * Requests the geometry for a given tile.  This function should not be called before
- * {@link TerrainProvider#ready} returns true.  The result includes terrain
+ * Requests the geometry for a given tile. The result includes terrain
  * data and indicates that all child tiles are available.
  *
  * @param {number} x The X coordinate of the tile for which to request geometry.

package/Source/Core/FrustumGeometry.js

@@ -295,8 +295,8 @@ FrustumGeometry._computeNearFarPlanes = function (
 
   let inverseView;
   let inverseViewProjection;
+  const projection = frustum.projectionMatrix;
   if (frustumType === PERSPECTIVE) {
-    const projection = frustum.projectionMatrix;
     const viewProjection = Matrix4.multiply(
       projection,
       view,
@@ -327,8 +327,9 @@ FrustumGeometry._computeNearFarPlanes = function (
       );
 
       if (!defined(inverseViewProjection)) {
-        if (defined(frustum._offCenterFrustum)) {
-          frustum = frustum._offCenterFrustum;
+        const offCenterFrustum = frustum.offCenterFrustum;
+        if (defined(offCenterFrustum)) {
+          frustum = offCenterFrustum;
         }
 
         const near = frustumSplits[i];

package/Source/Core/GeocoderService.js

@@ -1,9 +1,12 @@
+import Credit from "./Credit.js";
+import defined from "./defined.js";
 import DeveloperError from "./DeveloperError.js";
 
 /**
  * @typedef {object} GeocoderService.Result
  * @property {string} displayName The display name for a location
  * @property {Rectangle|Cartesian3} destination The bounding box for a location
+ * @property {object[]} [attributions]
  */
 
 /**
@@ -16,7 +19,35 @@ import DeveloperError from "./DeveloperError.js";
  * @see PeliasGeocoderService
  * @see OpenCageGeocoderService
  */
-function GeocoderService() {}
+function GeocoderService() {
+  DeveloperError.throwInstantiationError();
+}
+
+Object.defineProperties(GeocoderService.prototype, {
+  /**
+   * Gets the credit to display after a geocode is performed. Typically this is used to credit
+   * the geocoder service.
+   * @memberof GeocoderService.prototype
+   * @type {Credit|undefined}
+   * @readonly
+   */
+  credit: {
+    get: DeveloperError.throwInstantiationError,
+  },
+});
+
+/**
+ * Parses credits from the geocoder result attributions, if present.
+ * @param {GeocoderService.Result} geocoderResult The geocoder result
+ * @returns {Credit[]|undefined} A list of credits if present in the result, otherwise undefined
+ */
+GeocoderService.getCreditsFromResult = function (geocoderResult) {
+  if (defined(geocoderResult.attributions)) {
+    return geocoderResult.attributions.map(Credit.getIonCredit);
+  }
+
+  return undefined;
+};
 
 /**
  * @function

package/Source/Core/GoogleEarthEnterpriseMetadata.js

@@ -4,6 +4,7 @@ import Check from "./Check.js";
 import Credit from "./Credit.js";
 import defaultValue from "./defaultValue.js";
 import defined from "./defined.js";
+import deprecationWarning from "./deprecationWarning.js";
 import GoogleEarthEnterpriseTileInformation from "./GoogleEarthEnterpriseTileInformation.js";
 import isBitSet from "./isBitSet.js";
 import loadAndExecuteScript from "./loadAndExecuteScript.js";
@@ -30,37 +31,23 @@ const defaultKey = stringToBuffer(
 );
 
 /**
+ * <div class="notice">
+ * To construct GoogleEarthEnterpriseMetadata, call {@link GoogleEarthEnterpriseMetadata.fromUrl}. Do not call the constructor directly.
+ * </div>
+ *
  * Provides metadata using the Google Earth Enterprise REST API. This is used by the GoogleEarthEnterpriseImageryProvider
  *  and GoogleEarthEnterpriseTerrainProvider to share metadata requests.
  *
  * @alias GoogleEarthEnterpriseMetadata
  * @constructor
  *
- * @param {Resource|string} resourceOrUrl The url of the Google Earth Enterprise server hosting the imagery
+ * @param {Resource|string} [resourceOrUrl] The url of the Google Earth Enterprise server hosting the imagery. Deprecated.
  *
  * @see GoogleEarthEnterpriseImageryProvider
  * @see GoogleEarthEnterpriseTerrainProvider
  *
  */
 function GoogleEarthEnterpriseMetadata(resourceOrUrl) {
-  //>>includeStart('debug', pragmas.debug);
-  Check.defined("resourceOrUrl", resourceOrUrl);
-  //>>includeEnd('debug');
-
-  let url = resourceOrUrl;
-
-  if (typeof url !== "string" && !(url instanceof Resource)) {
-    //>>includeStart('debug', pragmas.debug);
-    Check.typeOf.string("resourceOrUrl.url", resourceOrUrl.url);
-    //>>includeEnd('debug');
-
-    url = resourceOrUrl.url;
-  }
-
-  const resource = Resource.createIfNeeded(url);
-  resource.appendForwardSlash();
-  this._resource = resource;
-
   /**
    * True if imagery is available.
    * @type {boolean}
@@ -109,25 +96,43 @@ function GoogleEarthEnterpriseMetadata(resourceOrUrl) {
    */
   this.key = undefined;
 
+  this._resource = undefined;
   this._quadPacketVersion = 1;
-
   this._tileInfo = {};
   this._subtreePromises = {};
 
-  const that = this;
-  this._readyPromise = requestDbRoot(this)
-    .then(function () {
-      return that.getQuadTreePacket("", that._quadPacketVersion);
-    })
-    .then(function () {
-      return true;
-    })
-    .catch(function (e) {
-      const message = `An error occurred while accessing ${
-        getMetadataResource(that, "", 1).url
-      }.`;
-      return Promise.reject(new RuntimeError(message));
-    });
+  this._readyPromise = Promise.resolve(true);
+  if (defined(resourceOrUrl)) {
+    deprecationWarning(
+      "GoogleEarthEnterpriseMetadata options.url",
+      "GoogleEarthEnterpriseMetadata constructor parmeter resourceOrUrl was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use GoogleEarthEnterpriseMetadata.fromUrl instead."
+    );
+
+    let url = resourceOrUrl;
+
+    if (typeof url !== "string" && !(url instanceof Resource)) {
+      url = resourceOrUrl.url;
+    }
+
+    const resource = Resource.createIfNeeded(url);
+    resource.appendForwardSlash();
+    this._resource = resource;
+
+    const that = this;
+    this._readyPromise = requestDbRoot(this)
+      .then(function () {
+        return that.getQuadTreePacket("", that._quadPacketVersion);
+      })
+      .then(function () {
+        return true;
+      })
+      .catch(function (e) {
+        const message = `An error occurred while accessing ${
+          getMetadataResource(that, "", 1).url
+        }.`;
+        return Promise.reject(new RuntimeError(message));
+      });
+  }
 }
 
 Object.defineProperties(GoogleEarthEnterpriseMetadata.prototype, {
@@ -172,14 +177,61 @@ Object.defineProperties(GoogleEarthEnterpriseMetadata.prototype, {
    * @memberof GoogleEarthEnterpriseMetadata.prototype
    * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "GoogleEarthEnterpriseMetadata.readyPromise",
+        "GoogleEarthEnterpriseMetadata.readyPromise was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use GoogleEarthEnterpriseMetadata.fromUrl instead."
+      );
       return this._readyPromise;
     },
   },
 });
 
+/**
+ * Creates a metadata object using the Google Earth Enterprise REST API. This is used by the GoogleEarthEnterpriseImageryProvider
+ * and GoogleEarthEnterpriseTerrainProvider to share metadata requests.
+ *
+ * @param {Resource|String} resourceOrUrl The url of the Google Earth Enterprise server hosting the imagery.
+ *
+ * @returns {Promise<GoogleEarthEnterpriseMetadata>} A promise which resolves to the created GoogleEarthEnterpriseMetadata instance/
+ */
+GoogleEarthEnterpriseMetadata.fromUrl = async function (resourceOrUrl) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("resourceOrUrl", resourceOrUrl);
+  //>>includeEnd('debug');
+  let url = resourceOrUrl;
+
+  if (typeof url !== "string" && !(url instanceof Resource)) {
+    //>>includeStart('debug', pragmas.debug);
+    Check.typeOf.string("resourceOrUrl.url", resourceOrUrl.url);
+    //>>includeEnd('debug');
+
+    url = resourceOrUrl.url;
+  }
+
+  const resource = Resource.createIfNeeded(url);
+  resource.appendForwardSlash();
+
+  const metadata = new GoogleEarthEnterpriseMetadata();
+  metadata._resource = resource;
+
+  try {
+    await requestDbRoot(metadata);
+    await metadata.getQuadTreePacket("", metadata._quadPacketVersion);
+  } catch (error) {
+    const message = `An error occurred while accessing ${
+      getMetadataResource(metadata, "", 1).url
+    }: ${error}`;
+
+    throw new RuntimeError(message);
+  }
+
+  return metadata;
+};
+
 /**
  * Converts a tiles (x, y, level) position into a quadkey used to request an image
  * from a Google Earth Enterprise server.