Add CesiumTerrainProvider.fromIonAssetId

Apps/Sandcastle/gallery/ArcticDEM.html

@@ -40,8 +40,8 @@
         try {
           // High-resolution arctic terrain from the Arctic DEM project (Release 4), tiled and hosted by Cesium ion.
           // https://www.pgc.umn.edu/data/arcticdem/
-          viewer.scene.terrainProvider = await Cesium.CesiumTerrainProvider.fromUrl(
-            Cesium.IonResource.fromAssetId(3956)
+          viewer.scene.terrainProvider = await Cesium.CesiumTerrainProvider.fromIonAssetId(
+            3956
           );
         } catch (error) {
           window.alert(`Failed to load terrain. ${error}`);

Apps/Sandcastle/gallery/PAMAP Terrain.html

@@ -40,8 +40,8 @@
         try {
           // High resolution terrain of Pennsylvania curated by Pennsylvania Spatial Data Access (PASDA)
           // http://www.pasda.psu.edu/
-          viewer.terrainProvider = await Cesium.CesiumTerrainProvider.fromUrl(
-            Cesium.IonResource.fromAssetId(3957)
+          viewer.terrainProvider = await Cesium.CesiumTerrainProvider.fromIonAssetId(
+            3957
           );
         } catch (error) {
           window.alert(`Failed to load terrain. ${error}`);

CHANGES.md

@@ -6,7 +6,7 @@
 
 ##### Additions :tada:
 
-- Added `ArcGisMapServerImageryProvider.fromUrl`, `ArcGISTiledElevationTerrainProvider.fromUrl`, `BingMapsImageryProvider.fromUrl`, `CesiumTerrainProvider.fromUrl`, `GoogleEarthEnterpriseMetadata.fromUrl`, `GoogleEarthEnterpriseImageryProvider.fromMetadata`, `GoogleEarthEnterpriseMapsProvider.fromUrl`, `GoogleEarthEnterpriseTerrainProvider.fromMetadata`, `ImageryLayer.fromProviderAsync`, `IonImageryProvider.fromAssetId`, `SingleTileImageryProvider.fromUrl`, `Terrain`, `TileMapServiceImageryProvider.fromUrl`, `VRTheWorldTerrainProvider.fromUrl`, and `createWorldTerrainAsync` for better async flow and error handling.
+- Added `ArcGisMapServerImageryProvider.fromUrl`, `ArcGISTiledElevationTerrainProvider.fromUrl`, `BingMapsImageryProvider.fromUrl`, `CesiumTerrainProvider.fromUrl`, `CesiumTerrainProvider.fromIonAssetId`, `GoogleEarthEnterpriseMetadata.fromUrl`, `GoogleEarthEnterpriseImageryProvider.fromMetadata`, `GoogleEarthEnterpriseMapsProvider.fromUrl`, `GoogleEarthEnterpriseTerrainProvider.fromMetadata`, `ImageryLayer.fromProviderAsync`, `IonImageryProvider.fromAssetId`, `SingleTileImageryProvider.fromUrl`, `Terrain`, `TileMapServiceImageryProvider.fromUrl`, `VRTheWorldTerrainProvider.fromUrl`, and `createWorldTerrainAsync` for better async flow and error handling.
 
 ##### Fixes :wrench:
 
@@ -39,7 +39,7 @@
 - `TerrainProvider.ready` and `TerrainProvider.readyPromise` were deprecated in CesiumJS 1.104. They will be removed in 1.107.
 - `createWorldImagery` was deprecated in CesiumJS 1.104. It will be removed in 1.107. Use `createWorldImageryAsync` instead.
 - `ArcGISTiledElevationTerrainProvider` constructor parameter `options.url`, `ArcGISTiledElevationTerrainProvider.ready`, and `ArcGISTiledElevationTerrainProvider.readyPromise` were deprecated in CesiumJS 1.104. They will be removed in 1.107. Use `ArcGISTiledElevationTerrainProvider.fromUrl` instead.
-- `CesiumTerrainProvider` constructor parameter `options.url`, `CesiumTerrainProvider.ready`, and `CesiumTerrainProvider.readyPromise` were deprecated in CesiumJS 1.104. They will be removed in 1.107. Use `CesiumTerrainProvider.fromUrl` instead.
+- `CesiumTerrainProvider` constructor parameter `options.url`, `CesiumTerrainProvider.ready`, and `CesiumTerrainProvider.readyPromise` were deprecated in CesiumJS 1.104. They will be removed in 1.107. Use `CesiumTerrainProvider.fromIonAssetId` or `CesiumTerrainProvider.fromUrl` instead.
 - `CustomHeightmapTerrainProvider.ready`, and `CustomHeightmapTerrainProvider.readyPromise` were deprecated in CesiumJS 1.104.
 - `EllipsoidTerrainProvider.ready`, and `EllipsoidTerrainProvider.readyPromise` were deprecated in CesiumJS 1.104.
 - `GoogleEarthEnterpriseMetadata` constructor parameter `options.url` and `GoogleEarthEnterpriseMetadata.readyPromise` were deprecated in CesiumJS 1.104. They will be removed in 1.107. Use `GoogleEarthEnterpriseMetadata.fromUrl` instead.

packages/engine/Source/Core/CesiumTerrainProvider.js

@@ -12,6 +12,7 @@ import WebMercatorTilingScheme from "./WebMercatorTilingScheme.js";
 import getJsonFromTypedArray from "./getJsonFromTypedArray.js";
 import HeightmapTerrainData from "./HeightmapTerrainData.js";
 import IndexDatatype from "./IndexDatatype.js";
+import IonResource from "./IonResource.js";
 import OrientedBoundingBox from "./OrientedBoundingBox.js";
 import QuantizedMeshTerrainData from "./QuantizedMeshTerrainData.js";
 import Request from "./Request.js";
@@ -444,7 +445,7 @@ async function requestLayerJson(terrainProviderBuilder, provider) {
 
 /**
  * <div class="notice">
- * To construct a CesiumTerrainProvider, call {@link CesiumTerrainProvider.fromUrl}. Do not call the constructor directly.
+ * To construct a CesiumTerrainProvider, call {@link CesiumTerrainProvider.fromIonAssetId} or {@link CesiumTerrainProvider.fromUrl}. Do not call the constructor directly.
  * </div>
  *
  * A {@link TerrainProvider} that accesses terrain data in a Cesium terrain format.
@@ -463,9 +464,8 @@ async function requestLayerJson(terrainProviderBuilder, provider) {
  * // Create Arctic DEM terrain with normals.
  * try {
  *   const viewer = new Cesium.Viewer("cesiumContainer", {
- *     terrainProvider: await Cesium.CesiumTerrainProvider.fromUrl(
- *       Cesium.IonResource.fromAssetId(3956), {
- *         requestVertexNormals: true
+ *     terrainProvider: await Cesium.CesiumTerrainProvider.fromIonAssetId(3956, {
+ *       requestVertexNormals: true
  *     })
  *   });
  * } catch (error) {
@@ -474,6 +474,7 @@ async function requestLayerJson(terrainProviderBuilder, provider) {
  *
  * @see createWorldTerrain
  * @see CesiumTerrainProvider.fromUrl
+ * @see CesiumTerrainProvider.fromIonAssetId
  * @see TerrainProvider
  */
 function CesiumTerrainProvider(options) {
@@ -534,7 +535,7 @@ function CesiumTerrainProvider(options) {
   if (defined(options.url)) {
     deprecationWarning(
       "CesiumTerrainProvider options.url",
-      "options.url was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use CesiumTerrainProvider.fromUrl instead."
+      "options.url was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use CesiumTerrainProvider.fromIonAssetId or CesiumTerrainProvider.fromUrl instead."
     );
     this._readyPromise = CesiumTerrainProvider._initializeReadyPromise(
       options,
@@ -1061,7 +1062,7 @@ Object.defineProperties(CesiumTerrainProvider.prototype, {
     get: function () {
       deprecationWarning(
         "CesiumTerrainProvider.ready",
-        "CesiumTerrainProvider.ready was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use CesiumTerrainProvider.fromUrl instead."
+        "CesiumTerrainProvider.ready was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use CesiumTerrainProvider.fromIonAssetId or CesiumTerrainProvider.fromUrl instead."
       );
       return this._ready;
     },
@@ -1078,7 +1079,7 @@ Object.defineProperties(CesiumTerrainProvider.prototype, {
     get: function () {
       deprecationWarning(
         "CesiumTerrainProvider.readyPromise",
-        "CesiumTerrainProvider.readyPromise was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use CesiumTerrainProvider.fromUrl instead."
+        "CesiumTerrainProvider.readyPromise was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use CesiumTerrainProvider.fromIonAssetId or CesiumTerrainProvider.fromUrl instead."
       );
       return this._readyPromise;
     },
@@ -1196,6 +1197,45 @@ CesiumTerrainProvider.prototype.getLevelMaximumGeometricError = function (
   return this._levelZeroMaximumGeometricError / (1 << level);
 };
 
+/**
+ * Creates a {@link TerrainProvider} from a Cesium ion asset ID that accesses terrain data in a Cesium terrain format
+ * Terrain formats can be one of the following:
+ * <ul>
+ * <li> {@link https://github.com/AnalyticalGraphicsInc/quantized-mesh Quantized Mesh} </li>
+ * <li> {@link https://github.com/AnalyticalGraphicsInc/cesium/wiki/heightmap-1.0 Height Map} </li>
+ * </ul>
+ *
+ * @param {Resource|String|Promise<Resource>|Promise<String>} url The URL of the Cesium terrain server.
+ * @param {CesiumTerrainProvider.ConstructorOptions} [options] An object describing initialization options.
+ * @returns {Promise<CesiumTerrainProvider>}
+ *
+ * @example
+ * // Create Arctic DEM terrain with normals.
+ * try {
+ *   const viewer = new Cesium.Viewer("cesiumContainer", {
+ *     terrainProvider: await Cesium.CesiumTerrainProvider.fromIonAssetId(3956, {
+ *         requestVertexNormals: true
+ *     })
+ *   });
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @exception {RuntimeError} layer.json does not specify a format
+ * @exception {RuntimeError} layer.json specifies an unknown format
+ * @exception {RuntimeError} layer.json specifies an unsupported quantized-mesh version
+ * @exception {RuntimeError} layer.json does not specify a tiles property, or specifies an empty array
+ * @exception {RuntimeError} layer.json does not specify any tile URL templates
+ */
+CesiumTerrainProvider.fromIonAssetId = async function (assetId, options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("assetId", assetId);
+  //>>includeEnd('debug');
+
+  const resource = await IonResource.fromAssetId(assetId);
+  return CesiumTerrainProvider.fromUrl(resource, options);
+};
+
 /**
  * Creates a {@link TerrainProvider} that accesses terrain data in a Cesium terrain format.
  * Terrain formats can be one of the following:

packages/engine/Source/Core/VRTheWorldTerrainProvider.js

@@ -137,7 +137,7 @@ async function requestMetadata(terrainProviderBuilder, resource, provider) {
 
 /**
  * <div class="notice">
- * To construct a CesiumTerrainProvider, call {@link CesiumTerrainProvider.fromUrl}. Do not call the constructor directly.
+ * 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

packages/engine/Source/Core/createWorldTerrainAsync.js

@@ -1,6 +1,5 @@
 import CesiumTerrainProvider from "./CesiumTerrainProvider.js";
 import defaultValue from "./defaultValue.js";
-import IonResource from "./IonResource.js";
 
 /**
  * Creates a {@link CesiumTerrainProvider} instance for the {@link https://cesium.com/content/#cesium-world-terrain|Cesium World Terrain}.
@@ -41,7 +40,7 @@ import IonResource from "./IonResource.js";
 function createWorldTerrainAsync(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
-  return CesiumTerrainProvider.fromUrl(IonResource.fromAssetId(1), {
+  return CesiumTerrainProvider.fromIonAssetId(1, {
     requestVertexNormals: defaultValue(options.requestVertexNormals, false),
     requestWaterMask: defaultValue(options.requestWaterMask, false),
   });

packages/engine/Specs/Core/CesiumTerrainProviderSpec.js

@@ -152,6 +152,14 @@ describe("Core/CesiumTerrainProvider", function () {
     expect(CesiumTerrainProvider).toConformToInterface(TerrainProvider);
   });
 
+  it("fromIonAssetId throws without assetId", async function () {
+    await expectAsync(
+      CesiumTerrainProvider.fromIonAssetId()
+    ).toBeRejectedWithDeveloperError(
+      "assetId is required, actual value was undefined"
+    );
+  });
+
   it("fromUrl throws without url", async function () {
     await expectAsync(
       CesiumTerrainProvider.fromUrl()