@cesium/engine 4.0.0 → 6.0.0

package/Source/Scene/createGooglePhotorealistic3DTileset.js

@@ -1,6 +1,7 @@
 import Cesium3DTileset from "./Cesium3DTileset.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import IonResource from "../Core/IonResource.js";
 import GoogleMaps from "../Core/GoogleMaps.js";
 import Resource from "../Core/Resource.js";
 
@@ -16,6 +17,17 @@ import Resource from "../Core/Resource.js";
  * @see GoogleMaps
  *
  * @example
+ * const viewer = new Cesium.Viewer("cesiumContainer");
+ *
+ * try {
+ *   const tileset = await Cesium.createGooglePhotorealistic3DTileset();
+ *   viewer.scene.primitives.add(tileset));
+ * } catch (error) {
+ *   console.log(`Error creating tileset: ${error}`);
+ * }
+ *
+ * @example
+ * // Use your own Google Maps API key
  * Cesium.GoogleMaps.defaultApiKey = "your-api-key";
  *
  * const viewer = new Cesium.Viewer("cesiumContainer");
@@ -28,14 +40,6 @@ import Resource from "../Core/Resource.js";
  * }
  */
 async function createGooglePhotorealistic3DTileset(key, options) {
-  key = defaultValue(key, GoogleMaps.defaultApiKey);
-
-  let credits;
-  const credit = GoogleMaps.getDefaultApiKeyCredit(key);
-  if (defined(credit)) {
-    credits = [credit];
-  }
-
   options = defaultValue(options, {});
   options.showCreditsOnScreen = true;
   options.cacheBytes = defaultValue(options.cacheBytes, 1536 * 1024 * 1024);
@@ -44,6 +48,17 @@ async function createGooglePhotorealistic3DTileset(key, options) {
     1024 * 1024 * 1024
   );
 
+  key = defaultValue(key, GoogleMaps.defaultApiKey);
+  if (!defined(key)) {
+    return requestCachedIonTileset(options);
+  }
+
+  let credits;
+  const credit = GoogleMaps.getDefaultCredit();
+  if (defined(credit)) {
+    credits = [credit];
+  }
+
   const resource = new Resource({
     url: `${GoogleMaps.mapTilesApiEndpoint}3dtiles/root.json`,
     queryParameters: {
@@ -55,4 +70,19 @@ async function createGooglePhotorealistic3DTileset(key, options) {
   return Cesium3DTileset.fromUrl(resource, options);
 }
 
+const metadataCache = {};
+async function requestCachedIonTileset(options) {
+  const ionAssetId = 2275207;
+  const cacheKey = ionAssetId;
+
+  let promise = metadataCache[cacheKey];
+  if (!defined(promise)) {
+    promise = IonResource.fromAssetId(ionAssetId);
+    metadataCache[cacheKey] = promise;
+  }
+
+  const resource = await promise;
+  return Cesium3DTileset.fromUrl(resource, options);
+}
+
 export default createGooglePhotorealistic3DTileset;

package/Source/Widget/CesiumWidget.js

@@ -132,7 +132,7 @@ function configureCameraFrustum(widget) {
  * @param {boolean} [options.scene3DOnly=false] When <code>true</code>, each geometry instance will only be rendered in 3D to save GPU memory.
  * @param {boolean} [options.orderIndependentTranslucency=true] If true and the configuration supports it, use order independent translucency.
  * @param {MapProjection} [options.mapProjection=new GeographicProjection()] The map projection to use in 2D and Columbus View modes.
- * @param {Globe | false} [options.globe=new Globe(mapProjection.ellipsoid)] The globe to use in the scene.  If set to <code>false</code>, no globe will be added.
+ * @param {Globe | false} [options.globe=new Globe(mapProjection.ellipsoid)] The globe to use in the scene.  If set to <code>false</code>, no globe will be added and the sky atmosphere will be hidden by default.
  * @param {boolean} [options.useDefaultRenderLoop=true] True if this widget should control the render loop, false otherwise.
  * @param {boolean} [options.useBrowserRecommendedResolution=true] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
  * @param {number} [options.targetFrameRate] The target frame rate when using the default render loop.
@@ -336,6 +336,7 @@ function CesiumWidget(container, options) {
     let skyAtmosphere = options.skyAtmosphere;
     if (!defined(skyAtmosphere)) {
       skyAtmosphere = new SkyAtmosphere(ellipsoid);
+      skyAtmosphere.show = options.globe !== false && globe.show;
     }
     if (skyAtmosphere !== false) {
       scene.skyAtmosphere = skyAtmosphere;

package/index.d.ts

@@ -7568,15 +7568,14 @@ export class GoogleEarthEnterpriseTerrainProvider {
 /**
  * Default settings for accessing the Google Maps API.
  * <br/>
- * An API key is only required if you are using any Google Maps APIs, such as {@link createGooglePhotorealistic3DTileset}.
- * A default key is provided for evaluation purposes only.
+ * An API key is only required if you are directly using any Google Maps APIs, such as through {@link createGooglePhotorealistic3DTileset}.
  * Follow instructions for managing API keys for the Google Maps Platform at {@link https://developers.google.com/maps/documentation/embed/get-api-key}
  */
 export namespace GoogleMaps {
     /**
      * Gets or sets the default Google Maps API key.
      */
-    var defaultApiKey: string;
+    var defaultApiKey: undefined | string;
     /**
      * Gets or sets the default Google Map Tiles API endpoint.
      */
@@ -12874,6 +12873,15 @@ export class PolygonGeometry {
      * @param [result] - The object into which to store the result.
      */
     static unpack(array: number[], startingIndex?: number, result?: PolygonGeometry): void;
+    /**
+     * Computes a rectangle which encloses the polygon defined by the list of positions, including cases over the international date line and the poles.
+     * @param positions - A linear ring defining the outer boundary of the polygon.
+     * @param [ellipsoid = Ellipsoid.WGS84] - The ellipsoid to be used as a reference.
+     * @param [arcType = ArcType.GEODESIC] - The type of line the polygon edges must follow. Valid options are {@link ArcType.GEODESIC} and {@link ArcType.RHUMB}.
+     * @param [result] - An object in which to store the result.
+     * @returns The result rectangle
+     */
+    static computeRectangleFromPositions(positions: Cartesian3[], ellipsoid?: Ellipsoid, arcType?: ArcType, result?: Rectangle): Rectangle;
     /**
      * Returns the bounding rectangle given the provided options
      * @param options - Object with the following properties:
@@ -16086,6 +16094,15 @@ export class SteppedSpline {
     evaluate(time: number, result?: Cartesian3 | Quaternion): number | Cartesian3 | Quaternion;
 }
 
+/**
+ * Represents a point in stereographic coordinates, which can be obtained by projecting a cartesian coordinate from one pole onto a tangent plane at the other pole.
+ * The stereographic projection faithfully represents the relative directions of all great circles passing through its center point.
+ * To faithfully represents angles everywhere, this is a conformal projection, which means points are projected onto an arbrary sphere.
+ * @param [position] - The steroegraphic coordinates.
+ * @param [tangentPlane] - The tangent plane onto which the point was projected.
+ */
+export function Stereographic(position?: Cartesian2, tangentPlane?: EllipseGeometry): void;
+
 /**
  * A wrapper around a web worker that allows scheduling tasks for a given worker,
  * returning results asynchronously via a promise.
@@ -18346,12 +18363,20 @@ export function queryToObject(queryString: string): any;
  * 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.
+ *
+ * // To handle tile errors, pass true for the rejectOnTileFail parameter.
+ * try {
+ *    const updatedPositions = await Cesium.sampleTerrain(terrainProvider, 11, positions, true);
+ * } catch (error) {
+ *   // A tile request error occurred.
+ * }
  * @param terrainProvider - The terrain provider from which to query heights.
  * @param level - The terrain level-of-detail from which to query terrain heights.
  * @param positions - The positions to update with terrain heights.
+ * @param [rejectOnTileFail = false] - If true, for a failed terrain tile request the promise will be rejected. If false, returned heights will be undefined.
  * @returns A promise that resolves to the provided list of positions when terrain the query has completed.
  */
-export function sampleTerrain(terrainProvider: TerrainProvider, level: number, positions: Cartographic[]): Promise<Cartographic[]>;
+export function sampleTerrain(terrainProvider: TerrainProvider, level: number, positions: Cartographic[], rejectOnTileFail?: boolean): Promise<Cartographic[]>;
 
 /**
  * Initiates a sampleTerrain() request at the maximum available tile level for a terrain dataset.
@@ -18365,12 +18390,20 @@ export function sampleTerrain(terrainProvider: TerrainProvider, level: number, p
  * const updatedPositions = await Cesium.sampleTerrainMostDetailed(terrainProvider, positions);
  * // positions[0].height and positions[1].height have been updated.
  * // updatedPositions is just a reference to positions.
+ *
+ * // To handle tile errors, pass true for the rejectOnTileFail parameter.
+ * try {
+ *    const updatedPositions = await Cesium.sampleTerrainMostDetailed(terrainProvider, positions, true);
+ * } catch (error) {
+ *   // A tile request error occurred.
+ * }
  * @param terrainProvider - The terrain provider from which to query heights.
  * @param positions - The positions to update with terrain heights.
+ * @param [rejectOnTileFail = false] - If true, for a failed terrain tile request the promise will be rejected. If false, returned heights will be undefined.
  * @returns A promise that resolves to the provided list of positions when terrain the query has completed.  This
  *                                     promise will reject if the terrain provider's `availability` property is undefined.
  */
-export function sampleTerrainMostDetailed(terrainProvider: TerrainProvider, positions: Cartographic[]): Promise<Cartographic[]>;
+export function sampleTerrainMostDetailed(terrainProvider: TerrainProvider, positions: Cartographic[], rejectOnTileFail?: boolean): Promise<Cartographic[]>;
 
 /**
  * Subdivides an array into a number of smaller, equal sized arrays.
@@ -28597,7 +28630,6 @@ export namespace Cesium3DTileset {
      * @property [modelForwardAxis = Axis.X] - Which axis is considered forward when loading models for tile contents.
      * @property [shadows = ShadowMode.ENABLED] - Determines whether the tileset casts or receives shadows from light sources.
      * @property [maximumScreenSpaceError = 16] - The maximum screen space error used to drive level of detail refinement.
-     * @property [maximumMemoryUsage = 512] - The maximum amount of memory in MB that can be used by the tileset. Deprecated.
      * @property [cacheBytes = 536870912] - The size (in bytes) to which the tile cache will be trimmed, if the cache contains tiles not needed for the current view.
      * @property [maximumCacheOverflowBytes = 536870912] - The maximum additional memory (in bytes) to allow for cache headroom, if more than {@link Cesium3DTileset#cacheBytes} are needed for the current view.
      * @property [cullWithChildrenBounds = true] - Optimization option. Whether to cull tiles using the union of their children bounding volumes.
@@ -28659,7 +28691,6 @@ export namespace Cesium3DTileset {
         modelForwardAxis?: Axis;
         shadows?: ShadowMode;
         maximumScreenSpaceError?: number;
-        maximumMemoryUsage?: number;
         cacheBytes?: number;
         maximumCacheOverflowBytes?: number;
         cullWithChildrenBounds?: boolean;
@@ -29258,26 +29289,6 @@ export class Cesium3DTileset {
      * </p>
      */
     maximumScreenSpaceError: number;
-    /**
-     * The maximum amount of GPU memory (in MB) that may be used to cache tiles. This value is estimated from
-     * geometry, textures, and batch table textures of loaded tiles. For point clouds, this value also
-     * includes per-point metadata.
-     * <p>
-     * Tiles not in view are unloaded to enforce this.
-     * </p>
-     * <p>
-     * If decreasing this value results in unloading tiles, the tiles are unloaded the next frame.
-     * </p>
-     * <p>
-     * If tiles sized more than <code>maximumMemoryUsage</code> are needed
-     * to meet the desired screen space error, determined by {@link Cesium3DTileset#maximumScreenSpaceError},
-     * for the current view, then the memory usage of the tiles loaded will exceed
-     * <code>maximumMemoryUsage</code>.  For example, if the maximum is 256 MB, but
-     * 300 MB of tiles are needed to meet the screen space error, then 300 MB of tiles may be loaded.  When
-     * these tiles go out of view, they will be unloaded.
-     * </p>
-     */
-    maximumMemoryUsage: number;
     /**
      * The amount of GPU memory (in bytes) used to cache tiles. This memory usage is estimated from
      * geometry, textures, and batch table textures of loaded tiles. For point clouds, this value also
@@ -38585,16 +38596,16 @@ export namespace PostProcessStageLibrary {
      * </p>
      * @example
      * // multiple silhouette effects
-     * const yellowEdge = Cesium.PostProcessLibrary.createEdgeDetectionStage();
+     * const yellowEdge = Cesium.PostProcessStageLibrary.createEdgeDetectionStage();
      * yellowEdge.uniforms.color = Cesium.Color.YELLOW;
      * yellowEdge.selected = [feature0];
      *
-     * const greenEdge = Cesium.PostProcessLibrary.createEdgeDetectionStage();
+     * const greenEdge = Cesium.PostProcessStageLibrary.createEdgeDetectionStage();
      * greenEdge.uniforms.color = Cesium.Color.LIME;
      * greenEdge.selected = [feature1];
      *
      * // draw edges around feature0 and feature1
-     * postProcessStages.add(Cesium.PostProcessLibrary.createSilhouetteStage([yellowEdge, greenEdge]);
+     * postProcessStages.add(Cesium.PostProcessStageLibrary.createSilhouetteStage([yellowEdge, greenEdge]);
      * @returns A post-process stage that applies an edge detection effect.
      */
     function createEdgeDetectionStage(): PostProcessStage;
@@ -39019,6 +39030,19 @@ export class PrimitiveCollection {
      * Gets the number of primitives in the collection.
      */
     readonly length: number;
+    /**
+     * An event that is raised when a primitive is added to the collection.
+     * Event handlers are passed the primitive that was added.
+     */
+    readonly primitiveAdded: Event;
+    /**
+     * An event that is raised when a primitive is removed from the collection.
+     * Event handlers are passed the primitive that was removed.
+     * <p>
+     * Note: Depending on the destroyPrimitives constructor option, the primitive may already be destroyed.
+     * </p>
+     */
+    readonly primitiveRemoved: Event;
     /**
      * Adds a primitive to the collection.
      * @example
@@ -42216,6 +42240,16 @@ export function createElevationBandMaterial(options: {
 /**
  * Creates a {@link Cesium3DTileset} instance for the Google Photorealistic 3D Tiles tileset.
  * @example
+ * const viewer = new Cesium.Viewer("cesiumContainer");
+ *
+ * try {
+ *   const tileset = await Cesium.createGooglePhotorealistic3DTileset();
+ *   viewer.scene.primitives.add(tileset));
+ * } catch (error) {
+ *   console.log(`Error creating tileset: ${error}`);
+ * }
+ * @example
+ * // Use your own Google Maps API key
  * Cesium.GoogleMaps.defaultApiKey = "your-api-key";
  *
  * const viewer = new Cesium.Viewer("cesiumContainer");
@@ -42370,7 +42404,7 @@ export function createWorldImageryAsync(options?: {
  * @param [options.scene3DOnly = false] - When <code>true</code>, each geometry instance will only be rendered in 3D to save GPU memory.
  * @param [options.orderIndependentTranslucency = true] - If true and the configuration supports it, use order independent translucency.
  * @param [options.mapProjection = new GeographicProjection()] - The map projection to use in 2D and Columbus View modes.
- * @param [options.globe = new Globe(mapProjection.ellipsoid)] - The globe to use in the scene.  If set to <code>false</code>, no globe will be added.
+ * @param [options.globe = new Globe(mapProjection.ellipsoid)] - The globe to use in the scene.  If set to <code>false</code>, no globe will be added and the sky atmosphere will be hidden by default.
  * @param [options.useDefaultRenderLoop = true] - True if this widget should control the render loop, false otherwise.
  * @param [options.useBrowserRecommendedResolution = true] - If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
  * @param [options.targetFrameRate] - The target frame rate when using the default render loop.