Sunlight Hours

The direct-sunlight-hours heatmap study. Accessed via snaptrude.analysis.sunlightHours.

Computes, for every space surface (Room or Department Mass — generic Masses are not enough), how many hours of direct sunlight it receives over a date range, and renders the result as a heatmap on the scene. The computation is an asynchronous backend job: compute starts it and returns immediately, get is the polling read (see the job polling pattern), cancel aborts an in-flight run, and reset clears a rendered heatmap. Heatmaps are invalidated by scene-mutating edits — re-run the study after changing the model. 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 (returns immediately)	✓
get()	Poll the job state	—
cancel()	Abort the in-flight run	✓
reset()	Clear the rendered heatmap	✓

Types

PluginAnalysisComputeResult

Property	Type	Description
success	boolean	true when the backend job was started
error	string | undefined	Failure reason when success is false (reserved — not yet emitted; start failures currently throw)

PluginAnalysisJobState

get() returns this record, or null when no run result is available (the study never ran, was cancelled, or the last run failed).

Property	Type	Description
status	"running" | "active" | "inactive"	See the status table below
startDate	string	ISO date ("YYYY-MM-DD") the run was computed from
endDate	string	ISO date ("YYYY-MM-DD") the run was computed to

Status	Meaning
"running"	A run is in flight — keep polling
"active"	The heatmap is rendered on the scene
"inactive"	A previous run exists but its heatmap is not showing

Functions

compute(startDate, endDate)

Start a direct-sunlight-hours run for a date range. Starts the backend job and returns immediately — poll get() until status is "active" (a run typically takes minutes). 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 project has no geo-located site/terrain, when the scene has no space (Room or Department Mass) to analyse, when 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.sunlightHours.compute("2026-06-01", "2026-06-30");

---

get()

Get the state of the sunlight-hours 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.sunlightHours.get();
if (job?.status === "active") console.log(job.startDate, job.endDate);

---

cancel()

Cancel the in-flight sunlight-hours 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.sunlightHours.cancel();

---

reset()

Clear the sunlight-hours heatmap from the scene and restore the normal material view. 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.sunlightHours.reset();