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.
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
- Each test point casts one ray towards every sun vector from the Heliodon, starting 0.01 m off the point.
- A ray that hits the Context mesh is blocked. On massing (Workflow 1), rays from faces turned away from the sun are not counted.
- 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).
- Sun Hours = sum of the transmitted fractions over all sun vectors, rounded; Exposure = that sum / number of sun vectors.
- 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.