org.geotoolkit.nature
Class SunRelativePosition

Object
  SunRelativePosition

public class SunRelativePosition
extends Object

Computes Sun apparent position relative to an observer on Earth. This class expects spatio-temporal coordinate input as below:

Observer longitude (decimal degrees on WGS84 ellipsoid) Observer latitude (decimal degrees on WGS84 ellipsoid) Date and time in GMT The calculated Sun position contains: Sun azimuth (decimal degrees, 0° toward north, increasing clockwise) Sun elevation (decimal degrees, 0° toward horizon)

Reference
This class is an adaptation of the Solar Position Calculator written in JavaScript by the National Oceanic and Atmospheric Administration (NOAA), Surface Radiation Research Branch.

The approximations used in these programs are very good for years between 1800 and 2100. Results should still be sufficiently accurate for the range from -1000 to 3000. Outside of this range, results will be given, but the potential for error is higher.

Since:

2.0

Version:

3.00

Author:

Rémi Eve (IRD), Martin Desruisseaux (IRD)

Module:

analytics/geotk-nature (download)

View source code for this class

Field Summary

static double	ASTRONOMICAL_TWILIGHT Elevation angle of astronomical twilight, in degrees.
static double	CIVIL_TWILIGHT Elevation angle of civil twilight, in degrees.
static double	NAUTICAL_TWILIGHT Elevation angle of nautical twilight, in degrees.

Constructor Summary

SunRelativePosition()
Constructs a sun relative position calculator.

SunRelativePosition(double twilight)
Constructs a sun relative position calculator with the specified value for the sun elevation at twilight.

Method Summary

double	getAzimuth() Computes and returns the azimuth.
Point2D	getCoordinate() Returns the coordinate used for elevation and azimuth computation.
Date	getDate() Returns the date used for elevation and azimuth computation.
double	getElevation() Computes and returns the elevation.
Date	getNoonDate() Returns the date and time at which the Sun is at its highest during a day.
long	getNoonTime() Returns the time at which the Sun is at its highest during a day.
double	getTwilight() Returns the sun's elevation angle at twilight, in degrees.
static void	main(String[] args) Prints the Sun position at the given coordinates and date.
void	setCoordinate(double longitude, double latitude) Sets the geographic coordinate where to compute the elevation and azimuth.
void	setCoordinate(Point2D point) Sets the geographic coordinate where to compute the elevation and azimuth.
void	setDate(Date date) Sets the date and time when to compute the elevation and azimuth.
void	setTwilight(double twilight) Sets the sun's elevation angle at twilight, in degrees.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ASTRONOMICAL_TWILIGHT

public static final double ASTRONOMICAL_TWILIGHT

Elevation angle of astronomical twilight, in degrees. Astronomical twilight is the time of morning or evening when the sun is 18° below the horizon (solar elevation angle of -18°).

See Also:

Constant Field Values

NAUTICAL_TWILIGHT

public static final double NAUTICAL_TWILIGHT

Elevation angle of nautical twilight, in degrees. Nautical twilight is the time of morning or evening when the sun is 12° below the horizon (solar elevation angle of -12°).

See Also:

Constant Field Values

CIVIL_TWILIGHT

public static final double CIVIL_TWILIGHT

Elevation angle of civil twilight, in degrees. Civil twilight is the time of morning or evening when the sun is 6° below the horizon (solar elevation angle of -6°).

See Also:

Constant Field Values

Constructor Detail

SunRelativePosition

public SunRelativePosition()

Constructs a sun relative position calculator.

SunRelativePosition

public SunRelativePosition(double twilight)
                    throws IllegalArgumentException

Constructs a sun relative position calculator with the specified value for the sun elevation at twilight.

Parameters:

twilight - The new sun elevation at twilight, or Double.NaN if no twilight value should be taken in account.

Throws:

IllegalArgumentException - if the twilight value is illegal.

Method Detail

setCoordinate

public void setCoordinate(double longitude,
                          double latitude)

Sets the geographic coordinate where to compute the elevation and azimuth.

Parameters:

longitude - The longitude in degrees. Positive values are East; negative values are West.

latitude - The latitude in degrees. Positive values are North, negative values are South.

setCoordinate

public void setCoordinate(Point2D point)

Sets the geographic coordinate where to compute the elevation and azimuth. This is the observer location on Earth, assuming a WGS84 ellipsoid.

Parameters:

point - The geographic coordinates in degrees of longitude and latitude.

getCoordinate

public Point2D getCoordinate()

Returns the coordinate used for elevation and azimuth computation. This is the coordinate specified during the last call to a setCoordinate(...) method.

Returns:

The observer location on Earth (WGS84 ellipsoid).

setDate

public void setDate(Date date)

Sets the date and time when to compute the elevation and azimuth.

Parameters:

date - The date and time (GMT).

getDate

public Date getDate()

Returns the date used for elevation and azimuth computation. This is the date specified during the last call to setDate(Date).

Returns:

The date and time (GMT).

setTwilight

public void setTwilight(double twilight)
                 throws IllegalArgumentException

Sets the sun's elevation angle at twilight, in degrees. Common values are defined for the astronomical twilight (-18°), nautical twilight (-12°) and civil twilight (-6°). The elevation and azimuth are set to NaN when the sun elevation is below the twilight value (i.e. during night). The default value is CIVIL_TWILIGHT.

Parameters:

twilight - The new sun elevation at twilight, or Double.NaN if no twilight value should be taken in account.

Throws:

IllegalArgumentException - if the twilight value is illegal.

getTwilight

public double getTwilight()

Returns the sun's elevation angle at twilight, in degrees. This is the value set during the last call to setTwilight(double).

Returns:

The Sun's elevation angle at twilight (decimal degrees).

getAzimuth

public double getAzimuth()

Computes and returns the azimuth.

Returns:

The azimuth (decimal degrees, 0° toward north, increasing clockwise).

getElevation

public double getElevation()

Computes and returns the elevation.

Returns:

The elevation (decimal degrees, 0° toward horizon).

getNoonTime

public long getNoonTime()

Returns the time at which the Sun is at its highest during a day.

Returns:

The time at which the Sun is at its highest, in milliseconds since midnight GMT.

getNoonDate

public Date getNoonDate()

Returns the date and time at which the Sun is at its highest during a day. This is equivalent to getNoonTime() except that the day is included in the returned date.

Returns:

The date and time at which the Sun is at its highest.

main

public static void main(String[] args)
                 throws ParseException

Prints the Sun position at the given coordinates and date. This application can be launch from the command line as below:

java org.geotoolkit.nature.SunRelativePosition [longitude] [latitude] [date]

where date is an optional argument specifying the date and time in the "yyyy-MM-dd HH:mm:ss" format, UTC time zone. If this argument is omitted, then the current time is used.

Parameters:

args - The command line argument.

Throws:

ParseException - If the date or an ordinate is not properly formatted.