Analysis

Sustainability-analysis APIs — the environmental-performance layer: sun and daylight studies computed for the project's geo-located site. Accessed via snaptrude.analysis.

The synchronous visual overlays (sun-path diagram, real-time shadows) toggle instantly; the heatmap studies (direct sunlight hours, daylight illuminance) are asynchronous backend jobs — start them with compute, poll their state with get, and cancel or reset them. Site inputs are read via program.site: getLocation() for the geo-coordinates and getNorthAngle() for true north.

Site required — no fallback location

Every method that positions the sun or starts a study throws "Site is needed" when the project has no geo-located site/terrain. There is deliberately no fallback location — import a terrain/site context first, then verify with program.site.getLocation().

Sub-namespaces

Namespace	What it covers
analysis.sunpath	The sun-path diagram overlay — enable/disable (undoable) and query
analysis.shadows	Real-time sun shadows — toggle and scrub the sun's date-time (ISO strings)
analysis.sunlightHours	Direct-sunlight-hours heatmap job — compute / poll / cancel / reset
analysis.illuminance	Daylight-illuminance (lux) heatmap job — same shape, Pro-gated
analysis.heatmaps	Plugin-supplied scalar heatmaps — renderSpaces / renderGrid / reset / isActive

Job polling pattern

The heatmap jobs run for minutes on the backend while every RPC call is capped at 30 s, so compute returns immediately and there is no completion event — polling is the pattern:

const { success } = await snaptrude.analysis.sunlightHours.compute("2026-06-01", "2026-06-30");

let job = await snaptrude.analysis.sunlightHours.get();
while (job?.status === "running") {
  await new Promise((r) => setTimeout(r, 5000));
  job = await snaptrude.analysis.sunlightHours.get();
}
// job?.status === "active" → the heatmap is rendered on the scene

State coherence

API writes go through the same command/helper paths as the UI, so the editor and plugins never desync:

• The sun-path toggle is undoable (core.history.undo reverts it).
• Shadows and the heatmap analyses are mutually exclusive (enabling one resets the other), exactly as in the sustainability sidebar.
• Heatmaps are invalidated by scene-mutating edits — re-run the study after changing the model.