@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/BufferPolylineCollection.js

@@ -1,6 +1,8 @@
 // @ts-check
 
 import defined from "../Core/defined.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import Frozen from "../Core/Frozen.js";
 import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
 import BufferPolyline from "./BufferPolyline.js";
 import renderPolylines from "./renderBufferPolylineCollection.js";
@@ -8,7 +10,12 @@ import BufferPolylineMaterial from "./BufferPolylineMaterial.js";
 
 /** @import { TypedArray } from "../Core/globalTypes.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
+/** @import BoundingSphere from "../Core/BoundingSphere.js"; */
+/** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
+/** @import BlendOption from "./BlendOption.js"; */
+/** @import HeightReference from "./HeightReference.js"; */
 /** @import FrameState from "./FrameState.js" */
+/** @import { BufferPrimitiveCollectionOptions } from "./BufferPrimitiveCollection.js"; */
 
 /**
  * @typedef {object} BufferPolylineOptions
@@ -57,6 +64,55 @@ import BufferPolylineMaterial from "./BufferPolylineMaterial.js";
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 class BufferPolylineCollection extends BufferPrimitiveCollection {
+  /**
+   * @param {object} [options]
+   * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+   * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
+   * @param {number} [options.vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
+   * @param {boolean} [options.show=true]
+   * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
+   * @param {boolean} [options.positionNormalized=false]
+   * @param {boolean} [options.allowPicking=false] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+   * @param {BoundingSphere} [options.boundingVolume] Bounding volume, in world space, for the collection.
+   * @param {boolean} [options.debugShowBoundingVolume=false]
+   * @param {BlendOption} [options.blendOption=BlendOption.TRANSLUCENT]
+   * @param {HeightReference} [options.heightReference=HeightReference.NONE]
+   * @param {"pixels"|"meters"} [options.widthUnits="pixels"] Unit of polyline widths in this collection:
+   *   <code>"pixels"</code> on the screen, or <code>"meters"</code> in world space. A clamped
+   *   {@link HeightReference} measures those meters on the ellipsoid surface, so elevation and terrain
+   *   slope stretch the drawn width.
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super(options);
+
+    const widthUnits = options.widthUnits ?? "pixels";
+
+    //>>includeStart('debug', pragmas.debug);
+    if (widthUnits !== "pixels" && widthUnits !== "meters") {
+      throw new DeveloperError(
+        'options.widthUnits must be "pixels" or "meters".',
+      );
+    }
+    //>>includeEnd('debug');
+
+    /**
+     * @type {"pixels"|"meters"}
+     * @private
+     */
+    this._widthUnits = widthUnits;
+  }
+
+  /**
+   * Unit of polyline widths in this collection: <code>"pixels"</code> on the screen, or
+   * <code>"meters"</code> in world space, measured on the ellipsoid surface when clamped.
+   *
+   * @type {"pixels"|"meters"}
+   * @readonly
+   */
+  get widthUnits() {
+    return this._widthUnits;
+  }
+
   _getCollectionClass() {
     return BufferPolylineCollection;
   }
@@ -73,17 +129,15 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
   // COLLECTION LIFECYCLE
 
   /**
-   * @param {BufferPolylineCollection} collection
+   * @param {BufferPrimitiveCollectionOptions} [options]
    * @returns {BufferPolylineCollection}
    * @override
    * @ignore
    */
-  static _cloneEmpty(collection) {
+  _cloneEmpty(options = Frozen.EMPTY_OBJECT) {
     return new BufferPolylineCollection({
-      primitiveCountMax: collection.primitiveCountMax,
-      vertexCountMax: collection.vertexCountMax,
-      positionDatatype: collection.positionDatatype,
-      positionNormalized: collection.positionNormalized,
+      widthUnits: this._widthUnits,
+      ...this._cloneEmptyBaseArgs(options),
     });
   }
 
@@ -126,8 +180,7 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
   update(frameState) {
     super.update(frameState);
 
-    const passes = frameState.passes;
-    if (this.show && (passes.render || passes.pick)) {
+    if (this._isRendered(frameState)) {
       this._renderContext = renderPolylines(
         this,
         frameState,

package/Source/Scene/BufferPolylineMaterial.js

@@ -11,7 +11,8 @@ import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js";
  * @property {Color} [color=Color.WHITE] Color of fill.
  * @property {Color} [outlineColor=Color.WHITE] Color of outline.
  * @property {number} [outlineWidth=0.0] Width of outline, 0-255px.
- * @property {number} [width=1.0] Width of line, 0-255px.
+ * @property {number} [width=1.0] Width of line, in the unit selected by
+ *   {@link BufferPolylineCollection#widthUnits}.
  */
 
 /**
@@ -28,7 +29,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
   /** @ignore */
   static Layout = {
     ...BufferPrimitiveMaterial.Layout,
-    WIDTH_U8: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH,
+    WIDTH_F32: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH,
     __BYTE_LENGTH: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH + 4,
   };
 
@@ -45,7 +46,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
     super(options);
 
     /**
-     * Width of polyline, 0–255px.
+     * Width of polyline, in the unit selected by {@link BufferPolylineCollection#widthUnits}.
      * @type {number}
      */
     this.width = options.width ?? 1;
@@ -59,7 +60,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
    */
   static pack(material, view, byteOffset) {
     super.pack(material, view, byteOffset);
-    view.setUint8(this.Layout.WIDTH_U8 + byteOffset, material.width);
+    view.setFloat32(this.Layout.WIDTH_F32 + byteOffset, material.width, true);
   }
 
   /**
@@ -71,7 +72,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
    */
   static unpack(view, byteOffset, result) {
     super.unpack(view, byteOffset, result);
-    result.width = view.getUint8(this.Layout.WIDTH_U8 + byteOffset);
+    result.width = view.getFloat32(this.Layout.WIDTH_F32 + byteOffset, true);
     return result;
   }
 

package/Source/Scene/BufferPrimitiveCollection.js

@@ -14,6 +14,7 @@ import SceneMode from "./SceneMode.js";
 import AttributeType from "./AttributeType.js";
 import oneTimeWarning from "../Core/oneTimeWarning.js";
 import BlendOption from "../Scene/BlendOption.js";
+import HeightReference, { isHeightReferenceClamp } from "./HeightReference.js";
 
 /** @import { Destroyable, TypedArray, TypedArrayConstructor } from "../Core/globalTypes.js"; */
 /** @import Context from "../Renderer/Context.js"; */
@@ -32,6 +33,31 @@ import BlendOption from "../Scene/BlendOption.js";
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 
+/**
+ * @typedef {object} BufferPrimitiveCollectionOptions
+ * @property {Matrix4} [modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {number} [primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of primitives.
+ * @property {number} [vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of vertices.
+ * @property {boolean} [show=true]
+ * @property {ComponentDatatype} [positionDatatype=ComponentDatatype.DOUBLE] The component datatype used to store position values.
+ * @property {boolean} [positionNormalized=false] When <code>true</code>, integer position values are treated as normalized,
+ *   where the full integer range maps to [-1, 1] (signed) or [0, 1] (unsigned). Only relevant for integer position datatypes
+ *   (BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT).
+ * @property {boolean} [allowPicking=false] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+ * @property {BoundingSphere} [boundingVolume] Bounding volume, in world space, for the collection. When
+ *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
+ *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
+ *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
+ * @property {boolean} [debugShowBoundingVolume=false]
+ * @property {BlendOption} [blendOption=BlendOption.TRANSLUCENT]
+ * @property {HeightReference} [options.heightReference=HeightReference.NONE] When set to a clamping value, the
+ *   collection is draped onto the surfaces selected by the value: {@link HeightReference.CLAMP_TO_TERRAIN} drapes
+ *   onto the globe, {@link HeightReference.CLAMP_TO_3D_TILE} drapes onto 3D Tiles, and
+ *   {@link HeightReference.CLAMP_TO_GROUND} drapes onto both. Only {@link BufferPolylineCollection} and
+ *   {@link BufferPolygonCollection} support draping, and only once the collection has been added to
+ *   {@link Scene#primitives}. A draped collection is not also drawn as geometry of its own.
+ */
+
 /**
  * Collection of primitives held in ArrayBuffer storage for performance and memory optimization.
  *
@@ -71,22 +97,7 @@ class BufferPrimitiveCollection {
   _renderContext = null;
 
   /**
-   * @param {object} options
-   * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
-   * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {boolean} [options.show=true]
-   * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
-   * @param {boolean} [options.positionNormalized=false] When <code>true</code>, integer position values are treated as normalized,
-   *   where the full integer range maps to [-1, 1] (signed) or [0, 1] (unsigned). Only relevant for integer position datatypes
-   *   (BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT).
-   * @param {boolean} [options.allowPicking=false] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
-   * @param {BoundingSphere} [options.boundingVolume] Bounding volume, in world space, for the collection. When
-   *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
-   *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
-   *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
-   * @param {boolean} [options.debugShowBoundingVolume=false]
-   * @param {BlendOption} [options.blendOption=BlendOption.TRANSLUCENT]
+   * @param {BufferPrimitiveCollectionOptions} [options]
    */
   constructor(options = Frozen.EMPTY_OBJECT) {
     /**
@@ -96,6 +107,13 @@ class BufferPrimitiveCollection {
      */
     this.show = options.show ?? true;
 
+    /**
+     * @type {HeightReference}
+     * @readonly
+     * @protected
+     */
+    this._heightReference = options.heightReference ?? HeightReference.NONE;
+
     /**
      * Collection blend option; must be OPAQUE or TRANSLUCENT.
      * @type {BlendOption}
@@ -148,11 +166,14 @@ class BufferPrimitiveCollection {
     this._pickIds = new Map();
 
     /**
+     * User-defined pick objects. Primitives without custom pick objects will have default
+     * pick objects assigned instead.
+     *
      * @type {object[]}
      * @readonly
      * @ignore
      */
-    this._pickObjects = [];
+    this._customPickObjects = [];
 
     /**
      * This property is for debugging only; it is not for production use nor is it optimized.
@@ -194,7 +215,6 @@ class BufferPrimitiveCollection {
 
     /**
      * @type {number}
-     * @protected
      * @ignore
      */
     this._positionCountMax =
@@ -249,6 +269,13 @@ class BufferPrimitiveCollection {
      */
     this._dirtyBoundingVolume = false;
 
+    /**
+     * Monotonically increasing counter, bumped each time collection is marked "clean".
+     * @type {number}
+     * @ignore
+     */
+    this._version = 0;
+
     this._allocatePrimitiveBuffer();
     this._allocatePositionBuffer();
     this._allocateMaterialBuffer();
@@ -336,7 +363,7 @@ class BufferPrimitiveCollection {
 
   /** Destroys collection and its GPU resources. */
   destroy() {
-    this._pickObjects.length = 0;
+    this._customPickObjects.length = 0;
 
     for (const contextPickIds of this._pickIds.values()) {
       for (const pickId of contextPickIds) {
@@ -388,7 +415,7 @@ class BufferPrimitiveCollection {
     }
 
     // Copy primitives to temporary collection, in sort order.
-    const tmp = CollectionClass._cloneEmpty(this);
+    const tmp = this._cloneEmpty();
     for (let i = 0; i < primitiveCount; i++) {
       const src = this.get(dstSrcMap[i], a);
       const dst = tmp.add({}, b);
@@ -418,9 +445,14 @@ class BufferPrimitiveCollection {
    *
    * @param {BufferPrimitiveCollection<T>} collection
    * @param {BufferPrimitiveCollection<T>} result
+   * @param {function(BufferPrimitive, number): boolean} [predicate] When provided, only primitives for which this returns <code>true</code> are copied. Surviving primitives are compacted into contiguous indices.
    * @template T extends BufferPrimitive
    */
-  static clone(collection, result) {
+  static clone(collection, result, predicate) {
+    if (defined(predicate)) {
+      return this._cloneFiltered(collection, result, predicate);
+    }
+
     //>>includeStart('debug', pragmas.debug);
     const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
     assert(collection.primitiveCount <= result.primitiveCountMax, ERR_CAPACITY);
@@ -449,14 +481,19 @@ class BufferPrimitiveCollection {
       collection.primitiveCount * MaterialClass.packedLength,
     );
 
-    result.show = collection.show;
-    result.debugShowBoundingVolume = collection.debugShowBoundingVolume;
+    // Collection-level display flags (show, debugShowBoundingVolume) are carried
+    // by the constructor, so they are intentionally not copied here.
     result._primitiveCount = collection._primitiveCount;
     result._positionCount = collection._positionCount;
 
-    // Unset PickIds.
+    // Copy per-primitive pick objects and unset each GPU PickId.
+    // PickIds are regenerated for the result collection on next render.
+    const srcPickObjects = collection._customPickObjects;
+    const dstPickObjects = result._customPickObjects;
+    dstPickObjects.length = 0;
     const primitive = new PrimitiveClass();
     for (let i = 0, il = result.primitiveCount; i < il; i++) {
+      dstPickObjects[i] = srcPickObjects[i];
       result.get(i, primitive)._pickId = 0;
     }
 
@@ -469,17 +506,123 @@ class BufferPrimitiveCollection {
   }
 
   /**
-   * Returns an empty collection with the same buffer sizes as this collection.
-   * Internal utility for operations requiring a working copy of memory.
+   * Filtered variant of {@link BufferPrimitiveCollection.clone}. Copies
+   * primitive-by-primitive via {@link BufferPrimitive.clone}, so it handles
+   * subclass data generically and needs no per-subclass override.
    *
    * @param {BufferPrimitiveCollection<T>} collection
+   * @param {BufferPrimitiveCollection<T>} result
+   * @param {function(BufferPrimitive, number): boolean} predicate
+   * @template T extends BufferPrimitive
+   * @protected
+   * @ignore
+   */
+  static _cloneFiltered(collection, result, predicate) {
+    const PrimitiveClass = collection._getPrimitiveClass();
+    const src = new PrimitiveClass();
+    const dst = new PrimitiveClass();
+
+    const srcPickObjects = collection._customPickObjects;
+    const dstPickObjects = result._customPickObjects;
+    dstPickObjects.length = 0;
+
+    for (let i = 0, il = collection._primitiveCount; i < il; i++) {
+      collection.get(i, src);
+      if (!predicate(src, i)) {
+        continue;
+      }
+
+      const dstIndex = result._primitiveCount;
+      PrimitiveClass.clone(src, result.add({}, dst));
+
+      if (defined(srcPickObjects[i])) {
+        dstPickObjects[dstIndex] = srcPickObjects[i];
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Returns a copy of the given collection, overriding any constructor options
+   * provided. Omitted options are inherited from the source collection. Any
+   * resized buffers must be large enough to hold every primitive.
+   *
+   * <p>Collection-level state (model matrix, blend option, picking, bounding-volume
+   * mode, etc.) is carried over, but GPU resources are not: the source collection
+   * retains ownership of its renderer resources, so the caller is responsible for
+   * calling {@link BufferPrimitiveCollection#destroy} on the source once it is no
+   * longer needed.</p>
+   *
+   * @example
+   * const grown = BufferPrimitiveCollection.fromCollection(collection, {
+   *   primitiveCountMax: collection.primitiveCountMax * 2,
+   *   vertexCountMax: collection.vertexCountMax * 2,
+   * });
+   * collection.destroy(); // release the source collection's GPU resources
+   *
+   * @example
+   * // Grow while dropping hidden primitives.
+   * const compacted = BufferPrimitiveCollection.fromCollection(
+   *   collection,
+   *   { primitiveCountMax: collection.primitiveCountMax * 2 },
+   *   (primitive) => primitive.show,
+   * );
+   *
+   * @param {BufferPrimitiveCollection<T>} collection Source collection to copy.
+   * @param {BufferPrimitiveCollectionOptions} [options] Constructor options to override. Omitted options are inherited from the source collection.
+   * @param {function(BufferPrimitive, number): boolean} [predicate] When provided, only primitives for which this returns <code>true</code> are copied. Surviving primitives are compacted into contiguous indices.
    * @returns {BufferPrimitiveCollection<T>}
    * @template T extends BufferPrimitive
+   */
+  static fromCollection(collection, options = Frozen.EMPTY_OBJECT, predicate) {
+    const result = collection._cloneEmpty(options);
+    collection._getCollectionClass().clone(collection, result, predicate);
+    return result;
+  }
+
+  /**
+   * Base constructor arguments that carry over collection-level state to an
+   * empty copy created by {@link BufferPrimitiveCollection.fromCollection}.
+   * Subclasses should spread the result into their constructor arguments,
+   * adding any type-specific options. Provided options override inherited
+   * state; omitted options are inherited from this collection.
+   *
+   * @param {BufferPrimitiveCollectionOptions} options
+   * @returns {object}
+   * @protected
+   * @ignore
+   */
+  _cloneEmptyBaseArgs(options) {
+    return {
+      primitiveCountMax: this.primitiveCountMax,
+      vertexCountMax: this.vertexCountMax,
+      positionDatatype: this.positionDatatype,
+      positionNormalized: this.positionNormalized,
+      modelMatrix: this._modelMatrix,
+      show: this.show,
+      debugShowBoundingVolume: this.debugShowBoundingVolume,
+      blendOption: this._blendOption,
+      allowPicking: this._allowPicking,
+      boundingVolume: this._boundingVolumeAutoUpdate
+        ? undefined
+        : this._boundingVolume,
+      ...options,
+    };
+  }
+
+  /**
+   * Returns an empty collection with the same structure as this one, overriding
+   * any constructor options provided. Omitted options are inherited from this
+   * collection.
+   *
+   * @param {BufferPrimitiveCollectionOptions} [options]
+   * @returns {BufferPrimitiveCollection<T>}
    * @protected
    * @abstract
    * @ignore
    */
-  static _cloneEmpty(collection) {
+  _cloneEmpty(options) {
     DeveloperError.throwInstantiationError();
   }
 
@@ -524,13 +667,14 @@ class BufferPrimitiveCollection {
       vertices,
       Cartesian3.ZERO,
       3,
-      this.boundingVolume,
+      this._boundingVolume,
     );
     BoundingSphere.transform(
-      this.boundingVolume,
-      this.modelMatrix,
-      this.boundingVolume,
+      this._boundingVolume,
+      this._modelMatrix,
+      this._boundingVolume,
     );
+
     this._dirtyBoundingVolume = false;
   }
 
@@ -559,7 +703,7 @@ class BufferPrimitiveCollection {
     for (let i = pickIds.length, il = this._primitiveCount; i < il; i++) {
       this.get(i, primitive);
 
-      const pickObject = this._pickObjects[i] || {
+      const pickObject = this._customPickObjects[i] || {
         collection: this,
         index: i,
         get primitive() {
@@ -637,7 +781,7 @@ class BufferPrimitiveCollection {
     result._dirty = true;
 
     if (defined(options.pickObject)) {
-      this._pickObjects[index] = options.pickObject;
+      this._customPickObjects[index] = options.pickObject;
     }
 
     return result;
@@ -660,6 +804,18 @@ class BufferPrimitiveCollection {
     }
   }
 
+  /**
+   * Marks all primitives 'clean', and updates version counter.
+   * @ignore
+   */
+  _makeClean() {
+    if (this._dirtyCount > 0) {
+      this._dirtyCount = 0;
+      this._dirtyOffset = 0;
+      this._version++;
+    }
+  }
+
   /**
    * Marks collection bounding volume as 'dirty', to be updated on next render,
    * if automatic bounding volume updates are enabled.
@@ -686,11 +842,31 @@ class BufferPrimitiveCollection {
     if (this._dirtyBoundingVolume) {
       this._updateBoundingVolume();
     }
-    if (this._allowPicking && this._dirtyCount > 0) {
+    // Not gated on the dirty count: a draped collection is packed by a surface,
+    // which may read the ids and mark the collection clean before this runs.
+    if (this._allowPicking) {
       this._updatePickIds(/** @type {FrameState} */ (frameState).context);
     }
   }
 
+  /**
+   * Whether the collection draws itself this frame. A draped collection is
+   * rendered by the surface it is draped onto.
+   *
+   * @param {FrameState} frameState
+   * @returns {boolean}
+   * @protected
+   * @ignore
+   */
+  _isRendered(frameState) {
+    const passes = frameState.passes;
+    return (
+      this.show &&
+      !isHeightReferenceClamp(this._heightReference) &&
+      (passes.render || passes.pick)
+    );
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // ACCESSORS
 
@@ -771,6 +947,9 @@ class BufferPrimitiveCollection {
    * @readonly
    */
   get boundingVolume() {
+    if (this._dirtyBoundingVolume) {
+      this._updateBoundingVolume();
+    }
     return this._boundingVolume;
   }
 
@@ -794,6 +973,19 @@ class BufferPrimitiveCollection {
     return this._positionNormalized;
   }
 
+  /**
+   * Determines which surfaces the collection is draped onto, in addition to
+   * being drawn as standalone geometry. Draping requires that the collection
+   * has been added to {@link Scene#primitives}.
+   *
+   * @type {HeightReference}
+   * @readonly
+   * @default HeightReference.NONE
+   */
+  get heightReference() {
+    return this._heightReference;
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // UTILS
 

package/Source/Scene/Camera.js

@@ -3,6 +3,7 @@ import Cartesian2 from "../Core/Cartesian2.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Cartesian4 from "../Core/Cartesian4.js";
 import Cartographic from "../Core/Cartographic.js";
+import Check from "../Core/Check.js";
 import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
@@ -2356,7 +2357,7 @@ const scratchLookAtHeadingPitchRangeQuaternion1 = new Quaternion();
 const scratchLookAtHeadingPitchRangeQuaternion2 = new Quaternion();
 const scratchHeadingPitchRangeMatrix3 = new Matrix3();
 
-function offsetFromHeadingPitchRange(heading, pitch, range) {
+function offsetFromHeadingPitchRange(heading, pitch, range, result) {
   pitch = CesiumMath.clamp(
     pitch,
     -CesiumMath.PI_OVER_TWO,
@@ -2380,10 +2381,7 @@ function offsetFromHeadingPitchRange(heading, pitch, range) {
     scratchHeadingPitchRangeMatrix3,
   );
 
-  const offset = Cartesian3.clone(
-    Cartesian3.UNIT_X,
-    scratchLookAtHeadingPitchRangeOffset,
-  );
+  const offset = Cartesian3.clone(Cartesian3.UNIT_X, result);
   Matrix3.multiplyByVector(rotMatrix, offset, offset);
   Cartesian3.negate(offset, offset);
   Cartesian3.multiplyByScalar(offset, range, offset);
@@ -2441,6 +2439,7 @@ Camera.prototype.lookAtTransform = function (transform, offset) {
       offset.heading,
       offset.pitch,
       offset.range,
+      scratchLookAtHeadingPitchRangeOffset,
     );
   } else {
     cartesianOffset = offset;
@@ -2492,6 +2491,72 @@ Camera.prototype.lookAtTransform = function (transform, offset) {
   this._adjustOrthographicFrustum(true);
 };
 
+const scratchLookAtWorldPositionTransform = new Matrix4();
+const scratchLookAtWorldPositionDirection = new Cartesian3();
+const scratchLookAtWorldPositionWorldUp = new Cartesian3();
+const scratchLookAtWorldPositionRight = new Cartesian3();
+
+/**
+ * Sets the camera orientation to look at a target position in world coordinates. The camera's up vector will be oriented to the world up vector at the target position.
+ * If the camera is at the target position, the camera will be oriented to the world up vector at the target position.
+ * @param {Cartesian3} target The target position in world coordinates.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid to use for determining the world up.
+ */
+Camera.prototype.lookAtWorldPosition = function (
+  target,
+  ellipsoid = Ellipsoid.default,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("target", target);
+  Check.typeOf.object("ellipsoid", ellipsoid);
+  //>>includeEnd('debug');
+
+  const transform = Matrix4.clone(
+    this._transform,
+    scratchLookAtWorldPositionTransform,
+  );
+
+  this._setTransform(Matrix4.IDENTITY);
+
+  // Get direction to look at target
+  let direction = Cartesian3.subtract(
+    target,
+    this.positionWC,
+    scratchLookAtWorldPositionDirection,
+  );
+
+  // If the camera is at the target position, we can't look at it, but we should still continue to re-orient the camera to the world up vector at the target position.
+  if (Cartesian3.magnitudeSquared(direction) < CesiumMath.EPSILON8) {
+    direction = Cartesian3.clone(
+      this.directionWC,
+      scratchLookAtWorldPositionDirection,
+    );
+  }
+
+  direction = Cartesian3.normalize(direction, this.direction);
+
+  // Orient the camera to the world up vector at the target position
+  const worldUp = ellipsoid.geodeticSurfaceNormal(
+    target,
+    scratchLookAtWorldPositionWorldUp,
+  );
+
+  let right = Cartesian3.cross(
+    direction,
+    worldUp,
+    scratchLookAtWorldPositionRight,
+  );
+  if (Cartesian3.magnitudeSquared(right) < CesiumMath.EPSILON8) {
+    right = Cartesian3.clone(this.rightWC, scratchLookAtWorldPositionRight);
+  }
+  Cartesian3.normalize(right, this.right);
+
+  const up = Cartesian3.cross(right, direction, this.up);
+  Cartesian3.normalize(up, this.up);
+
+  this._setTransform(transform);
+};
+
 const viewRectangle3DCartographic1 = new Cartographic();
 const viewRectangle3DCartographic2 = new Cartographic();
 const viewRectangle3DNorthEast = new Cartesian3();
@@ -3621,6 +3686,7 @@ Camera.prototype.flyToBoundingSphere = function (boundingSphere, options) {
       offset.heading,
       offset.pitch,
       offset.range,
+      scratchflyToBoundingSphereDestination,
     );
   }