Sun Hours Analysis

Multi-threaded raycaster. Analyzes arbitrary 3D massing or custom points for sun exposure. Optional tree crowns filter sunlight (Beer–Lambert) instead of blocking it.

Site Analysis Nickname: SunHours

Overview

Multi-threaded raycaster. Analyzes arbitrary 3D massing or custom points for sun exposure.

Inputs (11)

  • Test Points (Point): (Workflow 2) High LOD: Specific points to test (e.g., window centroids). Overrides Massing.
  • Geometry (Geometry): (Workflow 1) Low LOD: 3D Massing (Breps) or Terrain (Meshes) to analyze.
  • Grid Size (Number): Subdivision size for auto-meshing the Massing.
  • Context (Mesh): Environment geometry (buildings, terrain) as shadow casters.
  • Sun Vectors (Vector): Solar vectors from the Heliodon.
  • Gradient (Colour): Optional custom color gradient (list of colors from 0% to 100%).
  • Run (Boolean): Trigger the analysis.
  • Offset (Number): Offset distance for output points.
  • Trees (Mesh): Optional closed tree-crown meshes. Treated as porous (Beer–Lambert) instead of solid: sun through foliage is reduced, not blocked. Do not also put them in Context.
  • Leaf Area Density (Number): Leaf area density per crown (m²/m³), matched to Trees by index (last value repeats). ~0.5 sparse / winter, 1.0 typical, 2.0 dense evergreen.
  • Extinction k (Number): Light extinction coefficient. 0.5 = spherical leaf-angle distribution.

Outputs (8)

  • Sun Hours (Integer): Total number of sun rays that reached the point.
  • Exposure % (Number): Percentage of time in the sun (0.0 to 1.0).
  • Points Out (Point): The analyzed points.
  • Analysis Mesh (Mesh): The auto-subdivided Massing mesh (for easy gradient coloring).
  • Colors (Colour): Color mapped to each point.
  • Dashboard Data (Text): JSON legend data
  • Tree Shade % (Number): Share of the point's direct sun (0.0 to 1.0) removed by tree foliage. 0 when no Trees are given.
  • Info (Text): Method, assumptions, simplifications and references.

Method, assumptions and simplifications

The same notes appear in the component's Info output.

Method

  1. Each test point casts one ray towards every sun vector from the Heliodon, starting 0.01 m off the point.
  2. A ray that hits the Context mesh is blocked. On massing (Workflow 1), rays from faces turned away from the sun are not counted.
  3. Tree crowns are porous: a ray through foliage keeps a fraction T = exp(−k × LAD × L) of the sun, where L is the length of the ray inside each crown (from its crossings of the closed crown mesh) and LAD the leaf area density of that crown (Beer-Lambert law).
  4. Sun Hours = sum of the transmitted fractions over all sun vectors, rounded; Exposure = that sum / number of sun vectors.
  5. Tree Shade = 1 - (sun with trees / sun without trees) for the rays not blocked by Context.

Assumptions

  • Each sun vector stands for an equal time step (the Heliodon samples the period evenly), so counts read as hours.
  • Leaf area density is uniform inside a crown; k = 0.5 matches a spherical (random) leaf-angle distribution.
  • Tree crowns are closed meshes and are not also in Context.

Simplifications and limits

  • Direct sun only: no diffuse sky, no reflections, no light scattered by leaves.
  • Trunks and branches are ignored; overlapping crowns add their optical depths.
  • Crowns that are not closed meshes are ignored (warning).

Workflow

  • Heliodon -> Sun Vectors. Massing or Test Points -> Geometry or Test Points. Buildings and terrain -> Context.
  • Tree crowns (for example Site Fetch Tree Crowns) -> Trees; LAD per crown or one value; lower LAD for winter or sparse species.

References

  • Monsi M. and Saeki T. (1953), light extinction in plant canopies (Beer-Lambert law).
  • Campbell G.S. and Norman J.M. (1998), An Introduction to Environmental Biophysics: k = 0.5 for spherical leaf angles.
  • Fujiwara K. et al. (2025), VoxCity, Computers, Environment and Urban Systems 102366: porous canopy approach.