@cesium/engine 2.0.0 → 2.2.0

package/Source/Scene/ImageryLayerCollection.js

@@ -59,7 +59,7 @@ Object.defineProperties(ImageryLayerCollection.prototype, {
   /**
    * Gets the number of layers in this collection.
    * @memberof ImageryLayerCollection.prototype
-   * @type {Number}
+   * @type {number}
    */
   length: {
     get: function () {
@@ -72,10 +72,18 @@ Object.defineProperties(ImageryLayerCollection.prototype, {
  * Adds a layer to the collection.
  *
  * @param {ImageryLayer} layer the layer to add.
- * @param {Number} [index] the index to add the layer at.  If omitted, the layer will
+ * @param {number} [index] the index to add the layer at.  If omitted, the layer will
  *                         be added on top of all existing layers.
  *
  * @exception {DeveloperError} index, if supplied, must be greater than or equal to zero and less than or equal to the number of the layers.
+ *
+ * @example
+ * const imageryLayer = Cesium.ImageryLayer.fromWorldImagery();
+ * scene.imageryLayers.add(imageryLayer);
+ *
+ * @example
+ * const imageryLayer = Cesium.ImageryLayer.fromProviderAsync(Cesium.IonImageryProvider.fromAssetId(3812));
+ * scene.imageryLayers.add(imageryLayer);
  */
 ImageryLayerCollection.prototype.add = function (layer, index) {
   const hasIndex = defined(index);
@@ -104,15 +112,27 @@ ImageryLayerCollection.prototype.add = function (layer, index) {
 
   this._update();
   this.layerAdded.raiseEvent(layer, index);
+  const removeReadyEventListener = layer.readyEvent.addEventListener(() => {
+    this.layerShownOrHidden.raiseEvent(layer, layer._layerIndex, layer.show);
+    removeReadyEventListener();
+  });
 };
 
 /**
  * Creates a new layer using the given ImageryProvider and adds it to the collection.
  *
  * @param {ImageryProvider} imageryProvider the imagery provider to create a new layer for.
- * @param {Number} [index] the index to add the layer at.  If omitted, the layer will
+ * @param {number} [index] the index to add the layer at.  If omitted, the layer will
  *                         added on top of all existing layers.
  * @returns {ImageryLayer} The newly created layer.
+ *
+ * @example
+ * try {
+ *    const provider = await Cesium.IonImageryProvider.fromAssetId(3812);
+ *    scene.imageryLayers.addImageryProvider(provider);
+ * } catch (error) {
+ *   console.log(`There was an error creating the imagery layer. ${error}`)
+ * }
  */
 ImageryLayerCollection.prototype.addImageryProvider = function (
   imageryProvider,
@@ -133,8 +153,8 @@ ImageryLayerCollection.prototype.addImageryProvider = function (
  * Removes a layer from this collection, if present.
  *
  * @param {ImageryLayer} layer The layer to remove.
- * @param {Boolean} [destroy=true] whether to destroy the layers in addition to removing them.
- * @returns {Boolean} true if the layer was in the collection and was removed,
+ * @param {boolean} [destroy=true] whether to destroy the layers in addition to removing them.
+ * @returns {boolean} true if the layer was in the collection and was removed,
  *                    false if the layer was not in the collection.
  */
 ImageryLayerCollection.prototype.remove = function (layer, destroy) {
@@ -161,7 +181,7 @@ ImageryLayerCollection.prototype.remove = function (layer, destroy) {
 /**
  * Removes all layers from this collection.
  *
- * @param {Boolean} [destroy=true] whether to destroy the layers in addition to removing them.
+ * @param {boolean} [destroy=true] whether to destroy the layers in addition to removing them.
  */
 ImageryLayerCollection.prototype.removeAll = function (destroy) {
   destroy = defaultValue(destroy, true);
@@ -184,7 +204,7 @@ ImageryLayerCollection.prototype.removeAll = function (destroy) {
  *
  * @param {ImageryLayer} layer the layer to check for.
  *
- * @returns {Boolean} true if the collection contains the layer, false otherwise.
+ * @returns {boolean} true if the collection contains the layer, false otherwise.
  */
 ImageryLayerCollection.prototype.contains = function (layer) {
   return this.indexOf(layer) !== -1;
@@ -195,7 +215,7 @@ ImageryLayerCollection.prototype.contains = function (layer) {
  *
  * @param {ImageryLayer} layer The layer to find the index of.
  *
- * @returns {Number} The index of the layer in the collection, or -1 if the layer does not exist in the collection.
+ * @returns {number} The index of the layer in the collection, or -1 if the layer does not exist in the collection.
  */
 ImageryLayerCollection.prototype.indexOf = function (layer) {
   return this._layers.indexOf(layer);
@@ -204,7 +224,7 @@ ImageryLayerCollection.prototype.indexOf = function (layer) {
 /**
  * Gets a layer by index from the collection.
  *
- * @param {Number} index the index to retrieve.
+ * @param {number} index the index to retrieve.
  *
  * @returns {ImageryLayer} The imagery layer at the given index.
  */
@@ -353,6 +373,9 @@ function pickImageryHelper(scene, pickedLocation, pickFeatures, callback) {
     if (!defined(imagery)) {
       continue;
     }
+    if (!imagery.imageryLayer.ready) {
+      continue;
+    }
     const provider = imagery.imageryLayer.imageryProvider;
     if (pickFeatures && !defined(provider.pickFeatures)) {
       continue;
@@ -437,7 +460,7 @@ ImageryLayerCollection.prototype.pickImageryLayers = function (ray, scene) {
  *
  * @param {Ray} ray The ray to test for intersection.
  * @param {Scene} scene The scene.
- * @return {Promise.<ImageryLayerFeatureInfo[]>|undefined} A promise that resolves to an array of features intersected by the pick ray.
+ * @return {Promise<ImageryLayerFeatureInfo[]>|undefined} A promise that resolves to an array of features intersected by the pick ray.
  *                                             If it can be quickly determined that no features are intersected (for example,
  *                                             because no active imagery providers support {@link ImageryProvider#pickFeatures}
  *                                             or because the pick ray does not intersect the surface), this function will
@@ -476,6 +499,9 @@ ImageryLayerCollection.prototype.pickImageryLayerFeatures = function (
   const imageryLayers = [];
 
   pickImageryHelper(scene, pickedLocation, true, function (imagery) {
+    if (!imagery.imageryLayer.ready) {
+      return undefined;
+    }
     const provider = imagery.imageryLayer.imageryProvider;
     const promise = provider.pickFeatures(
       imagery.x,
@@ -552,7 +578,7 @@ ImageryLayerCollection.prototype.cancelReprojections = function () {
  * If this object was destroyed, it should not be used; calling any function other than
  * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
  *
- * @returns {Boolean} true if this object was destroyed; otherwise, false.
+ * @returns {boolean} true if this object was destroyed; otherwise, false.
  *
  * @see ImageryLayerCollection#destroy
  */

package/Source/Scene/ImageryLayerFeatureInfo.js

@@ -9,14 +9,14 @@ import defined from "../Core/defined.js";
 function ImageryLayerFeatureInfo() {
   /**
    * Gets or sets the name of the feature.
-   * @type {String|undefined}
+   * @type {string|undefined}
    */
   this.name = undefined;
 
   /**
    * Gets or sets an HTML description of the feature.  The HTML is not trusted and should
    * be sanitized before display to the user.
-   * @type {String|undefined}
+   * @type {string|undefined}
    */
   this.description = undefined;
 
@@ -30,13 +30,13 @@ function ImageryLayerFeatureInfo() {
   /**
    * Gets or sets the raw data describing the feature.  The raw data may be in any
    * number of formats, such as GeoJSON, KML, etc.
-   * @type {Object|undefined}
+   * @type {object|undefined}
    */
   this.data = undefined;
 
   /**
    * Gets or sets the image layer of the feature.
-   * @type {Object|undefined}
+   * @type {object|undefined}
    */
   this.imageryLayer = undefined;
 }
@@ -47,7 +47,7 @@ function ImageryLayerFeatureInfo() {
  * 3) the first property containing the word 'name', 4) the first property containing the word 'title'.  If
  * the name cannot be obtained from any of these sources, the existing name will be left unchanged.
  *
- * @param {Object} properties An object literal containing the properties of the feature.
+ * @param {object} properties An object literal containing the properties of the feature.
  */
 ImageryLayerFeatureInfo.prototype.configureNameFromProperties = function (
   properties
@@ -83,7 +83,7 @@ ImageryLayerFeatureInfo.prototype.configureNameFromProperties = function (
 /**
  * Configures the description of this feature by creating an HTML table of properties and their values.
  *
- * @param {Object} properties An object literal containing the properties of the feature.
+ * @param {object} properties An object literal containing the properties of the feature.
  */
 ImageryLayerFeatureInfo.prototype.configureDescriptionFromProperties = function (
   properties

package/Source/Scene/ImageryProvider.js

@@ -43,92 +43,6 @@ import Resource from "../Core/Resource.js";
  * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Layers%20Manipulation.html|Cesium Sandcastle Imagery Manipulation Demo}
  */
 function ImageryProvider() {
-  /**
-   * The default alpha blending value of this provider, with 0.0 representing fully transparent and
-   * 1.0 representing fully opaque.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultAlpha = undefined;
-
-  /**
-   * The default alpha blending value on the night side of the globe of this provider, with 0.0 representing fully transparent and
-   * 1.0 representing fully opaque.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultNightAlpha = undefined;
-
-  /**
-   * The default alpha blending value on the day side of the globe of this provider, with 0.0 representing fully transparent and
-   * 1.0 representing fully opaque.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultDayAlpha = undefined;
-
-  /**
-   * The default brightness of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0
-   * makes the imagery darker while greater than 1.0 makes it brighter.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultBrightness = undefined;
-
-  /**
-   * The default contrast of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0 reduces
-   * the contrast while greater than 1.0 increases it.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultContrast = undefined;
-
-  /**
-   * The default hue of this provider in radians. 0.0 uses the unmodified imagery color.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultHue = undefined;
-
-  /**
-   * The default saturation of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the
-   * saturation while greater than 1.0 increases it.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultSaturation = undefined;
-
-  /**
-   * The default gamma correction to apply to this provider.  1.0 uses the unmodified imagery color.
-   *
-   * @type {Number|undefined}
-   * @default undefined
-   */
-  this.defaultGamma = undefined;
-
-  /**
-   * The default texture minification filter to apply to this provider.
-   *
-   * @type {TextureMinificationFilter}
-   * @default undefined
-   */
-  this.defaultMinificationFilter = undefined;
-
-  /**
-   * The default texture magnification filter to apply to this provider.
-   *
-   * @type {TextureMagnificationFilter}
-   * @default undefined
-   */
-  this.defaultMagnificationFilter = undefined;
-
   DeveloperError.throwInstantiationError();
 }
 
@@ -136,8 +50,9 @@ Object.defineProperties(ImageryProvider.prototype, {
   /**
    * Gets a value indicating whether or not the provider is ready for use.
    * @memberof ImageryProvider.prototype
-   * @type {Boolean}
+   * @type {boolean}
    * @readonly
+   * @deprecated
    */
   ready: {
     get: DeveloperError.throwInstantiationError,
@@ -146,16 +61,16 @@ Object.defineProperties(ImageryProvider.prototype, {
   /**
    * Gets a promise that resolves to true when the provider is ready for use.
    * @memberof ImageryProvider.prototype
-   * @type {Promise.<Boolean>}
+   * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: DeveloperError.throwInstantiationError,
   },
 
   /**
-   * Gets the rectangle, in radians, of the imagery provided by the instance.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the rectangle, in radians, of the imagery provided by the instance.
    * @memberof ImageryProvider.prototype
    * @type {Rectangle}
    * @readonly
@@ -165,10 +80,9 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the width of each tile, in pixels.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the width of each tile, in pixels.
    * @memberof ImageryProvider.prototype
-   * @type {Number}
+   * @type {number}
    * @readonly
    */
   tileWidth: {
@@ -176,10 +90,9 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the height of each tile, in pixels.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the height of each tile, in pixels.
    * @memberof ImageryProvider.prototype
-   * @type {Number}
+   * @type {number}
    * @readonly
    */
   tileHeight: {
@@ -187,10 +100,9 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the maximum level-of-detail that can be requested.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the maximum level-of-detail that can be requested.
    * @memberof ImageryProvider.prototype
-   * @type {Number|undefined}
+   * @type {number|undefined}
    * @readonly
    */
   maximumLevel: {
@@ -198,14 +110,13 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the minimum level-of-detail that can be requested.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true. Generally,
+   * Gets the minimum level-of-detail that can be requested.  Generally,
    * a minimum level should only be used when the rectangle of the imagery is small
    * enough that the number of tiles at the minimum level is small.  An imagery
    * provider with more than a few tiles at the minimum level will lead to
    * rendering problems.
    * @memberof ImageryProvider.prototype
-   * @type {Number}
+   * @type {number}
    * @readonly
    */
   minimumLevel: {
@@ -213,8 +124,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the tiling scheme used by the provider.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the tiling scheme used by the provider.
    * @memberof ImageryProvider.prototype
    * @type {TilingScheme}
    * @readonly
@@ -226,8 +136,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   /**
    * Gets the tile discard policy.  If not undefined, the discard policy is responsible
    * for filtering out "missing" tiles via its shouldDiscardImage function.  If this function
-   * returns undefined, no tiles are filtered.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * returns undefined, no tiles are filtered.
    * @memberof ImageryProvider.prototype
    * @type {TileDiscardPolicy}
    * @readonly
@@ -237,7 +146,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets an event that is raised when the imagery provider encounters an asynchronous error..  By subscribing
+   * Gets an event that is raised when the imagery provider encounters an asynchronous error.  By subscribing
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
    * are passed an instance of {@link TileProviderError}.
    * @memberof ImageryProvider.prototype
@@ -250,8 +159,7 @@ Object.defineProperties(ImageryProvider.prototype, {
 
   /**
    * Gets the credit to display when this imagery provider is active.  Typically this is used to credit
-   * the source of the imagery. This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * the source of the imagery.
    * @memberof ImageryProvider.prototype
    * @type {Credit}
    * @readonly
@@ -277,40 +185,151 @@ Object.defineProperties(ImageryProvider.prototype, {
    * as if their alpha is 1.0 everywhere.  When this property is false, memory usage
    * and texture upload time are reduced.
    * @memberof ImageryProvider.prototype
-   * @type {Boolean}
+   * @type {boolean}
    * @readonly
    */
   hasAlphaChannel: {
     get: DeveloperError.throwInstantiationError,
   },
+
+  /**
+   * The default alpha blending value of this provider, with 0.0 representing fully transparent and
+   * 1.0 representing fully opaque.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultAlpha: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default alpha blending value on the night side of the globe of this provider, with 0.0 representing fully transparent and
+   * 1.0 representing fully opaque.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultNightAlpha: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default alpha blending value on the day side of the globe of this provider, with 0.0 representing fully transparent and
+   * 1.0 representing fully opaque.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultDayAlpha: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default brightness of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0
+   * makes the imagery darker while greater than 1.0 makes it brighter.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultBrightness: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default contrast of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0 reduces
+   * the contrast while greater than 1.0 increases it.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultContrast: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default hue of this provider in radians. 0.0 uses the unmodified imagery color.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultHue: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default saturation of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the
+   * saturation while greater than 1.0 increases it.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultSaturation: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default gamma correction to apply to this provider.  1.0 uses the unmodified imagery color.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultGamma: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default texture minification filter to apply to this provider.
+   * @memberof ImageryProvider.prototype
+   * @type {TextureMinificationFilter}
+   * @deprecated
+   */
+  defaultMinificationFilter: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default texture magnification filter to apply to this provider.
+   * @memberof ImageryProvider.prototype
+   * @type {TextureMagnificationFilter}
+   * @deprecated
+   */
+  defaultMagnificationFilter: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
 });
 
 /**
  * Gets the credits to be displayed when a given tile is displayed.
  *
- * @param {Number} x The tile X coordinate.
- * @param {Number} y The tile Y coordinate.
- * @param {Number} level The tile level;
+ * @param {number} x The tile X coordinate.
+ * @param {number} y The tile Y coordinate.
+ * @param {number} level The tile level;
  * @returns {Credit[]} The credits to be displayed when the tile is displayed.
- *
- * @exception {DeveloperError} <code>getTileCredits</code> must not be called before the imagery provider is ready.
  */
 ImageryProvider.prototype.getTileCredits = function (x, y, level) {
   DeveloperError.throwInstantiationError();
 };
 
 /**
- * Requests the image for a given tile.  This function should
- * not be called before {@link ImageryProvider#ready} returns true.
+ * Requests the image for a given tile.
  *
- * @param {Number} x The tile X coordinate.
- * @param {Number} y The tile Y coordinate.
- * @param {Number} level The tile level.
+ * @param {number} x The tile X coordinate.
+ * @param {number} y The tile Y coordinate.
+ * @param {number} level The tile level.
  * @param {Request} [request] The request object. Intended for internal use only.
- * @returns {Promise.<ImageryTypes>|undefined} Returns a promise for the image that will resolve when the image is available, or
+ * @returns {Promise<ImageryTypes>|undefined} Returns a promise for the image that will resolve when the image is available, or
  *          undefined if there are too many active requests to the server, and the request should be retried later.
- *
- * @exception {DeveloperError} <code>requestImage</code> must not be called before the imagery provider is ready.
  */
 ImageryProvider.prototype.requestImage = function (x, y, level, request) {
   DeveloperError.throwInstantiationError();
@@ -318,22 +337,21 @@ ImageryProvider.prototype.requestImage = function (x, y, level, request) {
 
 /**
  * Asynchronously determines what features, if any, are located at a given longitude and latitude within
- * a tile.  This function should not be called before {@link ImageryProvider#ready} returns true.
+ * a tile.
  * This function is optional, so it may not exist on all ImageryProviders.
  *
  * @function
  *
- * @param {Number} x The tile X coordinate.
- * @param {Number} y The tile Y coordinate.
- * @param {Number} level The tile level.
- * @param {Number} longitude The longitude at which to pick features.
- * @param {Number} latitude  The latitude at which to pick features.
- * @return {Promise.<ImageryLayerFeatureInfo[]>|undefined} A promise for the picked features that will resolve when the asynchronous
+ * @param {number} x The tile X coordinate.
+ * @param {number} y The tile Y coordinate.
+ * @param {number} level The tile level.
+ * @param {number} longitude The longitude at which to pick features.
+ * @param {number} latitude  The latitude at which to pick features.
+ * @return {Promise<ImageryLayerFeatureInfo[]>|undefined} A promise for the picked features that will resolve when the asynchronous
  *                   picking completes.  The resolved value is an array of {@link ImageryLayerFeatureInfo}
  *                   instances.  The array may be empty if no features are found at the given location.
  *                   It may also be undefined if picking is not supported.
  *
- * @exception {DeveloperError} <code>pickFeatures</code> must not be called before the imagery provider is ready.
  */
 ImageryProvider.prototype.pickFeatures = function (
   x,
@@ -353,8 +371,8 @@ const ktx2Regex = /\.ktx2$/i;
  * that the request should be retried later.
  *
  * @param {ImageryProvider} imageryProvider The imagery provider for the URL.
- * @param {Resource|String} url The URL of the image.
- * @returns {Promise.<ImageryTypes|CompressedTextureBuffer>|undefined} A promise for the image that will resolve when the image is available, or
+ * @param {Resource|string} url The URL of the image.
+ * @returns {Promise<ImageryTypes|CompressedTextureBuffer>|undefined} A promise for the image that will resolve when the image is available, or
  *          undefined if there are too many active requests to the server, and the request should be retried later.
  */
 ImageryProvider.loadImage = function (imageryProvider, url) {