Illuminance

The daylight illuminance (lux) heatmap study. Accessed via snaptrude.analysis.illuminance.

Computes interior daylight illuminance over a date range and renders the result as a heatmap on the scene. Same async-job shape as analysis.sunlightHours — compute / get / cancel / reset, with the same PluginAnalysisComputeResult and PluginAnalysisJobState types and the same polling pattern.

Pro-gated

Illuminance is a Pro feature: compute throws when the workspace is not on a Pro plan (the router has no entitlement check — the host enforces it).

Illuminance analyses BIM slab and roof objects (floors, roofs, …) — walls or bare Masses are not enough — and requires the 3D view. Dates cross as ISO 8601 date strings ("YYYY-MM-DD").

At a glance

Method	What it does	Mutates?
compute(startDate, endDate)	Start the backend run (Pro; returns immediately)	✓
get()	Poll the job state	—
cancel()	Abort the in-flight run	✓
reset()	Clear the rendered heatmap	✓

Functions

compute(startDate, endDate)

Start a daylight-illuminance run for a date range. Starts the backend job and returns immediately — poll get() until status is "active". Starting a new run while one is in flight replaces it.

• Parameters:
  • startDate: string — start of the study range, ISO date "YYYY-MM-DD".
  • endDate: string — end of the study range, on or after startDate.
• Returns: PluginAnalysisComputeResult — { success: true } when the job was started.
• Throws: When the workspace is not on a Pro plan, when the project has no geo-located site/terrain, when the scene has no slab or roof BIM object to analyse (walls or bare Masses are not enough) or the editor is not in the 3D view, when a date is not a parseable ISO date or the range is inverted, or when plugin writes are disabled.

const { success } = await snaptrude.analysis.illuminance.compute("2026-12-01", "2026-12-31");

---

get()

Get the state of the illuminance study — the polling read for the async job.

• Returns: PluginAnalysisJobState | null — the status and the run's ISO startDate/endDate, or null when no run result is available (the study never ran, was cancelled, or the last run failed).

const job = await snaptrude.analysis.illuminance.get();
if (job?.status === "active") console.log(job.startDate, job.endDate);

---

cancel()

Cancel the in-flight illuminance run. A no-op (returns false) when nothing is running.

• Returns: boolean — true when a run was cancelled.
• Throws: When plugin writes are disabled.

await snaptrude.analysis.illuminance.cancel();

---

reset()

Clear the illuminance heatmap from the scene. A no-op (returns false) when no heatmap is showing. Does not cancel an in-flight run — use cancel().

• Returns: boolean — true when a heatmap was cleared.
• Throws: When plugin writes are disabled.

await snaptrude.analysis.illuminance.reset();