Shadows

Real-time sun shadows in the scene. Accessed via snaptrude.analysis.shadows.

Shadows are cast for the sun position at a specific date and time at the project's geographic location. The date-time crosses this API as an ISO 8601 date-time string in the project's local time (e.g. "2026-06-21T14:30"); the engine snaps the time down to its half-hour grid and derives the timezone from the site location — do not append a UTC offset. Enabling shadows resets any active heatmap analysis (they are mutually exclusive in the product).

At a glance

Method	What it does	Mutates?
enable(options?)	Turn shadows ON, optionally at a specific date-time	✓
disable()	Turn shadows OFF (the stored date-time is kept)	✓
isEnabled()	Whether shadows are currently rendering	—
setDateTime(dateTime)	Move the sun to an ISO date-time	✓
getDateTime()	The stored sun date-time as an ISO string	—

Types

PluginAnalysisShadowsEnableOptions

Property	Type	Description
dateTime	string | undefined	ISO 8601 local date-time to position the sun at (snapped to the half-hour grid)

PluginAnalysisShadowsDateTimeResult

The sun's ISO 8601 local date-time — a string with minute precision, always on the engine's half-hour grid (:00 or :30).

Functions

enable(options?)

Turn real-time sun shadows ON. Without options.dateTime the shadows use the current stored sun position; with it, the sun is moved first (same as setDateTime).

• Parameters:
  • options: PluginAnalysisShadowsEnableOptions | undefined
• Returns: boolean — true; shadows are enabled after the call.
• Throws: When the project has no geo-located site/terrain ("Site is needed"), when options.dateTime is not a parseable ISO date-time, or when plugin writes are disabled.

await snaptrude.analysis.shadows.enable({ dateTime: "2026-06-21T15:00" });

---

disable()

Turn real-time sun shadows OFF. A no-op (returns false) when shadows are already off. The stored sun date-time is kept for the next enable.

• Returns: boolean — false; shadows are disabled after the call.
• Throws: When plugin writes are disabled.

await snaptrude.analysis.shadows.disable();

---

isEnabled()

Whether real-time sun shadows are currently enabled. A pure read — never mutates, never throws.

• Returns: boolean — true when shadows are rendering.

const on = await snaptrude.analysis.shadows.isEnabled();

---

setDateTime(dateTime)

Move the sun to a specific date and time. Takes an ISO 8601 date-time string in the project's local time; the engine snaps the time down to its half-hour grid and re-renders the shadows (when they are enabled). The engine stores no year — only the month, day, and time are applied, and the returned date-time always carries the current year (setting "2020-12-21T09:30" returns "2026-12-21T09:30" in 2026). Paired with getDateTime.

• Parameters:
  • dateTime: string — ISO 8601 local date-time, e.g. "2026-12-21T09:30".
• Returns: PluginAnalysisShadowsDateTimeResult — the applied ISO date-time after half-hour snapping.
• Throws: When the project has no geo-located site/terrain, when dateTime is not a parseable ISO date-time, or when plugin writes are disabled.

const applied = await snaptrude.analysis.shadows.setDateTime("2026-12-21T09:44");
console.log(applied); // "2026-12-21T09:30" (snapped to the half-hour grid)

---

getDateTime()

Get the sun's current date and time — the stored sun position as an ISO 8601 local date-time string, the value shadows render at (whether or not they are enabled). The engine stores no year, so the returned string always carries the current year, whatever year was passed to setDateTime (its pair).

• Returns: PluginAnalysisShadowsDateTimeResult — the current ISO local date-time of the sun.

const dateTime = await snaptrude.analysis.shadows.getDateTime();