@cesium/engine 26.2.0 → 26.3.0

package/index.d.ts

@@ -9164,6 +9164,252 @@ export class IonResource extends Resource {
     }): Promise<ImageBitmap | HTMLImageElement> | undefined;
 }
 
+/**
+ * The type of geometry a snap resolved to, reported by {@link IonSnapService#snap}
+ * as {@link IonSnapService.Result} <code>geometryType</code>. Values match the iTwin.js
+ * {@link https://www.itwinjs.org/reference/core-frontend/locatingelements/hitgeomtype/|HitGeomType} enum.
+ */
+export enum IonSnapGeometryType {
+    /**
+     * No geometry type.
+     */
+    NONE = 0,
+    /**
+     * A point.
+     */
+    POINT = 1,
+    /**
+     * A line segment.
+     */
+    SEGMENT = 2,
+    /**
+     * A curve.
+     */
+    CURVE = 3,
+    /**
+     * An arc.
+     */
+    ARC = 4,
+    /**
+     * A surface.
+     * <p>
+     * With {@link IonSnapMode} <code>NEAREST</code>, this value indicates
+     * the snap tracked the surface under the cursor because no edge was within
+     * the snap aperture. This means the snap point was not pulled to an edge.
+     * Edge snaps report one of the other types along with the edge geometry in
+     * {@link IonSnapService.Result} <code>curve</code>, which is absent when
+     * tracking a surface.
+     * </p>
+     */
+    SURFACE = 5
+}
+
+/**
+ * How close a snap result is to the cursor, reported by {@link IonSnapService#snap}
+ * as {@link IonSnapService.Result} <code>heat</code>. Values match the iTwin.js
+ * {@link https://www.itwinjs.org/reference/core-frontend/locatingelements/snapheat/|SnapHeat} enum.
+ */
+export enum IonSnapHeat {
+    /**
+     * The snap is not close to the cursor.
+     */
+    NONE = 0,
+    /**
+     * The snap is of interest, but outside the snap aperture.
+     */
+    NOT_IN_RANGE = 1,
+    /**
+     * The snap point is within the snap aperture of the close point in view space.
+     */
+    IN_RANGE = 2
+}
+
+/**
+ * The snap modes supported by {@link IonSnapService#snap}. These follow the
+ * MicroStation snap mode semantics; see the
+ * {@link https://docs.bentley.com/LiveContent/web/MicroStation%20Help-v27/en/GUID-77D54C0B-D6FF-13DA-5EC8-3196330F5244.html|MicroStation documentation}
+ * for reference.
+ */
+export enum IonSnapMode {
+    /**
+     * Snaps to the point on the element nearest to the cursor. When the cursor
+     * is farther than the snap aperture from an edge, tracks the surface under
+     * the cursor instead.
+     */
+    NEAREST = 1,
+    /**
+     * Snaps to the nearest of the element's keypoints. Keypoints are defined by
+     * the element's geometry type and the snap divisor.
+     * <p>
+     * On linear elements, keypoints are regularly spaced along each segment:
+     * the number of keypoints on a segment is one greater than the snap
+     * divisor, and a segment's midpoint is a keypoint only when the divisor is
+     * even. The ion API does not currently accept a snap divisor, so the
+     * server's default divisor applies.
+     * </p>
+     */
+    NEAREST_KEYPOINT = 2,
+    /**
+     * Snaps to the center of elements that have centers (such as circles and
+     * arcs). For other elements, may snap to the centroid.
+     */
+    CENTER = 8
+}
+
+/**
+ * The type of the parent geometry a snap resolved to, reported by
+ * {@link IonSnapService#snap} as {@link IonSnapService.Result} <code>parentGeometryType</code>.
+ * Values match the iTwin.js
+ * {@link https://www.itwinjs.org/reference/core-frontend/locatingelements/hitparentgeomtype/|HitParentGeomType} enum.
+ */
+export enum IonSnapParentGeometryType {
+    /**
+     * No parent geometry type.
+     */
+    NONE = 0,
+    /**
+     * A wire body.
+     */
+    WIRE = 1,
+    /**
+     * A sheet body.
+     */
+    SHEET = 2,
+    /**
+     * A solid body.
+     */
+    SOLID = 3,
+    /**
+     * A mesh.
+     */
+    MESH = 4,
+    /**
+     * Text.
+     */
+    TEXT = 5
+}
+
+export namespace IonSnapService {
+    /**
+     * The result of a successful {@link IonSnapService#snap}. Extends
+     * {@link SnapService.Result} with ion-specific fields.
+     * @property [snapPoint] - The snapped point. This is the point to consume.
+     * @property [hitPoint] - The point where the cursor hit the geometry: the nearest edge point when within the snap aperture, otherwise the surface point under the cursor.
+     * @property [heat] - How close the snap point is to the close point in view space.
+     * @property [geometryType] - The type of geometry snapped to.
+     * @property [parentGeometryType] - The type of the parent geometry snapped to.
+     * @property [normal] - The surface normal at the snap point, in the model's local cartesian frame.
+     * @property [curve] - The curve geometry near the snap point, with points as WGS84 degrees objects.
+     */
+    type Result = {
+        snapPoint?: Cartesian3;
+        hitPoint?: Cartesian3;
+        heat?: IonSnapHeat;
+        geometryType?: IonSnapGeometryType;
+        parentGeometryType?: IonSnapParentGeometryType;
+        normal?: any;
+        curve?: any;
+    };
+}
+
+/**
+ * Provides interactive snap-to-geometry against a Cesium ion 3D Tiles asset
+ * backed by a BIM/CAD Database model, using the ion REST API's element snap
+ * endpoint.
+ *
+ * This class handles conversions between the reference frame of a
+ * source BIM/CAD Database and the view-dependent screen space pixel
+ * coordinates. Each snap, it transforms using the ion asset's source
+ * reference frame, the camera's transform, and the canvas
+ * dimensions so that view-dependent features— such as the pixel aperture,
+ * nearest position, or surface tracking— behave correctly.
+ *
+ * This object is normally not instantiated directly, use {@link IonSnapService.fromAssetId}.
+ * @example
+ * const snapper = await Cesium.IonSnapService.fromAssetId(123456);
+ * const canvas = viewer.scene.canvas;
+ * const result = await snapper.snap({
+ *   elementId: "0x30000000df2",
+ *   testPoint: pickedPosition,
+ *   camera: viewer.camera,
+ *   canvasWidth: canvas.clientWidth,
+ *   canvasHeight: canvas.clientHeight,
+ * });
+ * if (Cesium.defined(result)) {
+ *   console.log("snapped to", result.snapPoint);
+ * }
+ * @param options - Object with the following properties:
+ * @param options.assetId - The ion asset id.
+ * @param options.resource - The asset's ion API resource.
+ * @param options.ecefTransform - A 4x4 transformation matrix from the source BIM/CAD Database reference frame local to the world's fixed reference frame.
+ */
+export class IonSnapService {
+    constructor(options: {
+        assetId: number;
+        resource: Resource;
+        ecefTransform: Matrix4;
+    });
+    /**
+     * A 4x4 transformation matrix from the source BIM/CAD Database reference frame local to the world's fixed reference frame.
+     */
+    readonly ecefTransform: Matrix4;
+    /**
+     * The ion asset id this snapper operates on.
+     */
+    readonly assetId: number;
+    /**
+     * Creates an {@link IonSnapService} for the given ion asset, fetching
+     * the asset's ECEF transform from the ion REST API.
+     * @param assetId - The ion ID of a 3D Tiles asset backed by a BIM/CAD Database model.
+     * @param [options] - Object with the following properties:
+     * @param [options.accessToken = Ion.defaultAccessToken] - The ion access token to use.
+     * @param [options.server = Ion.defaultServer] - The ion API server to use.
+     * @returns A snapper bound to the asset.
+     */
+    static fromAssetId(assetId: number, options?: {
+        accessToken?: string;
+        server?: string | Resource;
+    }): Promise<IonSnapService>;
+    /**
+     * Requests a snap against an element of this asset.
+     *
+     * A view-correct world-to-view matrix is composed from
+     * <code>options.camera</code>, <code>options.canvasWidth</code>, and
+     * <code>options.canvasHeight</code> so view-dependent snapping (nearest
+     * ordering, pixel apertures, surface tracking) matches the current view.
+     *
+     * Only 3D views are supported: the camera must be viewing in
+     * {@link SceneMode.SCENE3D}.
+     * @param options - Object with the following properties:
+     * @param options.elementId - The element id to snap to, as a hex string, e.g. <code>"0x30000000df2"</code>.
+     * @param options.testPoint - The point to snap from, typically the picked cursor position.
+     * @param options.camera - The camera defining the current view. Must be viewing in {@link SceneMode.SCENE3D}.
+     * @param options.canvasWidth - The canvas width in CSS pixels.
+     * @param options.canvasHeight - The canvas height in CSS pixels.
+     * @param [options.closePoint = options.testPoint] - A reference point near the target geometry that seeds the snap search.
+     * @param [options.snapAperture = IonSnapService.DEFAULT_SNAP_APERTURE] - The snap tolerance in CSS pixels of the world-to-view output space.
+     * @param [options.snapMode = IonSnapMode.NEAREST] - The type of snap to perform.
+     * @returns The snap result, or <code>undefined</code> if the element was not found or no snap was possible for it.
+     */
+    snap(options: {
+        elementId: string;
+        testPoint: Cartesian3;
+        camera: Camera;
+        canvasWidth: number;
+        canvasHeight: number;
+        closePoint?: Cartesian3;
+        snapAperture?: number;
+        snapMode?: IonSnapMode;
+    }): Promise<IonSnapService.Result | undefined>;
+    /**
+     * The default snap tolerance used by {@link IonSnapService#snap} when
+     * <code>options.snapAperture</code> is not provided, in CSS pixels of the
+     * world-to-view output space. This is {@link SnapService}'s
+     * <code>DEFAULT_SNAP_APERTURE</code> for this implementation.
+     */
+    static readonly DEFAULT_SNAP_APERTURE: number;
+}
+
 /**
  * Constants related to ISO8601 support.
  */
@@ -16393,6 +16639,61 @@ export class SimplePolylineGeometry {
     static createGeometry(simplePolylineGeometry: SimplePolylineGeometry): Geometry | undefined;
 }
 
+export namespace SnapService {
+    /**
+     * The result of a successful {@link SnapService#snap}.
+     *
+     * Implementations may return additional properties beyond those listed here.
+     * @property [snapPoint] - The snapped point. This is the point to consume.
+     * @property [hitPoint] - The point where the cursor hit the geometry: the nearest edge point when within the snap aperture, otherwise the surface point under the cursor.
+     */
+    type Result = {
+        snapPoint?: Cartesian3;
+        hitPoint?: Cartesian3;
+    };
+}
+
+/**
+ * Provides snap-to-geometry through an external service, which snaps against
+ * source geometry hosted remotely rather than geometry loaded in the scene.
+ * This type describes an interface and is not intended to be used.
+ */
+export class SnapService {
+    /**
+     * Requests a snap against geometry known to the service.
+     *
+     * The camera and canvas dimensions describe the current view so the
+     * implementation can perform view-dependent snapping (nearest ordering,
+     * pixel apertures, surface tracking) correctly.
+     *
+     * Implementations may accept additional options beyond those listed here.
+     * @param options - Object with the following properties:
+     * @param options.elementId - An implementation-defined identifier of the geometry to snap to.
+     * @param options.testPoint - The point to snap from, typically the picked cursor position.
+     * @param options.camera - The camera defining the current view.
+     * @param options.canvasWidth - The canvas width in CSS pixels.
+     * @param options.canvasHeight - The canvas height in CSS pixels.
+     * @param [options.closePoint = options.testPoint] - A reference point near the target geometry that seeds the snap search.
+     * @param [options.snapAperture = SnapService.DEFAULT_SNAP_APERTURE] - The snap tolerance in CSS pixels.
+     * @returns The snap result, or <code>undefined</code> if no snap was possible.
+     */
+    snap(options: {
+        elementId: string;
+        testPoint: Cartesian3;
+        camera: Camera;
+        canvasWidth: number;
+        canvasHeight: number;
+        closePoint?: Cartesian3;
+        snapAperture?: number;
+    }): Promise<SnapService.Result | undefined>;
+    /**
+     * The default snap tolerance used by {@link SnapService#snap} when
+     * <code>options.snapAperture</code> is not provided, in CSS pixels.
+     * The value is implementation-defined.
+     */
+    static readonly DEFAULT_SNAP_APERTURE: number;
+}
+
 /**
  * A description of a sphere centered at the origin.
  * @example
@@ -27971,6 +28272,38 @@ export type BufferPolygonOptions = {
     triangles?: TypedArray;
 };
 
+/**
+ * @property [primitiveCountMax = BufferPrimitiveCollection.DEFAULT_CAPACITY] - Maximum number of polygons.
+ * @property [vertexCountMax = BufferPrimitiveCollection.DEFAULT_CAPACITY] - Maximum number of vertices.
+ * @property [holeCountMax = BufferPrimitiveCollection.DEFAULT_CAPACITY] - Maximum number of holes.
+ * @property [triangleCountMax = BufferPrimitiveCollection.DEFAULT_CAPACITY] - Maximum number of triangles.
+ * @property [positionDatatype = ComponentDatatype.DOUBLE] - The component datatype used to store position values.
+ * @property [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 [allowPicking = true] - When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+ * @property [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 [heightReference = HeightReference.NONE] - When set to a clamping value, the
+ *   collection is draped onto terrain and/or 3D Tiles, rather than drawn as geometry of its own.
+ */
+export type BufferPolygonCollectionOptions = {
+    primitiveCountMax?: number;
+    vertexCountMax?: number;
+    holeCountMax?: number;
+    triangleCountMax?: number;
+    positionDatatype?: ComponentDatatype;
+    positionNormalized?: boolean;
+    show?: boolean;
+    allowPicking?: boolean;
+    boundingVolume?: BoundingSphere;
+    debugShowBoundingVolume?: boolean;
+    blendOption?: BlendOption;
+    heightReference?: HeightReference;
+};
+
 /**
  * Collection of polygons held in ArrayBuffer storage for performance and memory optimization.
  *
@@ -28006,26 +28339,9 @@ export type BufferPolygonOptions = {
  *   collection.get(i, polygon);
  *   polygon.setMaterial(material);
  * }
- * @param [options.allowPicking = true] - When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
- * @param [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.
  */
 export class BufferPolygonCollection extends BufferPrimitiveCollection<BufferPolygon> {
-    constructor(options: {
-        primitiveCountMax?: number;
-        vertexCountMax?: number;
-        holeCountMax?: number;
-        triangleCountMax?: number;
-        positionDatatype?: ComponentDatatype;
-        positionNormalized?: boolean;
-        show?: boolean;
-        allowPicking?: boolean;
-        boundingVolume?: BoundingSphere;
-        debugShowBoundingVolume?: boolean;
-        blendOption?: BlendOption;
-    });
+    constructor(options?: BufferPolygonCollectionOptions);
     /**
      * Duplicates the contents of this collection into the result collection.
      * Result collection is not resized, and must contain enough space for all
@@ -28037,8 +28353,18 @@ export class BufferPolygonCollection extends BufferPrimitiveCollection<BufferPol
      * @example
      * const result = new BufferPolygonCollection({ ... }); // allocate larger 'result' collection
      * BufferPolygonCollection.clone(collection, result);   // copy polygons from 'collection' into 'result'
+     * @param [predicate] - When provided, only polygons for which this returns <code>true</code> are copied. Surviving polygons are compacted into contiguous indices.
      */
-    static clone(collection: BufferPolygonCollection, result: BufferPolygonCollection): BufferPolygonCollection;
+    static clone(collection: BufferPolygonCollection, result: BufferPolygonCollection, predicate?: (...params: any[]) => any): BufferPolygonCollection;
+    /**
+     * 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 polygon.
+     * @param collection - Source collection to copy.
+     * @param [options] - Constructor options to override. Omitted options are inherited from the source collection.
+     * @param [predicate] - When provided, only polygons for which this returns <code>true</code> are copied. Surviving polygons are compacted into contiguous indices.
+     */
+    static fromCollection(collection: BufferPolygonCollection, options?: BufferPolygonCollectionOptions, predicate?: (...params: any[]) => any): BufferPolygonCollection;
     /**
      * Adds a new polygon to the collection, with the specified options. A
      * {@link BufferPolygon} instance is linked to the new polygon, using
@@ -28190,8 +28516,34 @@ export type BufferPolylineOptions = {
  *   collection.get(i, polyline);
  *   polyline.setMaterial(material);
  * }
+ * @param [options.modelMatrix = Matrix4.IDENTITY] - Transforms geometry from model to world coordinates.
+ * @param [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 [options.boundingVolume] - Bounding volume, in world space, for the collection.
+ * @param [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.
  */
 export class BufferPolylineCollection extends BufferPrimitiveCollection<BufferPolyline> {
+    constructor(options?: {
+        modelMatrix?: Matrix4;
+        primitiveCountMax?: number;
+        vertexCountMax?: number;
+        show?: boolean;
+        positionDatatype?: ComponentDatatype;
+        positionNormalized?: boolean;
+        allowPicking?: boolean;
+        boundingVolume?: BoundingSphere;
+        debugShowBoundingVolume?: boolean;
+        blendOption?: BlendOption;
+        heightReference?: HeightReference;
+        widthUnits?: "pixels" | "meters";
+    });
+    /**
+     * 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.
+     */
+    readonly widthUnits: "pixels" | "meters";
     /**
      * Adds a new polyline to the collection, with the specified options. A
      * {@link BufferPolyline} instance is linked to the new polyline, using
@@ -28206,7 +28558,8 @@ export class BufferPolylineCollection extends BufferPrimitiveCollection<BufferPo
  * @property [color = Color.WHITE] - Color of fill.
  * @property [outlineColor = Color.WHITE] - Color of outline.
  * @property [outlineWidth = 0.0] - Width of outline, 0-255px.
- * @property [width = 1.0] - Width of line, 0-255px.
+ * @property [width = 1.0] - Width of line, in the unit selected by
+ *   {@link BufferPolylineCollection#widthUnits}.
  */
 export type BufferPolylineMaterialOptions = {
     color?: Color;
@@ -28225,7 +28578,7 @@ export type BufferPolylineMaterialOptions = {
 export class BufferPolylineMaterial extends BufferPrimitiveMaterial {
     constructor(options?: BufferPolylineMaterialOptions);
     /**
-     * Width of polyline, 0–255px.
+     * Width of polyline, in the unit selected by {@link BufferPolylineCollection#widthUnits}.
      */
     width: number;
     static pack(material: BufferPolylineMaterial, view: DataView, byteOffset: number): void;
@@ -28296,6 +28649,39 @@ export type BufferPrimitiveOptions = {
     pickObject?: any;
 };
 
+/**
+ * @property [modelMatrix = Matrix4.IDENTITY] - Transforms geometry from model to world coordinates.
+ * @property [primitiveCountMax = BufferPrimitiveCollection.DEFAULT_CAPACITY] - Maximum number of primitives.
+ * @property [vertexCountMax = BufferPrimitiveCollection.DEFAULT_CAPACITY] - Maximum number of vertices.
+ * @property [positionDatatype = ComponentDatatype.DOUBLE] - The component datatype used to store position values.
+ * @property [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 [allowPicking = false] - When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+ * @property [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 [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.
+ */
+export type BufferPrimitiveCollectionOptions = {
+    modelMatrix?: Matrix4;
+    primitiveCountMax?: number;
+    vertexCountMax?: number;
+    show?: boolean;
+    positionDatatype?: ComponentDatatype;
+    positionNormalized?: boolean;
+    allowPicking?: boolean;
+    boundingVolume?: BoundingSphere;
+    debugShowBoundingVolume?: boolean;
+    blendOption?: BlendOption;
+};
+
 /**
  * Collection of primitives held in ArrayBuffer storage for performance and memory optimization.
  *
@@ -28303,33 +28689,14 @@ export type BufferPrimitiveOptions = {
  * be careful to avoid allocating "N" instances of any related JavaScript object. {@link BufferPrimitive},
  * {@link Color}, {@link Cartesian3}, and other objects can all be reused when working with large collections,
  * using the {@link https://en.wikipedia.org/wiki/Flyweight_pattern|flyweight pattern}.</p>
- * @param [options.modelMatrix = Matrix4.IDENTITY] - Transforms geometry from model to world coordinates.
- * @param [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 [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 [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.
  */
 export class BufferPrimitiveCollection<T extends BufferPrimitive> {
-    constructor(options: {
-        modelMatrix?: Matrix4;
-        primitiveCountMax?: number;
-        vertexCountMax?: number;
-        show?: boolean;
-        positionDatatype?: ComponentDatatype;
-        positionNormalized?: boolean;
-        allowPicking?: boolean;
-        boundingVolume?: BoundingSphere;
-        debugShowBoundingVolume?: boolean;
-        blendOption?: BlendOption;
-    });
+    constructor(options?: BufferPrimitiveCollectionOptions);
     /**
      * Determines if primitives in this collection will be shown.
      */
     show: boolean;
+    protected readonly _heightReference: HeightReference;
     /**
      * Transforms geometry from model to world coordinates.
      */
@@ -28373,8 +28740,37 @@ export class BufferPrimitiveCollection<T extends BufferPrimitive> {
      * @example
      * const result = new BufferPrimitiveCollection({ ... }); // allocate larger 'result' collection
      * BufferPrimitiveCollection.clone(collection, result);   // copy primitives from 'collection' into 'result'
+     * @param [predicate] - When provided, only primitives for which this returns <code>true</code> are copied. Surviving primitives are compacted into contiguous indices.
+     */
+    static clone<T extends BufferPrimitive>(collection: BufferPrimitiveCollection<T>, result: BufferPrimitiveCollection<T>, predicate?: (...params: any[]) => any): void;
+    /**
+     * 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 collection - Source collection to copy.
+     * @param [options] - Constructor options to override. Omitted options are inherited from the source collection.
+     * @param [predicate] - When provided, only primitives for which this returns <code>true</code> are copied. Surviving primitives are compacted into contiguous indices.
      */
-    static clone<T extends BufferPrimitive>(collection: BufferPrimitiveCollection<T>, result: BufferPrimitiveCollection<T>): void;
+    static fromCollection<T extends BufferPrimitive>(collection: BufferPrimitiveCollection<T>, options?: BufferPrimitiveCollectionOptions, predicate?: (...params: any[]) => any): BufferPrimitiveCollection<T>;
     /**
      * Makes the given {@link BufferPrimitive} a view onto this collection's
      * primitive at the given index, for use when reading/writing primitive
@@ -28444,6 +28840,12 @@ export class BufferPrimitiveCollection<T extends BufferPrimitive> {
      * (unsigned).
      */
     readonly positionNormalized: boolean;
+    /**
+     * 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}.
+     */
+    readonly heightReference: HeightReference;
     /**
      * Returns a JSON-serializable array representing the collection. This encoding
      * is not memory-efficient, and should generally be used for debugging and
@@ -32160,26 +32562,66 @@ export class ClippingPlaneCollection {
  * const polygon = new Cesium.ClippingPolygon({
  *     positions: positions
  * });
+ * @example
+ * // A clipping polygon with two holes. Regions inside the holes are not clipped.
+ * const outerRing = Cesium.Cartesian3.fromDegreesArray([
+ *     -100.0, 40.0,
+ *     -90.0, 40.0,
+ *     -90.0, 50.0,
+ *     -100.0, 50.0,
+ * ]);
+ *
+ * const firstHole = Cesium.Cartesian3.fromDegreesArray([
+ *     -98.0, 42.0,
+ *     -96.0, 42.0,
+ *     -96.0, 44.0,
+ *     -98.0, 44.0,
+ * ]);
+ *
+ * const secondHole = Cesium.Cartesian3.fromDegreesArray([
+ *     -94.0, 46.0,
+ *     -92.0, 46.0,
+ *     -92.0, 48.0,
+ *     -94.0, 48.0,
+ * ]);
+ *
+ * const polygonWithHoles = new Cesium.ClippingPolygon({
+ *     positions: outerRing,
+ *     holes: [firstHole, secondHole],
+ * });
  * @param options - Object with the following properties:
  * @param options.positions - A list of three or more Cartesian coordinates defining the outer ring of the clipping polygon.
+ * @param [options.holes] - An array of interior rings (holes), each a list of three or more Cartesian coordinates. Regions inside a hole are excluded from the polygon.
  */
 export class ClippingPolygon {
     constructor(options: {
         positions: Cartesian3[];
+        holes?: Cartesian3[][];
         ellipsoid?: Ellipsoid;
     });
     /**
-     * Returns the total number of positions in the polygon, include any holes.
+     * Returns the total number of positions in the polygon, including any holes.
      */
     readonly length: number;
     /**
-     * Returns the outer ring of positions.
+     * Returns the outer ring of positions. A ClippingPolygon's geometry is
+     * immutable; the returned array and its coordinates are frozen.
      */
     readonly positions: Cartesian3[];
+    /**
+     * Returns the interior rings (holes) of the polygon, each a list of positions.
+     */
+    readonly holes: Cartesian3[][];
     /**
      * Returns the ellipsoid used to project the polygon onto surfaces when clipping.
      */
     readonly ellipsoid: Ellipsoid;
+    /**
+     * Returns the cartographic rectangle enclosing the polygon, computed once on
+     * construction. Since a ClippingPolygon's geometry is immutable, this rectangle
+     * never changes.
+     */
+    readonly rectangle: Rectangle;
     /**
      * Clones the ClippingPolygon without setting its ownership.
      * @param polygon - The ClippingPolygon to be cloned
@@ -32203,6 +32645,8 @@ export class ClippingPolygon {
     computeRectangle(result?: Rectangle): Rectangle;
 }
 
+export const bufferPolygonScratch: any;
+
 /**
  * Specifies a set of clipping polygons. Clipping polygons selectively disable rendering in a region
  * inside or outside the specified list of {@link ClippingPolygon} objects for a single glTF model, 3D Tileset, or the globe.
@@ -32233,7 +32677,8 @@ export class ClippingPolygon {
  * @param [options.polygons = []] - An array of {@link ClippingPolygon} objects used to selectively disable rendering on the inside of each polygon.
  * @param [options.enabled = true] - Determines whether the clipping polygons are active.
  * @param [options.inverse = false] - If true, a region will be clipped if it is outside of every polygon in the collection. Otherwise, a region will only be clipped if it is on the inside of any polygon.
- * @param [options.quality = 1.0] - A scalar that controls the resolution of the signed distance texture used for clipping. Values greater than 1.0 increase quality, values less than 1.0 decrease it. Must be greater than 0.0.
+ * @param [options.quality = 1.0] - A scalar that controls the resolution of the signed distance texture used for clipping. Values greater than 1.0 increase quality, values less than 1.0 decrease it. Must be greater than 0.0. <p>Deprecated in CesiumJS 1.145 and will be removed in 1.147. Signed distance field clipping was replaced with vector clipping, so this option no longer has any effect.</p>
+ * @param [options.ellipsoid = Ellipsoid.default] - The ellipsoid to use to project the clipping polygons onto the globe.
  */
 export class ClippingPolygonCollection {
     constructor(options?: {
@@ -32241,6 +32686,7 @@ export class ClippingPolygonCollection {
         enabled?: boolean;
         inverse?: boolean;
         quality?: number;
+        ellipsoid?: Ellipsoid;
     });
     /**
      * If true, clipping will be enabled.
@@ -32252,11 +32698,6 @@ export class ClippingPolygonCollection {
      * inside of any polygon.
      */
     inverse: boolean;
-    /**
-     * A scalar that controls the resolution of the signed distance texture used for clipping.
-     * Values greater than 1.0 increase quality, values less than 1.0 decrease it. Must be greater than 0.0.
-     */
-    quality: number;
     /**
      * An event triggered when a new clipping polygon is added to the collection.  Event handlers
      * are passed the new polygon and the index at which it was added.
@@ -32267,12 +32708,24 @@ export class ClippingPolygonCollection {
      * are passed the new polygon and the index from which it was removed.
      */
     polygonRemoved: Event;
+    /**
+     * The ellipsoid to use to project the clipping polygons onto the globe.
+     */
+    ellipsoid: Ellipsoid;
     /**
      * Returns the number of polygons in this collection.  This is commonly used with
      * {@link ClippingPolygonCollection#get} to iterate over all the polygons
      * in the collection.
      */
     readonly length: number;
+    /**
+     * If true, a debug texture visualizing the signed distance field is shown.
+     */
+    debugShowDistanceTexture: boolean;
+    /**
+     * A scalar that controlled the resolution of the signed distance texture used for clipping.
+     */
+    quality: number;
     /**
      * Adds the specified {@link ClippingPolygon} to the collection to be used to selectively disable rendering
      * on the inside of each polygon. Use {@link ClippingPolygonCollection#unionClippingRegions} to modify
@@ -34617,6 +35070,11 @@ export class GaussianSplat3DTileContent implements Cesium3DTileContent {
     getFeature(batchId: number): Cesium3DTileFeature;
 }
 
+/**
+ * @property [heightReference = HeightReference.NONE] - Allows clamping (draping)
+ *  polylines and polygons on terrain and 3D Tiles. Point clamping is not currently supported.
+ * @property [scene] - Required for primitives that use a clamping {@link HeightReference}.
+ */
 export type GeoJsonPrimitiveConstructorOptions = {
     geoJson?: any;
     url?: Resource | string;
@@ -34624,6 +35082,8 @@ export type GeoJsonPrimitiveConstructorOptions = {
     allowPicking?: boolean;
     show?: boolean;
     pickObjectFactory?: (...params: any[]) => any;
+    heightReference?: HeightReference;
+    scene?: Scene;
 };
 
 /**
@@ -34635,14 +35095,33 @@ export type GeoJsonPrimitiveConstructorOptions = {
  * Instead, it exposes high-throughput buffer primitive collections that can be
  * added directly to {@link Scene#primitives}.
  * @example
+ * // Load GeoJSON
  * const loader = await Cesium.GeoJsonPrimitive.fromUrl("./data.geojson");
  * viewer.scene.primitives.add(loader);
- *
+ * @example
+ * // Access GeoJSON features and properties
  * loader.points;     // BufferPointCollection | undefined
  * loader.polylines;  // BufferPolylineCollection | undefined
  * loader.polygons;   // BufferPolygonCollection | undefined
  * loader.ids;        // source feature IDs
  * loader.properties; // source feature properties
+ * @example
+ * // Style GeoJSON
+ * const material = new Cesium.BufferPolylineMaterial({
+ *   color: Cesium.Color.RED,
+ *   width: 4,
+ * });
+ *
+ * const polyline = new Cesium.BufferPolyline();
+ * const count = primitive.polylines.primitiveCount;
+ * for (let i = 0; i < count; i++) {
+ *   primitive.polylines.get(i, polyline);
+ *
+ *   const properties = primitive.getProperties(polyline.featureId);
+ *   if (properties.myCustomProperty === true) {
+ *     polyline.setMaterial(material);
+ *   }
+ * }
  */
 export class GeoJsonPrimitive {
     constructor(options?: GeoJsonPrimitiveConstructorOptions);
@@ -36302,7 +36781,7 @@ export enum HeightReference {
      */
     RELATIVE_TO_GROUND = 2,
     /**
-     * The position is clamped to terain.
+     * The position is clamped to terrain.
      */
     CLAMP_TO_TERRAIN = 3,
     /**
@@ -38406,12 +38885,20 @@ export class MVTDataProvider extends UrlTemplate3DTilesDataProvider {
      * @param [options.maxZoom = 14] - Maximum zoom level represented in the generated tileset.
      * @param [options.extent] - Optional geographic extent in radians to constrain the generated tile tree.
      * @param [options.featureIdProperty] - MVT property name to use as feature ID.
+     * @param [options.heightReference] - Drapes the decoded points, lines and polygons 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 models, and
+     *   {@link HeightReference.CLAMP_TO_GROUND} drapes onto both. Requires <code>options.scene</code>.
+     * @param [options.scene] - The scene the generated tileset is rendered in, required when
+     *   <code>options.heightReference</code> is a clamping value.
      */
     static fromUrl(url: Resource | string, options?: {
         minZoom?: number;
         maxZoom?: number;
         extent?: Rectangle;
         featureIdProperty?: string;
+        heightReference?: HeightReference;
+        scene?: Scene;
     }): Promise<MVTDataProvider>;
 }
 
@@ -44722,12 +45209,14 @@ export class Scene {
  * The result of a snap operation. See {@link Scene#snap}.
  * @property object - The snapped primitive or feature.
  * @property position - The world-space position of the snap point, un-projected from the snap framebuffer's eye-space depth.
+ * @property surfacePosition - The world-space position of the same object's surface fragment nearest the snap point. For a surface snap this equals <code>position</code>; for an edge snap it is a point on a face of the object rather than on its silhouette, or <code>undefined</code> if no surface fragment of the object is visible in the search region.
  * @property screenPosition - The window coordinates of the snap point.
  * @property isEdge - <code>true</code> if the snap point lies on an edge; <code>false</code> if it lies on a surface.
  */
 export type SceneSnapResult = {
     object: any;
     position: Cartesian3;
+    surfacePosition: Cartesian3 | undefined;
     screenPosition: Cartesian2;
     isEdge: boolean;
 };
@@ -46137,6 +46626,10 @@ export enum Tonemapper {
  * @param [options.maxZoom = 14] - Maximum zoom level represented in the generated tileset.
  * @param [options.extent] - Optional geographic extent in radians to constrain the generated tile tree.
  * @param [options.featureIdProperty] - Feature property name to use as feature ID when supported by content decoding.
+ * @param [options.heightReference] - Drapes the vector content onto the surfaces selected by the
+ *   value. Requires <code>options.scene</code>.
+ * @param [options.scene] - The scene the generated tileset is rendered in, required when
+ *   <code>options.heightReference</code> is a clamping value.
  */
 export class UrlTemplate3DTilesDataProvider {
     constructor(urlTemplate: Resource | string, options?: {
@@ -46144,6 +46637,8 @@ export class UrlTemplate3DTilesDataProvider {
         maxZoom?: number;
         extent?: Rectangle;
         featureIdProperty?: string;
+        heightReference?: HeightReference;
+        scene?: Scene;
     });
     /**
      * Creates a provider from a URL template.
@@ -47030,7 +47525,10 @@ export namespace WebMapServiceImageryProvider {
      * @property [getFeatureInfoParameters = WebMapServiceImageryProvider.GetFeatureInfoDefaultParameters] - Additional parameters to pass to the WMS server in the GetFeatureInfo URL.
      * @property [getFeatureInfoUrl] - The getFeatureInfo URL of the WMS service. If the property is not defined then we use the property value of url.
      * @property [getFeatureInfoFormats = WebMapServiceImageryProvider.DefaultGetFeatureInfoFormats] - The formats
-     *        in which to try WMS GetFeatureInfo requests.
+     *        in which to try WMS GetFeatureInfo requests. Since feature info responses vary across WMS services,
+     *        you may need to supply a custom format and parsing callback; see the
+     *        {@link https://sandcastle.cesium.com/?id=web-map-tile-service-picking|Sandcastle example} for a complete
+     *        example of writing your own callback.
      * @property [rectangle = Rectangle.MAX_VALUE] - The rectangle of the layer.
      * @property [tilingScheme = new GeographicTilingScheme()] - The tiling scheme to use to divide the world into tiles.
      * @property [ellipsoid] - The ellipsoid.  If the tilingScheme is specified,
@@ -47241,7 +47739,10 @@ export namespace WebMapTileServiceImageryProvider {
      * @property [getFeatureInfoParameters] - Additional parameters to include in GetFeatureInfo requests. Keys are lowercased internally.
      * @property [getFeatureInfoUrl] - The GetFeatureInfo URL of the WMTS service. If not specified, the value of <code>url</code> is used.
      * @property [getFeatureInfoFormats = WebMapTileServiceImageryProvider.DefaultGetFeatureInfoFormats] - The formats
-     *                          in which to try WMTS GetFeatureInfo requests.
+     *                          in which to try WMTS GetFeatureInfo requests. Since feature info responses vary across WMTS services,
+     *                          you may need to supply a custom format and parsing callback; see the
+     *                          {@link https://sandcastle.cesium.com/?id=web-map-tile-service-picking|Sandcastle example} for a complete
+     *                          example of writing your own callback.
      * @property [rectangle = Rectangle.MAX_VALUE] - The rectangle covered by the layer.
      * @property [tilingScheme] - The tiling scheme corresponding to the organization of the tiles in the TileMatrixSet.
      * @property [ellipsoid] - The ellipsoid.  If not specified, the WGS84 ellipsoid is used.