@cesium/engine 2.1.0 → 2.2.0

package/Source/Scene/TileMapServiceImageryProvider.js

@@ -1,8 +1,9 @@
 import Cartesian2 from "../Core/Cartesian2.js";
 import Cartographic from "../Core/Cartographic.js";
+import Check from "../Core/Check.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
-import DeveloperError from "../Core/DeveloperError.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import GeographicProjection from "../Core/GeographicProjection.js";
 import GeographicTilingScheme from "../Core/GeographicTilingScheme.js";
 import Rectangle from "../Core/Rectangle.js";
@@ -18,7 +19,7 @@ import UrlTemplateImageryProvider from "./UrlTemplateImageryProvider.js";
  *
  * Initialization options for the TileMapServiceImageryProvider constructor
  *
- * @property {Resource|string|Promise<Resource>|Promise<string>} [url='.'] Path to image tiles on server.
+ * @property {Resource|string|Promise<Resource>|Promise<string>} [url] Path to image tiles on server. Deprecated
  * @property {string} [fileExtension='png'] The file extension for images on the server.
  * @property {Credit|string} [credit=''] A credit for the data source, which is displayed on the canvas.
  * @property {number} [minimumLevel=0] The minimum level-of-detail supported by the imagery provider.  Take care when specifying
@@ -35,10 +36,15 @@ import UrlTemplateImageryProvider from "./UrlTemplateImageryProvider.js";
  * @property {number} [tileWidth=256] Pixel width of image tiles.
  * @property {number} [tileHeight=256] Pixel height of image tiles.
  * @property {boolean} [flipXY] Older versions of gdal2tiles.py flipped X and Y values in tilemapresource.xml.
+ * @property {TileDiscardPolicy} [tileDiscardPolicy] A policy for discarding tile images according to some criteria
  * Specifying this option will do the same, allowing for loading of these incorrect tilesets.
  */
 
 /**
+ * <div class="notice">
+ * To construct a TileMapServiceImageryProvider, call {@link TileMapServiceImageryProvider.fromUrl}. Do not call the constructor directly.
+ * </div>
+ *
  * An imagery provider that provides tiled imagery as generated by
  * {@link http://www.maptiler.org/|MapTiler}, {@link http://www.klokan.cz/projects/gdal2tiles/|GDAL2Tiles}, etc.
  *
@@ -58,11 +64,11 @@ import UrlTemplateImageryProvider from "./UrlTemplateImageryProvider.js";
  * @see UrlTemplateImageryProvider
  *
  * @example
- * const tms = new Cesium.TileMapServiceImageryProvider({
- *    url : '../images/cesium_maptiler/Cesium_Logo_Color',
- *    fileExtension: 'png',
- *    maximumLevel: 4,
- *    rectangle: new Cesium.Rectangle(
+ * const tms = await Cesium.TileMapServiceImageryProvider.fromUrl(
+ *    "../images/cesium_maptiler/Cesium_Logo_Color", {
+ *      fileExtension: 'png',
+ *      maximumLevel: 4,
+ *      rectangle: new Cesium.Rectangle(
  *        Cesium.Math.toRadians(-120.0),
  *        Cesium.Math.toRadians(20.0),
  *        Cesium.Math.toRadians(-60.0),
@@ -72,43 +78,122 @@ import UrlTemplateImageryProvider from "./UrlTemplateImageryProvider.js";
 function TileMapServiceImageryProvider(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
-  //>>includeStart('debug', pragmas.debug);
-  if (!defined(options.url)) {
-    throw new DeveloperError("options.url is required.");
-  }
-  //>>includeEnd('debug');
+  if (defined(options.url)) {
+    deprecationWarning(
+      "TileMapServiceImageryProvider options.url",
+      "options.url was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use TileMapServiceImageryProvider.fromUrl instead."
+    );
 
-  this._tmsResource = undefined;
-  this._xmlResource = undefined;
-  this._options = options;
-  this._metadataError = undefined;
-
-  this._metadataSuccess = this._metadataSuccess.bind(this);
-  this._metadataFailure = this._metadataFailure.bind(this);
-  this._requestMetadata = this._requestMetadata.bind(this);
-
-  let resource;
-  const that = this;
-  const promise = Promise.resolve(options.url)
-    .then(function (url) {
-      resource = Resource.createIfNeeded(url);
-      resource.appendForwardSlash();
-
-      that._tmsResource = resource;
-      that._xmlResource = resource.getDerivedResource({
-        url: "tilemapresource.xml",
+    this._metadataError = undefined;
+    this._ready = false;
+
+    let resource;
+    const that = this;
+    const promise = Promise.resolve(options.url)
+      .then(function (url) {
+        resource = Resource.createIfNeeded(url);
+        resource.appendForwardSlash();
+
+        that._tmsResource = resource;
+        that._xmlResource = resource.getDerivedResource({
+          url: "tilemapresource.xml",
+        });
+
+        return TileMapServiceImageryProvider._requestMetadata(
+          options,
+          that._tmsResource,
+          that._xmlResource,
+          that
+        );
+      })
+      .catch((e) => {
+        return Promise.reject(e);
       });
 
-      return that._requestMetadata();
-    })
-    .catch((e) => {
-      return Promise.reject(e);
-    });
+    UrlTemplateImageryProvider.call(this, promise);
+    this._promise = promise;
+  }
 
-  UrlTemplateImageryProvider.call(this, promise);
-  this._promise = promise;
+  // After readyPromise deprecation, this should become just
+  // UrlTemplateImageryProvider.call(this, options);
 }
 
+TileMapServiceImageryProvider._requestMetadata = async function (
+  options,
+  tmsResource,
+  xmlResource,
+  provider
+) {
+  // Try to load remaining parameters from XML
+  try {
+    const xml = await xmlResource.fetchXML();
+    return TileMapServiceImageryProvider._metadataSuccess(
+      xml,
+      options,
+      tmsResource,
+      xmlResource,
+      provider
+    );
+  } catch (e) {
+    if (e instanceof RequestErrorEvent) {
+      return TileMapServiceImageryProvider._metadataFailure(
+        options,
+        tmsResource
+      );
+    }
+
+    throw e;
+  }
+};
+/**
+ * Creates a TileMapServiceImageryProvider from the specified url.
+ *
+ * @param {Resource|String} url Path to image tiles on server.
+ * @param {TileMapServiceImageryProvider.ConstructorOptions} [options] Object describing initialization options.
+ * @returns {Promise<TileMapServiceImageryProvider>} A promise that resolves to the created TileMapServiceImageryProvider.
+ *
+ * @example
+ * const tms = await Cesium.TileMapServiceImageryProvider.fromUrl(
+ *    '../images/cesium_maptiler/Cesium_Logo_Color', {
+ *      fileExtension: 'png',
+ *      maximumLevel: 4,
+ *      rectangle: new Cesium.Rectangle(
+ *        Cesium.Math.toRadians(-120.0),
+ *        Cesium.Math.toRadians(20.0),
+ *        Cesium.Math.toRadians(-60.0),
+ *        Cesium.Math.toRadians(40.0))
+ * });
+ *
+ * @exception {RuntimeError} Unable to find expected tilesets or bbox attributes in tilemapresource.xml
+ * @exception {RuntimeError} tilemapresource.xml specifies an unsupported profile attribute
+ */
+TileMapServiceImageryProvider.fromUrl = async function (url, options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("url", url);
+  //>>includeEnd('debug');
+
+  const resource = Resource.createIfNeeded(url);
+  resource.appendForwardSlash();
+
+  const tmsResource = resource;
+  const xmlResource = resource.getDerivedResource({
+    url: "tilemapresource.xml",
+  });
+
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  const metadata = await TileMapServiceImageryProvider._requestMetadata(
+    options,
+    tmsResource,
+    xmlResource
+  );
+
+  // Once the deprecated behavior is removed, this can become
+  // return new TileMapServiceImageryProvider(metadata);
+  const provider = new TileMapServiceImageryProvider();
+  UrlTemplateImageryProvider.call(provider, metadata);
+  return provider;
+};
+
 if (defined(Object.create)) {
   TileMapServiceImageryProvider.prototype = Object.create(
     UrlTemplateImageryProvider.prototype
@@ -116,19 +201,6 @@ if (defined(Object.create)) {
   TileMapServiceImageryProvider.prototype.constructor = TileMapServiceImageryProvider;
 }
 
-TileMapServiceImageryProvider.prototype._requestMetadata = function () {
-  // Try to load remaining parameters from XML
-  return this._xmlResource
-    .fetchXML()
-    .then(this._metadataSuccess)
-    .catch((e) => {
-      if (e instanceof RequestErrorEvent) {
-        return this._metadataFailure();
-      }
-      return Promise.reject(e);
-    });
-};
-
 /**
  * Mutates the properties of a given rectangle so it does not extend outside of the given tiling scheme's rectangle
  * @private
@@ -173,16 +245,29 @@ function calculateSafeMinimumDetailLevel(
   return minimumLevel;
 }
 
-TileMapServiceImageryProvider.prototype._metadataSuccess = function (xml) {
+/**
+ * Parses the results of a successful xml request
+ * @private
+ *
+ * @param {Object} xml
+ * @param {TileMapServiceImageryProvider.ConstructorOptions} options
+ * @param {Resource} tmsResource
+ * @param {Resource} xmlResource
+ * @returns {UrlTemplateImageryProvider.ConstructorOptions}
+ */
+TileMapServiceImageryProvider._metadataSuccess = function (
+  xml,
+  options,
+  tmsResource,
+  xmlResource,
+  provider
+) {
   const tileFormatRegex = /tileformat/i;
   const tileSetRegex = /tileset/i;
   const tileSetsRegex = /tilesets/i;
   const bboxRegex = /boundingbox/i;
   let format, bbox, tilesets;
   const tilesetsList = []; //list of TileSets
-  const xmlResource = this._xmlResource;
-  let metadataError = this._metadataError;
-  const requestMetadata = this._requestMetadata;
 
   // Allowing options properties (already copied to that) to override XML values
 
@@ -209,20 +294,18 @@ TileMapServiceImageryProvider.prototype._metadataSuccess = function (xml) {
   let message;
   if (!defined(tilesets) || !defined(bbox)) {
     message = `Unable to find expected tilesets or bbox attributes in ${xmlResource.url}.`;
-    metadataError = TileProviderError.reportError(
-      metadataError,
-      this,
-      this.errorEvent,
-      message
-    );
-    if (metadataError.retry) {
-      this._metadataError = metadataError;
-      return requestMetadata();
+    if (defined(provider)) {
+      TileProviderError.reportError(
+        undefined,
+        provider,
+        provider.errorEvent,
+        message
+      );
     }
-    return Promise.reject(new RuntimeError(message));
+
+    throw new RuntimeError(message);
   }
 
-  const options = this._options;
   const fileExtension = defaultValue(
     options.fileExtension,
     format.getAttribute("extension")
@@ -262,18 +345,17 @@ TileMapServiceImageryProvider.prototype._metadataSuccess = function (xml) {
         ellipsoid: options.ellipsoid,
       });
     } else {
-      message = `${xmlResource.url}specifies an unsupported profile attribute, ${tilingSchemeName}.`;
-      metadataError = TileProviderError.reportError(
-        metadataError,
-        this,
-        this.errorEvent,
-        message
-      );
-      if (metadataError.retry) {
-        this._metadataError = metadataError;
-        return requestMetadata();
+      message = `${xmlResource.url} specifies an unsupported profile attribute, ${tilingSchemeName}.`;
+      if (defined(provider)) {
+        TileProviderError.reportError(
+          undefined,
+          provider,
+          provider.errorEvent,
+          message
+        );
       }
-      return Promise.reject(new RuntimeError(message));
+
+      throw new RuntimeError(message);
     }
   }
 
@@ -344,11 +426,11 @@ TileMapServiceImageryProvider.prototype._metadataSuccess = function (xml) {
     minimumLevel
   );
 
-  const templateResource = this._tmsResource.getDerivedResource({
+  const templateResource = tmsResource.getDerivedResource({
     url: `{z}/{x}/{reverseY}.${fileExtension}`,
   });
 
-  return Promise.resolve({
+  return {
     url: templateResource,
     tilingScheme: tilingScheme,
     rectangle: rectangle,
@@ -358,12 +440,22 @@ TileMapServiceImageryProvider.prototype._metadataSuccess = function (xml) {
     maximumLevel: maximumLevel,
     tileDiscardPolicy: options.tileDiscardPolicy,
     credit: options.credit,
-  });
+  };
 };
 
-TileMapServiceImageryProvider.prototype._metadataFailure = function () {
+/**
+ * Handle xml request failure by providing the default values
+ * @private
+ *
+ * @param {TileMapServiceImageryProvider.ConstructorOptions} options
+ * @param {Resource} tmsResource
+ * @returns {UrlTemplateImageryProvider.ConstructorOptions}
+ */
+TileMapServiceImageryProvider._metadataFailure = function (
+  options,
+  tmsResource
+) {
   // Can't load XML, still allow options and defaults
-  const options = this._options;
   const fileExtension = defaultValue(options.fileExtension, "png");
   const tileWidth = defaultValue(options.tileWidth, 256);
   const tileHeight = defaultValue(options.tileHeight, 256);
@@ -383,11 +475,11 @@ TileMapServiceImageryProvider.prototype._metadataFailure = function () {
     options.minimumLevel
   );
 
-  const templateResource = this._tmsResource.getDerivedResource({
+  const templateResource = tmsResource.getDerivedResource({
     url: `{z}/{x}/{reverseY}.${fileExtension}`,
   });
 
-  return Promise.resolve({
+  return {
     url: templateResource,
     tilingScheme: tilingScheme,
     rectangle: rectangle,
@@ -397,7 +489,7 @@ TileMapServiceImageryProvider.prototype._metadataFailure = function () {
     maximumLevel: maximumLevel,
     tileDiscardPolicy: options.tileDiscardPolicy,
     credit: options.credit,
-  });
+  };
 };
 
 export default TileMapServiceImageryProvider;

package/Source/Scene/Tileset3DTileContent.js

@@ -1,4 +1,5 @@
 import destroyObject from "../Core/destroyObject.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 
 /**
  * Represents content for a tile in a
@@ -13,7 +14,7 @@ import destroyObject from "../Core/destroyObject.js";
  *
  * @private
  */
-function Tileset3DTileContent(tileset, tile, resource, json) {
+function Tileset3DTileContent(tileset, tile, resource) {
   this._tileset = tileset;
   this._tile = tile;
   this._resource = resource;
@@ -23,7 +24,8 @@ function Tileset3DTileContent(tileset, tile, resource, json) {
   this._metadata = undefined;
   this._group = undefined;
 
-  this._readyPromise = initialize(this, json);
+  this._ready = false;
+  this._readyPromise = Promise.resolve(this);
 }
 
 Object.defineProperties(Tileset3DTileContent.prototype, {
@@ -69,8 +71,37 @@ Object.defineProperties(Tileset3DTileContent.prototype, {
     },
   },
 
+  /**
+   * Returns true when the tile's content is ready to render; otherwise false
+   *
+   * @memberof Tileset3DTileContent.prototype
+   *
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  ready: {
+    get: function () {
+      return this._ready;
+    },
+  },
+
+  /**
+   * Gets the promise that will be resolved when the tile's content is ready to render.
+   *
+   * @memberof Tileset3DTileContent.prototype
+   *
+   * @type {Promise<Tileset3DTileContent>}
+   * @readonly
+   * @deprecated
+   * @private
+   */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "Tileset3DTileContent.readyPromise",
+        "Tileset3DTileContent.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Wait for Tileset3DTileContent.ready to return true instead."
+      );
       return this._readyPromise;
     },
   },
@@ -118,10 +149,21 @@ Object.defineProperties(Tileset3DTileContent.prototype, {
   },
 });
 
-function initialize(content, json) {
+/**
+ * Creates an instance of Tileset3DTileContent from a parsed JSON object
+ * @param {Cesium3DTileset} tileset
+ * @param {Cesium3DTile} tile
+ * @param {Resource} resource
+ * @param {object} json
+ * @returns {Tileset3DTileContent}
+ */
+Tileset3DTileContent.fromJson = function (tileset, tile, resource, json) {
+  const content = new Tileset3DTileContent(tileset, tile, resource);
   content._tileset.loadTileset(content._resource, json, content._tile);
-  return Promise.resolve(content);
-}
+  content._ready = true;
+
+  return content;
+};
 
 /**
  * Part of the {@link Cesium3DTileContent} interface.  <code>Tileset3DTileContent</code>

package/Source/Scene/TimeDynamicPointCloud.js

@@ -3,6 +3,7 @@ import combine from "../Core/combine.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import Event from "../Core/Event.js";
 import getTimestamp from "../Core/getTimestamp.js";
 import JulianDate from "../Core/JulianDate.js";
@@ -183,6 +184,7 @@ function TimeDynamicPointCloud(options) {
   this._clockMultiplier = 0.0;
   this._resolveReadyPromise = undefined;
   const that = this;
+  // This is here for backwards compatibility and can be removed when readyPromise is removed.
   this._readyPromise = new Promise(function (resolve) {
     that._resolveReadyPromise = resolve;
   });
@@ -252,9 +254,14 @@ Object.defineProperties(TimeDynamicPointCloud.prototype, {
    *
    * @type {Promise<TimeDynamicPointCloud>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "TimeDynamicPointCloud.readyPromise",
+        "TimeDynamicPointCloud.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Use TimeDynamicPointCloud.frameFailed instead."
+      );
       return this._readyPromise;
     },
   },
@@ -395,6 +402,7 @@ function requestFrame(that, interval, frameState) {
       sequential: true,
       ready: false,
       touchedFrameNumber: frameState.frameNumber,
+      uri: uri,
     };
     frames[index] = frame;
     Resource.fetchArrayBuffer({
@@ -410,7 +418,6 @@ function requestFrame(that, interval, frameState) {
           uniformMapLoaded: getUniformMapLoaded(that),
           pickIdLoaded: getPickIdLoaded,
         });
-        return frame.pointCloud.readyPromise;
       })
       .catch(handleFrameFailure(that, uri));
   }
@@ -507,7 +514,12 @@ function renderFrame(that, frame, updateState, frameState) {
   pointCloud.geometricErrorScale = shading.geometricErrorScale;
   pointCloud.maximumAttenuation = getMaximumAttenuation(that);
 
-  pointCloud.update(frameState);
+  try {
+    pointCloud.update(frameState);
+  } catch (error) {
+    handleFrameFailure(that, frame.uri)(error);
+  }
+
   frame.touchedFrameNumber = frameState.frameNumber;
 }
 
@@ -738,6 +750,7 @@ TimeDynamicPointCloud.prototype.update = function (frameState) {
   const that = this;
   if (defined(frame) && !defined(this._lastRenderedFrame)) {
     frameState.afterRender.push(function () {
+      // This is here for backwards compatibility and can be removed when readyPromise is removed.
       that._resolveReadyPromise(that);
       return true;
     });