@cesium/engine 22.0.0 → 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";
@@ -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 ?? {};
-  const maximumLevel = options.maximumLevel ?? 22;
-  const 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.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: 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,8 +89,8 @@ function Azure2DImageryProvider(options) {
 
   const provider = new UrlTemplateImageryProvider({
     ...options,
-    maximumLevel,
-    minimumLevel,
+    maximumLevel: this._maximumLevel,
+    minimumLevel: this._minimumLevel,
     url: resource,
     credit: credit,
   });
@@ -93,6 +99,7 @@ function Azure2DImageryProvider(options) {
 
   // This will be defined for ion resources
   this._tileCredits = resource.credits;
+  this._attributionsByLevel = undefined;
 }
 
 Object.defineProperties(Azure2DImageryProvider.prototype, {
@@ -263,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);
 };
 
 /**
@@ -282,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;
 };
 
 /**
@@ -306,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/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

@@ -34,6 +34,7 @@ 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;
@@ -2039,7 +2040,8 @@ BillboardCollection.prototype.update = function (frameState) {
     ) {
       this._rsOpaque = RenderState.fromCache({
         depthTest: {
-          enabled: false,
+          enabled: true,
+          func: WebGLConstants.LESS,
         },
         depthMask: true,
       });
@@ -2059,7 +2061,10 @@ BillboardCollection.prototype.update = function (frameState) {
     ) {
       this._rsTranslucent = RenderState.fromCache({
         depthTest: {
-          enabled: false,
+          enabled: true,
+          func: useTranslucentDepthMask
+            ? WebGLConstants.LEQUAL
+            : WebGLConstants.LESS,
         },
         depthMask: useTranslucentDepthMask,
         blending: BlendingState.ALPHA_BLEND,

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/Globe.js

@@ -943,7 +943,9 @@ Globe.prototype.getHeight = function (cartographic) {
 
   const intersection = tile.data.pick(
     ray,
-    undefined,
+    // Globe height is the same at a given cartographic regardless of the scene mode,
+    // but the ray is constructed via a surface normal (which assumes 3D), so pick in 3D mode.
+    SceneMode.SCENE3D,
     projection,
     false,
     scratchGetHeightIntersection,

package/Source/Scene/GlobeSurfaceTile.js

@@ -1,12 +1,9 @@
 import BoundingSphere from "../Core/BoundingSphere.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Cartesian4 from "../Core/Cartesian4.js";
-import Cartographic from "../Core/Cartographic.js";
 import defined from "../Core/defined.js";
 import IndexDatatype from "../Core/IndexDatatype.js";
-import IntersectionTests from "../Core/IntersectionTests.js";
 import PixelFormat from "../Core/PixelFormat.js";
-import Ray from "../Core/Ray.js";
 import Request from "../Core/Request.js";
 import RequestState from "../Core/RequestState.js";
 import RequestType from "../Core/RequestType.js";
@@ -23,7 +20,6 @@ import TextureWrap from "../Renderer/TextureWrap.js";
 import VertexArray from "../Renderer/VertexArray.js";
 import ImageryState from "./ImageryState.js";
 import QuadtreeTileLoadState from "./QuadtreeTileLoadState.js";
-import SceneMode from "./SceneMode.js";
 import TerrainState from "./TerrainState.js";
 
 /**
@@ -126,33 +122,6 @@ Object.defineProperties(GlobeSurfaceTile.prototype, {
   },
 });
 
-const scratchCartographic = new Cartographic();
-
-function getPosition(encoding, mode, projection, vertices, index, result) {
-  let position = encoding.getExaggeratedPosition(vertices, index, result);
-
-  if (defined(mode) && mode !== SceneMode.SCENE3D) {
-    const ellipsoid = projection.ellipsoid;
-    const positionCartographic = ellipsoid.cartesianToCartographic(
-      position,
-      scratchCartographic,
-    );
-    position = projection.project(positionCartographic, result);
-    position = Cartesian3.fromElements(
-      position.z,
-      position.x,
-      position.y,
-      result,
-    );
-  }
-
-  return position;
-}
-
-const scratchV0 = new Cartesian3();
-const scratchV1 = new Cartesian3();
-const scratchV2 = new Cartesian3();
-
 GlobeSurfaceTile.prototype.pick = function (
   ray,
   mode,
@@ -160,42 +129,11 @@ GlobeSurfaceTile.prototype.pick = function (
   cullBackFaces,
   result,
 ) {
-  const mesh = this.renderedMesh;
-  if (!defined(mesh)) {
+  if (!defined(this.renderedMesh)) {
     return undefined;
   }
-
-  const vertices = mesh.vertices;
-  const indices = mesh.indices;
-  const encoding = mesh.encoding;
-  const indicesLength = indices.length;
-
-  let minT = Number.MAX_VALUE;
-
-  for (let i = 0; i < indicesLength; i += 3) {
-    const i0 = indices[i];
-    const i1 = indices[i + 1];
-    const i2 = indices[i + 2];
-
-    const v0 = getPosition(encoding, mode, projection, vertices, i0, scratchV0);
-    const v1 = getPosition(encoding, mode, projection, vertices, i1, scratchV1);
-    const v2 = getPosition(encoding, mode, projection, vertices, i2, scratchV2);
-
-    const t = IntersectionTests.rayTriangleParametric(
-      ray,
-      v0,
-      v1,
-      v2,
-      cullBackFaces,
-    );
-    if (defined(t) && t < minT && t >= 0.0) {
-      minT = t;
-    }
-  }
-
-  return minT !== Number.MAX_VALUE
-    ? Ray.getPoint(ray, minT, result)
-    : undefined;
+  const value = this.renderedMesh.pick(ray, cullBackFaces, mode, projection);
+  return Cartesian3.clone(value, result);
 };
 
 GlobeSurfaceTile.prototype.freeResources = function () {
@@ -473,8 +411,10 @@ GlobeSurfaceTile.prototype.updateExaggeration = function (
     encoding.exaggeration !== exaggeration;
   const encodingRelativeHeightChanged =
     encoding.exaggerationRelativeHeight !== exaggerationRelativeHeight;
+  const exaggerationChanged =
+    encodingExaggerationScaleChanged || encodingRelativeHeightChanged;
 
-  if (encodingExaggerationScaleChanged || encodingRelativeHeightChanged) {
+  if (exaggerationChanged) {
     // Turning exaggeration scale on/off requires adding or removing geodetic surface normals
     // Relative height only translates, so it has no effect on normals
     if (encodingExaggerationScaleChanged) {
@@ -498,7 +438,19 @@ GlobeSurfaceTile.prototype.updateExaggeration = function (
         data.level = -1;
       }
     }
+
+    mesh.updateExaggeration(exaggeration, exaggerationRelativeHeight);
+  }
+};
+
+GlobeSurfaceTile.prototype.updateSceneMode = function (mode) {
+  const surfaceTile = this;
+  const mesh = surfaceTile.renderedMesh;
+  if (mesh === undefined) {
+    return;
   }
+
+  mesh.updateSceneMode(mode);
 };
 
 function prepareNewTile(tile, terrainProvider, imageryLayerCollection) {

package/Source/Scene/GlobeSurfaceTileProvider.js

@@ -193,6 +193,7 @@ function GlobeSurfaceTileProvider(options) {
 
   this._oldVerticalExaggeration = undefined;
   this._oldVerticalExaggerationRelativeHeight = undefined;
+  this._oldSceneMode = SceneMode.SCENE3D;
 }
 
 Object.defineProperties(GlobeSurfaceTileProvider.prototype, {
@@ -514,6 +515,16 @@ GlobeSurfaceTileProvider.prototype.endUpdate = function (frameState) {
     });
   }
 
+  const sceneModeChanged = this._oldSceneMode !== frameState.mode;
+  this._oldSceneMode = frameState.mode;
+
+  if (sceneModeChanged) {
+    quadtree.forEachLoadedTile(function (tile) {
+      const surfaceTile = tile.data;
+      surfaceTile.updateSceneMode(frameState.mode);
+    });
+  }
+
   // Add the tile render commands to the command list, sorted by texture count.
   const tilesToRenderByTextureCount = this._tilesToRenderByTextureCount;
   for (