diff --git a/Apps/Sandcastle/gallery/ArcticDEM.html b/Apps/Sandcastle/gallery/ArcticDEM.html index 8d6d3509b59e..63286fc22964 100644 --- a/Apps/Sandcastle/gallery/ArcticDEM.html +++ b/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}`); diff --git a/Apps/Sandcastle/gallery/PAMAP Terrain.html b/Apps/Sandcastle/gallery/PAMAP Terrain.html index 4d3d07e1fa44..5c8ab22a00ba 100644 --- a/Apps/Sandcastle/gallery/PAMAP Terrain.html +++ b/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}`); diff --git a/CHANGES.md b/CHANGES.md index 4c935d4b0b5f..36ae590d2182 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -19,7 +19,7 @@ try { ##### 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`, `createWorldTerrainAsync`, `Cesium3DTileset.fromUrl`, `Cesium3DTileset.fromIonAssetId`, `createOsmBuildingsAsync`, `Model.fromGltfAsync`, `Model.readyEvent`, `Model.errorEvent`,`Model.texturesReadyEvent`, `I3SDataProvider.fromUrl`, and `Cesium3DTilesVoxelProvider.fromUrl` 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`, `createWorldTerrainAsync`, `Cesium3DTileset.fromUrl`, `Cesium3DTileset.fromIonAssetId`, `createOsmBuildingsAsync`, `Model.fromGltfAsync`, `Model.readyEvent`, `Model.errorEvent`,`Model.texturesReadyEvent`, `I3SDataProvider.fromUrl`, and `Cesium3DTilesVoxelProvider.fromUrl` for better async flow and error handling. ##### Fixes :wrench: @@ -52,7 +52,7 @@ try { - `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. diff --git a/packages/engine/Source/Core/CesiumTerrainProvider.js b/packages/engine/Source/Core/CesiumTerrainProvider.js index 61bc5d98b687..26da3ade2696 100644 --- a/packages/engine/Source/Core/CesiumTerrainProvider.js +++ b/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) { /** *
- * 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. *
* * 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: + * + * + * @param {Resource|String|Promise|Promise} url The URL of the Cesium terrain server. + * @param {CesiumTerrainProvider.ConstructorOptions} [options] An object describing initialization options. + * @returns {Promise} + * + * @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: diff --git a/packages/engine/Source/Core/VRTheWorldTerrainProvider.js b/packages/engine/Source/Core/VRTheWorldTerrainProvider.js index 73a66d669ae9..5db5f33c2c82 100644 --- a/packages/engine/Source/Core/VRTheWorldTerrainProvider.js +++ b/packages/engine/Source/Core/VRTheWorldTerrainProvider.js @@ -137,7 +137,7 @@ async function requestMetadata(terrainProviderBuilder, resource, provider) { /** *
- * 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. *
* * A {@link TerrainProvider} that produces terrain geometry by tessellating height maps diff --git a/packages/engine/Source/Core/createWorldTerrainAsync.js b/packages/engine/Source/Core/createWorldTerrainAsync.js index 983b7e89ba3c..ec931a8ed4e6 100644 --- a/packages/engine/Source/Core/createWorldTerrainAsync.js +++ b/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), }); diff --git a/packages/engine/Specs/Core/CesiumTerrainProviderSpec.js b/packages/engine/Specs/Core/CesiumTerrainProviderSpec.js index 28a533b5412b..c4d6a6c5a29d 100644 --- a/packages/engine/Specs/Core/CesiumTerrainProviderSpec.js +++ b/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() diff --git a/packages/engine/Specs/Scene/BillboardCollectionSpec.js b/packages/engine/Specs/Scene/BillboardCollectionSpec.js index 2e605eb15d34..529ff9049530 100644 --- a/packages/engine/Specs/Scene/BillboardCollectionSpec.js +++ b/packages/engine/Specs/Scene/BillboardCollectionSpec.js @@ -2503,7 +2503,7 @@ describe( expect(b._clampedPosition).toBeUndefined(); }); - it("changing the terrain provider", function () { + it("changing the terrain provider", async function () { const b = billboardsWithHeight.add({ heightReference: HeightReference.CLAMP_TO_GROUND, position: Cartesian3.fromDegrees(-72.0, 40.0), @@ -2512,10 +2512,12 @@ describe( spyOn(b, "_updateClamping").and.callThrough(); - const terrainProvider = new CesiumTerrainProvider({ - url: "made/up/url", - requestVertexNormals: true, - }); + const terrainProvider = await CesiumTerrainProvider.fromUrl( + "made/up/url", + { + requestVertexNormals: true, + } + ); scene.terrainProvider = terrainProvider; diff --git a/packages/engine/Specs/Scene/GlobeSpec.js b/packages/engine/Specs/Scene/GlobeSpec.js index cfc2b6a5f68e..af2863a7a40f 100644 --- a/packages/engine/Specs/Scene/GlobeSpec.js +++ b/packages/engine/Specs/Scene/GlobeSpec.js @@ -227,11 +227,13 @@ describe( }); }); - it("terrainProviderChanged event fires", function () { - const terrainProvider = new CesiumTerrainProvider({ - url: "made/up/url", - requestVertexNormals: true, - }); + it("terrainProviderChanged event fires", async function () { + const terrainProvider = await CesiumTerrainProvider.fromUrl( + "made/up/url", + { + requestVertexNormals: true, + } + ); const spyListener = jasmine.createSpy("listener"); globe.terrainProviderChanged.addEventListener(spyListener); @@ -241,7 +243,7 @@ describe( expect(spyListener).toHaveBeenCalledWith(terrainProvider); }); - it("tilesLoaded return true when tile load queue is empty", function () { + it("tilesLoaded return true when tile load queue is empty", async function () { expect(globe.tilesLoaded).toBe(true); globe._surface._tileLoadQueueHigh.length = 2; @@ -262,10 +264,12 @@ describe( globe._surface._tileLoadQueueLow.length = 0; expect(globe.tilesLoaded).toBe(true); - const terrainProvider = new CesiumTerrainProvider({ - url: "made/up/url", - requestVertexNormals: true, - }); + const terrainProvider = await CesiumTerrainProvider.fromUrl( + "made/up/url", + { + requestVertexNormals: true, + } + ); globe.terrainProvider = terrainProvider; scene.render(); @@ -306,10 +310,12 @@ describe( returnVertexNormalTileJson(); - const terrainProvider = new CesiumTerrainProvider({ - url: "made/up/url", - requestVertexNormals: true, - }); + const terrainProvider = await CesiumTerrainProvider.fromUrl( + "made/up/url", + { + requestVertexNormals: true, + } + ); globe.terrainProvider = terrainProvider; scene.camera.setView({