fix(billboards): Scale SVGs in texture atlas to match billboard display size

Author: donmccurdy

CHANGES.md

@@ -7,6 +7,7 @@
 #### Fixes :wrench:
 
 - Billboards using `imageSubRegion` now render as expected. [#12585](https://github.com/CesiumGS/cesium/issues/12585)
+- Improved scaling of SVGs in billboards [#TODO](https://github.com/CesiumGS/cesium/issues/TODO)
 
 #### Additions :tada:
 

CONTRIBUTORS.md

@@ -105,6 +105,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
   - [Daniel Zhong](https://github.com/danielzhong)
   - [Mark Schlosser](https://github.com/markschlosseratbentley)
   - [Adam Larkeryd](https://github.com/alarkbentley)
+  - [Don McCurdy](https://github.com/donmccurdy)
 - [Flightradar24 AB](https://www.flightradar24.com)
   - [Aleksei Kalmykov](https://github.com/kalmykov)
 - [BIT Systems](http://www.caci.com/bit-systems)

packages/engine/Source/DataSources/BillboardGraphics.js

@@ -10,7 +10,7 @@ import createPropertyDescriptor from "./createPropertyDescriptor.js";
  * Initialization options for the BillboardGraphics constructor
  *
  * @property {Property | boolean} [show=true] A boolean Property specifying the visibility of the billboard.
- * @property {Property | string | HTMLCanvasElement} [image] A Property specifying the Image, URI, or Canvas to use for the billboard.
+ * @property {Property | string | HTMLImageElement | HTMLCanvasElement} [image] A Property specifying the Image, URI, or Canvas to use for the billboard.
  * @property {Property | number} [scale=1.0] A numeric Property specifying the scale to apply to the image size.
  * @property {Property | Cartesian2} [pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Property specifying the pixel offset.
  * @property {Property | Cartesian3} [eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the eye offset.

packages/engine/Source/DataSources/BillboardVisualizer.js

@@ -131,10 +131,6 @@ BillboardVisualizer.prototype.update = function (time) {
     }
 
     billboard.show = show;
-    if (item.textureValue !== textureValue) {
-      billboard.image = textureValue;
-      item.textureValue = textureValue;
-    }
     billboard.position = position;
     billboard.color = Property.getValueOrDefault(
       billboardGraphics._color,
@@ -227,6 +223,13 @@ BillboardVisualizer.prototype.update = function (time) {
       defaultSplitDirection,
     );
 
+    // Apply .image last, so any necessary property values are available
+    // in Billboard#_computeImageTextureSize before adding to the atlas.
+    if (item.textureValue !== textureValue) {
+      billboard.image = textureValue;
+      item.textureValue = textureValue;
+    }
+
     const subRegion = Property.getValueOrUndefined(
       billboardGraphics._imageSubRegion,
       time,

packages/engine/Source/Renderer/TextureAtlas.js

@@ -648,9 +648,11 @@ async function resolveImage(image, id) {
  * @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.
  * @returns {Promise<number>} A Promise that resolves to the image region index, or -1 if resources are in the process of being destroyed.
  */
-TextureAtlas.prototype.addImage = function (id, image) {
+TextureAtlas.prototype.addImage = function (id, image, width, height) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("id", id);
   Check.defined("image", image);
@@ -671,17 +673,24 @@ TextureAtlas.prototype.addImage = function (id, image) {
   this._indexById.set(id, index);
 
   const resolveAndAddImage = async () => {
-    image = await resolveImage(image, id);
+    const resolvedImage = await resolveImage(image, id);
     //>>includeStart('debug', pragmas.debug);
-    Check.defined("image", image);
+    Check.defined("image", resolvedImage);
     //>>includeEnd('debug');
 
-    if (this.isDestroyed() || !defined(image)) {
+    if (this.isDestroyed() || !defined(resolvedImage)) {
       this._indexPromiseById.delete(id);
       return -1;
     }
 
-    const imageIndex = await this._addImage(index, image);
+    if (defined(width)) {
+      resolvedImage.width = width;
+    }
+    if (defined(height)) {
+      resolvedImage.height = height;
+    }
+
+    const imageIndex = await this._addImage(index, resolvedImage);
     this._indexPromiseById.delete(id);
     return imageIndex;
   };

packages/engine/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.
@@ -190,28 +192,26 @@ function Billboard(options, 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;
@@ -945,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,
+      );
     },
   },
 
@@ -1250,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,
+  );
 };
 
 /**
@@ -1266,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.

packages/engine/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;

packages/engine/Specs/Scene/BillboardCollectionSpec.js

@@ -347,6 +347,40 @@ describe("Scene/BillboardCollection", function () {
     expect(b.image.length).toBe(guidLength);
   });
 
+  it("image property setter computes SVG width and height", function () {
+    const b = billboards.add();
+
+    // Don't override image size if billboard size is unspecified.
+    b.image = "icon.svg";
+    expect(b.image).toBe("icon.svg");
+    expect(b._imageWidth).toBeUndefined();
+    expect(b._imageHeight).toBeUndefined();
+
+    // Don't override image size for raster images.
+    b.width = b.height = 50;
+    b.image = "icon.png";
+    expect(b._imageWidth).toBeUndefined();
+    expect(b._imageHeight).toBeUndefined();
+
+    // Override image size with billboard size for SVGs.
+    b.width = b.height = 50;
+    b.image = "icon.svg";
+    expect(b._imageWidth).toBe(50);
+    expect(b._imageHeight).toBe(50);
+
+    // Limit billboard-derived SVG size to 512px.
+    b.width = b.height = 10000;
+    b.image = "icon-lg.svg";
+    expect(b._imageWidth).toBe(512);
+    expect(b._imageHeight).toBe(512);
+
+    // Don't override image size if billboard is not sized in pixels.
+    b.sizeInMeters = true;
+    b.image = "icon.svg";
+    expect(b._imageWidth).toBeUndefined();
+    expect(b._imageHeight).toBeUndefined();
+  });
+
   it("is not destroyed", function () {
     expect(billboards.isDestroyed()).toEqual(false);
   });