@cesium/engine 2.1.0 → 2.3.0

package/Source/Core/VRTheWorldTerrainProvider.js

@@ -1,7 +1,8 @@
+import Check from "./Check.js";
 import Credit from "./Credit.js";
 import defaultValue from "./defaultValue.js";
 import defined from "./defined.js";
-import DeveloperError from "./DeveloperError.js";
+import deprecationWarning from "./deprecationWarning.js";
 import Ellipsoid from "./Ellipsoid.js";
 import Event from "./Event.js";
 import GeographicTilingScheme from "./GeographicTilingScheme.js";
@@ -20,38 +21,143 @@ function DataRectangle(rectangle, maxLevel) {
 }
 
 /**
+ * @typedef {Object} VRTheWorldTerrainProvider.ConstructorOptions
+ *
+ * Initialization options for the VRTheWorldTerrainProvider constructor
+ *
+ * @property {Ellipsoid} [ellipsoid] The ellipsoid.  If not specified, the WGS84 ellipsoid is used.
+ * @property {Credit|string} [credit] A credit for the data source, which is displayed on the canvas.
+ * @property {Resource|string} [url] The URL of the VR-TheWorld TileMap. Deprecated.
+ */
+
+/**
+ * Used to track creation details while fetching initial metadata
+ *
+ * @constructor
+ * @private
+ *
+ * @param {VRTheWorldTerrainProvider.ConstructorOptions} options An object describing initialization options
+ */
+function TerrainProviderBuilder(options) {
+  this.ellipsoid = defaultValue(options.ellipsoid, Ellipsoid.WGS84);
+  this.tilingScheme = undefined;
+  this.heightmapWidth = undefined;
+  this.heightmapHeight = undefined;
+  this.levelZeroMaximumGeometricError = undefined;
+  this.rectangles = [];
+}
+
+TerrainProviderBuilder.prototype.build = function (provider) {
+  provider._tilingScheme = this.tilingScheme;
+  provider._heightmapWidth = this.heightmapWidth;
+  provider._heightmapHeight = this.heightmapHeight;
+  provider._levelZeroMaximumGeometricError = this.levelZeroMaximumGeometricError;
+  provider._rectangles = this.rectangles;
+  provider._ready = true;
+};
+
+function metadataSuccess(terrainProviderBuilder, xml) {
+  const srs = xml.getElementsByTagName("SRS")[0].textContent;
+  if (srs === "EPSG:4326") {
+    terrainProviderBuilder.tilingScheme = new GeographicTilingScheme({
+      ellipsoid: terrainProviderBuilder.ellipsoid,
+    });
+  } else {
+    throw new RuntimeError(`SRS ${srs} is not supported`);
+  }
+
+  const tileFormat = xml.getElementsByTagName("TileFormat")[0];
+  terrainProviderBuilder.heightmapWidth = parseInt(
+    tileFormat.getAttribute("width"),
+    10
+  );
+  terrainProviderBuilder.heightmapHeight = parseInt(
+    tileFormat.getAttribute("height"),
+    10
+  );
+  terrainProviderBuilder.levelZeroMaximumGeometricError = TerrainProvider.getEstimatedLevelZeroGeometricErrorForAHeightmap(
+    terrainProviderBuilder.ellipsoid,
+    Math.min(
+      terrainProviderBuilder.heightmapWidth,
+      terrainProviderBuilder.heightmapHeight
+    ),
+    terrainProviderBuilder.tilingScheme.getNumberOfXTilesAtLevel(0)
+  );
+
+  const dataRectangles = xml.getElementsByTagName("DataExtent");
+
+  for (let i = 0; i < dataRectangles.length; ++i) {
+    const dataRectangle = dataRectangles[i];
+
+    const west = CesiumMath.toRadians(
+      parseFloat(dataRectangle.getAttribute("minx"))
+    );
+    const south = CesiumMath.toRadians(
+      parseFloat(dataRectangle.getAttribute("miny"))
+    );
+    const east = CesiumMath.toRadians(
+      parseFloat(dataRectangle.getAttribute("maxx"))
+    );
+    const north = CesiumMath.toRadians(
+      parseFloat(dataRectangle.getAttribute("maxy"))
+    );
+    const maxLevel = parseInt(dataRectangle.getAttribute("maxlevel"), 10);
+
+    terrainProviderBuilder.rectangles.push(
+      new DataRectangle(new Rectangle(west, south, east, north), maxLevel)
+    );
+  }
+}
+
+function metadataFailure(resource, error, provider) {
+  let message = `An error occurred while accessing ${resource.url}`;
+
+  if (defined(error) && defined(error.message)) {
+    message = `${message}: ${error.message}`;
+  }
+
+  TileProviderError.reportError(
+    undefined,
+    provider,
+    defined(provider) ? provider._errorEvent : undefined,
+    message
+  );
+
+  throw new RuntimeError(message);
+}
+
+async function requestMetadata(terrainProviderBuilder, resource, provider) {
+  try {
+    const xml = await resource.fetchXML();
+    metadataSuccess(terrainProviderBuilder, xml);
+  } catch (error) {
+    metadataFailure(resource, error, provider);
+  }
+}
+
+/**
+ * <div class="notice">
+ * To construct a VRTheWorldTerrainProvider, call {@link VRTheWorldTerrainProvider.fromUrl}. Do not call the constructor directly.
+ * </div>
+ *
  * A {@link TerrainProvider} that produces terrain geometry by tessellating height maps
  * retrieved from a {@link http://vr-theworld.com/|VT MÄK VR-TheWorld server}.
  *
  * @alias VRTheWorldTerrainProvider
  * @constructor
  *
- * @param {object} options Object with the following properties:
- * @param {Resource|string} options.url The URL of the VR-TheWorld TileMap.
- * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84] The ellipsoid.  If this parameter is not
- *                    specified, the WGS84 ellipsoid is used.
- * @param {Credit|string} [options.credit] A credit for the data source, which is displayed on the canvas.
- *
+ * @param {VRTheWorldTerrainProvider.ConstructorOptions} [options] An object describing initialization options.
  *
  * @example
- * const terrainProvider = new Cesium.VRTheWorldTerrainProvider({
- *   url : 'https://www.vr-theworld.com/vr-theworld/tiles1.0.0/73/'
- * });
+ * const terrainProvider = await Cesium.VRTheWorldTerrainProvider.fromUrl(
+ *   "https://www.vr-theworld.com/vr-theworld/tiles1.0.0/73/"
+ * );
  * viewer.terrainProvider = terrainProvider;
  *
  * @see TerrainProvider
  */
 function VRTheWorldTerrainProvider(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
-  //>>includeStart('debug', pragmas.debug);
-  if (!defined(options.url)) {
-    throw new DeveloperError("options.url is required.");
-  }
-  //>>includeEnd('debug');
-
-  const resource = Resource.createIfNeeded(options.url);
-
-  this._resource = resource;
 
   this._errorEvent = new Event();
   this._ready = false;
@@ -76,80 +182,26 @@ function VRTheWorldTerrainProvider(options) {
   this._tilingScheme = undefined;
   this._rectangles = [];
 
-  const that = this;
-  let metadataError;
-  const ellipsoid = defaultValue(options.ellipsoid, Ellipsoid.WGS84);
-
-  function metadataSuccess(xml) {
-    const srs = xml.getElementsByTagName("SRS")[0].textContent;
-    if (srs === "EPSG:4326") {
-      that._tilingScheme = new GeographicTilingScheme({ ellipsoid: ellipsoid });
-    } else {
-      return Promise.reject(new RuntimeError(`SRS ${srs} is not supported.`));
-    }
-
-    const tileFormat = xml.getElementsByTagName("TileFormat")[0];
-    that._heightmapWidth = parseInt(tileFormat.getAttribute("width"), 10);
-    that._heightmapHeight = parseInt(tileFormat.getAttribute("height"), 10);
-    that._levelZeroMaximumGeometricError = TerrainProvider.getEstimatedLevelZeroGeometricErrorForAHeightmap(
-      ellipsoid,
-      Math.min(that._heightmapWidth, that._heightmapHeight),
-      that._tilingScheme.getNumberOfXTilesAtLevel(0)
+  if (defined(options.url)) {
+    deprecationWarning(
+      "VRTheWorldTerrainProvider options.url",
+      "options.url was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  VRTheWorldTerrainProvider.fromUrl instead."
     );
-
-    const dataRectangles = xml.getElementsByTagName("DataExtent");
-
-    for (let i = 0; i < dataRectangles.length; ++i) {
-      const dataRectangle = dataRectangles[i];
-
-      const west = CesiumMath.toRadians(
-        parseFloat(dataRectangle.getAttribute("minx"))
-      );
-      const south = CesiumMath.toRadians(
-        parseFloat(dataRectangle.getAttribute("miny"))
-      );
-      const east = CesiumMath.toRadians(
-        parseFloat(dataRectangle.getAttribute("maxx"))
-      );
-      const north = CesiumMath.toRadians(
-        parseFloat(dataRectangle.getAttribute("maxy"))
-      );
-      const maxLevel = parseInt(dataRectangle.getAttribute("maxlevel"), 10);
-
-      that._rectangles.push(
-        new DataRectangle(new Rectangle(west, south, east, north), maxLevel)
-      );
-    }
-
-    that._ready = true;
-    return Promise.resolve(true);
-  }
-
-  function metadataFailure(e) {
-    const message = defaultValue(
-      defined(e) ? e.message : undefined,
-      `An error occurred while accessing ${that._resource.url}.`
-    );
-    metadataError = TileProviderError.reportError(
-      metadataError,
-      that,
-      that._errorEvent,
-      message
-    );
-    if (metadataError.retry) {
-      return requestMetadata();
-    }
-    return Promise.reject(new RuntimeError(message));
-  }
-
-  function requestMetadata() {
-    return that._resource
-      .fetchXML()
-      .then(metadataSuccess)
-      .catch(metadataFailure);
+    const that = this;
+    const terrainProviderBuilder = new TerrainProviderBuilder(options);
+    const resource = Resource.createIfNeeded(options.url);
+
+    this._resource = resource;
+
+    this._readyPromise = requestMetadata(
+      terrainProviderBuilder,
+      resource,
+      that
+    ).then(() => {
+      terrainProviderBuilder.build(that);
+      return true;
+    });
   }
-
-  this._readyPromise = requestMetadata();
 }
 
 Object.defineProperties(VRTheWorldTerrainProvider.prototype, {
@@ -169,7 +221,7 @@ Object.defineProperties(VRTheWorldTerrainProvider.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 VRTheWorldTerrainProvider#ready} returns true.
+   * the source of the terrain.
    * @memberof VRTheWorldTerrainProvider.prototype
    * @type {Credit}
    * @readonly
@@ -181,22 +233,13 @@ Object.defineProperties(VRTheWorldTerrainProvider.prototype, {
   },
 
   /**
-   * Gets the tiling scheme used by this provider.  This function should
-   * not be called before {@link VRTheWorldTerrainProvider#ready} returns true.
+   * Gets the tiling scheme used by this provider.
    * @memberof VRTheWorldTerrainProvider.prototype
    * @type {GeographicTilingScheme}
    * @readonly
    */
   tilingScheme: {
     get: function () {
-      //>>includeStart('debug', pragmas.debug);
-      if (!this.ready) {
-        throw new DeveloperError(
-          "requestTileGeometry must not be called before ready returns true."
-        );
-      }
-      //>>includeEnd('debug');
-
       return this._tilingScheme;
     },
   },
@@ -206,9 +249,14 @@ Object.defineProperties(VRTheWorldTerrainProvider.prototype, {
    * @memberof VRTheWorldTerrainProvider.prototype
    * @type {boolean}
    * @readonly
+   * @deprecated
    */
   ready: {
     get: function () {
+      deprecationWarning(
+        "VRTheWorldTerrainProvider.ready",
+        "VRTheWorldTerrainProvider.ready was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use VRTheWorldTerrainProvider.fromUrl instead."
+      );
       return this._ready;
     },
   },
@@ -218,9 +266,14 @@ Object.defineProperties(VRTheWorldTerrainProvider.prototype, {
    * @memberof VRTheWorldTerrainProvider.prototype
    * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "VRTheWorldTerrainProvider.readyPromise",
+        "VRTheWorldTerrainProvider.readyPromise was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use VRTheWorldTerrainProvider.fromUrl instead."
+      );
       return this._readyPromise;
     },
   },
@@ -228,8 +281,7 @@ Object.defineProperties(VRTheWorldTerrainProvider.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 VRTheWorldTerrainProvider#ready} returns true.
+   * as a reflective surface with animated waves.
    * @memberof VRTheWorldTerrainProvider.prototype
    * @type {boolean}
    * @readonly
@@ -242,7 +294,6 @@ Object.defineProperties(VRTheWorldTerrainProvider.prototype, {
 
   /**
    * Gets a value indicating whether or not the requested tiles include vertex normals.
-   * This function should not be called before {@link VRTheWorldTerrainProvider#ready} returns true.
    * @memberof VRTheWorldTerrainProvider.prototype
    * @type {boolean}
    * @readonly
@@ -254,8 +305,7 @@ Object.defineProperties(VRTheWorldTerrainProvider.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 VRTheWorldTerrainProvider.prototype
    * @type {TileAvailability}
@@ -269,8 +319,42 @@ Object.defineProperties(VRTheWorldTerrainProvider.prototype, {
 });
 
 /**
- * Requests the geometry for a given tile.  This function should not be called before
- * {@link VRTheWorldTerrainProvider#ready} returns true.  The result includes terrain
+ * Creates a {@link TerrainProvider} that produces terrain geometry by tessellating height maps
+ * retrieved from a {@link http://vr-theworld.com/|VT MÄK VR-TheWorld server}.
+ *
+ * @param {Resource|String} url The URL of the VR-TheWorld TileMap.
+ * @param {VRTheWorldTerrainProvider.ConstructorOptions} [options] An object describing initialization options.
+ * @returns {Promise<VRTheWorldTerrainProvider>}
+ *
+ * @example
+ * const terrainProvider = await Cesium.VRTheWorldTerrainProvider.fromUrl(
+ *   "https://www.vr-theworld.com/vr-theworld/tiles1.0.0/73/"
+ * );
+ * viewer.terrainProvider = terrainProvider;
+ *
+ * @exception {RuntimeError} metadata specifies and unknown SRS
+ */
+VRTheWorldTerrainProvider.fromUrl = async function (url, options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("url", url);
+  //>>includeEnd('debug');
+
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+
+  const terrainProviderBuilder = new TerrainProviderBuilder(options);
+  const resource = Resource.createIfNeeded(url);
+
+  await requestMetadata(terrainProviderBuilder, resource);
+
+  const provider = new VRTheWorldTerrainProvider(options);
+  terrainProviderBuilder.build(provider);
+  provider._resource = resource;
+
+  return provider;
+};
+
+/**
+ * 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.
@@ -287,14 +371,6 @@ VRTheWorldTerrainProvider.prototype.requestTileGeometry = function (
   level,
   request
 ) {
-  //>>includeStart('debug', pragmas.debug);
-  if (!this.ready) {
-    throw new DeveloperError(
-      "requestTileGeometry must not be called before ready returns true."
-    );
-  }
-  //>>includeEnd('debug');
-
   const yTiles = this._tilingScheme.getNumberOfYTilesAtLevel(level);
   const resource = this._resource.getDerivedResource({
     url: `${level}/${x}/${yTiles - y - 1}.tif`,
@@ -331,13 +407,6 @@ VRTheWorldTerrainProvider.prototype.requestTileGeometry = function (
 VRTheWorldTerrainProvider.prototype.getLevelMaximumGeometricError = function (
   level
 ) {
-  //>>includeStart('debug', pragmas.debug);
-  if (!this.ready) {
-    throw new DeveloperError(
-      "requestTileGeometry must not be called before ready returns true."
-    );
-  }
-  //>>includeEnd('debug');
   return this._levelZeroMaximumGeometricError / (1 << level);
 };
 

package/Source/Core/buildModuleUrl.js

@@ -98,9 +98,10 @@ let implementation;
  *
  * @example
  * const viewer = new Cesium.Viewer("cesiumContainer", {
- *   imageryProvider: new Cesium.TileMapServiceImageryProvider({
- *   url: Cesium.buildModuleUrl("Assets/Textures/NaturalEarthII"),
- *   }),
+ *   baseLayer: Cesium.ImageryLayer.fromProviderAsync(
+ *     Cesium.TileMapServiceImageryProvider.fromUrl(
+ *       Cesium.buildModuleUrl("Assets/Textures/NaturalEarthII"),
+ *     )),
  *   baseLayerPicker: false,
  * });
  */

package/Source/Core/createWorldTerrain.js

@@ -1,5 +1,6 @@
 import CesiumTerrainProvider from "./CesiumTerrainProvider.js";
 import defaultValue from "./defaultValue.js";
+import deprecationWarning from "./deprecationWarning.js";
 import IonResource from "./IonResource.js";
 
 /**
@@ -31,12 +32,29 @@ import IonResource from "./IonResource.js";
  *
  */
 function createWorldTerrain(options) {
+  deprecationWarning(
+    "createWorldTerrain",
+    "createWorldTerrain was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use createWorldTerrainAsync instead."
+  );
+
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
-  return new CesiumTerrainProvider({
-    url: IonResource.fromAssetId(1),
+  const provider = new CesiumTerrainProvider({
     requestVertexNormals: defaultValue(options.requestVertexNormals, false),
     requestWaterMask: defaultValue(options.requestWaterMask, false),
   });
+
+  // This is here in order to avoid throwing a second deprecation error
+  // by using the deprecated url parameter in the constructor above
+  provider._readyPromise = CesiumTerrainProvider._initializeReadyPromise(
+    {
+      url: IonResource.fromAssetId(1),
+      requestVertexNormals: defaultValue(options.requestVertexNormals, false),
+      requestWaterMask: defaultValue(options.requestWaterMask, false),
+    },
+    provider
+  );
+
+  return provider;
 }
 export default createWorldTerrain;

package/Source/Core/createWorldTerrainAsync.js

@@ -0,0 +1,48 @@
+import CesiumTerrainProvider from "./CesiumTerrainProvider.js";
+import defaultValue from "./defaultValue.js";
+
+/**
+ * Creates a {@link CesiumTerrainProvider} instance for the {@link https://cesium.com/content/#cesium-world-terrain|Cesium World Terrain}.
+ *
+ * @function
+ *
+ * @param {Object} [options] Object with the following properties:
+ * @param {Boolean} [options.requestVertexNormals=false] Flag that indicates if the client should request additional lighting information from the server if available.
+ * @param {Boolean} [options.requestWaterMask=false] Flag that indicates if the client should request per tile water masks from the server if available.
+ * @returns {Promise<CesiumTerrainProvider>} A promise that resolves to the created CesiumTerrainProvider
+ *
+ * @see Ion
+ *
+ * @example
+ * // Create Cesium World Terrain with default settings
+ * try {
+ *   const viewer = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.createWorldTerrainAsync();
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @example
+ * // Create Cesium World Terrain with water and normals.
+ * try {
+ *   const viewer1 = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.createWorldTerrainAsync({
+ *       requestWaterMask: true,
+ *       requestVertexNormals: true
+ *     });
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ */
+function createWorldTerrainAsync(options) {
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+
+  return CesiumTerrainProvider.fromIonAssetId(1, {
+    requestVertexNormals: defaultValue(options.requestVertexNormals, false),
+    requestWaterMask: defaultValue(options.requestWaterMask, false),
+  });
+}
+export default createWorldTerrainAsync;

package/Source/Core/sampleTerrain.js

@@ -26,27 +26,26 @@ import defined from "./defined.js";
  *
  * @example
  * // Query the terrain height of two Cartographic positions
- * const terrainProvider = Cesium.createWorldTerrain();
+ * const terrainProvider = await Cesium.createWorldTerrainAsync();
  * const positions = [
  *     Cesium.Cartographic.fromDegrees(86.925145, 27.988257),
  *     Cesium.Cartographic.fromDegrees(87.0, 28.0)
  * ];
- * const promise = Cesium.sampleTerrain(terrainProvider, 11, positions);
- * Promise.resolve(promise).then(function(updatedPositions) {
- *     // positions[0].height and positions[1].height have been updated.
- *     // updatedPositions is just a reference to positions.
- * });
+ * const updatedPositions = await Cesium.sampleTerrain(terrainProvider, 11, positions);
+ * // positions[0].height and positions[1].height have been updated.
+ * // updatedPositions is just a reference to positions.
  */
-function sampleTerrain(terrainProvider, level, positions) {
+async function sampleTerrain(terrainProvider, level, positions) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("terrainProvider", terrainProvider);
   Check.typeOf.number("level", level);
   Check.defined("positions", positions);
   //>>includeEnd('debug');
 
-  return terrainProvider.readyPromise.then(function () {
-    return doSampling(terrainProvider, level, positions);
-  });
+  // readyPromise has been deprecated; This is here for backwards compatibility
+  await terrainProvider._readyPromise;
+
+  return doSampling(terrainProvider, level, positions);
 }
 
 /**