Merge remote-tracking branch 'origin/main' into DanielZ/feat/vector-3dtiles-polygon

Author: danielzhong

CHANGES.md

@@ -15,6 +15,7 @@
 - Fixed the "Data attribution" credit link and the credit lightbox not being usable with a keyboard. Both the link and the lightbox close button are now focusable and can be activated with `Enter` or `Space`, the lightbox is exposed as a modal dialog and can be dismissed with `Escape`, and focus is moved into the lightbox when it opens and restored when it closes. [#13670](https://github.com/CesiumGS/cesium/issues/13670)
 - Fixed feature ID textures ignoring the wrap mode declared by the glTF sampler. Forcing nearest filtering no longer replaces `wrapS` and `wrapT` with `CLAMP_TO_EDGE`. [#11574](https://github.com/CesiumGS/cesium/issues/11574)
 - Fixed vertical exaggeration for models and tilesets with existing scale factors, so they now exaggerate proportionally to the rest of the scene. [#13518](https://github.com/CesiumGS/cesium/pull/13518)
+- Added experimental `IonSnapService` for server-side snap-to-geometry against iModel-backed Cesium ion assets, and the `SnapService` interface it implements. [#13682](https://github.com/CesiumGS/cesium/pull/13682)
 
 ## 1.144 - 2026-08-01
 

packages/engine/Source/Core/IonResource.js

@@ -270,6 +270,11 @@ function addClientHeaders(headers = {}) {
   return headers;
 }
 
+/**
+ * @private
+ **/
+IonResource._addClientHeaders = addClientHeaders;
+
 function retryCallback(that, error) {
   const ionRoot = that._ionRoot ?? that;
   const endpointResource = ionRoot._ionEndpointResource;

packages/engine/Source/Core/IonSnapGeometryType.js

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @enum {number}
+ */
+const IonSnapGeometryType = {
+  /**
+   * No geometry type.
+   * @type {number}
+   * @constant
+   */
+  NONE: 0,
+  /**
+   * A point.
+   * @type {number}
+   * @constant
+   */
+  POINT: 1,
+  /**
+   * A line segment.
+   * @type {number}
+   * @constant
+   */
+  SEGMENT: 2,
+  /**
+   * A curve.
+   * @type {number}
+   * @constant
+   */
+  CURVE: 3,
+  /**
+   * An arc.
+   * @type {number}
+   * @constant
+   */
+  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>
+   * @type {number}
+   * @constant
+   */
+  SURFACE: 5,
+};
+
+Object.freeze(IonSnapGeometryType);
+
+export default IonSnapGeometryType;

packages/engine/Source/Core/IonSnapHeat.js

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @enum {number}
+ */
+const IonSnapHeat = {
+  /**
+   * The snap is not close to the cursor.
+   * @type {number}
+   * @constant
+   */
+  NONE: 0,
+  /**
+   * The snap is of interest, but outside the snap aperture.
+   * @type {number}
+   * @constant
+   */
+  NOT_IN_RANGE: 1,
+  /**
+   * The snap point is within the snap aperture of the close point in view space.
+   * @type {number}
+   * @constant
+   */
+  IN_RANGE: 2,
+};
+
+Object.freeze(IonSnapHeat);
+
+export default IonSnapHeat;

packages/engine/Source/Core/IonSnapMode.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @enum {number}
+ */
+const 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.
+   * @type {number}
+   * @constant
+   */
+  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>
+   * @type {number}
+   * @constant
+   */
+  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.
+   * @type {number}
+   * @constant
+   */
+  CENTER: 8,
+};
+
+Object.freeze(IonSnapMode);
+
+export default IonSnapMode;

packages/engine/Source/Core/IonSnapParentGeometryType.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @enum {number}
+ */
+const IonSnapParentGeometryType = {
+  /**
+   * No parent geometry type.
+   * @type {number}
+   * @constant
+   */
+  NONE: 0,
+  /**
+   * A wire body.
+   * @type {number}
+   * @constant
+   */
+  WIRE: 1,
+  /**
+   * A sheet body.
+   * @type {number}
+   * @constant
+   */
+  SHEET: 2,
+  /**
+   * A solid body.
+   * @type {number}
+   * @constant
+   */
+  SOLID: 3,
+  /**
+   * A mesh.
+   * @type {number}
+   * @constant
+   */
+  MESH: 4,
+  /**
+   * Text.
+   * @type {number}
+   * @constant
+   */
+  TEXT: 5,
+};
+
+Object.freeze(IonSnapParentGeometryType);
+
+export default IonSnapParentGeometryType;