Snap

A custom inference point that tools can snap to.

Snaps are like placing a magnet at a specific location and orientation in the model. Extensions use them to guide user interactions — for example, marking the center of a shape so that other tools can infer that point while drawing.

Example

// Create a circle with a snap at its center
let model = await SketchUpApi.getActiveModel();
let { Transformation } = SketchUpApi;

await model.performOperation(async op => {
  const groupRef = op.createGroup(model);
  op.groupSetName(groupRef, 'Snappable Circle');

  // Draw a 20" radius circle inside the group
  op.createCircle(
    groupRef,
    [0, 0, 0], // center (group-local)
    [0, 0, 1], // normal (up)
    20         // radius
  );

  // Add a snap at the group's origin so tools
  // can infer the circle's center
  const snapRef = op.createSnap(
    groupRef,
    [0, 0, 0], // position (group-local)
    [0, 0, 1]  // direction (up)
  );

  // Move the group to [30, 30, 0]
  op.drawingElementsApplyTransformation(
    groupRef, Transformation.translation([30, 30, 0])
  );

  const snap = await op.entityForRef(snapRef);
  console.log(snap.position.x, snap.position.y);
  // => 0 0 (group-local coordinates)
}, 'Create a circle with a snap at its center');

See

Since

SDK 2.20.0 Protocol 1.17.0

Extends

BaseDrawingElement

Properties

attributes

readonly attributes: Attributes

The attribute dictionaries attached to this element. Attributes store custom key-value metadata that extensions can read and write.

Inherited from

BaseDrawingElement.attributes

castsShadows

readonly castsShadows: boolean

Whether this element casts shadows onto other geometry.

Inherited from

BaseDrawingElement.castsShadows

direction

readonly direction: Vector3d

The direction this snap points, used to infer orientation.

hidden

readonly hidden: boolean

Whether this element is hidden. Hidden elements don’t appear in the viewport unless the user enables “View > Hidden Geometry.”

Inherited from

BaseDrawingElement.hidden

id

readonly id: number

The persistent ID that uniquely identifies this snap.

materialRef

readonly materialRef: MaterialRef | undefined

A reference to the material applied to this element, if any. Call getMaterial() to fetch the full Material object with color and texture data.

Inherited from

BaseDrawingElement.materialRef

position

readonly position: Point3d

The 3D coordinates of this snap in model space.

receivesShadows

readonly receivesShadows: boolean

Whether this element receives shadows cast by other geometry.

Inherited from

BaseDrawingElement.receivesShadows

tagRef

readonly tagRef: TagRef | undefined

A reference to the tag (formerly “layer”) assigned to this element. Call getTag() to fetch the full Tag object.

Inherited from

BaseDrawingElement.tagRef

type

readonly type: Snap = EntityType.Snap

up

readonly up: Vector3d | undefined

The up vector for this snap, if one was specified.

Accessors

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this snap. Pass it to API methods that accept a sketchupId.

Returns

SketchupId

Overrides

BaseDrawingElement.sketchupId

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

getBounds()

getBounds(): Promise<BoundingBox>

Fetches the axis-aligned bounding box for this element from SketchUp.

Returns

Promise<BoundingBox>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let box = await element.getBounds();
console.log(box.min.x, box.min.y, box.min.z);
console.log(box.max.x, box.max.y, box.max.z);

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getBounds

getMaterial()

getMaterial(): Promise<Material | undefined>

Fetches the material applied to this element. Returns undefined if the element uses the default material.

Returns

Promise<Material | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let mat = await element.getMaterial();
if (mat) {
  console.log(mat.name, mat.color.toHex());
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getMaterial

getTag()

getTag(): Promise<Tag | undefined>

Fetches the tag assigned to this element. Most elements have a tag — even those on the default “Untagged” tag. Returns undefined only if the tag reference is missing.

Returns

Promise<Tag | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let tag = await element.getTag();
if (tag) {
  console.log(tag.name);
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getTag

refresh()

refresh(): Promise<Snap>

Re-fetches this snap from SketchUp to get its current state. Because Snap is a snapshot, it can become stale if the model changes. Call refresh() to get an up-to-date copy.

Returns

Promise<Snap>

A new Snap reflecting the current model state. Throws if the snap has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let snaps = await model.entities.get({
  filterBy: { types: ['Snap'] },
});
// Later, after the user makes changes...
let fresh = await snaps[0].refresh();
console.log(fresh.position.x, fresh.position.y);

toString()

toString(): string

Returns a string representation of an object.

Returns

string

Show Deprecated

Deprecated

materialId

readonly materialId: number | undefined

Inherited from

BaseDrawingElement.materialId

tagId

readonly tagId: number | undefined

Inherited from

BaseDrawingElement.tagId

bounds

Get Signature

get bounds(): Promise<BoundingBox>

Returns

Promise<BoundingBox>

Inherited from

BaseDrawingElement.bounds