Astronomy Database

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.

class Earth {

 Earth(InputStream dataFileStream, Accuracy accuracy)

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

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

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

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

// Additional methods exist in this class; for complete documentation, please see the Full Java Docs

}

The topocentric coordinates of a astronomical body are expressed in terms of an observer on the surface of the Earth at a given location at a given time. This object includes the azimuth (degrees), zenith (degrees), declination (degrees), right ascension (hours), and distance (astronomical units, AU).

The members of an instance are immutable and the constructor is not public. Instances of this class are returned by methods in the Earth class and can only be used by users in a read-only capacity.

The coordinates in this object may or may not include atmospheric refraction, depending on the parameters passed to the method that creates it. Please see the Earth class for more details.

class TopocentricCoordinates {

double getAzimuthDeg()

double getZenithDeg()

double getRightAscensionHours()

double getDeclinationDeg()

double getDistanceAu()

}

A ZenithEvent object represents one of several particular and meaningful moments in the course of an astronomical body's passage across the celestial sphere of an observer. These include the rising and setting of the object in addition to a number of other important moments.

A full list of the zenith event types and their descriptions are given in the Java enumeration ZenithEvent.Type.

The elevation (also known as altitude) of an astronomical body is the complement of the zenith and represents the angle above the horizon of the body.

It should be noted that in polar regions of the globe some of these events do not occur for months at a time. The only events that occur every day at every location on the globe are MIN_ELEVATION and MAX_ELEVATION.

class ZenithEvent {

double getElevationDeg()

long getTimeMsecs()

ZenithEvent.Type getEventType()

String toString()

}

The accuracy of a new Earth instance is specified with this enumeration. Higher accuracy comes at the cost of longer computation times. The lowest accuracy is sufficient for most purposes.

The primary difference between the accuracy levels is in the number of terms used to represent the nutation of the Earth (described in each value below). In addition, the low and medium accuracy modes are less accurate in computing:

• the complementary terms of the equation of the equinoxes
• the geocentric position of a solar system body, as antedated for light-time
• the total gravitational deflection of light for the observed body due to the major gravitating bodies in the solar system

The enumerated values are as follows:

LOW_ACCURACY

Uses the IAU 2000B nutation model that includes 77-terms and is accurate to about 1 milliarcsecond.

MEDIUM_ACCURACY

Uses the IAU 2000K nutation model that includes the largest 488 terms from the IAU 2000A model and is accurate to about 0.1 milliarcseconds.

HIGH_ACCURACY

Uses the IAU 2000A nutation model that includes 1,365 terms and is the most accurate model we make available.

Again, as the medium and high accuracy modes are more computationally expensive, it is important to emphasize that in most cases, the LOW_ACCURACY accuracy level will be sufficient.

The ZenithEvent.Type enumerates the event types that mark important moments in the course of astronomical body's passage across the celestial sphere of an observer.

The enumerated values are listed in the JavaDocs

The following is a complete example program demonstrating the use of the Ask Geo Astronomy Java Library. It prints the sunrise and sunset times for the next 48 hours near San Francisco (latitude: 37 degrees, longitude: -122 degrees).

import com.askgeo.astronomy.*;
import java.io.FileInputStream;

public class AstronomyExample {
    static String license = "INSERT YOUR LICENSE STRING HERE";
    static String dataFilePath = "askgeo-astronomy-1.1.0.dat";

    public static void main(String[] args) {
        ZenithEvent.Type[] types = {
                ZenithEvent.Type.RISE_UPPER_LIMB,
                ZenithEvent.Type.SET_UPPER_LIMB
        };

        try {
            Earth earth = new Earth(new FileInputStream(dataFilePath), Accuracy.LOW_ACCURACY);
            earth.authorize(license);

            long start = System.currentTimeMillis();
            long end = start + 48L * 3600L * 1000L; // 48 hours later
            double latDeg = 37.0;
            double lonDeg = -122.0;
            double heightM = 0.0;

            ZenithEvent[] events = earth.sunZenithEvents(start, end, 1000L, latDeg, lonDeg, heightM, types);

            for (ZenithEvent event : events) {
                System.out.println(event.toString());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

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 (as static public members) in the ZenithEventType class. The topocentric coordinates that are returned include the azimuth, zenith, declination, right ascension, and distance to the body from the observer.

All times are as .NET DateTime objects. Angles are in degrees. In general, the units of a given variable are included as a suffix in the variable name.

class Earth {

 Earth(Accuracy accuracy)

ZenithEvent[] GetSunZenithEvents(DateTime start, DateTime end, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEventType[] types)

ZenithEvent[] GetMoonZenithEvents(DateTime start, DateTime end, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEventType[] types)

TopocentricCoordinates GetSunTopocentricCoordinates(DateTime dateTime, double latDeg, double lonDeg, double heightM, boolean includeRefraction)

TopocentricCoordinates GetMoonTopocentricCoordinates(DateTime dateTime, double latDeg, double lonDeg, double heightM, boolean includeRefraction)

// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs

}

The topocentric coordinates of a astronomical body are expressed in terms of an observer on the surface of the Earth at a given location at a given time. This object includes the azimuth (degrees), zenith (degrees), declination (degrees), right ascension (hours), and distance (astronomical units, AU).

The members of an instance are immutable and the constructor is not public. Instances of this class are returned by methods in the Earth class and can only be used by users in a read-only capacity.

The coordinates in this object may or may not include atmospheric refraction, depending on the parameters passed to the method that creates it. Please see the Earth class for more details.

class TopocentricCoordinates {

double GetAzimuthDeg()

double GetZenithDeg()

double GetRightAscensionHours()

double GetDeclinationDeg()

double GetDistanceAu()

}

A ZenithEvent object represents one of several particular and meaningful moments in the course of an astronomical body's passage across the celestial sphere of an observer. These include the rising and setting of the object in addition to a number of other important moments.

A full list of the zenith event types and their descriptions are given in the static public members of the ZenithEventType class.

The elevation (also known as altitude) of an astronomical body is the complement of the zenith and represents the angle above the horizon of the body.

It should be noted that in polar regions of the globe some of these events do not occur for months at a time. The only events that occur every day at every location on the globe are MinElevation and MaxElevation.

class ZenithEvent {

double GetElevationDeg()

DateTime GetDateTime()

ZenithEventType GetEventType()

String ToString()

// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs

}

The accuracy of a new Earth instance is specified with this enumeration. Higher accuracy comes at the cost of longer computation times. The lowest accuracy is sufficient for most purposes.

The primary difference between the accuracy levels is in the number of terms used to represent the nutation of the Earth (described in each value below). In addition, the low and medium accuracy modes are less accurate in computing:

• the complementary terms of the equation of the equinoxes
• the geocentric position of a solar system body, as antedated for light-time
• the total gravitational deflection of light for the observed body due to the major gravitating bodies in the solar system

The enumerated values are as follows:

LowAccuracy

Uses the IAU 2000B nutation model that includes 77-terms and is accurate to about 1 milliarcsecond.

MediumAccuracy

Uses the IAU 2000K nutation model that includes the largest 488 terms from the IAU 2000A model and is accurate to about 0.1 milliarcseconds.

HighAccuracy

Uses the IAU 2000A nutation model that includes 1,365 terms and is the most accurate model we make available.

Again, as the medium and high accuracy modes are more computationally expensive, it is important to emphasize that in most cases, the LowAccuracy accuracy level will be sufficient.

The ZenithEventType enumerates (as static public members) the event types that mark important moments in the course of astronomical body's passage across the celestial sphere of an observer.

The static public members (enumerated values) are listed in the .NET docs

The following is a complete example program demonstrating the use of the Ask Geo Astronomy .NET Library. It prints the sunrise and sunset times for the next 48 hours near San Francisco (latitude: 37 degrees, longitude: -122 degrees).

using System;
using System.IO;
using AskGeo.Astronomy;

class Astronomy {
    static void Main(string[] args) {
        String license = "INSERT YOUR LICENSE STRING HERE";
        String dataFilePath = @"askgeo-astronomy-1.1.0.dat";
        
        ZenithEventType[] types = {
                ZenithEventType.RiseUpperLimb,
                ZenithEventType.SetUpperLimb
        };

        Earth earth = new Earth(new FileStream(dataFilePath, FileMode.Open), Accuracy.LowAccuracy);
        earth.Authorize(license);

        DateTime start = DateTime.Now;
        DateTime end = start.AddDays(2.0);
        double latDeg = 37.0;
        double lonDeg = -122.0;
        double heightM = 0.0;

        ZenithEvent[] events = earth.GetSunZenithEvents(start, end, 1000L, latDeg, lonDeg, heightM, types);

        foreach (ZenithEvent zenithEvent in events) {
            Console.WriteLine(zenithEvent.ToString());
        }
    }
}