com.askgeo.astronomy
Class Earth

java.lang.Object
  com.askgeo.astronomy.Earth

public class Earth
extends java.lang.Object

Provides the primary user-facing interface to the AskGeo Astronomy Library. The user should instantiate a single instance with the desired accuracy level. The library is thread safe, so a single Earth instance may be queried from several threads.

An Earth instance allows queries of the Sun and Moon related events that have taken place during a given time interval at a given location, as well as queries of the topocentric positions of the Sun and Moon from a given vantage point at a given time. The events that may be queried are enumerated in the ZenithEvent.Type enum. The topocentric coordinates that are returned include the azimuth, zenith, declination, right ascension, and distance to the body from the observer.

All times are in UTC milliseconds since 1970 (standard Unix time). Angles are in degrees. In general, the units of a given variable are included as a suffix in the variable name.

Constructor Summary

Earth(java.io.InputStream dataFileStream, Accuracy accuracy)
Constructs an Earth object with a given accuracy level.

Method Summary

void	authorize(java.io.File f) Authorizes the use of the object by providing a license file.
void	authorize(java.io.InputStream is) Authorizes the use of the object by providing a license file.
void	authorize(java.lang.String s) Authorizes the use of the object by providing a license String.
TopocentricCoordinates	moonTopocentricCoordinates(long msecsSince1970, double latDeg, double lonDeg, double heightM, boolean includeRefraction) Returns the topocentric coordinates of the Moon at the given time and at the given location.
ZenithEvent[]	moonZenithEvents(long startTimeMsecs, long endTimeMsecs, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEvent.Type[] types) Returns an array of ZenithEvent objects that occurred for the Moon during the given time interval and at the given location.
TopocentricCoordinates	sunTopocentricCoordinates(long msecsSince1970, double latDeg, double lonDeg, double heightM, boolean includeRefraction) Returns the topocentric coordinates of the Sun at the given time and at the given location.
ZenithEvent[]	sunZenithEvents(long startTimeMsecs, long endTimeMsecs, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEvent.Type[] types) Returns an array of ZenithEvent objects that occurred for the Sun during the given time interval and at the given location.

Methods inherited from class java.lang.Object

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

Constructor Detail

Earth

public Earth(java.io.InputStream dataFileStream,
             Accuracy accuracy)
      throws java.lang.Exception

Constructs an Earth object with a given accuracy level.

Parameters:

accuracy - is the accuracy level (e.g., LOW_ACCURACY, MEDIUM_ACCURACY, or HIGH_ACCURACY).

Throws:

java.lang.Exception

Method Detail

sunZenithEvents

public ZenithEvent[] sunZenithEvents(long startTimeMsecs,
                                     long endTimeMsecs,
                                     long maxTimeErrorMsecs,
                                     double latDeg,
                                     double lonDeg,
                                     double heightM,
                                     ZenithEvent.Type[] types)

Returns an array of ZenithEvent objects that occurred for the Sun during the given time interval and at the given location.

Parameters:

startTimeMsecs - is the start time of the closed interval in milliseconds since 1970.

endTimeMsecs - is the end time of the closed interval in milliseconds since 1970.

maxTimeErrorMsecs - is the convergence criterion used in the numerical search methods.

latDeg - is the latitude of the observer in degrees.

lonDeg - is the longitude of the observer in degrees.

heightM - is the height in meters above the geoid (i.e., theoretical sea level).

types - is an array of ZenithEvent.Type enum values for the events that the user wishes to be returned.

Returns:

an array of ZenithEvent objects that occurred for the Sun during the given time interval and at the given location.

moonZenithEvents

public ZenithEvent[] moonZenithEvents(long startTimeMsecs,
                                      long endTimeMsecs,
                                      long maxTimeErrorMsecs,
                                      double latDeg,
                                      double lonDeg,
                                      double heightM,
                                      ZenithEvent.Type[] types)

Returns an array of ZenithEvent objects that occurred for the Moon during the given time interval and at the given location.

Parameters:

startTimeMsecs - is the start time of the closed interval in milliseconds since 1970.

endTimeMsecs - is the end time of the closed interval in milliseconds since 1970.

maxTimeErrorMsecs - is the convergence criterion used in the numerical search methods.

latDeg - is the latitude of the observer in degrees.

lonDeg - is the longitude of the observer in degrees.

heightM - is the height in meters above the geoid (i.e., theoretical sea level).

types - is an array of ZenithEvent.Type enum values for the events that the user wishes to be returned.

Returns:

an array of ZenithEvent objects that occurred for the Moon during the given time interval and at the given location.

sunTopocentricCoordinates

public TopocentricCoordinates sunTopocentricCoordinates(long msecsSince1970,
                                                        double latDeg,
                                                        double lonDeg,
                                                        double heightM,
                                                        boolean includeRefraction)

Returns the topocentric coordinates of the Sun at the given time and at the given location.

Parameters:

msecsSince1970 - is the time to query in milliseconds since 1970.

latDeg - is the latitude of the observer in degrees.

lonDeg - is the longitude of the observer in degrees.

heightM - is the height in meters above the geoid (i.e., theoretical sea level).

includeRefraction - should be true to include atmospheric refraction in the model.

Returns:

a TopocentricCoordinates object that describes the azimuth, zenith, declination, right ascension and distance to the Sun from the given location at the given time.

moonTopocentricCoordinates

public TopocentricCoordinates moonTopocentricCoordinates(long msecsSince1970,
                                                         double latDeg,
                                                         double lonDeg,
                                                         double heightM,
                                                         boolean includeRefraction)

Returns the topocentric coordinates of the Moon at the given time and at the given location.

Parameters:

msecsSince1970 - is the time to query in milliseconds since 1970.

latDeg - is the latitude of the observer in degrees.

lonDeg - is the longitude of the observer in degrees.

heightM - is the height in meters above the geoid (i.e., theoretical sea level).

includeRefraction - should be true to include atmospheric refraction in the model.

Returns:

a TopocentricCoordinates object that describes the azimuth, zenith, declination, right ascension and distance to the Moon from the given location at the given time.

authorize

public void authorize(java.io.File f)
               throws java.io.IOException

Authorizes the use of the object by providing a license file.

Parameters:

f - the license file.

Throws:

java.io.IOException - if there are problems reading the file.

authorize

public void authorize(java.io.InputStream is)
               throws java.io.IOException

Authorizes the use of the object by providing a license file.

Parameters:

is - the input stream of the license file.

Throws:

java.io.IOException - if there are problems reading the stream.

authorize

public void authorize(java.lang.String s)

Authorizes the use of the object by providing a license String.

Parameters:

s - the license String.