API Docs

Class: Location

PD. Location

Defines a terrestrial location on the Earth's surface.

The primary components of a terrestrial location are its latitude, longitude, timezone and North offset angle. An elevation can also be specified, but this has only a minimal effect on solar and energy calculations.

new Location( [config])

Creates a terrestrial location on the Earth's surface.

NOTE: This defaults to Greenwich Royal Observatory in England.

Parameters:
Name Type Argument Description
config object <optional>

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

An optional geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number <optional>

An optional geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
timezone number <optional>

An optional local time zone at the current location, in decimal hours.
northAngle number <optional>

An optional angle between north and the +Y axis, in decimal degrees.
elevation number <optional>

An optional average height of the site above sea level, in metres.
Author:
  • drajmarsh

Members

:number

elevation

The average height of the site above sea level, in metres.

Type
  • number
:boolean

isLocation <readonly>

A flag identifying this object as a location.

Type
  • boolean
:number

latitude

The terrestrial latitude of the current location, in decimal degrees.

Type
  • number
:number

longitude

The terrestrial longitude of the current location, in decimal degrees.

Type
  • number
:number

northAngle

The angle between north and the +Y axis, in decimal degrees.

Type
  • number
:number

timezone

The local time zone at the current location, in decimal hours.

Type
  • number

Methods

closeTo(latitude, longitude [, timezone])

Determines if this location is sufficiently close to the given location to be considered effectively equal.

This method checks if the given latitude and longitude values are within 1e-6 degrees of this location, and that the timezone (if given) is within 1 minute of this location's timezone. A threshold of 1e-6 degrees represents a terrestrial distance of about 0.1 metre (4 inches) at sea level.

Parameters:
Name Type Argument Description
latitude number

The geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
timezone number <optional>

The timezone in decimal hours (-12 to +13), ignored if not given.
Returns:

Returns true if the given values are very close (within 1e-6 degrees).

Type
boolean

copy(from)

Copy the given location to this location.

Parameters:
Name Type Description
from PD.Location

Another location instance to copy from.
Returns:

Returns this location instance to support method chaining.

Type
PD.Location

distanceTo(loc)

Estimates the terrestrial distance to the given location on the Earth's surface.

This uses the static PD.Location.terrestrialDistance method which is based on the haversine formula for calculating the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface 'as-the-crow-flies' between the two locations, ignoring any hills or valleys they may fly over.

Parameters:
Name Type Description
loc PD.Location

The target location.
Returns:

Returns the computed distance 'as-the-crow-flies' over the Earth's surface, in metres.

Type
number

distanceToLatLng(latitude, longitude)

Estimates the terrestrial distance to the given location on the Earth's surface.

This uses the static PD.Location.terrestrialDistance method which is based on the haversine formula for calculating the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface 'as-the-crow-flies' between the two locations, ignoring any hills or valleys they may fly over.

Parameters:
Name Type Description
latitude number

The target geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The target geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
Returns:

Returns the computed distance 'as-the-crow-flies' over the Earth's surface, in metres.

Type
number

fromJSON(data)

Extracts location information from the given object.

Parameters:
Name Type Description
data object

An object that might contain location information.
Properties of data:
Name Type Argument Description
latitude number <optional>

An optional terrestrial latitude of the current location, in decimal degrees.
longitude number <optional>

An optional terrestrial longitude of the current location, in decimal degrees.
timezone number <optional>

An optional local time zone at the current location, in decimal hours
northAngle number <optional>

An optional angle between north and the +Y axis, in decimal degrees.
elevation number <optional>

An optional average height of the site above sea level, in metres.
Returns:

Returns true if any matching data was found, or false if nothing was copied.

set(latitude, longitude, timezone)

Sets the geographic location to calculate solar positions for.

Parameters:
Name Type Description
latitude number

The geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
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.Location

toJSON( [data])

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object

JSONSchema() <static>

Retrieves the JSON schema for a location object.

Returns:

Returns a JSON schema object.

Type
object

computeTimezone(latitude, longitude) <static>

Calculates a time zone from geographic location.

This method checks for PD.TimeZones and, if available, does a detailed lookup. If not available, it does a simple estimation based only on longitude.

Parameters:
Name Type Description
latitude number

The geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
Returns:

Returns the difference between local time at the location and UTC in decimal hours (-13 to +13),

Type
number

getSiteLocation() <static>

Retrieves the global geographic location used for the current site.

This method returns the PD.GlobalState.location object that is used by several other classes as the default location for the current site.

Returns:

Returns the global default site location object.

Type
PD.Location

terrestrialDistance(lat1, lng1, lat2, lng2) <static>

Estimates the terrestrial distance between the two locations on the Earth's surface.

This uses the haversine formula to calculate the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface 'as-the-crow-flies' between the two locations, ignoring any hills or valleys they may fly over.

Parameters:
Name Type Description
lat1 number

The start geographic latitude above the equator, in decimal degrees (-90 to 90).
lng1 number

The start geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
lat2 number

The end geographic latitude above the equator, in decimal degrees (-90 to 90).
lng2 number

The end geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
See:
Returns:

Returns the computed distance 'as-the-crow-flies' over the Earth's surface, in metres.

Type
number