Class CalendarAstronomer
CalendarAstronomer
is a class that can perform the calculations to
determine the positions of the sun and moon, the time of sunrise and
sunset, and other astronomy-related data. The calculations it performs
are in some cases quite complicated, and this utility class saves you
the trouble of worrying about them.
The measurement of time is a very important part of astronomy. Because
astronomical bodies are constantly in motion, observations are only valid
at a given moment in time. Accordingly, each CalendarAstronomer
object has a time
property that determines the date
and time for which its calculations are performed. You can set and
retrieve this property with setDate
, getDate
and related methods.
Almost all of the calculations performed by this class, or by any astronomer, are approximations to various degrees of accuracy. The calculations in this class are mostly modelled after those described in the book Practical Astronomy With Your Calculator, by Peter J. Duffett-Smith, Cambridge University Press, 1990. This is an excellent book, and if you want a greater understanding of how these calculations are performed it a very good, readable starting point.
WARNING: This class is very early in its development, and
it is highly likely that its API will change to some degree in the future.
At the moment, it basically does just enough to support IslamicCalendar
and ChineseCalendar
.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static interface
private static interface
static final class
Represents the position of an object in the sky relative to the ecliptic, the plane of the earth's orbit around the Sun.static final class
Represents the position of an object in the sky relative to the plane of the earth's equator.static final class
Represents the position of an object in the sky relative to the local horizon.private static class
private static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final CalendarAstronomer.SolarLongitude
Constant representing the autumnal equinox.static final long
The number of milliseconds in one day.private static final double
private double
(package private) static final long
Milliseconds value for 0.0 January 2000 AD.private long
static final CalendarAstronomer.MoonAge
Constant representing the moon's first quarter.private double
private double
static final CalendarAstronomer.MoonAge
Constant representing a full moon.static final int
The number of milliseconds in one hour.private static final double
(package private) static final double
static final long
The start of the julian day numbering scheme used by astronomers, which is 1/1/4713 BC (Julian), 12:00 GMT.private double
private double
static final CalendarAstronomer.MoonAge
Constant representing the moon's last quarter.private double
static final int
The number of milliseconds in one minute.(package private) static final double
(package private) static final double
private double
(package private) static final double
(package private) static final double
private double
(package private) static final double
(package private) static final double
(package private) static final double
private CalendarAstronomer.Equatorial
(package private) static final double
static final CalendarAstronomer.MoonAge
Constant representing a new moon.private static final double
private static final double
private static final double
private static final double
static final int
The number of milliseconds in one second.static final double
The number of standard hours in one sidereal day.static final double
The average number of days it takes for the moon to return to the same ecliptic longitude relative to the stellar background.static final double
The average number of days it takes for the sun to return to the same position against the fixed stellar background.private double
private double
static final double
The number of sidereal hours in one mean solar day.static final CalendarAstronomer.SolarLongitude
Constant representing the summer solstice.(package private) static final double
(package private) static final double
(package private) static final double
private double
static final double
The average number of solar days from one new moon to the next.private long
Current time in milliseconds since 1/1/1970 ADstatic final double
The average number number of days between successive vernal equinoxes.static final CalendarAstronomer.SolarLongitude
Constant representing the vernal equinox.static final CalendarAstronomer.SolarLongitude
Constant representing the winter solstice. -
Constructor Summary
ConstructorsConstructorDescriptionConstruct a newCalendarAstronomer
object that is initialized to the current date and time.CalendarAstronomer
(double longitude, double latitude) Construct a newCalendarAstronomer
object with the given latitude and longitude.CalendarAstronomer
(long aTime) Construct a newCalendarAstronomer
object that is initialized to the specified time.Construct a newCalendarAstronomer
object that is initialized to the specified date and time. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
private double
Return the obliquity of the ecliptic (the angle between the ecliptic and the earth's equator) at the current time.eclipticToEquatorial
(double eclipLong) Convert from ecliptic longitude to equatorial coordinates.eclipticToEquatorial
(double eclipLong, double eclipLat) Convert from ecliptic to equatorial coordinates.Convert from ecliptic to equatorial coordinates.eclipticToHorizon
(double eclipLong) getDate()
Get the current time of thisCalendarAstronomer
object, represented as aDate
object.double
Returns the current Greenwich sidereal time, measured in hoursdouble
Return this object's time expressed in julian centuries: the number of centuries after 1/1/1900 AD, 12:00 GMTdouble
Get the current time of thisCalendarAstronomer
object, expressed as a "julian day number", which is the number of elapsed days since 1/1/4713 BC (Julian), 12:00 GMT.double
Returns the current local sidereal time, measured in hoursdouble
The "age" of the moon at the time specified in this object.double
Calculate the phase of the moon at the time set in this object.The position of the moon at the time set on this object, in equatorial coordinates.long
getMoonRiseSet
(boolean rise) Returns the time (GMT) of sunrise or sunset on the local date to which this calendar is currently set.long
getMoonTime
(double desired, boolean next) Find the next or previous time at which the Moon's ecliptic longitude will have the desired value.long
getMoonTime
(CalendarAstronomer.MoonAge desired, boolean next) Find the next or previous time at which the moon will be in the desired phase.private double
double
The longitude of the sun at the time specified by this object.(package private) double[]
getSunLongitude
(double julian) TODO Make this public when the entire class is package-private.The position of the sun at this object's current date and time, in equatorial coordinates.long
getSunRiseSet
(boolean rise) Returns the time (GMT) of sunrise or sunset on the local date to which this calendar is currently set.long
getSunTime
(double desired, boolean next) Find the next time at which the sun's ecliptic longitude will have the desired value.long
getSunTime
(CalendarAstronomer.SolarLongitude desired, boolean next) Find the next time at which the sun's ecliptic longitude will have the desired value.long
getTime()
Get the current time of thisCalendarAstronomer
object, represented as the number of milliseconds since 1/1/1970 AD 0:00 GMT (Gregorian).local
(long localMillis) private long
lstToUT
(double lst) Converts local sidereal time to Universal Time.private static final double
norm2PI
(double angle) Normalize an angle so that it's in the range 0 - 2pi.private static final double
normalize
(double value, double range) Given 'value', add or subtract 'range' until 0 invalid input: '<'= 'value' invalid input: '<' range.private static final double
normPI
(double angle) Normalize an angle into the range -PI - PIprivate static String
radToDms
(double angle) private static String
radToHms
(double angle) private long
riseOrSet
(CalendarAstronomer.CoordFunc func, boolean rise, double diameter, double refraction, long epsilon) void
Set the current date and time of thisCalendarAstronomer
object.void
setJulianDay
(double jdn) Set the current date and time of thisCalendarAstronomer
object.void
setTime
(long aTime) Set the current date and time of thisCalendarAstronomer
object.private long
timeOfAngle
(CalendarAstronomer.AngleFunc func, double desired, double periodDays, long epsilon, boolean next) private double
trueAnomaly
(double meanAnomaly, double eccentricity) Find the "true anomaly" (longitude) of an object from its mean anomaly and the eccentricity of its orbit.
-
Field Details
-
SIDEREAL_DAY
public static final double SIDEREAL_DAYThe number of standard hours in one sidereal day. Approximately 24.93.- See Also:
-
SOLAR_DAY
public static final double SOLAR_DAYThe number of sidereal hours in one mean solar day. Approximately 24.07.- See Also:
-
SYNODIC_MONTH
public static final double SYNODIC_MONTHThe average number of solar days from one new moon to the next. This is the time it takes for the moon to return the same ecliptic longitude as the sun. It is longer than the sidereal month because the sun's longitude increases during the year due to the revolution of the earth around the sun. Approximately 29.53.- See Also:
-
SIDEREAL_MONTH
public static final double SIDEREAL_MONTHThe average number of days it takes for the moon to return to the same ecliptic longitude relative to the stellar background. This is referred to as the sidereal month. It is shorter than the synodic month due to the revolution of the earth around the sun. Approximately 27.32.- See Also:
-
TROPICAL_YEAR
public static final double TROPICAL_YEARThe average number number of days between successive vernal equinoxes. Due to the precession of the earth's axis, this is not precisely the same as the sidereal year. Approximately 365.24- See Also:
-
SIDEREAL_YEAR
public static final double SIDEREAL_YEARThe average number of days it takes for the sun to return to the same position against the fixed stellar background. This is the duration of one orbit of the earth about the sun as it would appear to an outside observer. Due to the precession of the earth's axis, this is not precisely the same as the tropical year. Approximately 365.25.- See Also:
-
SECOND_MS
public static final int SECOND_MSThe number of milliseconds in one second.- See Also:
-
MINUTE_MS
public static final int MINUTE_MSThe number of milliseconds in one minute.- See Also:
-
HOUR_MS
public static final int HOUR_MSThe number of milliseconds in one hour.- See Also:
-
DAY_MS
public static final long DAY_MSThe number of milliseconds in one day.- See Also:
-
JULIAN_EPOCH_MS
public static final long JULIAN_EPOCH_MSThe start of the julian day numbering scheme used by astronomers, which is 1/1/4713 BC (Julian), 12:00 GMT. This is given as the number of milliseconds since 1/1/1970 AD (Gregorian), a negative number. Note that julian day numbers and the Julian calendar are not the same thing. Also note that julian days start at noon, not midnight.- See Also:
-
EPOCH_2000_MS
static final long EPOCH_2000_MSMilliseconds value for 0.0 January 2000 AD.- See Also:
-
PI
private static final double PI- See Also:
-
PI2
private static final double PI2- See Also:
-
RAD_HOUR
private static final double RAD_HOUR- See Also:
-
DEG_RAD
private static final double DEG_RAD- See Also:
-
RAD_DEG
private static final double RAD_DEG- See Also:
-
JD_EPOCH
static final double JD_EPOCH- See Also:
-
SUN_ETA_G
static final double SUN_ETA_G- See Also:
-
SUN_OMEGA_G
static final double SUN_OMEGA_G- See Also:
-
SUN_E
static final double SUN_E- See Also:
-
VERNAL_EQUINOX
Constant representing the vernal equinox. For use withgetSunTime
. Note: In this case, "vernal" refers to the northern hemisphere's seasons. -
SUMMER_SOLSTICE
Constant representing the summer solstice. For use withgetSunTime
. Note: In this case, "summer" refers to the northern hemisphere's seasons. -
AUTUMN_EQUINOX
Constant representing the autumnal equinox. For use withgetSunTime
. Note: In this case, "autumn" refers to the northern hemisphere's seasons. -
WINTER_SOLSTICE
Constant representing the winter solstice. For use withgetSunTime
. Note: In this case, "winter" refers to the northern hemisphere's seasons. -
moonL0
static final double moonL0- See Also:
-
moonP0
static final double moonP0- See Also:
-
moonN0
static final double moonN0- See Also:
-
moonI
static final double moonI- See Also:
-
moonE
static final double moonE- See Also:
-
moonA
static final double moonA- See Also:
-
moonT0
static final double moonT0- See Also:
-
moonPi
static final double moonPi- See Also:
-
NEW_MOON
Constant representing a new moon. For use withgetMoonTime
-
FIRST_QUARTER
Constant representing the moon's first quarter. For use withgetMoonTime
-
FULL_MOON
Constant representing a full moon. For use withgetMoonTime
-
LAST_QUARTER
Constant representing the moon's last quarter. For use withgetMoonTime
-
time
private long timeCurrent time in milliseconds since 1/1/1970 AD- See Also:
-
fLongitude
private double fLongitude -
fLatitude
private double fLatitude -
fGmtOffset
private long fGmtOffset -
INVALID
private static final double INVALID- See Also:
-
julianDay
private transient double julianDay -
julianCentury
private transient double julianCentury -
sunLongitude
private transient double sunLongitude -
meanAnomalySun
private transient double meanAnomalySun -
moonLongitude
private transient double moonLongitude -
moonEclipLong
private transient double moonEclipLong -
eclipObliquity
private transient double eclipObliquity -
siderealT0
private transient double siderealT0 -
siderealTime
private transient double siderealTime -
moonPosition
-
-
Constructor Details
-
CalendarAstronomer
public CalendarAstronomer()Construct a newCalendarAstronomer
object that is initialized to the current date and time. -
CalendarAstronomer
Construct a newCalendarAstronomer
object that is initialized to the specified date and time. -
CalendarAstronomer
public CalendarAstronomer(long aTime) Construct a newCalendarAstronomer
object that is initialized to the specified time. The time is expressed as a number of milliseconds since January 1, 1970 AD (Gregorian).- See Also:
-
CalendarAstronomer
public CalendarAstronomer(double longitude, double latitude) Construct a newCalendarAstronomer
object with the given latitude and longitude. The object's time is set to the current date and time.- Parameters:
longitude
- The desired longitude, in degrees east of the Greenwich meridian.latitude
- The desired latitude, in degrees. Positive values signify North, negative South.- See Also:
-
-
Method Details
-
setTime
public void setTime(long aTime) Set the current date and time of thisCalendarAstronomer
object. All astronomical calculations are performed based on this time setting.- Parameters:
aTime
- the date and time, expressed as the number of milliseconds since 1/1/1970 0:00 GMT (Gregorian).- See Also:
-
setDate
Set the current date and time of thisCalendarAstronomer
object. All astronomical calculations are performed based on this time setting.- Parameters:
date
- the time and date, expressed as aDate
object.- See Also:
-
setJulianDay
public void setJulianDay(double jdn) Set the current date and time of thisCalendarAstronomer
object. All astronomical calculations are performed based on this time setting.- Parameters:
jdn
- the desired time, expressed as a "julian day number", which is the number of elapsed days since 1/1/4713 BC (Julian), 12:00 GMT. Note that julian day numbers start at noon. To get the jdn for the corresponding midnight, subtract 0.5.- See Also:
-
getTime
public long getTime()Get the current time of thisCalendarAstronomer
object, represented as the number of milliseconds since 1/1/1970 AD 0:00 GMT (Gregorian).- See Also:
-
getDate
Get the current time of thisCalendarAstronomer
object, represented as aDate
object.- See Also:
-
getJulianDay
public double getJulianDay()Get the current time of thisCalendarAstronomer
object, expressed as a "julian day number", which is the number of elapsed days since 1/1/4713 BC (Julian), 12:00 GMT.- See Also:
-
getJulianCentury
public double getJulianCentury()Return this object's time expressed in julian centuries: the number of centuries after 1/1/1900 AD, 12:00 GMT- See Also:
-
getGreenwichSidereal
public double getGreenwichSidereal()Returns the current Greenwich sidereal time, measured in hours -
getSiderealOffset
private double getSiderealOffset() -
getLocalSidereal
public double getLocalSidereal()Returns the current local sidereal time, measured in hours -
lstToUT
private long lstToUT(double lst) Converts local sidereal time to Universal Time.- Parameters:
lst
- The Local Sidereal Time, in hours since sidereal midnight on this object's current date.- Returns:
- The corresponding Universal Time, in milliseconds since 1 Jan 1970, GMT.
-
eclipticToEquatorial
public final CalendarAstronomer.Equatorial eclipticToEquatorial(CalendarAstronomer.Ecliptic ecliptic) Convert from ecliptic to equatorial coordinates.- Parameters:
ecliptic
- A point in the sky in ecliptic coordinates.- Returns:
- The corresponding point in equatorial coordinates.
-
eclipticToEquatorial
Convert from ecliptic to equatorial coordinates.- Parameters:
eclipLong
- The ecliptic longitudeeclipLat
- The ecliptic latitude- Returns:
- The corresponding point in equatorial coordinates.
-
eclipticToEquatorial
Convert from ecliptic longitude to equatorial coordinates.- Parameters:
eclipLong
- The ecliptic longitude- Returns:
- The corresponding point in equatorial coordinates.
-
eclipticToHorizon
-
getSunLongitude
public double getSunLongitude()The longitude of the sun at the time specified by this object. The longitude is measured in radians along the ecliptic from the "first point of Aries," the point at which the ecliptic crosses the earth's equatorial plane at the vernal equinox.Currently, this method uses an approximation of the two-body Kepler's equation for the earth and the sun. It does not take into account the perturbations caused by the other planets, the moon, etc.
-
getSunLongitude
double[] getSunLongitude(double julian) TODO Make this public when the entire class is package-private. -
getSunPosition
The position of the sun at this object's current date and time, in equatorial coordinates. -
getSunTime
public long getSunTime(double desired, boolean next) Find the next time at which the sun's ecliptic longitude will have the desired value. -
getSunTime
Find the next time at which the sun's ecliptic longitude will have the desired value. -
getSunRiseSet
public long getSunRiseSet(boolean rise) Returns the time (GMT) of sunrise or sunset on the local date to which this calendar is currently set. NOTE: This method only works well if this object is set to a time near local noon. Because of variations between the local official time zone and the geographic longitude, the computation can flop over into an adjacent day if this object is set to a time near local midnight. -
getMoonPosition
The position of the moon at the time set on this object, in equatorial coordinates. -
getMoonAge
public double getMoonAge()The "age" of the moon at the time specified in this object. This is really the angle between the current ecliptic longitudes of the sun and the moon, measured in radians.- See Also:
-
getMoonPhase
public double getMoonPhase()Calculate the phase of the moon at the time set in this object. The returned phase is adouble
in the range0 invalid input: '<'= phase invalid input: '<' 1
, interpreted as follows:- 0.00: New moon
- 0.25: First quarter
- 0.50: Full moon
- 0.75: Last quarter
- See Also:
-
getMoonTime
public long getMoonTime(double desired, boolean next) Find the next or previous time at which the Moon's ecliptic longitude will have the desired value.- Parameters:
desired
- The desired longitude.next
- true if the next occurrance of the phase is desired, false for the previous occurrance.
-
getMoonTime
Find the next or previous time at which the moon will be in the desired phase.- Parameters:
desired
- The desired phase of the moon.next
- true if the next occurrance of the phase is desired, false for the previous occurrance.
-
getMoonRiseSet
public long getMoonRiseSet(boolean rise) Returns the time (GMT) of sunrise or sunset on the local date to which this calendar is currently set. -
timeOfAngle
private long timeOfAngle(CalendarAstronomer.AngleFunc func, double desired, double periodDays, long epsilon, boolean next) -
riseOrSet
private long riseOrSet(CalendarAstronomer.CoordFunc func, boolean rise, double diameter, double refraction, long epsilon) -
normalize
private static final double normalize(double value, double range) Given 'value', add or subtract 'range' until 0 invalid input: '<'= 'value' invalid input: '<' range. The modulus operator. -
norm2PI
private static final double norm2PI(double angle) Normalize an angle so that it's in the range 0 - 2pi. For positive angles this is just (angle % 2pi), but the Java mod operator doesn't work that way for negative numbers.... -
normPI
private static final double normPI(double angle) Normalize an angle into the range -PI - PI -
trueAnomaly
private double trueAnomaly(double meanAnomaly, double eccentricity) Find the "true anomaly" (longitude) of an object from its mean anomaly and the eccentricity of its orbit. This uses an iterative solution to Kepler's equation.- Parameters:
meanAnomaly
- The object's longitude calculated as if it were in a regular, circular orbit, measured in radians from the point of perigee.eccentricity
- The eccentricity of the orbit- Returns:
- The true anomaly (longitude) measured in radians
-
eclipticObliquity
private double eclipticObliquity()Return the obliquity of the ecliptic (the angle between the ecliptic and the earth's equator) at the current time. This varies due to the precession of the earth's axis.- Returns:
- the obliquity of the ecliptic relative to the equator, measured in radians.
-
clearCache
private void clearCache() -
local
-
radToHms
-
radToDms
-