@cesium/engine 21.0.1 → 22.1.0

package/Source/Scene/Azure2DImageryProvider.js

@@ -1,4 +1,5 @@
 import Check from "../Core/Check.js";
+import Frozen from "../Core/Frozen.js";
 import Credit from "../Core/Credit.js";
 import defined from "../Core/defined.js";
 import Resource from "../Core/Resource.js";
@@ -14,7 +15,7 @@ const trailingSlashRegex = /\/$/;
  *
  * @property {object} options Object with the following properties:
  * @property {string} [options.url="https://atlas.microsoft.com/"] The Azure server url.
- * @property {string} [options.tilesetId="microsoft.imagery"] The Azure tileset ID. Valid options are {@link microsoft.imagery}, {@link microsoft.base.road}, and {@link microsoft.base.labels.road}
+ * @property {string} options.tilesetId="microsoft.imagery" The Azure tileset ID. Valid options are {@link microsoft.imagery}, {@link microsoft.base.road}, and {@link microsoft.base.labels.road}
  * @property {string} options.subscriptionKey The public subscription key for the imagery.
  * @property {Ellipsoid} [options.ellipsoid=Ellipsoid.default] The ellipsoid.  If not specified, the default ellipsoid is used.
  * @property {number} [options.minimumLevel=0] The minimum level-of-detail supported by the imagery provider.  Take care when specifying
@@ -29,7 +30,6 @@ const trailingSlashRegex = /\/$/;
  *
  * @alias Azure2DImageryProvider
  * @constructor
- * @private
  * @param {Azure2DImageryProvider.ConstructorOptions} options Object describing initialization options
  *
  * @example
@@ -41,16 +41,18 @@ const trailingSlashRegex = /\/$/;
  */
 function Azure2DImageryProvider(options) {
   options = options ?? {};
-  options.maximumLevel = options.maximumLevel ?? 22;
-  options.minimumLevel = options.minimumLevel ?? 0;
+  const tilesetId = options.tilesetId ?? "microsoft.imagery";
+  this._maximumLevel = options.maximumLevel ?? 22;
+  this._minimumLevel = options.minimumLevel ?? 0;
 
-  const subscriptionKey =
+  this._subscriptionKey =
     options.subscriptionKey ?? options["subscription-key"];
   //>>includeStart('debug', pragmas.debug);
-  Check.defined("options.tilesetId", options.tilesetId);
-  Check.defined("options.subscriptionKey", subscriptionKey);
+  Check.defined("options.subscriptionKey", this._subscriptionKey);
   //>>includeEnd('debug');
 
+  this._tilesetId = options.tilesetId;
+
   const resource =
     options.url instanceof IonResource
       ? options.url
@@ -60,19 +62,23 @@ function Azure2DImageryProvider(options) {
   if (!trailingSlashRegex.test(templateUrl)) {
     templateUrl += "/";
   }
-  templateUrl += `map/tile`;
 
-  resource.url = templateUrl;
+  const tilesUrl = `${templateUrl}map/tile`;
+  this._viewportUrl = `${templateUrl}map/attribution`;
+
+  resource.url = tilesUrl;
 
   resource.setQueryParameters({
     "api-version": "2024-04-01",
-    tilesetId: options.tilesetId,
+    tilesetId: tilesetId,
+    "subscription-key": this._subscriptionKey,
     zoom: `{z}`,
     x: `{x}`,
     y: `{y}`,
-    "subscription-key": subscriptionKey,
   });
 
+  this._resource = resource;
+
   let credit;
   if (defined(options.credit)) {
     credit = options.credit;
@@ -83,6 +89,8 @@ function Azure2DImageryProvider(options) {
 
   const provider = new UrlTemplateImageryProvider({
     ...options,
+    maximumLevel: this._maximumLevel,
+    minimumLevel: this._minimumLevel,
     url: resource,
     credit: credit,
   });
@@ -91,6 +99,7 @@ function Azure2DImageryProvider(options) {
 
   // This will be defined for ion resources
   this._tileCredits = resource.credits;
+  this._attributionsByLevel = undefined;
 }
 
 Object.defineProperties(Azure2DImageryProvider.prototype, {
@@ -261,7 +270,18 @@ Object.defineProperties(Azure2DImageryProvider.prototype, {
  * @returns {Credit[]|undefined} The credits to be displayed when the tile is displayed.
  */
 Azure2DImageryProvider.prototype.getTileCredits = function (x, y, level) {
-  return this._imageryProvider.getTileCredits(x, y, level);
+  const hasAttributions = defined(this._attributionsByLevel);
+
+  if (!hasAttributions || !defined(this._tileCredits)) {
+    return undefined;
+  }
+
+  const innerCredits = this._attributionsByLevel.get(level);
+  if (!defined(this._tileCredits)) {
+    return innerCredits;
+  }
+
+  return this._tileCredits.concat(innerCredits);
 };
 
 /**
@@ -280,7 +300,21 @@ Azure2DImageryProvider.prototype.requestImage = function (
   level,
   request,
 ) {
-  return this._imageryProvider.requestImage(x, y, level, request);
+  const promise = this._imageryProvider.requestImage(x, y, level, request);
+
+  // If the requestImage call returns undefined, it couldn't be scheduled this frame. Make sure to return undefined so this can be handled upstream.
+  if (!defined(promise)) {
+    return undefined;
+  }
+
+  // Asynchronously request and populate _attributionsByLevel if it hasn't been already. We do this here so that the promise can be properly awaited.
+  if (!defined(this._attributionsByLevel)) {
+    return Promise.all([promise, this.getViewportCredits()]).then(
+      (results) => results[0],
+    );
+  }
+
+  return promise;
 };
 
 /**
@@ -304,5 +338,57 @@ Azure2DImageryProvider.prototype.pickFeatures = function (
   return undefined;
 };
 
+/**
+ * Get attribution for imagery from Azure Maps to display in the credits
+ * @private
+ * @return {Promise<Map<Credit[]>>} The list of attribution sources to display in the credits.
+ */
+Azure2DImageryProvider.prototype.getViewportCredits = async function () {
+  const maximumLevel = this._maximumLevel;
+
+  const promises = [];
+  for (let level = 0; level < maximumLevel + 1; level++) {
+    promises.push(
+      fetchViewportAttribution(
+        this._resource,
+        this._viewportUrl,
+        this._subscriptionKey,
+        this._tilesetId,
+        level,
+      ),
+    );
+  }
+  const results = await Promise.all(promises);
+
+  const attributionsByLevel = new Map();
+  for (let level = 0; level < maximumLevel + 1; level++) {
+    const credits = [];
+    const attributions = results[level].join(",");
+    if (attributions) {
+      const levelCredits = new Credit(attributions);
+      credits.push(levelCredits);
+    }
+    attributionsByLevel.set(level, credits);
+  }
+
+  this._attributionsByLevel = attributionsByLevel;
+
+  return attributionsByLevel;
+};
+
+async function fetchViewportAttribution(resource, url, key, tilesetId, level) {
+  const viewportResource = resource.getDerivedResource({
+    url,
+    queryParameters: {
+      zoom: level,
+      bounds: "-180,-90,180,90",
+    },
+    data: JSON.stringify(Frozen.EMPTY_OBJECT),
+  });
+
+  const viewportJson = await viewportResource.fetchJson();
+  return viewportJson.copyrights;
+}
+
 // Exposed for tests
 export default Azure2DImageryProvider;

package/Source/Scene/BatchTable.js

@@ -20,7 +20,7 @@ import Texture from "../Renderer/Texture.js";
  * @private
  *
  * @param {Context} context The context in which the batch table is created.
- * @param {Object[]} attributes An array of objects describing a per instance attribute. Each object contains a datatype, components per attributes, whether it is normalized and a function name
+ * @param {object[]} attributes An array of objects describing a per instance attribute. Each object contains a datatype, components per attributes, whether it is normalized and a function name
  *     to retrieve the value in the vertex shader.
  * @param {number} numberOfInstances The number of instances in a batch table.
  *
@@ -131,7 +131,7 @@ Object.defineProperties(BatchTable.prototype, {
   /**
    * The attribute descriptions.
    * @memberOf BatchTable.prototype
-   * @type {Object[]}
+   * @type {object[]}
    * @readonly
    */
   attributes: {

package/Source/Scene/Billboard.js

@@ -23,6 +23,8 @@ import SceneMode from "./SceneMode.js";
 import SceneTransforms from "./SceneTransforms.js";
 import VerticalOrigin from "./VerticalOrigin.js";
 import SplitDirection from "./SplitDirection.js";
+import getExtensionFromUri from "../Core/getExtensionFromUri.js";
+import isDataUri from "../Core/isDataUri.js";
 
 /**
  * @typedef {object} Billboard.ConstructorOptions
@@ -32,7 +34,7 @@ import SplitDirection from "./SplitDirection.js";
  * @property {Cartesian3} position The cartesian position of the billboard.
  * @property {*} [id] A user-defined object to return when the billboard is picked with {@link Scene#pick}.
  * @property {boolean} [show=true] Determines if this billboard will be shown.
- * @property {string | HTMLCanvasElement} [image] A loaded HTMLImageElement, ImageData, or a url to an image to use for the billboard.
+ * @property {string | HTMLImageElement | HTMLCanvasElement} [image] A loaded HTMLImageElement, ImageData, or a url to an image to use for the billboard.
  * @property {number} [scale=1.0] A number specifying the uniform scale that is multiplied with the billboard's image size in pixels.
  * @property {Cartesian2} [pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Specifying the pixel offset in screen space from the origin of this billboard.
  * @property {Cartesian3} [eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Specifying the 3D Cartesian offset applied to this billboard in eye coordinates.
@@ -189,31 +191,27 @@ function Billboard(options, billboardCollection) {
   this._batchIndex = undefined; // Used only by Vector3DTilePoints and BillboardCollection
 
   this._imageTexture = new BillboardTexture(billboardCollection);
+
+  this._imageId = options.imageId;
   this._imageWidth = undefined;
   this._imageHeight = undefined;
-
   this._labelDimensions = undefined;
   this._labelHorizontalOrigin = undefined;
   this._labelTranslate = undefined;
 
   const image = options.image;
-  let imageId = options.imageId;
   if (defined(image)) {
-    if (!defined(imageId)) {
-      if (typeof image === "string") {
-        imageId = image;
-      } else if (defined(image.src)) {
-        imageId = image.src;
-      } else {
-        imageId = createGuid();
-      }
-    }
-
-    this._imageTexture.loadImage(imageId, image);
+    this._computeImageTextureProperties(options.imageId, image);
+    this._imageTexture.loadImage(
+      this._imageId,
+      image,
+      this._imageWidth,
+      this._imageHeight,
+    );
   }
 
   if (defined(options.imageSubRegion)) {
-    this._imageTexture.addImageSubRegion(imageId, options.imageSubRegion);
+    this._imageTexture.addImageSubRegion(this._imageId, options.imageSubRegion);
   }
 
   this._actualClampedPosition = undefined;
@@ -947,18 +945,13 @@ Object.defineProperties(Billboard.prototype, {
         return;
       }
 
-      let id;
-      if (typeof value === "string") {
-        id = value;
-      } else if (value instanceof Resource) {
-        id = value._url;
-      } else if (defined(value.src)) {
-        id = value.src;
-      } else {
-        id = createGuid();
-      }
-
-      this._imageTexture.loadImage(id, value);
+      this._computeImageTextureProperties(undefined, value);
+      this._imageTexture.loadImage(
+        this._imageId,
+        value,
+        this._imageWidth,
+        this._imageHeight,
+      );
     },
   },
 
@@ -1252,7 +1245,13 @@ Billboard.prototype.setImage = function (id, image) {
   Check.defined("image", image);
   //>>includeEnd('debug');
 
-  this._imageTexture.loadImage(id, image);
+  this._computeImageTextureProperties(id, image);
+  this._imageTexture.loadImage(
+    this._imageId,
+    image,
+    this._imageWidth,
+    this._imageHeight,
+  );
 };
 
 /**
@@ -1268,6 +1267,54 @@ Billboard.prototype.setImageTexture = function (billboardTexture) {
   BillboardTexture.clone(billboardTexture, this._imageTexture);
 };
 
+/** Arbitrary limit on allocated SVG size, in pixels. Raster images use image resolution. */
+const SVG_MAX_SIZE_PX = 512;
+
+/**
+ * Computes billboard texture ID, width, and height. For raster images, width and height are left
+ * undefined, defaulting to image resolution. For SVG, use billboard pixel width and height.
+ * @param {string | undefined} id The id of the image.
+ * @param {string | HTMLImageElement | HTMLCanvasElement | undefined} image A loaded HTMLImageElement, ImageData, or a url to an image to use for the billboard.
+ * @private
+ */
+Billboard.prototype._computeImageTextureProperties = function (id, image) {
+  this._imageWidth = undefined;
+  this._imageHeight = undefined;
+
+  if (!defined(image)) {
+    this._imageId = createGuid();
+    return;
+  }
+
+  let imageUri;
+  if (typeof image === "string") {
+    imageUri = image;
+  } else if (image instanceof Resource) {
+    imageUri = image._url;
+  } else if (defined(image.src)) {
+    imageUri = image.src;
+  }
+
+  this._imageId = id ?? imageUri ?? createGuid();
+
+  const hasSizeInPixels =
+    defined(this._width) && defined(this._height) && !this._sizeInMeters;
+
+  if (hasSizeInPixels && isSvgUri(imageUri)) {
+    this._imageWidth = Math.min(this._width, SVG_MAX_SIZE_PX);
+    this._imageHeight = Math.min(this._height, SVG_MAX_SIZE_PX);
+  }
+};
+
+function isSvgUri(uri) {
+  if (!defined(uri)) {
+    return false;
+  }
+  return isDataUri(uri)
+    ? uri.startsWith("data:image/svg+xml")
+    : getExtensionFromUri(uri) === "svg";
+}
+
 /**
  * Uses a sub-region of the image with the given id as the image for this billboard,
  * measured in pixels from the bottom-left.

package/Source/Scene/BillboardCollection.js

@@ -13,7 +13,6 @@ import EncodedCartesian3 from "../Core/EncodedCartesian3.js";
 import IndexDatatype from "../Core/IndexDatatype.js";
 import CesiumMath from "../Core/Math.js";
 import Matrix4 from "../Core/Matrix4.js";
-import WebGLConstants from "../Core/WebGLConstants.js";
 import Buffer from "../Renderer/Buffer.js";
 import BufferUsage from "../Renderer/BufferUsage.js";
 import ContextLimits from "../Renderer/ContextLimits.js";
@@ -34,6 +33,8 @@ import SceneMode from "./SceneMode.js";
 import SDFSettings from "./SDFSettings.js";
 import TextureAtlas from "../Renderer/TextureAtlas.js";
 import VerticalOrigin from "./VerticalOrigin.js";
+import Ellipsoid from "../Core/Ellipsoid.js";
+import WebGLConstants from "../Core/WebGLConstants.js";
 
 const SHOW_INDEX = Billboard.SHOW_INDEX;
 const POSITION_INDEX = Billboard.POSITION_INDEX;
@@ -315,6 +316,8 @@ function BillboardCollection(options) {
   ];
 
   this._highlightColor = Color.clone(Color.WHITE); // Only used by Vector3DTilePoints
+  this._coarseDepthTestDistance = Ellipsoid.default.minimumRadius / 100;
+  this._threePointDepthTestDistance = Ellipsoid.default.minimumRadius / 1000;
 
   this._uniforms = {
     u_atlas: () => {
@@ -323,6 +326,16 @@ function BillboardCollection(options) {
     u_highlightColor: () => {
       return this._highlightColor;
     },
+    // An eye-space distance, beyond which, the billboard is simply tested against a camera-facing plane at the ellipsoid's center,
+    // rather than against a depth texture. Note: only if the disableDepthTestingDistance property permits.
+    u_coarseDepthTestDistance: () => {
+      return this._coarseDepthTestDistance;
+    },
+    // Within this distance, if the billboard is clamped to the ground, we'll depth-test 3 key points.
+    // If any key point is visible, the whole billboard will be visible.
+    u_threePointDepthTestDistance: () => {
+      return this._threePointDepthTestDistance;
+    },
   };
 
   const scene = this._scene;
@@ -1372,9 +1385,6 @@ function writeCompressedAttribute3(
   const clampToGround =
     isHeightReferenceClamp(billboard.heightReference) &&
     frameState.context.depthTexture;
-  if (!defined(disableDepthTestDistance)) {
-    disableDepthTestDistance = clampToGround ? 5000.0 : 0.0;
-  }
 
   disableDepthTestDistance *= disableDepthTestDistance;
   if (clampToGround || disableDepthTestDistance > 0.0) {
@@ -2042,7 +2052,6 @@ BillboardCollection.prototype.update = function (frameState) {
     // If OPAQUE_AND_TRANSLUCENT is in use, only the opaque pass gets the benefit of the depth buffer,
     // not the translucent pass.  Otherwise, if the TRANSLUCENT pass is on its own, it turns on
     // a depthMask in lieu of full depth sorting (because it has opaque-ish fragments that look bad in OIT).
-    // When the TRANSLUCENT depth mask is in use, label backgrounds require the depth func to be LEQUAL.
     const useTranslucentDepthMask =
       this._blendOption === BlendOption.TRANSLUCENT;
 
@@ -2141,9 +2150,9 @@ BillboardCollection.prototype.update = function (frameState) {
     }
     if (this._shaderClampToGround) {
       if (supportVSTextureReads) {
-        vs.defines.push("VERTEX_DEPTH_CHECK");
+        vs.defines.push("VS_THREE_POINT_DEPTH_CHECK");
       } else {
-        vs.defines.push("FRAGMENT_DEPTH_CHECK");
+        vs.defines.push("FS_THREE_POINT_DEPTH_CHECK");
       }
     }
 
@@ -2162,9 +2171,9 @@ BillboardCollection.prototype.update = function (frameState) {
       });
       if (this._shaderClampToGround) {
         if (supportVSTextureReads) {
-          fs.defines.push("VERTEX_DEPTH_CHECK");
+          fs.defines.push("VS_THREE_POINT_DEPTH_CHECK");
         } else {
-          fs.defines.push("FRAGMENT_DEPTH_CHECK");
+          fs.defines.push("FS_THREE_POINT_DEPTH_CHECK");
         }
       }
 
@@ -2187,9 +2196,9 @@ BillboardCollection.prototype.update = function (frameState) {
       });
       if (this._shaderClampToGround) {
         if (supportVSTextureReads) {
-          fs.defines.push("VERTEX_DEPTH_CHECK");
+          fs.defines.push("VS_THREE_POINT_DEPTH_CHECK");
         } else {
-          fs.defines.push("FRAGMENT_DEPTH_CHECK");
+          fs.defines.push("FS_THREE_POINT_DEPTH_CHECK");
         }
       }
       if (this._sdf) {
@@ -2212,9 +2221,9 @@ BillboardCollection.prototype.update = function (frameState) {
       });
       if (this._shaderClampToGround) {
         if (supportVSTextureReads) {
-          fs.defines.push("VERTEX_DEPTH_CHECK");
+          fs.defines.push("VS_THREE_POINT_DEPTH_CHECK");
         } else {
-          fs.defines.push("FRAGMENT_DEPTH_CHECK");
+          fs.defines.push("FS_THREE_POINT_DEPTH_CHECK");
         }
       }
       if (this._sdf) {
@@ -2237,9 +2246,9 @@ BillboardCollection.prototype.update = function (frameState) {
       });
       if (this._shaderClampToGround) {
         if (supportVSTextureReads) {
-          fs.defines.push("VERTEX_DEPTH_CHECK");
+          fs.defines.push("VS_THREE_POINT_DEPTH_CHECK");
         } else {
-          fs.defines.push("FRAGMENT_DEPTH_CHECK");
+          fs.defines.push("FS_THREE_POINT_DEPTH_CHECK");
         }
       }
       if (this._sdf) {

package/Source/Scene/BillboardTexture.js

@@ -160,8 +160,15 @@ BillboardTexture.prototype.unload = async function () {
  * @param {string} id An identifier to detect whether the image already exists in the atlas.
  * @param {HTMLImageElement|HTMLCanvasElement|string|Resource|Promise|TextureAtlas.CreateImageCallback} image An image or canvas to add to the texture atlas,
  *        or a URL to an Image, or a Promise for an image, or a function that creates an image.
+ * @param {number} width A number specifying the width of the texture. If undefined, the image width will be used.
+ * @param {number} height A number specifying the height of the texture. If undefined, the image height will be used.
  */
-BillboardTexture.prototype.loadImage = async function (id, image) {
+BillboardTexture.prototype.loadImage = async function (
+  id,
+  image,
+  width,
+  height,
+) {
   if (this._id === id) {
     // This image has already been loaded
     return;
@@ -192,7 +199,7 @@ BillboardTexture.prototype.loadImage = async function (id, image) {
   let index;
   const atlas = this._billboardCollection.textureAtlas;
   try {
-    index = await atlas.addImage(id, image);
+    index = await atlas.addImage(id, image, width, height);
   } catch (error) {
     // There was an error loading the image
     billboardTexture._loadState = BillboardLoadState.ERROR;
@@ -251,16 +258,38 @@ BillboardTexture.prototype.loadImage = async function (id, image) {
  * @param {string} id An identifier to detect whether the image already exists in the atlas.
  * @param {BoundingRectangle} subRegion An {@link BoundingRectangle} defining a region of an existing image, measured in pixels from the bottom-left of the image.
  */
-BillboardTexture.prototype.addImageSubRegion = async function (id, subRegion) {
+BillboardTexture.prototype.addImageSubRegion = function (id, subRegion) {
   this._id = id;
-  this._loadState = BillboardLoadState.LOADING;
   this._loadError = undefined;
   this._hasSubregion = true;
 
-  let index;
   const atlas = this._billboardCollection.textureAtlas;
+  const indexOrPromise = atlas.addImageSubRegion(id, subRegion);
+
+  if (typeof indexOrPromise === "number") {
+    this.setImageSubRegion(indexOrPromise, subRegion);
+    return;
+  }
+
+  this.loadImageSubRegion(id, subRegion, indexOrPromise);
+};
+
+/**
+ * @see {TextureAtlas#addImageSubRegion}
+ * @private
+ * @param {string} id An identifier to detect whether the image already exists in the atlas.
+ * @param {BoundingRectangle} subRegion An {@link BoundingRectangle} defining a region of an existing image, measured in pixels from the bottom-left of the image.
+ * @param {Promise<number>} indexPromise A promise that resolves to the image region index.
+ */
+BillboardTexture.prototype.loadImageSubRegion = async function (
+  id,
+  subRegion,
+  indexPromise,
+) {
+  let index;
   try {
-    index = await atlas.addImageSubRegion(id, subRegion);
+    this._loadState = BillboardLoadState.LOADING;
+    index = await indexPromise;
   } catch (error) {
     // There was an error loading the referenced image
     this._loadState = BillboardLoadState.ERROR;
@@ -268,6 +297,27 @@ BillboardTexture.prototype.addImageSubRegion = async function (id, subRegion) {
     return;
   }
 
+  if (this._id !== id) {
+    // Another load was initiated and resolved resolved before this one. This operation is cancelled.
+    return;
+  }
+
+  this._loadState = BillboardLoadState.LOADED;
+
+  this.setImageSubRegion(index, subRegion);
+};
+
+/**
+ * @see {TextureAtlas#addImageSubRegion}
+ * @private
+ * @param {number} index The resolved index in the {@link TextureAtlas}
+ * @param {BoundingRectangle} subRegion An {@link BoundingRectangle} defining a region of an existing image, measured in pixels from the bottom-left of the image.
+ */
+BillboardTexture.prototype.setImageSubRegion = function (index, subRegion) {
+  if (this._index === index) {
+    return;
+  }
+
   if (!defined(index) || index === -1) {
     this._loadState = BillboardLoadState.FAILED;
     this._index = -1;
@@ -280,7 +330,6 @@ BillboardTexture.prototype.addImageSubRegion = async function (id, subRegion) {
   this._height = subRegion.height;
 
   this._index = index;
-  this._loadState = BillboardLoadState.LOADED;
 
   this.dirty = true;
 };

package/Source/Scene/BingMapsImageryProvider.js

@@ -457,7 +457,7 @@ Object.defineProperties(BingMapsImageryProvider.prototype, {
 /**
  * Creates an {@link ImageryProvider} which provides tiled imagery using the Bing Maps Imagery REST API.
  *
- * @param {Resource|String} url The url of the Bing Maps server hosting the imagery.
+ * @param {Resource|string} url The url of the Bing Maps server hosting the imagery.
  * @param {BingMapsImageryProvider.ConstructorOptions} options Object describing initialization options
  * @returns {Promise<BingMapsImageryProvider>} A promise that resolves to the created BingMapsImageryProvider
  *