API Docs

Class: SunPath

PD.SVG. SunPath

Generates a 2D Sun-path Diagram within an SVG element.

new SunPath(config [, initialise])

Creates a new 2D Sun-path Diagram instance.

Parameters:
Name Type Argument Description
config object

A configuration object.
Properties of config:
Name Type Argument Description
svgId SVGElement | string

The SVG element to use, or the DOM ID of an SVG element.
canvasId HTMLCanvasElement | string <optional>

An optional CANVAS element to use, or the DOM ID of a CANVAS element.
sunPos PD.SolarPosition <optional>

An optional solar position calculator to use.
latitude number <optional>

An optional terrestrial latitude, in decimal degrees (-90 to 90).
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, in decimal degrees (-180 to 180).
dayOfMonth number <optional>

An optional day of the month on which to draw monthly Sun-path lines, defaults to the 21st (1 to 31).
dayOfYear number <optional>

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

An optional time of the day in decimal hours (0 to 24).
projection PD.PROJECTION <optional>

An optional sun-path diagram projection type, defaults to PD.PROJECTION.EQUIDISTANT.
callbackMetrics function <optional>

An optional callback invoked whenever the shading metrics are updated.
scale number <optional>

An optional scale factor for font sizes and line widths (0.01 to 10.0), defaults to 1.
useGlobalState boolean <optional>

An optional flag indicating that the diagram uses global date, time and location, defaults to true.
addShadowFilter boolean <optional>

An optional flag indicating that the diagram should add a drop shadow filter to better stand out against dark backgrounds, defaults to false.
useTheme boolean <optional>

An optional flag indicating that the diagram uses the global dark/light theme, defaults to true.
interactive boolean <optional>

An optional flag indicating that the diagram should add pointer/touch interactivity, defaults to false.
initialise boolean <optional>

A flag used by subclasses to control initialisation, defaults to true.
Author:
  • drajmarsh
Throws:

Throws an error if provided with an invalid svgId element or id.

Type
Error

Members

:number

analemmaIncrement

The number of days in each analemma increment (1 to 14).

Type
  • number
:number

dayOfMonth

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

Type
  • number
:number

id

A unique identifier for this sun-path.

Type
  • number
:boolean

interactive <readonly>

A flag indicating that the diagram uses pointer/touch interactivity.

Type
  • boolean
:boolean

isSunPath <readonly>

A flag identifying this object as a Sunpath diagram.

Type
  • boolean
:number

projection

The sun-path diagram projection type.

The projection type refers to some standard equations for converting 3D altitude angles to radius values within a 2D polar chart. The different methods allow the detail at the zenith or the horizon to be emphasised, or all altitudes equally.

Type
  • number
:PD.SolarPosition

sunPos

An internal solar position calculator.

Type
:SVGElement

svgElem

The SVG element to render the diagram to.

Type
  • SVGElement
:boolean

usesGlobalState <readonly>

A flag indicating that the diagram uses global date, time and location.

Type
  • boolean

Methods

animateProjection(projection)

Animates between the current and given projection types.

Parameters:
Name Type Description
projection PD.PROJECTION

The new projection to animate to.

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.

set(config [, update])

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

Parameters:
Name Type Argument Default 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).
update boolean <optional>
 true

Whether or not to update sun-path diagram if changed.
Returns:

Returns true if anything changed, otherwise false.

Type
boolean

setDateTime(dateTime [, update])

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

Parameters:
Name Type Argument Default Description
dateTime PD.DateTime

A date/time configuration object.
update boolean <optional>
 true

Whether or not to update sun-path diagram if changed.
Returns:

Returns true if date or time changed, otherwise false.

Type
boolean

setLocation(location [, update])

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

Parameters:
Name Type Argument Default Description
location PD.Location

A location configuration object.
update boolean <optional>
 true

Whether or not to update sun-path diagram if changed.
Returns:

Returns true if location changed, otherwise false.

Type
boolean

setProjection(type [, update])

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

Parameters:
Name Type Argument Default Description
type PD.PROJECTION

The new sun-path diagram projection type.
update boolean <optional>
 true

Whether or not to update sun-path diagram if changed.
Returns:

Returns true if the projection changed, otherwise false.

Type
boolean

setScale(scale [, update])

Sets the scale of detail in the Sun-path diagram and updates it.

This scale is used to adjust the font sizes and line widths relative to the overall size of the diagram.

Parameters:
Name Type Argument Default Description
scale float

The new sun-path feature scale (0.01 to 2.5).
update boolean <optional>
 true

Whether or not to update sun-path diagram if changed.
Returns:

Returns true if the scale changed, otherwise false.

Type
boolean

show(state)

Shows or hides the chart based on given state.

Parameters:
Name Type Description
state boolean

Use true to show, false to hide.
Returns:

Returns this chart instance to support method chaining.

Type
object

update()

Performs a complete update of the diagram.

This method updates the diagram to reflect the current date, time and location.

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnDateChange()

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

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnLocationChange()

Update the sun paths over the diagram whenever the site location or north offset angle changes.

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnProjectionChange()

Update the diagram when the projection changes.

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnTimeChange()

Update the Sun position indicator whenever the time changes.

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath