Snap

A Snap is a named point of interest in a SketchUp model that defines a position and orientation (direction + up vector). Snaps can be placed on the model, inside groups, or inside component definitions.

Requires SDK 2.20.0 / Protocol 1.17.0 or later.

Creating a Snap

The minimal form requires a position and a direction vector. SketchUp derives the up vector automatically.

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async (operation) => {
  const snapRef = operation.createSnap(
    operation.model,
    [0, 0, 0], // position
    [0, 0, 1], // direction (pointing up along Z)
  );
  const snap = await operation.entityForRef(snapRef);
  console.log(
    JSON.stringify(
      {
        position: snap.position, // Point3d(0, 0, 0)
        direction: snap.direction, // Vector3d(0, 0, 1)
        up: snap.up, // Vector3d(0, 1, 0) — auto-derived
      },
      undefined,
      2,
    ),
  );
}, "Create snap");

Creating a Snap with an explicit up vector

Provide a third vector to control the orientation of the snap fully. The up vector must not be parallel to the direction vector.

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async (operation) => {
  const snapRef = operation.createSnap(
    operation.model,
    [10, 0, 0], // position
    [1, 0, 0], // direction (along X)
    [0, 1, 0], // up (along Y)
  );
  const snap = await operation.entityForRef(snapRef);
  console.log("up:", snap.up); // Vector3d(0, 1, 0)
}, "Create snap with up vector");

Moving a Snap (snapSetPose)

Use snapSetPose to reposition or reorient a snap after it has been created.

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async (operation) => {
  const snapRef = operation.createSnap(
    operation.model,
    [0, 0, 0],
    [1, 0, 0],
    [0, 1, 0],
  );

  // Move to a new position, keeping direction and up unchanged
  operation.snapSetPose(snapRef, [5, 10, 15]);

  // Move and change direction (up is auto-derived)
  operation.snapSetPose(snapRef, [5, 10, 15], [0, 1, 0]);

  // Move, change direction, and set a new up vector
  operation.snapSetPose(snapRef, [5, 10, 15], [0, 1, 0], [0, 0, 1]);
}, "Move snap");