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.

CAD geometry types

CAD geometry reads return plain records in Snaptrude world space and Snaptrude internal units.

type CadLineGeometry = {
  type: "line";
  start: { x: number; y: number; z: number };
  end: { x: number; y: number; z: number };
};

type CadArcGeometry = {
  type: "arc";
  centre: { x: number; y: number; z: number };
  axis: { x: number; y: number; z: number };
  start: { x: number; y: number; z: number };
  end: { x: number; y: number; z: number };
};

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}`);

---

listCadLayers(underlay)

List the distinct original AutoCAD layer names retained by a placed CAD underlay, in first-appearance order. Returns [] for non-CAD underlays, missing underlays, drawings without layer tags, and legacy imports created before source-layer retention.

• Parameters:
  • underlay: UnderlayHandle — The placed CAD underlay to inspect
• Returns: string[]

const layers = await snaptrude.core.io.underlay.listCadLayers(cad);

---

getCadLayerGeometry(underlay, layer, options?)

Read one original AutoCAD layer's retained lines and arcs. Coordinates include the underlay's current position, rotation, scale, and storey elevation, and are returned in Snaptrude world space and Snaptrude internal units.

• Parameters:
  • underlay: UnderlayHandle — The placed CAD underlay to inspect
  • layer: string — Exact, case-sensitive original AutoCAD layer name
  • options.offset: number (optional, default 0) — Zero-based curve offset
  • options.limit: number (optional, default 500, maximum 1000) — Page size
• Returns: { layer, coordinateSpace: "snaptrude-world", units: "snaptrude-internal", total, offset, curves } | null
• Throws: if the handle resolves to an image or PDF rather than a CAD underlay

An unknown layer returns a page with total: 0. null means the underlay no longer resolves.

const page = await snaptrude.core.io.underlay.getCadLayerGeometry(cad, "A-WALL", {
  offset: 0,
  limit: 500
});
if (page) console.log(`${page.curves.length} of ${page.total} curves`);

---

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	getCadLayerGeometry	The underlay is an image or PDF rather than CAD	handles, kind
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, getOpacity, and getCadLayerGeometry return null when the handle no longer resolves; list and listCadLayers return []. getCadLayerGeometry rejects a live non-CAD underlay. The "writes are disabled" rejections carry METHOD_NOT_PERMITTED.