API Docs

Class: SunPath3D

PD. SunPath3D

Generates a 3D Sun-path diagram as a grouped set of THREE.js objects.

A Sun-path diagram is formed from a group of five (5) components made from a combination of four line-based meshes and three triangulated meshes. It is generated this way to allow the individual components to be dynamically rotated, scaled and translated into position to match the current date, time and location. These transformations are relatively low-overhead actions for meshes, which allows the diagram to be highly dynamic and reflect user-driven changes in real-time.

Whilst each 3D Sun-path diagram instance has its own set of THREE.Mesh and THREE.LineSegments objects, these all use the same shared static geometry and materials provided by the static PD.SunPathManager class.

The five (5) shared components are:

1. The 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 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.

Custom Date, Time and Location

By default, the PD.SunPath3D#sunPos property of this class is null, in which case the shared static sun position provided by PD.SunPathManager 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 sunPos property. You can do this most easily using the constructor's config argument when you first create the Sun-path. If you assign this property at any other time, make sure you call the PD.SunPath3D#rebuild method to instantiate any changes.

Position and Size

To move the Sun-path diagram around, simply set its PD.SunPath3D#position property. The diagram itself is created with an absolute sky spherical radius of 1.0, so to give it a size, simply set its PD.SunPath3D#scale property to the required radius in model units.

new SunPath3D( [config])

Creates a new 3D WebGL Sun-path diagram instance.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
sunPos PD.SolarPosition <optional>

An optional solar position calculator to use.
detailed boolean <optional>

A static diagram sits over the whole model and does not move with the current level.
Author:
  • drajmarsh

Extends

  • THREE.Group

Members

:boolean

detailed

A static diagram sits over the whole model and does not move with the current level.

Type
  • boolean
:THREE.LineSegments

linesAnnualPaths

The line segment mesh displaying monthly Sun-path lines.

Type
  • THREE.LineSegments
:THREE.LineSegments|null

linesBaseDiagram

The line segment mesh displaying the base diagram.

Type
  • THREE.LineSegments | null
:THREE.LineSegments

linesDailyPath

The line segment mesh displaying the daily Sun-path line.

Type
  • THREE.LineSegments
:THREE.LineSegments

linesSunDirection

The line segment mesh displaying an arrow directly at the Sun.

Type
  • THREE.LineSegments
:THREE.Mesh

meshAnnualPathRange

The surface mesh showing the sky area the sun passes through over the year.

Type
  • THREE.Mesh
:THREE.Mesh

meshBaseDiagram

The surface mesh showing the angles and tick lines around the base diagram.

Type
  • THREE.Mesh
:THREE.Mesh

meshSunPosition

The surface mesh for a small sphere displaying the position of the Sun.

Type
  • THREE.Mesh
:boolean

showCurrentSunPosition

Determines visibility of the current sun position indicators.

Type
  • boolean
:PD.SolarPosition

sunPos

An internal solar position calculator, defaults to null.

When this property is null, the shared static solar position calculator provided by PD.SunPathManager will be used. If assigned its own solar position calculator instance, that will be used to scale, translate and rotate its meshes into position rather than reflecting current site conditions.

If you set this property anytime after creating the Sun-path diagram, make sure you call the PD.SunPath3D#rebuild method to instantiate any changes.

Type

Methods

createExportableMesh(exporter)

Creates a new THREE.Mesh instance that is better suited for export using standard THREE.JS exporters.

This method is detected and used by the PD.File.exportGeometry method to replace this object with the returned mesh when exporting the model.

SunPath3D instances are not well suited for direct export via THREE as they share multiple static meshes and a custom shader that discards any geometry that falls below the Z=0 plane. As no standard geometry export formats support custom GLSL shaders, a direct export will include the entire uncut geometry.

As a result, this method creates a set of new geometry that manually trim away any geometry below the Z=0 plane. This means creating new buffer attributes for the freshly trimmed geometry and associating it with new exportable material definitions that match the custom shader.

Parameters:
Name Type Description
exporter PD.File.ExportOptions

The exporter settings.
Returns:

Returns a new mesh that can be exported.

Type
THREE.Mesh | null

dispose()

Cleans up the sun-path 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.

rebuild()

Performs a complete update of the diagram.

This method updates the diagram to reflect the current date, time and location. As the diagram is composed of multiple meshes that are rotated, translated and scaled into place, the actual updating does not required much overhead at all.

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SunPath3D

set(config)

Sets the date/time/location of the Sun-path diagram and updates it.

Parameters:
Name Type Description
config number

A configuration object.
Properties of config:
Name Type Argument Description
latitude number <optional>

An optional terrestrial latitude, in decimal degrees (-90 to 90).
longitude number <optional>

An optional terrestrial longitude, in decimal degrees (-180 to 180).
timezone number <optional>

An optional local time zone at the location, in decimal hours (-14 to +14).
northAngle number <optional>

An optional angle between North and the +Y axis, clockwise in decimal degrees (-180 to 180).
dayOfYear number <optional>

The ordinal index of the day of the year (0 - 364/365).
timeOfDay number <optional>

The time of day in decimal hours (0 - 24).
Returns:

Returns this Sun-path manager to support method chaining.

Type
PD.SunPath3D

setDateTime(dateTime)

Sets the date/time of the Sun-path diagram and updates it.

Parameters:
Name Type Description
dateTime PD.DateTime | object

A date/time configuration object.
Properties of dateTime:
Name Type Argument Description
dayOfYear number <optional>

The ordinal index of the day of the year (0 - 364/365).
timeOfDay number <optional>

The time of day in decimal hours (0 - 24).
Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SunPath3D

setLocation(location)

Sets the location of the Sun-path diagram and updates it.

Parameters:
Name Type Description
location PD.Location | object

A location configuration object.
Properties of location:
Name Type Argument Description
latitude number <optional>

An optional terrestrial latitude, in decimal degrees (-90 to 90).
longitude number <optional>

An optional terrestrial longitude, in decimal degrees (-180 to 180).
timezone number <optional>

An optional local time zone at the location, in decimal hours (-14 to +14).
northAngle number <optional>

An optional angle between North and the +Y axis, clockwise in decimal degrees (-180 to 180).
Returns:

Returns this Sun-path manager to support method chaining.

Type
PD.SunPath3D

updateOnDateChange()

Update the daily Sun-path line whenever the date changes.

updateOnLocationChange()

Update the main diagram whenever the site location or north offset angle changes.

updateOnTimeChange()

Update the Sun position indicator whenever the time changes.