@cesium/engine 2.1.0 → 2.2.0

package/Source/Scene/createWorldImagery.js

@@ -1,4 +1,5 @@
 import defaultValue from "../Core/defaultValue.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import IonImageryProvider from "./IonImageryProvider.js";
 import IonWorldImageryStyle from "./IonWorldImageryStyle.js";
 
@@ -10,17 +11,18 @@ import IonWorldImageryStyle from "./IonWorldImageryStyle.js";
  * @param {object} [options] Object with the following properties:
  * @param {IonWorldImageryStyle} [options.style=IonWorldImageryStyle] The style of base imagery, only AERIAL, AERIAL_WITH_LABELS, and ROAD are currently supported.
  * @returns {IonImageryProvider}
+ * @deprecated
  *
  * @see Ion
  *
  * @example
- * // Create Cesium World Terrain with default settings
+ * // Create Cesium World Imagery with default settings
  * const viewer = new Cesium.Viewer('cesiumContainer', {
  *     imageryProvider : Cesium.createWorldImagery();
  * });
  *
  * @example
- * // Create Cesium World Terrain with water and normals.
+ * // Create Cesium World Imagery with a different style
  * const viewer = new Cesium.Viewer('cesiumContainer', {
  *     imageryProvider : Cesium.createWorldImagery({
  *         style: Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS
@@ -29,10 +31,17 @@ import IonWorldImageryStyle from "./IonWorldImageryStyle.js";
  *
  */
 function createWorldImagery(options) {
+  deprecationWarning(
+    "createWorldImagery",
+    "createWorldImagery was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use createWorldImageryAsync instead."
+  );
+
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
   const style = defaultValue(options.style, IonWorldImageryStyle.AERIAL);
-  return new IonImageryProvider({
-    assetId: style,
-  });
+  const provider = new IonImageryProvider();
+
+  // This is here for backwards compatibility
+  IonImageryProvider._initialize(provider, style, options);
+  return provider;
 }
 export default createWorldImagery;

package/Source/Scene/createWorldImageryAsync.js

@@ -0,0 +1,39 @@
+import defaultValue from "../Core/defaultValue.js";
+import IonImageryProvider from "./IonImageryProvider.js";
+import IonWorldImageryStyle from "./IonWorldImageryStyle.js";
+
+/**
+ * Creates an {@link IonImageryProvider} instance for ion's default global base imagery layer, currently Bing Maps.
+ *
+ * @function
+ *
+ * @param {Object} [options] Object with the following properties:
+ * @param {IonWorldImageryStyle} [options.style=IonWorldImageryStyle] The style of base imagery, only AERIAL, AERIAL_WITH_LABELS, and ROAD are currently supported.
+ * @returns {Promise<IonImageryProvider>}
+ *
+ * @see Ion
+ *
+ * @example
+ * // Create a Cesium World Imagery base layer with default settings
+ * try {
+ *   const imageryProvider = await Cesium.createWorldImageryAsync();
+ * } catch (error) {
+ *   console.log(`There was an error creating world imagery: ${error}`);
+ * }
+ *
+ * @example
+ * // Create Cesium World Imagery with different style
+ * try {
+ *   const imageryProvider = await Cesium.createWorldImageryAsync({
+ *         style: Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS
+ *   });
+ * } catch (error) {
+ *   console.log(`There was an error creating world imagery: ${error}`);
+ * }
+ */
+function createWorldImageryAsync(options) {
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  const style = defaultValue(options.style, IonWorldImageryStyle.AERIAL);
+  return IonImageryProvider.fromAssetId(style);
+}
+export default createWorldImageryAsync;

package/Source/Widget/CesiumWidget.js

@@ -1,9 +1,9 @@
 import buildModuleUrl from "../Core/buildModuleUrl.js";
-import createWorldImagery from "../Scene/createWorldImagery.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Clock from "../Core/Clock.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
@@ -11,6 +11,7 @@ import FeatureDetection from "../Core/FeatureDetection.js";
 import formatError from "../Core/formatError.js";
 import getElement from "../DataSources/getElement.js";
 import Globe from "../Scene/Globe.js";
+import ImageryLayer from "../Scene/ImageryLayer.js";
 import Moon from "../Scene/Moon.js";
 import Scene from "../Scene/Scene.js";
 import SceneMode from "../Scene/SceneMode.js";
@@ -123,8 +124,10 @@ function configureCameraFrustum(widget) {
  * @param {Element|string} container The DOM element or ID that will contain the widget.
  * @param {object} [options] Object with the following properties:
  * @param {Clock} [options.clock=new Clock()] The clock to use to control current time.
- * @param {ImageryProvider | false} [options.imageryProvider=createWorldImagery()] The imagery provider to serve as the base layer. If set to <code>false</code>, no imagery provider will be added.
+ * @param {ImageryProvider | false} [options.imageryProvider=createWorldImagery()] The imagery provider to serve as the base layer. If set to <code>false</code>, no imagery provider will be added. Deprecated.
+ * @param {ImageryLayer|false} [baseLayer=ImageryLayer.fromWorldImagery()] The bottommost imagery layer applied to the globe. If set to <code>false</code>, no imagery provider will be added.
  * @param {TerrainProvider} [options.terrainProvider=new EllipsoidTerrainProvider] The terrain provider.
+ * @param {Terrain} [options.terrain] A terrain object which handles asynchronous terrain provider. Can only specify if options.terrainProvider is undefined.
  * @param {SkyBox| false} [options.skyBox] The skybox used to render the stars.  When <code>undefined</code>, the default stars are used. If set to <code>false</code>, no skyBox, Sun, or Moon will be added.
  * @param {SkyAtmosphere | false} [options.skyAtmosphere] Blue sky, and the glow around the Earth's limb.  Set to <code>false</code> to turn it off.
  * @param {SceneMode} [options.sceneMode=SceneMode.SCENE3D] The initial scene mode.
@@ -156,26 +159,26 @@ function configureCameraFrustum(widget) {
  * // For each example, include a link to CesiumWidget.css stylesheet in HTML head,
  * // and in the body, include: <div id="cesiumContainer"></div>
  *
- * //Widget with no terrain and default Bing Maps imagery provider.
- * const widget = new Cesium.CesiumWidget('cesiumContainer');
+ * // Widget with no terrain and default Bing Maps imagery provider.
+ * const widget = new Cesium.CesiumWidget("cesiumContainer");
  *
- * //Widget with ion imagery and Cesium World Terrain.
- * const widget2 = new Cesium.CesiumWidget('cesiumContainer', {
- *     imageryProvider : Cesium.createWorldImagery(),
- *     terrainProvider : Cesium.createWorldTerrain(),
- *     skyBox : new Cesium.SkyBox({
- *         sources : {
- *           positiveX : 'stars/TychoSkymapII.t3_08192x04096_80_px.jpg',
- *           negativeX : 'stars/TychoSkymapII.t3_08192x04096_80_mx.jpg',
- *           positiveY : 'stars/TychoSkymapII.t3_08192x04096_80_py.jpg',
- *           negativeY : 'stars/TychoSkymapII.t3_08192x04096_80_my.jpg',
- *           positiveZ : 'stars/TychoSkymapII.t3_08192x04096_80_pz.jpg',
- *           negativeZ : 'stars/TychoSkymapII.t3_08192x04096_80_mz.jpg'
- *         }
+ * // Widget with ion imagery and Cesium World Terrain.
+ * const widget2 = new Cesium.CesiumWidget("cesiumContainer", {
+ *     baseLayer: Cesium.ImageryLayer.fromWorldTerrain(),
+ *     terrain: Cesium.Terrain.fromWorldTerrain()
+ *     skyBox: new Cesium.SkyBox({
+ *       sources: {
+ *         positiveX: "stars/TychoSkymapII.t3_08192x04096_80_px.jpg",
+ *         negativeX: "stars/TychoSkymapII.t3_08192x04096_80_mx.jpg",
+ *         positiveY: "stars/TychoSkymapII.t3_08192x04096_80_py.jpg",
+ *         negativeY: "stars/TychoSkymapII.t3_08192x04096_80_my.jpg",
+ *         positiveZ: "stars/TychoSkymapII.t3_08192x04096_80_pz.jpg",
+ *         negativeZ: "stars/TychoSkymapII.t3_08192x04096_80_mz.jpg"
+ *       }
  *     }),
  *     // Show Columbus View map with Web Mercator projection
- *     sceneMode : Cesium.SceneMode.COLUMBUS_VIEW,
- *     mapProjection : new Cesium.WebMercatorProjection()
+ *     sceneMode: Cesium.SceneMode.COLUMBUS_VIEW,
+ *     mapProjection: new Cesium.WebMercatorProjection()
  * });
  */
 function CesiumWidget(container, options) {
@@ -340,22 +343,47 @@ function CesiumWidget(container, options) {
       scene.skyAtmosphere = skyAtmosphere;
     }
 
-    //Set the base imagery layer
-    let imageryProvider =
-      options.globe === false ? false : options.imageryProvider;
-    if (!defined(imageryProvider)) {
-      imageryProvider = createWorldImagery();
+    if (defined(options.imageryProvider)) {
+      deprecationWarning(
+        "CesiumWidget options.imageryProvider",
+        "options.imageryProvider was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use options.baseLayer instead."
+      );
     }
 
-    if (imageryProvider !== false) {
-      scene.imageryLayers.addImageryProvider(imageryProvider);
+    // Set the base imagery layer
+    let baseLayer = options.baseLayer;
+    if (
+      options.globe !== false &&
+      baseLayer !== false &&
+      options.imageryProvider !== false
+    ) {
+      if (defined(options.imageryProvider) && !defined(baseLayer)) {
+        baseLayer = new ImageryLayer(options.imageryProvider);
+      }
+
+      if (!defined(baseLayer)) {
+        baseLayer = ImageryLayer.fromWorldImagery();
+      }
+      scene.imageryLayers.add(baseLayer);
     }
 
-    //Set the terrain provider if one is provided.
+    // Set the terrain provider if one is provided.
     if (defined(options.terrainProvider) && options.globe !== false) {
       scene.terrainProvider = options.terrainProvider;
     }
 
+    if (defined(options.terrain) && options.globe !== false) {
+      //>>includeStart('debug', pragmas.debug);
+      if (defined(options.terrainProvider)) {
+        throw new DeveloperError(
+          "Specify either options.terrainProvider or options.terrain."
+        );
+      }
+      //>>includeEnd('debug')
+
+      scene.setTerrain(options.terrain);
+    }
+
     this._screenSpaceEventHandler = new ScreenSpaceEventHandler(canvas);
 
     if (defined(options.sceneMode)) {