IonSnapService

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 IonSnapService.fromAssetId.

new Cesium.IonSnapService(options)
engine/Source/Core/IonSnapService.js 136

Name Type Description
options object Object with the following properties:
Name Type Description
assetId number The ion asset id.
resource Resource The asset's ion API resource.
ecefTransform Matrix4 A 4x4 transformation matrix from the source BIM/CAD Database reference frame local to the world's fixed reference frame.
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);
}
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

See:

Members

static constant Cesium.IonSnapService.DEFAULT_SNAP_APERTURE : number
engine/Source/Core/IonSnapService.js 367

The default snap tolerance used by IonSnapService#snap when options.snapAperture is not provided, in CSS pixels of the world-to-view output space. This is SnapService's DEFAULT_SNAP_APERTURE for this implementation.
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

readonly assetId : number
engine/Source/Core/IonSnapService.js 160

The ion asset id this snapper operates on.

readonly ecefTransform : Matrix4
engine/Source/Core/IonSnapService.js 152

A 4x4 transformation matrix from the source BIM/CAD Database reference frame local to the world's fixed reference frame.

Methods

async static Cesium.IonSnapService.fromAssetId(assetId, options) → Promise.<IonSnapService>
engine/Source/Core/IonSnapService.js 178

Creates an IonSnapService for the given ion asset, fetching the asset's ECEF transform from the ion REST API.
Name Type Description
assetId number The ion ID of a 3D Tiles asset backed by a BIM/CAD Database model.
options object optional Object with the following properties:
Name Type Default Description
accessToken string Ion.defaultAccessToken optional The ion access token to use.
server string | Resource Ion.defaultServer optional The ion API server to use.
Returns:
A snapper bound to the asset.
Throws:
  • RuntimeError : The asset is not geolocated, so view-correct snapping is not possible.
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

async snap(options) → Promise.<(IonSnapService.Result|undefined)>
engine/Source/Core/IonSnapService.js 281

Requests a snap against an element of this asset. A view-correct world-to-view matrix is composed from options.camera, options.canvasWidth, and options.canvasHeight 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 SceneMode.SCENE3D.
Name Type Description
options object Object with the following properties:
Name Type Default Description
elementId string The element id to snap to, as a hex string, e.g. "0x30000000df2".
testPoint Cartesian3 The point to snap from, typically the picked cursor position.
camera Camera The camera defining the current view. Must be viewing in SceneMode.SCENE3D.
canvasWidth number The canvas width in CSS pixels.
canvasHeight number The canvas height in CSS pixels.
closePoint Cartesian3 options.testPoint optional A reference point near the target geometry that seeds the snap search.
snapAperture number IonSnapService.DEFAULT_SNAP_APERTURE optional The snap tolerance in CSS pixels of the world-to-view output space.
snapMode IonSnapMode IonSnapMode.NEAREST optional The type of snap to perform.
Returns:
The snap result, or undefined if the element was not found or no snap was possible for it.
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

Type Definitions

Cesium.IonSnapService.Result
engine/Source/Core/IonSnapService.js 89

The result of a successful IonSnapService#snap. Extends SnapService.Result with ion-specific fields.
Properties:
Name Type Attributes Description
snapPoint Cartesian3 <optional>
 The snapped point. This is the point to consume.
hitPoint Cartesian3 <optional>
 The point where the cursor hit the geometry: the nearest edge point when within the snap aperture, otherwise the surface point under the cursor.
heat IonSnapHeat <optional>
 How close the snap point is to the close point in view space.
geometryType IonSnapGeometryType <optional>
 The type of geometry snapped to.
parentGeometryType IonSnapParentGeometryType <optional>
 The type of the parent geometry snapped to.
normal object <optional>
 The surface normal at the snap point, in the model's local cartesian frame.
curve object <optional>
 The curve geometry near the snap point, with points as WGS84 degrees objects.
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.
CtrlK
packages/engine
packages/widgets