Underlay

Inspect and edit the placed reference planes imported into the scene (core.io.import.image / pdf / dwg / cadJson) — image, PDF, and CAD sketches you trace over. Each underlay is an UnderlayHandle. Accessed via snaptrude.core.io.underlay.

Set-scale takes either a numeric factor or a { planSize } — the real-world length of the plan's longest side. A numeric factor is absolute: the total scale relative to the underlay's import-time size, the same number getScale returns as scaleFactor — so setScale(u, 2) is idempotent and setScale(u, (await getScale(u)).scaleFactor) is a no-op. planSize is the way to calibrate programmatically ("this plan is 50 m across") without clicking points on the canvas. Scale is supported for image and PDF underlays; CAD scaling is not supported (getScale → null, setScale/resetScale throw).

Image scale is committed directly and is not undoable; PDF scale is baked into the mesh (X/Z) and is undoable. For PDF the import-time baseline is 1.

Functions

list(storey?)

List the underlays in the scene, optionally limited to one storey.

• Parameters:
  • storey: number (optional) — Only underlays on this storey
• Returns: UnderlayHandle[] — empty, never null

const underlays = await snaptrude.core.io.underlay.list(1);
console.log(`${underlays.length} underlays on storey 1`);

---

getBounds(underlay)

Read an underlay's world-space bounding box (image, PDF, or CAD) — { min: {x,y,z}, max: {x,y,z} }, or null if it no longer resolves. Useful for fitting drawn geometry to a reference or computing a plan size.

const bb = await snaptrude.core.io.underlay.getBounds(plan);
if (bb) console.log(`width ${bb.max.x - bb.min.x}`);

---

getScale(underlay)

Read an underlay's scale — image or PDF. null for CAD (scaling not supported) or if the handle no longer resolves.

• scaleFactor — the cumulative user scale relative to the import-time size (1 = as imported); the same number setScale accepts.

• initialScaleFactor — the engine's import-time fit factor (informational; 1 for PDF).

• Parameters:

  • underlay: UnderlayHandle — The underlay to read

• Returns: { scaleFactor: number; initialScaleFactor: number } | null

const s = await snaptrude.core.io.underlay.getScale(plan);
if (s) console.log(`scale ${s.scaleFactor} (was ${s.initialScaleFactor})`);

---

setScale(underlay, scale)

Set an underlay's scale — the calibration step after import. Works for image and PDF (CAD not supported — throws). Image scale is not undoable; PDF scale is undoable.

• Parameters:
  • underlay: UnderlayHandle — The underlay to scale (image or PDF)
  • scale: number | { planSize: number } — An absolute scale factor relative to the import-time size (the same number getScale returns; repeating the call is idempotent), or { planSize } = the real-world length of the plan's longest side in project units
• Returns: { scaleFactor: number } — the new absolute factor

// Absolute factor — set the underlay to 2× its imported size:
await snaptrude.core.io.underlay.setScale(plan, 2);

// Fit to real size — make the plan's longest side 50 project-units:
await snaptrude.core.io.underlay.setScale(plan, { planSize: 50 });

---

resetScale(underlay)

Reset an underlay's scale back to its import-time size — image or PDF (CAD not supported — throws). Equivalent to setScale(underlay, 1).

• Parameters:
  • underlay: UnderlayHandle — The underlay to reset (image or PDF)
• Returns: { scaleFactor: number } — 1

await snaptrude.core.io.underlay.resetScale(plan);

---

getOpacity(underlay)

Read an underlay's opacity (0..1), or null if it has no material.

• Parameters:
  • underlay: UnderlayHandle — The underlay to read
• Returns: number | null

---

setOpacity(underlay, opacity)

Set an underlay's opacity (0 = transparent .. 1 = opaque). Undoable. The engine keeps underlays faintly visible: values below 0.01 clamp to 0.01, so setOpacity(u, 0) reads back 0.01.

• Parameters:
  • underlay: UnderlayHandle — The underlay to change
  • opacity: number — Target opacity, 0..1
• Returns: void
• Throws: if writes are disabled, the underlay can't be resolved, or the underlay is locked (unlock it in the app first).

await snaptrude.core.io.underlay.setOpacity(plan, 0.3);

---

delete(underlay)

Delete an underlay from the scene (image, PDF, or CAD).

• Parameters:
  • underlay: UnderlayHandle — The underlay to delete
• Returns: void

const [first] = await snaptrude.core.io.underlay.list(1);
if (first) await snaptrude.core.io.underlay.delete(first);

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
PRECONDITION_FAILED	setScale, resetScale	The underlay is a CAD sketch — CAD scaling is not supported	handles, kind: "cad"
PRECONDITION_FAILED	setOpacity	The underlay is locked in the app	handles
OPERATION_FAILED	setScale, resetScale	The engine scale command failed	engineCode where available
HANDLE_INVALID	mutators (setScale, resetScale, setOpacity, delete)	The underlay handle no longer resolves	—

Reads are lenient — getBounds, getScale, and getOpacity return null when the handle no longer resolves, and list returns []; only the mutators reject. The "writes are disabled" rejections carry METHOD_NOT_PERMITTED.