@cesium/engine 2.2.0 → 2.3.0

package/index.d.ts

@@ -887,6 +887,11 @@ export class BingMapsGeocoderService {
      * The key for the Bing geocoder service
      */
     readonly key: string;
+    /**
+     * Gets the credit to display after a geocode is performed. Typically this is used to credit
+     * the geocoder service.
+     */
+    readonly credit: Credit | undefined;
     /**
      * @param query - The query to be sent to the geocoder service
      */
@@ -2716,6 +2721,11 @@ export class Cartographic {
  */
 export class CartographicGeocoderService {
     constructor();
+    /**
+     * Gets the credit to display after a geocode is performed. Typically this is used to credit
+     * the geocoder service.
+     */
+    readonly credit: Credit | undefined;
     /**
      * @param query - The query to be sent to the geocoder service
      */
@@ -4818,7 +4828,7 @@ export class CorridorOutlineGeometry {
 /**
  * A credit contains data pertaining to how to display attributions/credits for certain content on the screen.
  * @example
- * //Create a credit with a tooltip, image and link
+ * // Create a credit with a tooltip, image and link
  * const credit = new Cesium.Credit('<a href="https://cesium.com/" target="_blank"><img src="/images/cesium_logo.png" title="Cesium"/></a>');
  * @param html - An string representing an html code snippet
  * @param [showOnScreen = false] - If true, the credit will be visible in the main credit container.  Otherwise, it will appear in a popover
@@ -6595,6 +6605,7 @@ export namespace GeocoderService {
     type Result = {
         displayName: string;
         destination: Rectangle | Cartesian3;
+        attributions?: object[];
     };
 }
 
@@ -6604,6 +6615,17 @@ export namespace GeocoderService {
  */
 export class GeocoderService {
     constructor();
+    /**
+     * Gets the credit to display after a geocode is performed. Typically this is used to credit
+     * the geocoder service.
+     */
+    readonly credit: Credit | undefined;
+    /**
+     * Parses credits from the geocoder result attributions, if present.
+     * @param geocoderResult - The geocoder result
+     * @returns A list of credits if present in the result, otherwise undefined
+     */
+    static getCreditsFromResult(geocoderResult: GeocoderService.Result): Credit[] | undefined;
     /**
      * @param query - The query to be sent to the geocoder service
      * @param [type = GeocodeType.SEARCH] - The type of geocode to perform.
@@ -8545,6 +8567,11 @@ export class IonGeocoderService {
         accessToken?: string;
         server?: string | Resource;
     });
+    /**
+     * Gets the credit to display after a geocode is performed. Typically this is used to credit
+     * the geocoder service.
+     */
+    readonly credit: Credit | undefined;
     /**
      * @param query - The query to be sent to the geocoder service
      * @param [type = GeocodeType.SEARCH] - The type of geocode to perform.
@@ -11591,6 +11618,11 @@ export class OpenCageGeocoderService {
      * Optional params passed to OpenCage in order to customize geocoding
      */
     readonly params: any;
+    /**
+     * Gets the credit to display after a geocode is performed. Typically this is used to credit
+     * the geocoder service.
+     */
+    readonly credit: Credit | undefined;
     /**
      * @param query - The query to be sent to the geocoder service
      */
@@ -12113,6 +12145,11 @@ export class PeliasGeocoderService {
      * The Resource used to access the Pelias endpoint.
      */
     readonly url: Resource;
+    /**
+     * Gets the credit to display after a geocode is performed. Typically this is used to credit
+     * the geocoder service.
+     */
+    readonly credit: Credit | undefined;
     /**
      * @param query - The query to be sent to the geocoder service
      * @param [type = GeocodeType.SEARCH] - The type of geocode to perform.
@@ -14398,6 +14435,7 @@ export enum ReferenceFrame {
  * @param [options.throttle = false] - Whether to throttle and prioritize the request. If false, the request will be sent immediately. If true, the request will be throttled and sent based on priority.
  * @param [options.throttleByServer = false] - Whether to throttle the request by server.
  * @param [options.type = RequestType.OTHER] - The type of request.
+ * @param [options.serverKey] - A key used to identify the server that a request is going to.
  */
 export class Request {
     constructor(options?: {
@@ -14409,6 +14447,7 @@ export class Request {
         throttle?: boolean;
         throttleByServer?: boolean;
         type?: RequestType;
+        serverKey?: string;
     });
     /**
      * The URL to request.
@@ -14524,11 +14563,14 @@ export namespace RequestScheduler {
      */
     var maximumRequestsPerServer: number;
     /**
-     * A per server key list of overrides to use for throttling instead of <code>maximumRequestsPerServer</code>
+     * A per server key list of overrides to use for throttling instead of <code>maximumRequestsPerServer</code>.
+     * Useful when streaming data from a known HTTP/2 or HTTP/3 server.
+     * @example
+     * RequestScheduler.requestsByServer["myserver.com:443"] = 18;
      * @example
      * RequestScheduler.requestsByServer = {
-     *   'api.cesium.com:443': 18,
-     *   'assets.cesium.com:443': 18
+     *   "api.cesium.com:443": 18,
+     *   "assets.cesium.com:443": 18,
      * };
      */
     var requestsByServer: any;
@@ -14601,6 +14643,7 @@ export namespace Resource {
      * @property [retryCallback] - The Function to call when a request for this resource fails. If it returns true, the request will be retried.
      * @property [retryAttempts = 0] - The number of times the retryCallback should be called before giving up.
      * @property [request] - A Request object that will be used. Intended for internal use only.
+     * @property [parseUrl = true] - If true, parse the url for query parameters; otherwise store the url without change
      */
     type ConstructorOptions = {
         url: string;
@@ -14611,6 +14654,7 @@ export namespace Resource {
         retryCallback?: Resource.RetryCallback;
         retryAttempts?: number;
         request?: Request;
+        parseUrl?: boolean;
     };
     /**
      * A function that returns the value of the property.
@@ -25284,6 +25328,15 @@ export class Appearance {
     getRenderState(): any;
 }
 
+/**
+ * ArcGisBaseMapType enumerates the ArcGIS image tile layers that are supported by default.
+ */
+export enum ArcGisBaseMapType {
+    SATELLITE = 1,
+    OCEANS = 2,
+    HILLSHADE = 3
+}
+
 export namespace ArcGisMapServerImageryProvider {
     /**
      * Initialization options for the ArcGisMapServerImageryProvider constructor
@@ -25301,8 +25354,7 @@ export namespace ArcGisMapServerImageryProvider {
      *        that no tiles are discarded, construct and pass a {@link NeverTileDiscardPolicy} for this
      *        parameter.
      * @property [usePreCachedTilesIfAvailable = true] - If true, the server's pre-cached
-     *        tiles are used if they are available.  If false, any pre-cached tiles are ignored and the
-     *        'export' service is used.
+     *        tiles are used if they are available. Exporting Tiles is only supported with deprecated APIs.
      * @property [layers] - A comma-separated list of the layers to show, or undefined if all layers should be shown.
      * @property [enablePickFeatures = true] - If true, {@link ArcGisMapServerImageryProvider#pickFeatures} will invoke
      *        the Identify service on the MapServer and return the features included in the response.  If false,
@@ -25341,15 +25393,35 @@ export namespace ArcGisMapServerImageryProvider {
 
 /**
  * <div class="notice">
- * To construct a ArcGisMapServerImageryProvider call {@link ArcGisMapServerImageryProvider.fromUrl}. Do not call the constructor directly.
+ * This object is normally not instantiated directly, use {@link ArcGisMapServerImageryProvider.fromBasemapType} or {@link ArcGisMapServerImageryProvider.fromUrl}.
  * </div>
  *
  * Provides tiled imagery hosted by an ArcGIS MapServer.  By default, the server's pre-cached tiles are
  * used, if available.
+ *
+ * <br/>
+ *
+ * An {@link https://developers.arcgis.com/documentation/mapping-apis-and-services/security| ArcGIS Access Token } is required to authenticate requests to an ArcGIS Image Tile service.
+ * To access secure ArcGIS resources, it's required to create an ArcGIS developer
+ * account or an ArcGIS online account, then implement an authentication method to obtain an access token.
  * @example
+ * // Set the default access token for accessing ArcGIS Image Tile service
+ * Cesium.ArcGisMapService.defaultAccessToken = "<ArcGIS Access Token>";
+ *
+ * // Add a base layer from a default ArcGIS basemap
+ * const viewer = new Cesium.Viewer("cesiumContainer", {
+ *   baseLayer: Cesium.ImageryLayer.fromProviderAsync(
+ *     Cesium.ArcGisMapServerImageryProvider.fromBasemapType(
+ *       Cesium.ArcGisBaseMapType.SATELLITE
+ *     )
+ *   ),
+ * });
+ * @example
+ * // Create an imagery provider from the url directly
  * const esri = await Cesium.ArcGisMapServerImageryProvider.fromUrl(
- *     "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
- * );
+ *   "https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer", {
+ *     token: "<ArcGIS Access Token>"
+ * });
  * @param [options] - Object describing initialization options
  */
 export class ArcGisMapServerImageryProvider {
@@ -25361,6 +25433,31 @@ export class ArcGisMapServerImageryProvider {
      * without communicating with the server.
      */
     enablePickFeatures: boolean;
+    /**
+     * Creates an {@link ImageryProvider} which provides tiled imagery from an ArcGIS base map.
+     * @example
+     * // Set the default access token for accessing ArcGIS Image Tile service
+     * Cesium.ArcGisMapService.defaultAccessToken = "<ArcGIS Access Token>";
+     *
+     * // Add a base layer from a default ArcGIS basemap
+     * const provider = await Cesium.ArcGisMapServerImageryProvider.fromBasemapType(
+     *   Cesium.ArcGisBaseMapType.SATELLITE);
+     * @example
+     * // Add a base layer from a default ArcGIS Basemap
+     * const viewer = new Cesium.Viewer("cesiumContainer", {
+     *   baseLayer: Cesium.ImageryLayer.fromProviderAsync(
+     *     Cesium.ArcGisMapServerImageryProvider.fromBasemapType(
+     *       Cesium.ArcGisBaseMapType.HILLSHADE, {
+     *         token: "<ArcGIS Access Token>"
+     *       }
+     *     )
+     *   ),
+     * });
+     * @param style - The style of the ArcGIS base map imagery. Valid options are {@link ArcGisBaseMapType.SATELLITE}, {@link ArcGisBaseMapType.OCEANS}, and {@link ArcGisBaseMapType.HILLSHADE}.
+     * @param [options] - Object describing initialization options.
+     * @returns A promise that resolves to the created ArcGisMapServerImageryProvider.
+     */
+    static fromBasemapType(style: ArcGisBaseMapType, options?: ArcGisMapServerImageryProvider.ConstructorOptions): Promise<ArcGisMapServerImageryProvider>;
     /**
      * Gets the URL of the ArcGIS MapServer.
      */
@@ -25531,6 +25628,34 @@ export class ArcGisMapServerImageryProvider {
     pickFeatures(x: number, y: number, level: number, longitude: number, latitude: number): Promise<ImageryLayerFeatureInfo[]> | undefined;
 }
 
+/**
+ * Default options for accessing the ArcGIS image tile service.
+ *
+ * An ArcGIS access token is required to access ArcGIS image tile layers.
+ * A default token is provided for evaluation purposes only.
+ * To obtain an access token, go to {@link https://developers.arcgis.com} and create a free account.
+ * More info can be found in the {@link https://developers.arcgis.com/documentation/mapping-apis-and-services/security/ | ArcGIS developer guide}.
+ */
+export namespace ArcGisMapService {
+    /**
+     * Gets or sets the default ArcGIS access token.
+     */
+    var defaultAccessToken: string;
+    /**
+     * Gets or sets the URL of the ArcGIS World Imagery tile service.
+     */
+    var defaultWorldImageryServer: string | Resource;
+    /**
+     * Gets or sets the URL of the ArcGIS World Hillshade tile service.
+     */
+    var defaultWorldHillshadeServer: string | Resource;
+    /**
+     * Gets or sets the URL of the ArcGIS World Oceans tile service.
+     */
+    var defaultWorldOceanServer: string | Resource;
+    function getDefaultTokenCredit(providedKey: string): string | undefined;
+}
+
 /**
  * An enum describing the x, y, and z axes and helper conversion functions.
  */
@@ -28808,7 +28933,7 @@ export namespace Cesium3DTileset {
  * try {
  *   const tileset = await Cesium.Cesium3DTileset.fromUrl(
  *      "http://localhost:8002/tilesets/Seattle/tileset.json"
- *   });
+ *   );
  *   scene.primitives.add(tileset);
  * } catch (error) {
  *   console.error(`Error creating tileset: ${error}`);
@@ -29526,7 +29651,7 @@ export class Cesium3DTileset {
      * try {
      *   const tileset = await Cesium.Cesium3DTileset.fromUrl(
      *      "http://localhost:8002/tilesets/Seattle/tileset.json"
-     *   });
+     *   );
      *   scene.primitives.add(tileset);
      * } catch (error) {
      *   console.error(`Error creating tileset: ${error}`);
@@ -29555,9 +29680,9 @@ export class Cesium3DTileset {
      * });
      * scene.primitives.add(tileset);
      * @param url - The url to a tileset JSON file.
-     * @param options - An object describing initialization options
+     * @param [options] - An object describing initialization options
      */
-    static fromUrl(url: Resource | string, options: Cesium3DTileset.ConstructorOptions): Promise<Cesium3DTileset>;
+    static fromUrl(url: Resource | string, options?: Cesium3DTileset.ConstructorOptions): Promise<Cesium3DTileset>;
     /**
      * Provides a hook to override the method used to request the tileset json
      * useful when fetching tilesets from remote servers
@@ -30272,7 +30397,13 @@ export class ConeEmitter {
 /**
  * The credit display is responsible for displaying credits on screen.
  * @example
- * const creditDisplay = new Cesium.CreditDisplay(creditContainer);
+ * // Add a credit with a tooltip, image and link to display onscreen
+ * const credit = new Cesium.Credit(`<a href="https://cesium.com/" target="_blank"><img src="/images/cesium_logo.png" title="Cesium"/></a>`, true);
+ * viewer.creditDisplay.addStaticCredit(credit);
+ * @example
+ * // Add a credit with a plaintext link to display in the lightbox
+ * const credit = new Cesium.Credit('<a href="https://cesium.com/" target="_blank">Cesium</a>');
+ * viewer.creditDisplay.addStaticCredit(credit);
  * @param container - The HTML element where credits will be displayed
  * @param [delimiter = ' • '] - The string to separate text credits
  * @param [viewport = document.body] - The HTML element that will contain the credits popup
@@ -30285,16 +30416,41 @@ export class CreditDisplay {
     container: HTMLElement;
     /**
      * Adds a credit to the list of current credits to be displayed in the credit container
+     * for the next frame
      * @param credit - The credit to display
      */
     addCredit(credit: Credit): void;
+    /**
+     * Adds a {@link Credit} that will show on screen or in the lightbox until
+     * the next frame. This is mostly for internal use. Use {@link CreditDisplay.addStaticCredit} to add a persistent credit to the screen.
+     * @param credit - The credit to display in the next frame.
+     */
+    addCreditToNextFrame(credit: Credit): void;
     /**
      * Adds credits that will persist until they are removed
      * @param credit - The credit to added to defaults
      */
     addDefaultCredit(credit: Credit): void;
     /**
-     * Removes a default credit
+     * Adds a {@link Credit} that will show on screen or in the lightbox until removed with {@link CreditDisplay.removeStaticCredit}.
+     * @example
+     * // Add a credit with a tooltip, image and link to display onscreen
+     * const credit = new Cesium.Credit(`<a href="https://cesium.com/" target="_blank"><img src="/images/cesium_logo.png" title="Cesium"/></a>`, true);
+     * viewer.creditDisplay.addStaticCredit(credit);
+     * @example
+     * // Add a credit with a plaintext link to display in the lightbox
+     * const credit = new Cesium.Credit('<a href="https://cesium.com/" target="_blank">Cesium</a>');
+     * viewer.creditDisplay.addStaticCredit(credit);
+     * @param credit - The credit to added
+     */
+    addStaticCredit(credit: Credit): void;
+    /**
+     * Removes a static credit shown on screen or in the lightbox.
+     * @param credit - The credit to be removed.
+     */
+    removeStaticCredit(credit: Credit): void;
+    /**
+     * Removes a default credit.
      * @param credit - The credit to be removed from defaults
      */
     removeDefaultCredit(credit: Credit): void;
@@ -36581,6 +36737,27 @@ export class Model {
      * } catch (error) {
      *  console.log(`Failed to load model. ${error}`);
      * }
+     * @example
+     * // Load a model and play the last animation at half speed
+     * let animations;
+     * try {
+     *  const model = await Cesium.Model.fromGltfAsync({
+     *    url: "../../SampleData/models/CesiumMan/Cesium_Man.glb",
+     *    gltfCallback: gltf => {
+     *      animations = gltf.animations
+     *    }
+     *  });
+     *  viewer.scene.primitives.add(model);
+     *  model.readyEvent.addEventListener(() => {
+     *    model.activeAnimations.add({
+     *      index: animations.length - 1,
+     *      loop: Cesium.ModelAnimationLoop.REPEAT,
+     *      multiplier: 0.5,
+     *    });
+     *  });
+     * } catch (error) {
+     *  console.log(`Failed to load model. ${error}`);
+     * }
      * @param options - Object with the following properties:
      * @param options.url - The url to the .gltf or .glb file.
      * @param [options.basePath = ''] - The base path that paths in the glTF JSON are relative to.
@@ -36628,6 +36805,7 @@ export class Model {
      * @param [options.instanceFeatureIdLabel = "instanceFeatureId_0"] - Label of the instance feature ID set used for picking and styling. If instanceFeatureIdLabel is set to an integer N, it is converted to the string "instanceFeatureId_N" automatically. If both per-primitive and per-instance feature IDs are present, the instance feature IDs take priority.
      * @param [options.pointCloudShading] - Options for constructing a {@link PointCloudShading} object to control point attenuation and lighting.
      * @param [options.classificationType] - Determines whether terrain, 3D Tiles or both will be classified by this model. This cannot be set after the model has loaded.
+     * @param [options.gltfCallback] - A function that is called with the loaded gltf object once loaded.
      * @returns A promise that resolves to the created model when it is ready to render.
      */
     static fromGltfAsync(options: {
@@ -36677,9 +36855,18 @@ export class Model {
         instanceFeatureIdLabel?: string | number;
         pointCloudShading?: any;
         classificationType?: ClassificationType;
+        gltfCallback?: Model.GltfCallback;
     }): Promise<Model>;
 }
 
+export namespace Model {
+    /**
+     * Interface for the function that is called with the loaded gltf object once loaded.
+     * @param gltf - The gltf object
+     */
+    type GltfCallback = (gltf: any) => void;
+}
+
 /**
  * <div class="notice">
  * Create animations by calling {@link ModelAnimationCollection#add}. Do not call the constructor directly.
@@ -37230,7 +37417,7 @@ export enum UniformType {
     /**
      * A 3x3 matrix of floating point values.
      */
-    MAT3 = "mat2",
+    MAT3 = "mat3",
     /**
      * A 3x3 matrix of floating point values.
      */
@@ -43332,6 +43519,10 @@ export class CesiumWidget {
      * The terrain provider providing surface geometry for the globe.
      */
     terrainProvider: TerrainProvider;
+    /**
+     * Manages the list of credits to display on screen and in the lightbox.
+     */
+    creditDisplay: CreditDisplay;
     /**
      * Gets the camera.
      */