API Docs

Class: SunPathManager

PD. SunPathManager

new SunPathManager()

A utility class for managing shared WebGL Sun-path components.

All 3D Sun-path diagrams comprise a diagram base with angle indicators and all the major N, E, S, W cardinal direction indicators, as well as monthly Sun-path lines, hourly analemma lines, a band showing the range of possible Sun positions over the year, a daily Sun-path line, a current Sun direction indicator and a current Sun position indicator.

The only thing that does change between Sun-path diagram instances is any localised shading effects that can be shown over the sky distribution. These can by added and managed by the PD.SkyDome class.

All of these 3D components can be created as static geometry, and then scaled, translated and/or rotated into position to accurately represent any combination of date, time and geographic location. This static geometry can therefore be shared by each Sun-path diagram instance in order to significantly reduce resource use and optimise regeneration times.

Also, these kinds of transformations are relatively low-overhead actions for meshes, which allows all diagrams in a model to be highly dynamic and reflect user-driven changes in real-time.

Moreover, if only the static geometries and materials are shared, and each Sun-path instance has its own THREE.Mesh and THREE.LineSegments instances that use them, then it is possible to display multiple Sun-paths diagrams within the one model that each have different dates, times and/or locations by simply applying different scaling, translations and/or rotations.

Whilst this is possible and supported, in reality there is rarely ever any need within the framework to simultaneously display Sun-path diagrams with anything other than the current site location and the current date, time and site location.

Shared Date, Time and Location

This class also provides a static PD.SolarPosition instance that mirrors the current site date, time and location in PD.GlobalState. When a Sun-path diagram instance is updated, it first checks for a valid PD.SunPath3D#sunPos property. If found, this will be used to set the correct scaling, translations and rotations of its components. If this is null, which is its default value, the static sun position that mirrors the current site date, time and location will be used.

This means that, by default, each new Sun-path diagram will reflect the current global site conditions. To override this with a different set of conditions, assign a custom PD.SolarPosition instance to the Sun-path's PD.SunPath3D#sunPos property. You can do this most easily via the constructor's config argument. If you assign this property at any other time, make sure you call the PD.SunPath3D#rebuild method to instantiate any changes.

Shared Geometry

A 3D Sun-path diagram is formed from a group of five (5) components and generated as a combination of four line-based meshes and three triangulated meshes. Whilst each Sun-path diagram instance has its own set of THREE.Mesh and THREE.LineSegments objects, these all use the shared geometry and materials provided by this class.

The five (5) components are:

1. Base Diagram This comprises a THREE.Mesh and THREE.LineSegments object that displays the main cartesian axis, a radial grid, tick marks and angle numbers in 15deg (or 1deg) increments.

2. Monthly Sun-Path Lines This is a THREE.LineSegments object that displays the daily path of the Sun through the sky for each month of the year. In order to show the full range of Sun paths, these are typically generated for the 21st day in each month as the Summer and Winter solstices occur on or about the 21st of June and 21st of December. It can also optionally display analemma lines for each hour of the day throughout the year. This line object is rotated about two axis to reflect the latitude, longitude and timezone of the site location.

3. Annual Sun-Path Range This is a THREE.Mesh object that displays the area of the sky through which the Sun passes throughout the year. It is also rotated along with the monthly Sun-path lines object to reflect the latitude, longitude and timezone of the site location.

4. Daily Sun-Path Line This is a THREE.LineSegments object that displays the path of the Sun through the sky on the current day of the year. This line object is rotated along with the monthly Sun-path lines object to reflect the latitude, longitude and timezone of the site location, as well as translated and scaled to reflect the current day of the year.

5. Sun Position Indicator This comprises a THREE.Mesh object that shows a small red sphere indicating the current position of the Sun in the sky at the current date and time, and a THREE.LineSegments object in the form of an arrow running from the center of the diagram through the center of the small Sun sphere and beyond. Both are rotated into position relative to the center of the diagram, and must be updated whenever anything changes - the site location, date and current time.

Author:
  • drajmarsh

Members

:number

dayOfMonth <static>

The day of the month on which to draw monthly Sun-path lines.

This defaults to the 21st of each month and can be given an integer value between 1 and 30.

Type
  • number
:number

fontSize <static>

The relative size of the font used to display angles and directions.

This value defaults to 1 and is given as a fraction of the standard model point size.

Type
  • number

Methods

checkToInitialise() <static>

Checks to see if this static class needs initialisation.

This method adds some global event listeners that ensure the manager is using the site location and current date/time.

Any class that utilises the resources provided by this static class should call this method very early in their constructor to ensure resources are available.

copyToCanvas(canvas [, skyDome] [, projection] [, shading]) <static>

Renders the current sun-path lines to the given canvas.

Parameters:
Name Type Argument Description
canvas CanvasElement

The canvas element to render in.
skyDome PD.SkyDome <optional>

The sky dome to render, if available.
projection function | PD.PROJECTION <optional>

A function for projecting altitude angles to radius, or a projection enumerator value.
shading Array.<number> | null <optional>

An array of sky patch shading values, if available.
Returns:

Returns true if sun path(s) were rendered to canvas.

Type
boolean

createAnnualSunPathLineSegments() <static>

Creates the shared annual Sun-path range surface mesh.

This is a semi-transparent surface that shows the range of Sun positions throughout the entire year.

Returns:

Returns a new annual Sun-path line segments object.

Type
THREE.Mesh

createAnnualSunPathMesh() <static>

Creates the shared annual Sun-path range surface mesh.

This is a semi-transparent surface that shows the range of Sun positions throughout the entire year.

Returns:

Returns a new triangulated mesh object.

Type
THREE.Mesh

createBaseDiagramLines() <static>

Creates the shared base diagram line segments.

This is essentially just NS and EW axis lines.

Returns:

Returns a new line segments object.

Type
THREE.LineSegments

createBaseDiagramMesh(detailed) <static>

Creates the shared annual Sun-path range surface mesh.

This is a semi-transparent surface that shows the range of Sun positions throughout the entire year.

Parameters:
Name Type Description
detailed boolean

Whether or not to generate 1deg or 5deg angle ticks.
Returns:

Returns a new line segments object.

Type
THREE.Mesh

createDailySunPathLineSegments() <static>

Create a new line segments object with shared geometry and material.

This is a single dashed line that runs from sunrise to sunset on the current day. It is actually created as a series of line segments that define a dashed circle which is rotated, scaled, moved and clipped to represent the path of the Sun through the sky on the current day of the year.

Returns:

Returns a new line segments object.

Type
THREE.LineSegments

createSharedExportLineMaterial() <static>

Creates the shared export line material when required.

Returns:

Returns the shared export line material.

Type
THREE.LineBasicMaterial

createSharedExportMeshMaterial() <static>

Creates the shared export mesh material when required.

Returns:

Returns the shared export mesh material.

Type
THREE.MeshBasicMaterial

createSunDirectionLineSegments() <static>

Create a new Sun direction indicator line segments object with shared geometry and material.

This is a single line with an arrow head that is rotated to point in the current direction of the Sun.

Returns:

Returns a new line segments object.

Type
THREE.LineSegments

createSunPositionMesh() <static>

Creates the shared Sun position indicator mesh.

This is a spherical surface that shows the relative position of the Sun on the sky dome.

Returns:

Returns a new spherical mesh object.

Type
THREE.Mesh

dispose() <static>

Cleans up the sun-path manager and removes all event listeners.

NOTE: Only call this method when the sun-path is no longer needed and you wish to free all its resources.

getSiteSunPos() <static>

Retrieves the internal solar position calculator that reflects global site conditions.

Returns:

Returns a solar position calculator for the current site.

Type
PD.SolarPosition

setSharedUniforms(mesh, r, g, b, a) <static>

Updates the color and opacity uniforms of the shared Z-clip shader.

Parameters:
Name Type Description
mesh THREE.Object3D

The mesh or line segments to be updated.
r number

The red color component (0 to 1).
g number

The green color component (0 to 1).
b number

The blue color component (0 to 1).
a number

The alpha/opacity to set (0 to 1);