API Docs

Class: SkyDome

PD.SVG. SkyDome

Generates a 2D Sun-path Diagram overlaid on a sky dome with distribution.

new SkyDome(config)

Creates a new 2D Sky Dome instance.

Parameters:
Name Type 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

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

An optional solar position calculator to use, defaults to a new instance.
skyDome PD.SkyDome <optional>

An optional sky dome distribution calculator to use, defaults to a new instance.
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 - 364/365).
timeOfDay number <optional>

An optional time of the day in decimal hours (0 - 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.
Author:
  • drajmarsh
Throws:

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

Type
Error

Extends

Members

:number

analemmaIncrement

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

Type
  • number
Inherited From:
Overrides:
:function

callbackMetrics

A callback invoked whenever the shading metrics are updated.

When shading data has been calculated, this function is called with a shading metrics data object as the sole argument. If there is no shading, it is called with null as its argument.

The shading data is a simple object containing the following properties.

Property Type Description
skyFactorLuminance number Fraction of the available sky luminance distribution not obstructed by shading.
skyFactorUniform number Fraction of the visible sky dome not obstructed by shading.
Type
  • function
:CanvasElement

canvasElem

The canvas element to render shading and sky distributions to.

Type
  • CanvasElement
:number

dayOfMonth

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

Type
  • number
Inherited From:
Overrides:
:number

id

A unique identifier for this sun-path.

Type
  • number
Inherited From:
Overrides:
:boolean

interactive <readonly>

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

Type
  • boolean
Inherited From:
Overrides:
:boolean

isSunPath <readonly>

A flag identifying this object as a Sunpath diagram.

Type
  • boolean
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
:PD.SkyDome

skyDome

An internal sky dome model.

Type
:PD.SolarPosition

sunPos

An internal solar position calculator.

Type
Inherited From:
Overrides:
:SVGElement

svgElem

The SVG element to render the diagram to.

Type
  • SVGElement
Inherited From:
Overrides:
:boolean

usesGlobalState <readonly>

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

Type
  • boolean
Inherited From:
Overrides:

Methods

_generateSkyDistribution()

Regenerates and renders sky patch luminances to the canvas.

_updateSkyDistributionChange()

Dispatches a global PD.EVENT.SKY_DISTRIBUTION event and updates the sky distribution.

This method is called when the sky patch configuration or luminance/radiance distribution changes.

animateProjection(projection)

Animates between the current and given projection types.

Parameters:
Name Type Description
projection PD.PROJECTION

The new projection to animate to.
Inherited From:
Overrides:

checkToUpdateSky()

Checks whether the sky distribution needs to be updated.

This method is typically called when the sun-path becomes visible in the frontend UI to update if the date, time, location or sky type changed.

Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

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.

Inherited From:
Overrides:

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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
Returns:

Returns this chart instance to support method chaining.

Type
object

update( [updateSky])

Performs a complete update of the diagram.

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

Parameters:
Name Type Argument Description
updateSky boolean <optional>

When true, forces the sky distribution to update.
Inherited From:
Overrides:
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.

Inherited From:
Overrides:
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.

Inherited From:
Overrides:
Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnProjectionChange()

Update the diagram when the projection changes.

Inherited From:
Overrides:
Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnSkyChange( [forceUpdate])

Update the sky distribution the sky changes.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

Force update even if sky dome has not changed, defaults to false.
Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath

updateOnTimeChange()

Update the Sun position indicator whenever the time changes.

Inherited From:
Overrides:
Returns:

Returns this Sun-path instance to support method chaining.

Type
PD.SVG.SunPath