Terrain

Inspect and manage the project's site terrain — the singleton created by core.io.import.terrain. At most one terrain exists per project. All edits are undoable. Accessed via snaptrude.core.io.terrain.

Datum = the terrain's vertical position. setDatum(offset) shifts the terrain vertically by a relative offset (cumulative — each call moves it further, not to a fixed level); getDatum() reads the terrain's current vertical position (world Y, internal units — import places the highest point at y = 0, so a never-shifted terrain reads a negative baseline, not 0).

Types

TerrainReport

Cut/fill earthwork report: { cutVolume: number; fillVolume: number; netVolume: number }.

Functions

exists()

Whether the project has a site terrain. → boolean.

get()

Resolve the project's TerrainHandle, or null. Same handle import.terrain returns.

getDatum()

The terrain's current vertical position (world Y, internal units), or null if no terrain. A never-shifted terrain reads its import baseline (negative), not 0.

setDatum(offset)

Shift the whole terrain vertically down by offset (internal units) from its current position; pass a negative value to raise it. Relative and cumulative — setDatum(5) twice shifts down by 10 total, not to a fixed level. Undoable. Throws if writes are disabled, there is no terrain, or the terrain is locked.

await snaptrude.core.io.terrain.setDatum(12); // shift terrain down by 12 (relative)

delete()

Delete the site terrain. Undoable. Throws if none.

getReport()

The cut/fill TerrainReport, or null.

const r = await snaptrude.core.io.terrain.getReport();
if (r) console.log(`cut ${r.cutVolume}, fill ${r.fillVolume}, net ${r.netVolume}`);

isElevationEnabled() / enableElevation() / disableElevation()

Read/toggle terrain elevation (DEM height — a real 3D topography vs a flat plane). Toggles are undoable. Read → boolean | null.

isSatelliteEnabled() / enableSatellite() / disableSatellite()

Read/toggle draped satellite imagery. Toggles are undoable. Read → boolean | null.

getOpacity() / setOpacity(opacity)

Read/set terrain opacity 0..1. setOpacity is undoable; throws if no terrain or the terrain is locked.

await snaptrude.core.io.terrain.setOpacity(0.5);

Errors

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

Code	Thrown by	When	details
PRECONDITION_FAILED	setDatum, delete, enableElevation, disableElevation, enableSatellite, disableSatellite, setOpacity	The project has no site terrain	—

Reads never throw for a missing terrain — get, getDatum, getReport, isElevationEnabled, isSatelliteEnabled, and getOpacity return null instead; check exists() (or import one with core.io.import.terrain) before mutating. The "writes are disabled" rejections carry METHOD_NOT_PERMITTED.