API Docs Class: SolarPosition

new SolarPosition( [config])

Creates a terrestrial solar position calculator.

Parameters:

Name Type Argument Description

config

object

An optional configuration object.

Properties of `config`:

Name	Type	Argument	Description
`latitude`	number	<optional>	The terrestrial latitude, in decimal degrees.
`longitude`	number	<optional>	The terrestrial longitude, in decimal degrees.
`timezone`	number	<optional>	The local time zone at the location, in decimal hours.
`northAngle`	number	<optional>	The angle between north and the +Y axis, in clockwise decimal degrees.
`interpolateDeclination`	boolean	<optional>	Whether or not to interpolate declinations over each day.
`clockTime`	number	<optional>	An optional local clock time, in decimal hours (0.0 to 24.0).
`dayOfMonth`	number	<optional>	An optional day of the month component of the date (1 to 31).
`monthOfYear`	number	<optional>	An optional month of the year component of the date (0 to 11).
`year`	number	<optional>	An optional 4 digit year component of the date (-4712 to 3500).

Author:

drajmarsh

Members

:number clockTime

The local clock time at which to calculate, in decimal hours (0.0 to 24.0).

Type

number

:number clockTimeUTC

The time in Coordinated Universal Time (UTC), in decimal hours (0.0 - 24.0).

Type

number

:number dayOfMonth

The ordinal day of the month (1 to 31).

Type

number

:number dayOfYear

The ordinal day of the year (0 to 364/5).

Type

number

:boolean isSolarPosition <readonly>

A flag identifying this object as a solar position calculator.

Type

boolean

:number latitudeInDegrees

The geographic latitude relative to the equator, in decimal degrees (-89.9 to 89.9).

Type

number

:number latitudeInRadians

The geographic latitude relative to the equator, in radians (-PI/2 to PI/2).

Type

number

:number longitudeInDegrees

The geographic longitude relative to the prime meridian, in decimal degrees (-180 to 180).

Type

number

:number longitudeInRadians

The geographic longitude relative to the prime meridian, in radians (-PI to PI).

Type

number

:number monthOfYear

The ordinal month within the year (0 to 11).

Type

number

:number northAngleInDegrees

The angle of North in a clockwise direction from the positive Y angle, in decimal degrees (-180 to 180).

Type

number

:number northAngleInRadians

The angle of North in a clockwise direction from the positive Y angle, in decimal degrees (-180 to 180).

Type

number

:number solarTime

The current solar time, in decimal hours (0.0 - 24.0).

Type

number

:number solarTimeUTC

The solar time in Coordinated Universal Time, in decimal hours (0.0 - 24.0).

Type

number

:number timezone

The local time zone offset from UTC, in decimal hours (-14.0 to 14.0).

Type

number

:number year

The year of the calculation as an integer (ie: 2014 or 2021).

Type

number

Methods

_calculateDate()

Calculates all date-based properties.

Do this in preparation for one or more subsequent time-of-day-based calculations.

calcDayOfYearIndex(day_of_month, month_of_year, year)

Calculates the ordinal index of the day within the year (0 - 364/5).

Parameters:

Name	Type	Description
`day_of_month`	number	The ordinal day of the month (1-31).
`month_of_year`	number	The ordinal day of the year (0-11).
`year`	number	The four-digit year number (eg: 2010).

Returns:

Returns the calculated index of the day within the year (0 - 364/5).

Type: number

calcDefaultTimezone(longitude)

Calculates the default timezone offset for the given longitude. This is a simple calculation that does not consider regional boundaries and is given in decimal hours (-13 to 13).

Parameters:

Name	Type	Description
`longitude`	number	The longitude to get the timezone for, in decimal degrees (-180 to 180).

Returns:

Returns the calculated time zone offset, in decimal hours (-13 to 13).

Type: number

calculate()

(Re)Calculate the solar position based on the current settings.

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

copy(sunPos)

Copies all solar position data from the given instance.

Parameters:

Name	Type	Description
`sunPos`	PD.SolarPosition	The solar position calculator instance to copy from.

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

copyLocation(src)

Copies any geographic location data from the given source object.

Parameters:

Name	Type	Description
`src`	PD.SolarPosition \| PD.Location	A `PD.SolarPosition` or `PD.Location` object to copy data from.

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

formatAsDate(day_of_year, year)

Returns a string with the given day of the year in "dd mm YYYY" format.

Parameters:

Name	Type	Description
`day_of_year`	number	The ordinal day of the year (0-364/5).
`year`	number	The four-digit year number (eg: 2010).

Returns:

Returns the formatted date string.

Type: string

formatAsDuration( [decimal_hours] [, seconds])

Returns a string with the given duration in "HH:mm" or "HH:mm:ss" format.

Parameters:

Name	Type	Argument	Description
`decimal_hours`	number	<optional>	The time period, in decimal hours (0-24), defaults to current time.
`seconds`	boolean	<optional>	When true it displays seconds value, otherwise just rounds to nearest minute.

Returns:

Returns the formatted duration string.

Type: string

formatAsTime( [decimal_hours] [, seconds])

Returns a string with the given time in "HH:mm" or "HH:mm:ss" format.

Parameters:

Name	Type	Argument	Description
`decimal_hours`	number	<optional>	The time period, in decimal hours (0-24), defaults to current time.
`seconds`	boolean	<optional>	When true it displays seconds value, otherwise just rounds to nearest minute.

Returns:

Returns the formatted time string.

Type: string

formatAsTimezone( [decimal_hours])

Returns a string with the given duration in "±HH:mm" or "±HH:mm:ss" format.

Parameters:

Name	Type	Argument	Description
`decimal_hours`	number	<optional>	The time period, in decimal hours (0-24), defaults to current timezone.

Returns:

Returns the formatted timezone.

Type: string

generateAnnualSolarTables()

Generates a table of solar data for each day of the current year.

This method generates an array of arrays, where each inner array contains the solar data for a specific day.

Each row of daily solar data contains the following:

[ 0] Date (in the format "DD MON")
[ 1] Solar Noon (in the format "HH:MM")
[ 2] Solar Noon Altitude (in degrees as "XXX.XX°")
[ 3] Sunrise (in the format "HH:MM")
[ 4] Sunrise Azimuth (in degrees as "XXX.XX°")
[ 5] Sunset (in the format "HH:MM")
[ 6] Sunset Azimuth (in degrees as "XXX.XX°")
[ 7] Day Length (in the format "HH:MM")
[ 8] Day Length Change (in the format "HH:MM")
[ 9] Civil Dawn (in the format "HH:MM")
[10] Civil Dusk (in the format "HH:MM")
[11] Nautical Dawn (in the format "HH:MM")
[12] Nautical Dusk (in the format "HH:MM")
[13] Astronomical Dawn (in the format "HH:MM")
[14] Astronomical Dusk (in the format "HH:MM")

Returns:

Returns an array of arrays, one for each day of the year.

Type: Array.<Array.<string>>

generateDailySolarTables( [timeIncr])

Generates a table of solar data over the course of the current day.

This method generates an array of arrays, where each inner array contains the solar data for a specific time increment, staring at sunrise.

Each row of daily solar data contains the following:

[0] Time (in the format "HH:MM")
[1] Solar Altitude (in degrees as "XXX.XX°")
[2] Solar Azimuth (in degrees as "XXX.XX°")
[3] Horizontal Angle to Sun (in degrees as "XXX.XX°")
4] Shadow Angle (in degrees as "XXX.XX°")
[5] Shadow Length (in metres or feet/in)

Parameters:

Name	Type	Argument	Description
`timeIncr`	number	<optional>	The time increment over the day, defaults to 5min.

Returns:

Returns an array of arrays, one for each time increment over the current day.

Type: Array.<Array.<string>>

getAnalemmaSunAngles(day_step [, day_start] [, day_end])

Creates an array of [azimuth, altitude] angles over the whole year at the current time in steps equal to the given day increment.

Parameters:

Name	Type	Argument	Default	Description
`day_step`	number			The increment step in days (1 to 90).
`day_start`	number	<optional>	0	An optional start time in decimal hours, defaulting to 0.0.
`day_end`	number	<optional>	365	An optional stop time in decimal hours, defaulting to 24.0.

Returns:

Returns an array of arrays, one for each day step, with the first value of each being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

Type: Array

getAnalemmaSunPathAsPositions(day_step, center, radius)

Retrieves an array of 3D solar positions over the whole year at the current time in steps equal to the given increment.

Parameters:

Name	Type	Description
`day_step`	number	The increment step in days (1 to 90).
`center`	Array	The position of the center point, given as a [x,y,z] coordinate array.
`radius`	number	The radius of the sphere on which the Sun path positions should sit.

Returns:

Returns the given array or a new one containing connected [x,y,z] coordinate arrays.

Type: object

getClockTime()

Retrieves the local clock time at which to calculate, in decimal hours.

Returns:

Returns the local clock time, in decimal hours (0.0 to 24.0).

Type: number

getClockTimeAsString()

Retrieves the time in the format 'HH:mm'.

Returns:

Returns the time in the format 'HH:mm'.

Type: string

getClockTimeUTC()

Retrieves the time in Coordinated Universal Time (UTC), in decimal hours.

Returns:

Returns the local clock time, in decimal hours (0.0 to 24.0).

Type: number

getDailySunAngles(time_step [, time_start] [, time_end])

Creates an array of [azimuth, altitude] angles over the current day from -180 to 180 in the steps equal to the given time increment.

Parameters:

Name	Type	Argument	Description
`time_step`	number		The increment step in decimal hours (1/60.0 to 6hrs).
`time_start`	number	<optional>	An optional start time in decimal hours, defaulting to sunrise.
`time_end`	number	<optional>	An optional stop time in decimal hours, defaulting to sunset.

Returns:

Returns an array of arrays, one for each time step, with the first value of each being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

Type: Array

getDailySunPathAsPositions(time_step, center, radius [, results])

Retrieves an array of 3D Solar positions over the current day from midnight to midnight in the steps equal to the given increment.

Each position is given as an [x,y,z] coordinate array.

Parameters:

Name	Type	Argument	Description
`time_step`	number		The increment step in decimal hours (1/60.0 to 6hrs).
`center`	Array		The position of the center point, given as a [x,y,z] coordinate array.
`radius`	number		The radius of the sphere on which the Sun path positions should sit.
`results`	Array	<optional>	An optional array to receive the calculated points.

Returns:

Returns the given array or a new one containing connected [x, y, z] coordinate arrays.

Type: object

getDateAsString()

Retrieves the date in the format 'dd M YYYY'.

Returns:

Returns the date in the format 'dd M YYYY'.

Type: string

getDateObject()

Retrieves the calculation date and time as a JavaScript Date object.

Returns:

Returns a JavaScript Date() object.

Type: object

getDateTimeAsString()

Retrieves the date/time in the format 'HH:mm DD MMM YYYY'.

Returns:

Returns the date/time in the format 'HH:mm DD MMM YYYY'.

Type: string

getDawnTime(stage)

Retrieves the local time at which the specified twilight stage occurs at dawn on the current day, in decimal hours.

Parameters:

Name	Type	Description
`stage`	PD.TWILIGHT	A twilight stage definition.

Throws:

Throws an error
Type Error

Returns:

Returns the specified time, in decimal hours.

Type: number

getDayOfMonth()

Retrieves the ordinal day of the month.

Returns:

Returns the ordinal day of the month (1 to 31).

Type: number

getDayOfYear()

Retrieves the ordinal day of the year.

Returns:

Returns the ordinal day of the year (0 to 364/5).

Type: number

getDecemberSolstice()

Returns the December Solstice as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Returns:

Returns an object containing event data.

Type: object

getDeclinationInDegrees()

Retrieves the current declination angle from the equator, in decimal degrees.

This is the first component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Returns:

Returns the declination angle, in decimal degrees.

Type: number

getDeclinationInRadians()

Retrieves the current declination angle from the equator, in radians.

This is the first component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Returns:

Returns the declination angle, in radians.

Type: number

getDuskDawnData(check)

Retrieves the sunrise and sunset time for the current day, as well as all the twilight stages of dawn and dusk.

The returned object represents the data for the current day, in the form:

{
    "dayOfYear": 90,
    "solarNoon": 12.366226227429355,
    "sunrise": 5.840749703399434,
    "sunset": 18.891702751459277,
    "civilDawn": 5.237202798554755,
    "civilDusk": 19.495249656303955,
    "nauticalDawn": 4.504181173134206,
    "nauticalDusk": 20.228271281724503,
    "astronomicalDawn": 3.7054231232068187,
    "astronomicalDusk": 21.02702933165189
}

Parameters:

Name	Type	Default	Description
`check`	boolean	true	Whether or not to check to recalculate, defaults to true.

Returns:

Returns an object with all the dusk and dawn times.

Type: object

getDuskTime(stage)

Retrieves the local time at which the specified twilight stage occurs at dusk on the current day, in decimal hours.

Parameters:

Name	Type	Description
`stage`	number	A twilight stage definition.

Returns:

Returns the specified time, in decimal hours.

Type: number

getEquationOfTime()

Retrieves the current equation of time, in minutes.

Returns:

Returns the solar hour angle, in minutes.

Type: number

getHourAngleInDegrees()

Retrieves the current solar hour angle offset, in decimal degrees.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Returns:

Returns the solar hour angle, in decimal degrees.

Type: number

getHourAngleInRadians()

Retrieves the current solar hour angle offset, in radians.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Returns:

Returns the solar hour angle, in radians.

Type: number

getJuneSolstice()

Returns the June Solstice as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Returns:

Returns an object containing event data.

Type: object

getLatitudeInDegrees()

Retrieves the geographic latitude relative to the equator, in decimal degrees.

Returns:

Returns the latitude in decimal degrees (-89.9 to 89.9).

Type: number

getLatitudeInRadians()

Retrieves the geographic latitude relative to the equator, in radians.

Returns:

Returns the latitude in radians (-PI/2 to PI/2).

Type: number

getLongitudeInDegrees()

Retrieves the geographic longitude relative to the prime meridian, in radians.

Returns:

Returns the longitude in decimal degrees (-180 to 180).

Type: number

getLongitudeInRadians()

Retrieves the geographic longitude relative to the prime meridian, in radians.

Returns:

Returns the longitude in radians (-PI to PI).

Type: number

getMarchEquinox()

Returns the March Equinox as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Returns:

Returns an object containing event data.

Type: object

getMonthOfYear()

Retrieves the ordinal month within the year.

Returns:

Returns the ordinal month within the year (0 to 11).

Type: number

getNorthAngleInDegrees()

Retrieves the angle of North in a clockwise direction from the positive Y angle, in decimal degrees.

Returns:

Returns the angle of North, in decimal degrees (-180 to 180)

Type: number

getNorthAngleInRadians()

Retrieves the angle of North in a clockwise direction from the positive Y angle, in radians.

Returns:

Returns the angle of North, in radians (-PI to PI).

Type: number

getSeptemberEquinox()

Returns the September Equinox as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Returns:

Returns an object containing event data.

Type: object

getSkyColor()

Calculates the sky color at the current date and time.

This method uses the current sunrise/sunset times as well as the twilight stages of dawn and dusk to calculate a representative color for the sky.

Returns:

Returns a hexadecimal color value.

Type: number

getSolarHourAngleInDegreesUTC()

Retrieves the current solar hour angle offset in Universal Coordinated Time, corrected for time zone and daylight savings, in decimal degrees.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Returns:

Returns the UTC solar hour angle, in degrees.

Type: number

getSolarHourAngleInRadiansUTC()

Retrieves the current solar hour angle offset in Universal Coordinated Time, corrected for time zone and daylight savings, in radians.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Returns:

Returns the UTC solar hour angle, in radians.

Type: number

getSolarNoonTime()

Retrieves the local clock time when the Sun is directly overhead, in decimal hours.

Returns:

Returns the local clock time at solar noon, in decimal hours.

Type: number

getSolarPosition(center, radius)

Retrieves the current Sun position as a coordinate array relative to the given center point.

Parameters:

Name	Type	Description
`center`	Array	The position of the center point, given as a [x,y,z] coordinate array.
`radius`	number	The radius of the sphere on which the Sun path positions should sit.

Returns:

A 3D coordinate array in the form [x, y, z].

Type: Array

getSolarTime()

Retrieves the current solar time, in decimal hours.

Returns:

Returns the current solar time, in decimal hours (0.0 to 24.0).

Type: number

getSolarTimeUTC()

Retrieves the current solar time in Coordinated Universal Time, in decimal hours.

Returns:

Returns the current UTC solar time, in decimal hours (0.0 to 24.0).

Type: number

getSunAltitudeInDegrees()

Retrieves the altitude angle of the calculated Sun position, in decimal degrees above the horizon.

Returns:

Returns the altitude angle of the Sun, in decimal degrees.

Type: number

getSunAltitudeInRadians()

Retrieves the altitude angle of the calculated Sun position, in radians above the horizon.

Returns:

Returns the altitude angle of the Sun, in radians.

Type: number

getSunAnglesAsArray( [array])

Retrieves the azimuth and altitude angles of the Sun at the previously set date, time and location.

Parameters:

Name	Type	Argument	Description
`array`	Array	<optional>	An optional array to receive the two values.

Returns:

Returns an array with the first value being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

Type: Array

getSunAnglesAsObject( [obj])

Retrieves the azimuth and altitude angles of the Sun at the current date, time and location.

Parameters:

Name	Type	Argument	Description
`obj`	object	<optional>	An optional object on which to set the `azi` and `alt` properties.

Returns:

Returns an object with the 'azi' property being the solar azimuth (in decimal degrees clockwise from North), and the 'alt' property being solar altitude (in decimal degrees above the horizon).

Type: object

getSunAzimuthInDegrees()

Retrieves the azimuth angle of the calculated Sun position, in decimal degrees clockwise from North.

Returns:

Returns the azimuth angle of the Sun, in decimal degrees.

Type: number

getSunAzimuthInRadians()

Retrieves the azimuth angle of the calculated Sun position, in radians clockwise from North.

Returns:

Returns the azimuth angle of the Sun, in radians.

Type: number

getSunDirectionAsArray( [array])

Retrieves an [x,y,z] vector array giving the direction of the Sun at the current date, time and location.

NOTE: The vector returned by this method is also rotated by the the current North offset angle. To get a vector relative to North if there is a non-zero North offset angle, use the PD.SolarPosition#getSunDirectionFromNorthAsArray method.

Parameters:

Name	Type	Argument	Description
`array`	Array	<optional>	An optional [x,y,z] vector array to receive the results.

Returns:

Returns the given vector array, or a new one.

Type: Array

getSunDirectionAsObject(vector)

Retrieves a vector array giving the direction of the Sun at the previously set date, time and location.

NOTE: The vector returned by this method is also rotated by the the current North offset angle.

Parameters:

Name	Type	Description
`vector`	object	An object with {x,y,z} properties to receive the results.

Returns:

Returns the given vector object.

Type: object

getSunDirectionFromNorthAsArray( [array])

Retrieves an [x,y,z] vector array giving the direction of the Sun at the current date, time and location.

NOTE: The vector returned by this method is given relative to North. To get a vector in world coordinates if there is a non-zero North offset angle, use the PD.SolarPosition#getSunDirectionAsArray method.

Parameters:

Name	Type	Argument	Description
`array`	Array	<optional>	An optional [x,y,z] vector array to receive the results.

Returns:

Returns the given vector array, or a new one.

Type: Array

getSunDirectionFromNorthAsObject(vector)

Retrieves a vector array giving the direction of the Sun at the current date, time and location.

NOTE: The vector returned by this method is given relative to North. To get a vector in world coordinates if there is a non-zero North offset angle, use the getSunDirectionAsObject() method.

Parameters:

Name	Type	Description
`vector`	object	An object with {x,y,z} properties to receive the results.

Returns:

Returns the given vector object.

Type: object

getSunriseSunsetAsObjectArray(day_step [, array])

Retrieves an array of object containing sunrise/sunset and twilight data.

Each object in the array represents the data for a specific day, in the form:

{
    "dayOfYear": 90,
    "solarNoon": 12.366226227429355,
    "sunrise": 5.840749703399434,
    "sunset": 18.891702751459277,
    "civilDawn": 5.237202798554755,
    "civilDusk": 19.495249656303955,
    "nauticalDawn": 4.504181173134206,
    "nauticalDusk": 20.228271281724503,
    "astronomicalDawn": 3.7054231232068187,
    "astronomicalDusk": 21.02702933165189
}

Parameters:

Name	Type	Argument	Description
`day_step`	number		The increment step in days (1 to 90).
`array`	Array	<optional>	An optional existing array to append to.

Returns:

Returns an array of dawn/dusk objects.

Type: Array

getSunriseTime()

Retrieves the local clock time of sunrise on the current day, in decimal hours.

Returns:

Returns the local clock time of sunrise, in decimal hours.

Type: number

getSunsetTime()

Retrieves the local clock time of sunset on the current day, in decimal hours.

Returns:

Returns the local clock time at sunset, in decimal hours.

Type: number

getTimezone()

Retrieves the local time zone offset from UTC, in decimal hours.

Returns:

Returns the time zone offset in decimal hours (-14.0 to 14.0).

Type: number

getTimezoneAsString()

Retrieves the time zone in the format '+/-HH:mm'.

Returns:

Returns the time zone in the format '+/-HH:mm'.

Type: string

getTimezoneCorrection()

Retrieves the correction factor due to the difference between actual longitude and the references longitude (based on timezone), as well as daylight savings, in decimal hours.

Returns:

Returns the correction factor, in decimal hours.

Type: number

getYear()

Retrieves the year of the calculation as an integer (ie: 2014 or 2021).

Returns:

Returns the year of the calculation as an integer (-4712 to 3500).

Type: number

isLeapYear()

Determines if the current year is a leap year.

Returns:

Returns true if the current year is a leap year.

Type: boolean

now()

Creates a new solar position calculator with the current date, time, site location and sun position.

This method is effectively a shortcut to creating a new PD.SolarPosition instance with its date, time and location taken from PD.GlobalState.dateTime and PD.GlobalState.location.

Returns:

Returns a solar calculator with the current sun position.

Type: PD.SolarPosition

Example

/// Option 1: Using this method.
 const sun_pos = PD.SolarPosition.now();

 /// Option 2: Doing the same manually.
 const sun_pos = new PD.SolarPosition({
     latitude: PD.GlobalState.location.latitude,
     longitude: PD.GlobalState.location.longitude,
     timezone: PD.GlobalState.location.timezone,
     northAngle: PD.GlobalState.location.northAngle,
     clockTime: PD.GlobalState.dateTime.clockTime,
     dayOfYear: PD.GlobalState.dateTime.dayOfYear,
     year: PD.GlobalState.dateTime.year,
 }).calculate();

setClockTime(time)

Sets the local clock time at which to calculate, in decimal hours.

Parameters:

Name	Type	Description
`time`	number	The local clock time, in decimal hours (0.0 to 24.0).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setClockTimeUTC(time_utc)

Sets the time in Coordinated Universal Time (UTC), in decimal hours.

Parameters:

Name	Type	Description
`time_utc`	number	The time in Coordinated Universal Time (UTC), in decimal hours (0.0 to 24.0).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setDateFromJSDate(jsDate)

Sets only the day, month and year using the given Date() object.

Parameters:

Name	Type	Description
`jsDate`	object	A JavaScript Date() object containing the day, month and year for solar calculations.

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setDateTime(date_time)

Sets the day, month, year and local time using the given Date() object.

Parameters:

Name	Type	Description
`date_time`	PD.DateTime	An object containing the date and time for solar calculations.

Returns:

Returns this solar position instance to support method chaining.

Type: PD.SolarPosition

setDateTimeFromJSDate(jsDate)

Sets the day, month, year and local time using the given Date() object.

Parameters:

Name	Type	Description
`jsDate`	object	A JavaScript Date() object containing the date and time for solar calculations.

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setDayMonthYear(day_of_month, month_of_year, year)

Sets up the calculation for the given ordinal day and year.

This method simply pre-calculates a range of values that depend solely on the date and year, allowing subsequent time-based calculations on that date to be much faster and less involved.

Parameters:

Name	Type	Description
`day_of_month`	number	The ordinal day of the month (1-31).
`month_of_year`	number	The ordinal day of the year (0-11).
`year`	number	The four-digit year number (eg: 2010).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setDayOfMonth(day)

Sets the ordinal day of the month.

Parameters:

Name	Type	Description
`day`	number	The ordinal day of the month (1 to 31).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setDayOfYear(day [, year])

Sets the date based on the ordinal index of day within the year.

Parameters:

Name	Type	Argument	Description
`day`	number		The ordinal day of the year (0 to 364/5).
`year`	number	<optional>	An optional four-digit year number (eg: 2014 or 2021).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setLatitudeInDegrees(degrees)

Sets the geographic latitude relative to the equator, in decimal degrees.

Parameters:

Name	Type	Description
`degrees`	number	The new latitude in decimal degrees (-89.9 to 89.9).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setLatitudeInRadians(radians)

Sets the geographic latitude relative to the equator, in decimal degrees.

Parameters:

Name	Type	Description
`radians`	number	The new latitude in radians (-PI/2 to PI/2).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setLocation(latitude, longitude, timezone)

Sets the geographic location to calculate solar positions for.

Parameters:

Name	Type	Description
`latitude`	number	The geographic latitude relative to the equator, in decimal degrees (-180 to 180).
`longitude`	number	The geographic longitude relative to the prime meridian, in decimal degrees (-90 to 90).
`timezone`	number	The difference between local time at the location and UTC, in decimal hours (-13.0 to 13.0). The value should be positive for all time zone behind/east of UTC and negative for ahead/west.

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setLongitudeInDegrees(degrees)

Sets the geographic longitude relative to the prime meridian, in decimal degrees.

Parameters:

Name	Type	Description
`degrees`	number	The new longitude in decimal degrees (-180 to 180).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setLongitudeInRadians(radians)

Sets the geographic longitude relative to the prime meridian, in radians.

Parameters:

Name	Type	Description
`radians`	number	The new longitude in radians (-PI to PI).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setMonthOfYear(month)

Sets the ordinal month within the year.

Parameters:

Name	Type	Description
`month`	number	The ordinal month within the year (0 to 11).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setNorthAngleInDegrees(degrees)

Sets the angle of North in a clockwise direction from the positive Y angle, in decimal degrees.

Parameters:

Name	Type	Description
`degrees`	number	The angle of North in decimal degrees (-180 to 180).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setNorthAngleInRadians(radians)

Sets the angle of North in a clockwise direction from the positive Y angle, in radians.

Parameters:

Name	Type	Description
`radians`	number	The angle of North in radians (-PI to PI).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setSolarTime(time_solar)

Sets a new solar time, in decimal hours.

Parameters:

Name	Type	Description
`time_solar`	number	The new solar time, in decimal hours (0.0 to 24.0).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setSolarTimeUTC(time_solar_utc)

Sets a new solar time in Coordinated Universal Time, in decimal hours.

Parameters:

Name	Type	Description
`time_solar_utc`	number	The new UTC solar time, in decimal hours (0.0 to 24.0).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setTimeFromJSDate(jsDate)

Sets only the local time using the given Date() object.

Parameters:

Name	Type	Description
`jsDate`	number	A Date() object containing the time at which to calculate.

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setTimeOfDay(decimal_hours)

Sets the local time to calculate the Sun position.

Parameters:

Name	Type	Description
`decimal_hours`	number	The local time of the day, in decimal hours (0 to 24).

Returns:

Returns this solar calculator to support method chaining.

Type: PD.SolarPosition

setTimeOfDayAndGetArray(decimal_hours)

Sets the local time and returns the resulting Sun position.

This combination is provided to support some aspects of D3 charting.

Parameters:

Name	Type	Description
`decimal_hours`	number	The local time of the day, in decimal hours (0-24).

Returns:

Returns an array with the first value being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

Type: Array

setTimezone(hours)

Sets the local time zone offset from UTC, in decimal hours.

Parameters:

Name	Type	Description
`hours`	number	The time zone offset in decimal hours (-14.0 to 14.0).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

setYear(year)

Sets the year of the calculation as an integer (ie: 2014 or 2021).

Parameters:

Name	Type	Description
`year`	number	The year of the calculation as an integer (-4712 to 3500).

Returns:

Returns this solar position calculator to support method chaining.

Type: PD.SolarPosition

calcEquationOfTime(julian_centuries) <static>

Calculates the difference between apparent solar time and mean solar time.

The equation of time gives the relative offset of the analemma, a figure-8 curve representing the angular offset of the Sun from its mean position on the celestial sphere as viewed from Earth.

Parameters:

Name	Type	Description
`julian_centuries`	number	The number of Julian centuries since J2000.

Returns:

Returns the calculated equation of time, in minutes.

Type: number

calcJulianCenturies(day_of_year, year) <static>

Calculates the number of Julian centuries since J2000.

A Julian century represents 100 Julian years and is a unit of time defined as exactly 36525 days of 86,400 SI seconds each.

Parameters:

Name	Type	Description
`day_of_year`	number	The ordinal day of the year (0-364/5).
`year`	number	The four-digit year number (eg: 2010).

Returns:

Returns the number of Julian centuries since J2000, as a decimal.

Type: number

calcJulianCenturiesByMonth(day_of_month, month_of_year, year) <static>

Calculates the number of Julian centuries since J2000 using day, month and year.

A Julian century represents 100 Julian years and is a unit of time defined as exactly 36525 days of 86,400 SI seconds each.

Parameters:

Name	Type	Description
`day_of_month`	number	The ordinal day of the month (1-31).
`month_of_year`	number	The ordinal day of the year (0-11).
`year`	number	The four-digit year number (eg: 2010).

Returns:

Returns the number of Julian centuries since J2000, as a decimal.

Type: number

calcSolarDeclination(julian_centuries) <static>

Calculates the angle of the Sun relative to the celestial equator.

Declination in astronomy is comparable to geographic latitude on Earth, but projected onto out onto a larger celestial sphere.

Parameters:

Name	Type	Description
`julian_centuries`	number	The number of Julian centuries since J2000.

Returns:

Returns the calculated solar declination.

Type: number

Class: SolarPosition

new SolarPosition( [config])

Parameters:

Properties of config:

Members

clockTime

Type

clockTimeUTC

Type

dayOfMonth

Type

dayOfYear

Type

isSolarPosition <readonly>

Type

latitudeInDegrees

Type

latitudeInRadians

Type

longitudeInDegrees

Type

longitudeInRadians

Type

monthOfYear

Type

northAngleInDegrees

Type

northAngleInRadians

Type

solarTime

Type

solarTimeUTC

Type

timezone

Type

year

Type

Methods

_calculateDate()

calcDayOfYearIndex(day_of_month, month_of_year, year)

Parameters:

Returns:

calcDefaultTimezone(longitude)

Parameters:

Returns:

calculate()

Returns:

copy(sunPos)

Parameters:

Returns:

copyLocation(src)

Parameters:

Returns:

formatAsDate(day_of_year, year)

Parameters:

Returns:

formatAsDuration( [decimal_hours] [, seconds])

Parameters:

Returns:

formatAsTime( [decimal_hours] [, seconds])

Parameters:

Returns:

formatAsTimezone( [decimal_hours])

Parameters:

Returns:

generateAnnualSolarTables()

Returns:

generateDailySolarTables( [timeIncr])

Parameters:

Returns:

getAnalemmaSunAngles(day_step [, day_start] [, day_end])

Parameters:

Returns:

getAnalemmaSunPathAsPositions(day_step, center, radius)

Parameters:

Returns:

getClockTime()

Returns:

getClockTimeAsString()

Returns:

Properties of `config`: