Solar

Sample solar exposure at caller-chosen points. Accessed via snaptrude.analysis.solar.

Unlike the heatmap studies (which raster the model's own surfaces), this samples solar exposure at points you supply — an instant (sun visible? / irradiance now) or aggregated over a date range (shaded fraction / cumulative irradiance). Positions are world plan-space coordinates, the same frame as plugin geometry reads; the backend echoes them verbatim. Raw numbers only: it renders no heatmap, mutates no geometry, and writes no save commands.

Pro plan + GPU host

sampleGrid is Pro-gated and write-gated (mirrors analysis.illuminance.compute). The computation runs on the GPU host; when it is unavailable the call fails with OPERATION_FAILED and details.reason === "GPU_UNAVAILABLE".

At a glance

Method	What it does	Mutates?
sampleGrid(args)	Sample per-point solar exposure (instant or range)	—

Types

PluginSolarSamplePoint

Property	Type	Description
id	string	Caller-chosen id, echoed back verbatim
position	[number, number, number]	World plan-space [x, y, z]
normal	[number, number, number]?	Surface normal for plane-of-array; omit = horizontal

PluginSolarSampleGridArgs

Provide exactly one timing mode: dateTime (instant) XOR startDate+endDate (range).

Property	Type	Description
points	PluginSolarSamplePoint[]	Points to sample
dateTime	string?	Instant mode: local ISO 8601 with offset
startDate	string?	Range mode: inclusive start "YYYY-MM-DD"
endDate	string?	Range mode: inclusive end "YYYY-MM-DD"
includeHourlyArtifact	boolean?	Attach a downloadable per-hour series

PluginSolarSampleResult

One sampled point's result. Irradiance fields are in the result's units and omitted when the backend did not compute them.

Property	Type	Description
id	string	The point's caller-chosen id
directSunVisible	boolean	Instant mode: sun disc visible from the point
shadeFraction	number	0..1; range mode: fraction of sun-up hours shaded
directIrradiance	number?	Direct component, in the result's units
diffuseIrradiance	number?	Diffuse component, in the result's units
totalIrradiance	number?	Total (direct + diffuse), in the result's units

PluginSolarSampleGridResult

Property	Type	Description
status	"running" | "complete" | "cancelled" | "failed"	Run status
mode	"instant" | "range"	Timing mode
coordinateSystem	"world-plan-space"	Echo of the input frame
modelRevision	string	Geometry revision sampled against (staleness key)
inputHash	string	Hash of points+dates+geometry (staleness key)
units	"W/m2" | "kWh/m2"	"W/m2" (instant) or "kWh/m2" (range)
sunUpHours	number	Sun-up hours over the sampled window
weather	PluginWeatherSourceMeta | null	Resolved weather file, or null
weatherQuality	string[]	Deduped quality flags in the consumed rows
results	PluginSolarSampleResult[]	This page of per-point results
hourlyArtifact	{ url, format, expiresAt } | null	Per-hour download, or null
nextCursor	string | null	Next page cursor; null = last page

Functions

sampleGrid(args)

Sample solar exposure at a set of points. Provide exactly one timing mode: dateTime (a single instant → mode: "instant", results in W/m²), or startDate + endDate (a range → mode: "range", results in kWh/m²). Each point's optional normal gives plane-of-array irradiance.

• Parameters:
  • args: PluginSolarSampleGridArgs — the points, exactly one timing mode, and an optional includeHourlyArtifact.
• Returns: PluginSolarSampleGridResult — the run status, mode/units, provenance, this page of results, an optional hourlyArtifact, and nextCursor.
• Throws: When the workspace is not on a Pro plan, when plugin writes are disabled, when the scene has no analysable geometry, or when the GPU host is unavailable (OPERATION_FAILED, details.reason === "GPU_UNAVAILABLE").

const grid = await snaptrude.analysis.solar.sampleGrid({
  points: [
    { id: "a", position: [0, 3, 0] },
    { id: "b", position: [5, 3, 0], normal: [0, 0, 1] }
  ],
  dateTime: "2026-06-21T12:00:00+05:30"
});
for (const r of grid.results) {
  console.log(r.id, r.directSunVisible, r.totalIrradiance, grid.units);
}