@cesium/engine 22.2.0 → 23.0.0

package/Source/Scene/GoogleStreetViewCubeMapPanoramaProvider.js

@@ -0,0 +1,341 @@
+import DeveloperError from "../Core/DeveloperError.js";
+import defined from "../Core/defined.js";
+import Resource from "../Core/Resource.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import Cartographic from "../Core/Cartographic.js";
+import Matrix3 from "../Core/Matrix3.js";
+import Matrix4 from "../Core/Matrix4.js";
+import CesiumMath from "../Core/Math.js";
+import Transforms from "../Core/Transforms.js";
+import Frozen from "../Core/Frozen.js";
+import Ellipsoid from "../Core/Ellipsoid.js";
+import GoogleMaps from "../Core/GoogleMaps.js";
+import CubeMapPanorama from "./CubeMapPanorama.js";
+
+const DEFAULT_TILE_SIZE = 600;
+
+/**
+ * <div class="notice">
+ * This object is normally not instantiated directly, use {@link GoogleStreetViewCubeMapPanoramaProvider.fromUrl}.
+ * </div>
+ *
+ *
+ * Creates a {@link PanoramaProvider} which provides imagery from {@link https://developers.google.com/maps/documentation/streetview|Google Street View Static API} to be displayed in a panorama.
+ *
+ * @alias GoogleStreetViewCubeMapPanoramaProvider
+ * @constructor
+ *
+ * @see CubeMapPanorama
+ *
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=google-streetview-panorama|Cesium Sandcastle Google Streetview Panorama}
+ *
+ */
+function GoogleStreetViewCubeMapPanoramaProvider(options) {
+  options = options ?? Frozen.EMPTY_OBJECT;
+  this._key = defined(options.key) ? options.key : GoogleMaps.defaultApiKey;
+
+  this._baseResource = Resource.createIfNeeded(
+    options.url ?? GoogleMaps.streetViewStaticApiEndpoint,
+  );
+
+  this._metadataResource = this._baseResource.getDerivedResource({
+    url: "streetview/metadata",
+  });
+
+  this._tileSize = options.tileSize ?? DEFAULT_TILE_SIZE;
+}
+
+Object.defineProperties(GoogleStreetViewCubeMapPanoramaProvider.prototype, {});
+
+/**
+ * Gets the panorama primitive for a requested position and orientation.
+ * @param {object} options Object with the following properties:
+ * @param {Cartographic} options.cartographic The position to place the panorama in the scene.
+ * @param {string} [options.panoId] The panoramaId identifier for the image in the Google API. If not provided this will be looked up for the provided cartographic location.
+ * @param {number} [options.tileSize] - Optional tile size override (square).
+ * @param {string} [options.signature] - Optional signature for signed URLs. See {@link https://developers.google.com/maps/documentation/streetview/digital-signature} for more information.
+ * @param {Credit|string} [options.credit] A credit for the data source, which is displayed on the canvas.
+ *
+ * @returns {CubeMapPanorama} The panorama primitive textured with imagery.
+ *
+ * @example
+ *
+ * const provider = await Cesium.GoogleStreetViewCubeMapPanoramaProvider.fromUrl({
+ *   key: 'your Google Streetview Static api key'
+ * })
+ *
+ * const panoIdObject = provider.getNearestPanoId(position);
+ * const position = Cartographic.fromDegrees(panoIdObject.location.lng, panoIdObject.location.lat, 0);
+ *
+ * const primitive = await provider.loadPanorama({
+ *   cartographic: position,
+ *   panoId: panoIdObject.panoId
+ * });
+ * viewer.scene.primitive.add(primitive);
+ *
+ */
+GoogleStreetViewCubeMapPanoramaProvider.prototype.loadPanorama =
+  async function (options) {
+    const cartographic = options.cartographic;
+    //>>includeStart('debug', pragmas.debug);
+    if (!defined(options.cartographic)) {
+      throw new DeveloperError("options.cartographic is required.");
+    }
+    //>>includeEnd('debug');
+
+    const tileSize = options.tileSize ?? this._tileSize;
+    const tileSizeString = `${tileSize}x${tileSize}`;
+
+    const signature = options.signature;
+
+    let { panoId } = options;
+
+    if (!defined(panoId)) {
+      const panoIdObject = await this.getNearestPanoId(cartographic);
+      panoId = panoIdObject.panoId;
+    }
+
+    const credit = GoogleMaps.getDefaultCredit();
+
+    const posObj = Cartesian3.fromDegrees(
+      CesiumMath.toDegrees(cartographic.longitude),
+      CesiumMath.toDegrees(cartographic.latitude),
+      0,
+    );
+
+    const facePromises = [
+      this._loadFaceImage({
+        heading: 0,
+        pitch: 0,
+        tileSizeString,
+        panoId,
+        signature,
+      }),
+      this._loadFaceImage({
+        heading: 180,
+        pitch: 0,
+        tileSizeString,
+        panoId,
+        signature,
+      }),
+      this._loadFaceImage({
+        heading: -90,
+        pitch: -90,
+        tileSizeString,
+        panoId,
+        signature,
+      }),
+      this._loadFaceImage({
+        heading: -90,
+        pitch: 90,
+        tileSizeString,
+        panoId,
+        signature,
+      }),
+      this._loadFaceImage({
+        heading: 270,
+        pitch: 0,
+        tileSizeString,
+        panoId,
+        signature,
+      }),
+      this._loadFaceImage({
+        heading: 90,
+        pitch: 0,
+        tileSizeString,
+        panoId,
+        signature,
+      }),
+    ];
+
+    const [positiveX, negativeX, positiveY, negativeY, positiveZ, negativeZ] =
+      await Promise.all(facePromises);
+
+    const northDownEastToFixedFrameTransform =
+      Transforms.localFrameToFixedFrameGenerator("north", "down");
+
+    const transform = Matrix4.getMatrix3(
+      northDownEastToFixedFrameTransform(posObj, Ellipsoid.default),
+      new Matrix3(),
+    );
+
+    const panorama = new CubeMapPanorama({
+      sources: {
+        positiveX,
+        negativeX,
+        positiveY,
+        negativeY,
+        positiveZ,
+        negativeZ,
+      },
+      transform: transform,
+      credit,
+    });
+
+    return panorama;
+  };
+
+/**
+ * Gets the panoIds for the given cartographic location. See {@link https://developers.google.com/maps/documentation/tile/streetview#panoid-search}.
+
+ * @param {Cartographic} position The position to search for the nearest panoId.
+ * @param {number} [radius=50] The radius in meters to search for the nearest panoId.
+ * 
+ * @returns {Object} an object containing a panoId, latitude, and longitude of the closest panorama
+ * 
+ * @example
+ * 
+ * const provider = await Cesium.GoogleStreetViewCubeMapPanoramaProvider.fromUrl({
+ *   key: 'your Google Streetview Static api key'
+ * })
+ * const panoIds = provider.getNearestPanoId(position);
+ */
+GoogleStreetViewCubeMapPanoramaProvider.prototype.getNearestPanoId =
+  async function (position, radius) {
+    //>>includeStart('debug', pragmas.debug);
+    if (!defined(position)) {
+      throw new DeveloperError("position is required.");
+    }
+    //>>includeEnd('debug');
+
+    const pos = [
+      CesiumMath.toDegrees(position.latitude),
+      CesiumMath.toDegrees(position.longitude),
+    ];
+    const posString = pos.join(",");
+
+    const resource = this._metadataResource.getDerivedResource({
+      queryParameters: {
+        key: this._key,
+        location: posString,
+        radius: radius ?? 50,
+      },
+    });
+
+    const panoIdObject = await resource.fetchJson();
+
+    if (panoIdObject.status !== "OK") {
+      throw new DeveloperError(
+        `GoogleStreetViewCubeMapPanoramaProvider metadata error: ${panoIdObject.status}`,
+      );
+    }
+    return {
+      panoId: panoIdObject.pano_id,
+      latitude: panoIdObject.location.lat,
+      longitude: panoIdObject.location.lng,
+    };
+  };
+
+/**
+ * Gets metadata for panoId. See {@link https://developers.google.com/maps/documentation/tile/streetview#metadata_response} for response object.
+ * @param {string} panoId
+ *
+ * @returns {object} object containing metadata for the panoId.
+ *
+ * @example
+ * const panoIdObject = provider.getNearestPanoId(position);
+ * const panoIdMetadata = provider.getPanoIdMetadata(panoIdObject.panoId);
+ *
+ */
+GoogleStreetViewCubeMapPanoramaProvider.prototype.getPanoIdMetadata =
+  async function (panoId) {
+    const resource = this._metadataResource.getDerivedResource({
+      queryParameters: {
+        key: this._key,
+        pano: panoId,
+      },
+    });
+
+    const panoIdObject = await resource.fetchJson();
+
+    if (panoIdObject.status !== "OK") {
+      throw new DeveloperError(
+        `GoogleStreetViewCubeMapPanoramaProvider metadata error: ${panoIdObject.status}`,
+      );
+    }
+    return panoIdObject;
+  };
+
+GoogleStreetViewCubeMapPanoramaProvider.prototype._loadFaceImage =
+  async function (options) {
+    const url = this._buildFaceUrl(options);
+
+    try {
+      return await Resource.fetchImage({
+        url,
+        preferImageBitmap: true,
+        flipY: true,
+      });
+    } catch (error) {
+      throw new DeveloperError(`Failed to load Street View face image: ${url}`);
+    }
+  };
+
+GoogleStreetViewCubeMapPanoramaProvider.prototype._buildFaceUrl = function (
+  options,
+) {
+  const { heading, pitch, tileSizeString, panoId, signature } = options;
+  const resource = this._baseResource.getDerivedResource({
+    queryParameters: {
+      size: tileSizeString,
+      pano: panoId,
+      heading,
+      pitch,
+      key: this._key,
+      ...(defined(signature) && { signature }),
+    },
+  });
+
+  return resource.url;
+};
+
+/**
+ * Creates a {@link PanoramaProvider} which provides cube face images from the {@link https://developers.google.com/maps/documentation/streetview|Google Street View Static API}.
+ * @param {object} options Object with the following properties:
+ * @param {string} [options.key=GoogleMaps.defaultStreetViewStaticApiKey] Your API key to access Google Street View Static API. See {@link https://developers.google.com/maps/documentation/javascript/get-api-key} for instructions on how to create your own key. If undefined, defaults to {@link GoogleMaps.defaultStreetViewStaticApiKey}. If that value is unavailable, falls back to {@link GoogleMaps.defaultApiKey}.
+ * @param {string|Resource} [options.url=GoogleMaps.streetViewStaticApiEndpoint] The URL to access Google Street View Static API. See {@link https://developers.google.com/maps/documentation/streetview/overview} for more information.
+ * @param {number} [options.tileSize=600] Default width and height (in pixels) of each square tile.
+ * @param {Credit|string} [options.credit] A credit for the data source, which is displayed on the canvas.
+ *
+ * @returns {Promise<GoogleStreetViewCubeMapPanoramaProvider>} A promise that resolves to the created GoogleStreetViewCubeMapPanoramaProvider.'
+ *
+ * @example
+ * const provider = await Cesium.GoogleStreetViewCubeMapPanoramaProvider.fromUrl({
+ *   key: 'your Google Streetview Static api key'
+ * })
+ */
+GoogleStreetViewCubeMapPanoramaProvider.fromUrl = async function (options) {
+  options = options ?? {};
+  options.key =
+    options.key ??
+    GoogleMaps.defaultStreetViewStaticApiKey ??
+    GoogleMaps.defaultApiKey;
+  if (
+    !defined(options.key) &&
+    !defined(GoogleMaps.defaultStreetViewStaticApiKey) &&
+    !defined(GoogleMaps.defaultApiKey)
+  ) {
+    throw new DeveloperError(
+      "options.key, GoogleMaps.defaultStreetViewStaticApiKey or GoogleMaps.defaultApiKey is required.",
+    );
+  }
+
+  return new GoogleStreetViewCubeMapPanoramaProvider({
+    ...options,
+  });
+};
+
+GoogleStreetViewCubeMapPanoramaProvider._parseMetadata = function (
+  panoIdMetadata,
+) {
+  const cartographic = Cartographic.fromDegrees(
+    panoIdMetadata.location.lng,
+    panoIdMetadata.location.lat,
+    0,
+  );
+  return {
+    cartographic,
+  };
+};
+
+export default GoogleStreetViewCubeMapPanoramaProvider;

package/Source/Scene/ImageBasedLighting.js

@@ -162,7 +162,7 @@ Object.defineProperties(ImageBasedLighting.prototype, {
    * @memberof ImageBasedLighting.prototype
    *
    * @type {Cartesian3[]}
-   * @demo {@link https://sandcastle.cesium.com/index.html?src=Image-Based Lighting.html|Sandcastle Image Based Lighting Demo}
+   * @demo {@link https://sandcastle.cesium.com/index.html?id=image-based-lighting|Sandcastle Image Based Lighting Demo}
    * @see {@link https://graphics.stanford.edu/papers/envmap/envmap.pdf|An Efficient Representation for Irradiance Environment Maps}
    */
   sphericalHarmonicCoefficients: {
@@ -187,7 +187,7 @@ Object.defineProperties(ImageBasedLighting.prototype, {
    * A URL to a KTX2 file that contains a cube map of the specular lighting and the convoluted specular mipmaps.
    *
    * @memberof ImageBasedLighting.prototype
-   * @demo {@link https://sandcastle.cesium.com/index.html?src=Image-Based Lighting.html|Sandcastle Image Based Lighting Demo}
+   * @demo {@link https://sandcastle.cesium.com/index.html?id=image-based-lighting|Sandcastle Image Based Lighting Demo}
    * @type {string}
    * @see ImageBasedLighting#sphericalHarmonicCoefficients
    */

package/Source/Scene/ImageryLayerCollection.js

@@ -13,8 +13,8 @@ import ImageryLayer from "./ImageryLayer.js";
  * @constructor
  * @see {@link Scene#imageryLayers} for manipulating imagery layers on the globe.
  * @see {@link Cesium3DTileset#imageryLayers} for manipulating imagery layers on a 3D tileset.
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Adjustment.html|Cesium Sandcastle Imagery Adjustment Demo}
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Layers%20Manipulation.html|Cesium Sandcastle Imagery Manipulation Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=imagery-adjustment|Cesium Sandcastle Imagery Adjustment Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=imagery-layers-manipulation|Cesium Sandcastle Imagery Manipulation Demo}
  */
 function ImageryLayerCollection() {
   this._layers = [];

package/Source/Scene/ImageryProvider.js

@@ -39,8 +39,8 @@ import Resource from "../Core/Resource.js";
  * @see WebMapServiceImageryProvider
  * @see WebMapTileServiceImageryProvider
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Layers.html|Cesium Sandcastle Imagery Layers Demo}
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Layers%20Manipulation.html|Cesium Sandcastle Imagery Manipulation Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=imagery-layers|Cesium Sandcastle Imagery Layers Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=imagery-layers-manipulation|Cesium Sandcastle Imagery Manipulation Demo}
  */
 function ImageryProvider() {
   DeveloperError.throwInstantiationError();

package/Source/Scene/Label.js

@@ -112,7 +112,7 @@ function parseFont(label) {
  * @property {NearFarScalar} [pixelOffsetScaleByDistance] A {@link NearFarScalar} specifying near and far pixel offset scaling properties of the label based on the label's distance from the camera.
  * @property {NearFarScalar} [scaleByDistance] A {@link NearFarScalar} specifying near and far scaling properties of the label based on the label's distance from the camera.
  * @property {DistanceDisplayCondition} [distanceDisplayCondition] A {@link DistanceDisplayCondition} specifying at what distance from the camera that this label will be displayed.
- * @property {number} [disableDepthTestDistance] A number specifying the distance from the camera at which to disable the depth test to, for example, prevent clipping against terrain.
+ * @property {number} [disableDepthTestDistance] The distance from the camera, beyond which, depth testing is disabled—to, for example, prevent clipping against terrain.
  */
 
 /**
@@ -134,7 +134,7 @@ function parseFont(label) {
  * @see LabelCollection
  * @see LabelCollection#add
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Labels.html|Cesium Sandcastle Labels Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=labels|Cesium Sandcastle Labels Demo}
  */
 function Label(options, labelCollection) {
   options = options ?? Frozen.EMPTY_OBJECT;
@@ -1048,10 +1048,12 @@ Object.defineProperties(Label.prototype, {
   },
 
   /**
-   * Gets or sets the distance from the camera at which to disable the depth test to, for example, prevent clipping against terrain.
-   * When set to zero, the depth test is always applied. When set to Number.POSITIVE_INFINITY, the depth test is never applied.
+   * Gets or sets the distance from the camera, beyond which, depth testing is disabled—to, for example, prevent clipping against terrain.
+   * When set to <code>undefined</code> or
+   * <code>0</code>, the depth test is always applied. When set to Number.<code>POSITIVE_INFINITY</code>, the depth test is never applied.
    * @memberof Label.prototype
-   * @type {number}
+   * @type {number|undefined}
+   * @default undefined
    */
   disableDepthTestDistance: {
     get: function () {

package/Source/Scene/LabelCollection.js

@@ -19,6 +19,7 @@ import SDFSettings from "./SDFSettings.js";
 import TextureAtlas from "../Renderer/TextureAtlas.js";
 import VerticalOrigin from "./VerticalOrigin.js";
 import GraphemeSplitter from "grapheme-splitter";
+import { Check } from "@cesium/engine";
 
 /**
  * A glyph represents a single character in label.
@@ -593,7 +594,8 @@ function destroyLabel(labelCollection, label) {
  * is used for rendering both opaque and translucent labels. However, if either all of the labels are completely opaque or all are completely translucent,
  * setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x.
  * @param {boolean} [options.show=true] Determines if the labels in the collection will be shown.
- *
+ * @param {number} [options.coarseDepthTestDistance] The distance from the camera, beyond which, labels are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. If unspecified, the default value is determined relative to the value of {@link Ellipsoid.default}.
+ * @param {number} [options.threePointDepthTestDistance] The distance from the camera, within which, lables with a {@link Label#heightReference} value of {@link HeightReference.CLAMP_TO_GROUND} or {@link HeightReference.CLAMP_TO_TERRAIN} are depth tested against three key points. This ensures that if any key point of the label is visible, the whole label will be visible. If unspecified, the default value is determined relative to the value of {@link Ellipsoid.default}.
  * @performance For best performance, prefer a few collections, each with many labels, to
  * many collections with only a few labels each.  Avoid having collections where some
  * labels change every frame and others do not; instead, create one or more collections
@@ -604,7 +606,7 @@ function destroyLabel(labelCollection, label) {
  * @see Label
  * @see BillboardCollection
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Labels.html|Cesium Sandcastle Labels Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=labels|Cesium Sandcastle Labels Demo}
  *
  * @example
  * // Create a label collection with two labels
@@ -629,6 +631,8 @@ function LabelCollection(options) {
     textureAtlas: new TextureAtlas({
       initialSize: whitePixelSize,
     }),
+    coarseDepthTestDistance: options.coarseDepthTestDistance,
+    threePointDepthTestDistance: options.threePointDepthTestDistance,
   });
   this._backgroundBillboardCollection = backgroundBillboardCollection;
   this._backgroundBillboardTexture = new BillboardTexture(
@@ -638,6 +642,8 @@ function LabelCollection(options) {
   this._glyphBillboardCollection = new BillboardCollection({
     scene: this._scene,
     batchTable: this._batchTable,
+    coarseDepthTestDistance: options.coarseDepthTestDistance,
+    threePointDepthTestDistance: options.threePointDepthTestDistance,
   });
   this._glyphBillboardCollection._sdf = true;
 
@@ -759,6 +765,58 @@ Object.defineProperties(LabelCollection.prototype, {
       return this._glyphBillboardCollection.ready;
     },
   },
+
+  /**
+   * The distance from the camera, beyond which, labels are depth-tested against an approximation of
+   * the globe ellipsoid rather than against the full globe depth buffer. When set to <code>0</code>, the
+   * approximate depth test is always applied. When set to <code>Number.POSITIVE_INFINITY</code>, the
+   * approximate depth test is never applied.
+   * <br/><br/>
+   * This setting only applies when a label's {@link Label#disableDepthTestDistance} value would
+   * otherwise allow depth testing—i.e., distance from the camera to the label is less than the
+   * label's {@link Label#disableDepthTestDistance} value.
+   * @memberof LabelCollection.prototype
+   * @type {number}
+   */
+  coarseDepthTestDistance: {
+    get: function () {
+      return this._backgroundBillboardCollection.coarseDepthTestDistance;
+    },
+    set: function (value) {
+      //>>includeStart('debug', pragmas.debug);
+      Check.typeOf.number("coarseDepthTestDistance", value);
+      //>>includeEnd('debug');
+      this._backgroundBillboardCollection.coarseDepthTestDistance = value;
+      this._glyphBillboardCollection.coarseDepthTestDistance = value;
+    },
+  },
+
+  /**
+   * The distance from the camera, within which, labels with a {@link Label#heightReference} value
+   * of {@link HeightReference.CLAMP_TO_GROUND} or {@link HeightReference.CLAMP_TO_TERRAIN} are depth tested
+   * against three key points. This ensures that if any key point of the label is visible, the whole
+   * label will be visible. When set to <code>0</code>, this feature is disabled and portions of a
+   * label behind terrain be clipped.
+   * <br/><br/>
+   * This setting only applies when a labels's {@link Label#disableDepthTestDistance} value would
+   * otherwise allow depth testing—i.e., distance from the camera to the label is less than the
+   * labels's {@link Label#disableDepthTestDistance} value.
+   * @see {@link https://cesium.com/blog/2018/07/30/billboards-on-terrain-improvements/|Billboards and Labels on Terrain Improvements}
+   * @memberof LabelCollection.prototype
+   * @type {number}
+   */
+  threePointDepthTestDistance: {
+    get: function () {
+      return this._backgroundBillboardCollection.threePointDepthTestDistance;
+    },
+    set: function (value) {
+      //>>includeStart('debug', pragmas.debug);
+      Check.typeOf.number("threePointDepthTestDistance", value);
+      //>>includeEnd('debug');
+      this._backgroundBillboardCollection.threePointDepthTestDistance = value;
+      this._glyphBillboardCollection.threePointDepthTestDistance = value;
+    },
+  },
 });
 
 /**

package/Source/Scene/Material.js

@@ -250,7 +250,7 @@ import WaterMaterial from "../Shaders/Materials/Water.js";
  * @exception {DeveloperError} strict: shader source does not use material.
  *
  * @see {@link https://github.com/CesiumGS/cesium/wiki/Fabric|Fabric wiki page} for a more detailed options of Fabric.
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Materials.html|Cesium Sandcastle Materials Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=materials|Cesium Sandcastle Materials Demo}
  *
  * @example
  * // Create a color material with fromType:

package/Source/Scene/MaterialAppearance.js

@@ -29,7 +29,7 @@ import Material from "./Material.js";
      * @param {object} [options.renderState] Optional render state to override the default render state.
      *
      * @see {@link https://github.com/CesiumGS/cesium/wiki/Fabric|Fabric}
-     * @demo {@link https://sandcastle.cesium.com/index.html?src=Materials.html|Cesium Sandcastle Material Appearance Demo}
+     * @demo {@link https://sandcastle.cesium.com/index.html?id=materials|Cesium Sandcastle Material Appearance Demo}
      *
      * @example
      * const primitive = new Cesium.Primitive({