org.hermit.astro
Class Observation

java.lang.Object
  extended by org.hermit.astro.Observation
All Implemented Interfaces:
AstroConstants

public class Observation
extends java.lang.Object
implements AstroConstants

This class represents a particular set of circumstances for a calculation, for example at a particular location and moment in time. It provides methods to access information about all the celestial bodies relating to this observation.

There may be multiple Observations in existence at one time, each one representing a particular set of circumstances -- for example, a particular time of observation. Each Observation has its own set of Body objects associated with it.


Nested Class Summary
static class Observation.OField
          This enumeration defines the data fields that are stored for each body.
 
Field Summary
 
Fields inherited from interface org.hermit.astro.AstroConstants
ABERRATION, AU, HALFPI, J1900, J1990, J2000, JD_UNIX, REFRACTION, SECS_PER_DAY, SIDEREAL_RATIO, SIDEREAL_YEAR, TROPICAL_YEAR, TWILIGHT, TWOPI, ε_2000
 
Constructor Summary
Observation()
          Create an observation for right now.
Observation(double jd)
          Create an observation for a given Julian day.
Observation(Instant i)
          Create an observation for a given Julian day.
Observation(Instant i, Position pos)
          Create an observation for a given Julian day.
Observation(long time)
          Create an observation for a given Java time.
Observation(long time, Position pos)
          Create an observation for a given Java time.
 
Method Summary
static java.lang.String angleAsDms(java.lang.Double ar)
          Deprecated. 
static java.lang.String angleAsHms(java.lang.Double ar)
          Deprecated. 
 void apparentEquatorialToEcliptic(double α, double δ, double[] pos)
          Convert apparent equatorial co-ordinates (right ascension and declination) to ecliptic co-ordinates for the circumstances of this Observation.
 void eclipticToApparentEquatorial(double λ, double β, double[] pos)
          Convert ecliptic co-ordinates to apparent equatorial co-ordinates (right ascension and declination) for the circumstances of this Observation.
 void eclipticToMeanEquatorial(double λ, double β, double[] pos)
          Convert ecliptic co-ordinates to mean equatorial co-ordinates (right ascension and declination) for the circumstances of this Observation.
 double get(Observation.OField key)
          Get the value of one of the data fields of this Observation.
 Body getBody(Body.Name which)
          Get the named celestial body.
 double getDaysSince(double epoch)
          Get the number of days since a given epoch.
 Moon getMoon()
          Get the Moon.
 double getObserverAltitude()
          Get the observer's altitude.
 Position getObserverPosition()
          Get the observer's geographical position.
 Planet getPlanet(Body.Name which)
          Get a planet.
 Sun getSun()
          Get the Sun.
 double getTd()
          Get the Julian date in TD of this Observation.
 Instant getTime()
          Get the time of this Observation.
 double getUt()
          Get the UT1 Julian date of this Observation.
protected  void invalidate()
          Invalidate all of the data caches associated with this Observation.
 void meanEquatorialToEcliptic(double α, double δ, double[] pos)
          Convert mean equatorial co-ordinates (right ascension and declination) to ecliptic co-ordinates for the circumstances of this Observation.
protected  void put(Observation.OField key, java.lang.Double val)
          Save a specified value in the data cache.
 void setDate(int y, int m, double d)
          Set the date / time of this Observation.
 void setJavaTime(long time)
          Set the time of this Observation.
 void setJulian(double jd)
          Set the time for calculations as a UTC Julian date.
 void setObserverAltitude(double alt)
          Set the observer's altitude for this observation.
 void setObserverPosition(Position pos)
          Set the observer's position for this observation.
 void setTime(Instant time)
          Set the time for calculations.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Observation

public Observation(Instant i)
Create an observation for a given Julian day.

Parameters:
i - The Instant of time for this observation.

Observation

public Observation(Instant i,
                   Position pos)
Create an observation for a given Julian day.

Parameters:
i - The Instant of time for this observation.
pos - The observer's geographical position.

Observation

public Observation(long time)
Create an observation for a given Java time.

Parameters:
time - Java-style time in milliseconds since 1 Jan, 1970.

Observation

public Observation(long time,
                   Position pos)
Create an observation for a given Java time.

Parameters:
time - Java-style time in milliseconds since 1 Jan, 1970.
pos - The observer's geographical position.

Observation

public Observation()
Create an observation for right now.


Observation

public Observation(double jd)
Create an observation for a given Julian day.

Parameters:
jd - The date to set as a Julian date relative to the astronomical epoch of 4713 BC UTC.
Method Detail

getTime

public Instant getTime()
Get the time of this Observation.

Returns:
The time of this Observation.

getUt

public double getUt()
Get the UT1 Julian date of this Observation.

Returns:
The configured Julian date relative to the astronomical epoch of 4713 BC UT1.

getTd

public double getTd()
Get the Julian date in TD of this Observation.

Note that we don't distinguish between TDT(TT) and TDB, which are always within 0.0017 seconds.

Returns:
The Julian date in TD, in days.

setTime

public void setTime(Instant time)
Set the time for calculations. This clears out any cached data we may have calculated.

Parameters:
time - The time to use for all calculations on this Observation.

setDate

public void setDate(int y,
                    int m,
                    double d)
Set the date / time of this Observation. This clears out any cached data we may have calculated.

Parameters:
y - Year number; BC years in astronomical form.
m - Month number; January = 1.
d - Day of the month, including the fraction of the day; e.g. 0.25 = 6 a.m.

setJavaTime

public void setJavaTime(long time)
Set the time of this Observation. This clears out any cached data we may have calculated.

Parameters:
time - Java-style time in milliseconds since 1 Jan, 1970.

setJulian

public void setJulian(double jd)
Set the time for calculations as a UTC Julian date. This clears out any cached data we may have calculated.

Parameters:
jd - The date to set as a Julian date relative to the astronomical epoch of 4713 BC UTC.

getDaysSince

public double getDaysSince(double epoch)
Get the number of days since a given epoch.

Parameters:
epoch - Epoch of interest (e.g. Instant.JD_1990).
Returns:
The number of days since the 1990 Jan 0.0 epoch.

getObserverPosition

public Position getObserverPosition()
Get the observer's geographical position.

Returns:
The observer's geographical position.

setObserverPosition

public void setObserverPosition(Position pos)
Set the observer's position for this observation. This clears out any cached data we may have calculated.

Parameters:
pos - The observer's geographical position.

getObserverAltitude

public double getObserverAltitude()
Get the observer's altitude.

Returns:
The observer's altitude above sea level in metres.

setObserverAltitude

public void setObserverAltitude(double alt)
Set the observer's altitude for this observation. This clears out any cached data we may have calculated.

Parameters:
alt - The observer's altitude above sea level in metres.

getBody

public Body getBody(Body.Name which)
Get the named celestial body. There is a single instance of each body associated with the set of observing circumstances represented by this Observation; we return a handle to that instance.

Bear in mind that there may be multiple Observations in use; each one has its own set of associated Body objects.

Parameters:
which - Which body to get.
Returns:
A handle on the instance of that body for this Observation.

getSun

public Sun getSun()
Get the Sun. There is a single instance of Sun associated with the set of observing circumstances represented by this Observation; we return a handle to that instance.

This is essentially a convenience routine which calls getBody() and casts the return to the correct type.

Returns:
A handle on the instance of the Sun for this Observation.

getMoon

public Moon getMoon()
Get the Moon. There is a single instance of Moon associated with the set of observing circumstances represented by this Observation; we return a handle to that instance.

This is essentially a convenience routine which calls getBody() and casts the return to the correct type.

Returns:
A handle on the instance of the Moon for this Observation.

getPlanet

public Planet getPlanet(Body.Name which)
Get a planet. There is a single instance of each planet associated with the set of observing circumstances represented by this Observation; we return a handle to that instance.

This is essentially a convenience routine which calls getBody() and casts the return to the correct type.

Parameters:
which - Which planet to get.
Returns:
A handle on the instance of the given planet for this Observation.

get

public double get(Observation.OField key)
Get the value of one of the data fields of this Observation.

Parameters:
key - The field we want.
Returns:
The field value.

put

protected void put(Observation.OField key,
                   java.lang.Double val)
Save a specified value in the data cache.

Parameters:
key - The name of the value to save.
val - The value.

invalidate

protected void invalidate()
Invalidate all of the data caches associated with this Observation.


eclipticToMeanEquatorial

public void eclipticToMeanEquatorial(double λ,
                                     double β,
                                     double[] pos)
Convert ecliptic co-ordinates to mean equatorial co-ordinates (right ascension and declination) for the circumstances of this Observation. This does not take nutation into account.

Note the returned ascension is in radians, not hours, for internal consistency.

From AA chapter 13.

Parameters:
λ - The ecliptic longitude, in radians.
β - The ecliptic latitude, in radians.
pos - An array { α, δ } in which the right ascension in radians and the declination in radians will be placed.

eclipticToApparentEquatorial

public void eclipticToApparentEquatorial(double λ,
                                         double β,
                                         double[] pos)
Convert ecliptic co-ordinates to apparent equatorial co-ordinates (right ascension and declination) for the circumstances of this Observation. This takes nutation into account -- so don't apply nutation to the returned values.

Note the returned ascension is in radians, not hours, for internal consistency.

From AA chapter 13.

Parameters:
λ - The ecliptic longitude, in radians.
β - The ecliptic latitude, in radians.
pos - An array { α, δ } in which the right ascension in radians and the declination in radians will be placed.

meanEquatorialToEcliptic

public void meanEquatorialToEcliptic(double α,
                                     double δ,
                                     double[] pos)
Convert mean equatorial co-ordinates (right ascension and declination) to ecliptic co-ordinates for the circumstances of this Observation. This does not take nutation into account.

Note the given ascension is in radians, not hours, for internal consistency.

From AA chapter 13.

Parameters:
α - The mean right ascension, in radians.
δ - The mean declination, in radians.
pos - An array { λ, β } in which the ecliptic longitude and the ecliptic latitude in radians will be placed.

apparentEquatorialToEcliptic

public void apparentEquatorialToEcliptic(double α,
                                         double δ,
                                         double[] pos)
Convert apparent equatorial co-ordinates (right ascension and declination) to ecliptic co-ordinates for the circumstances of this Observation. This takes nutation into account.

Note the given ascension is in radians, not hours, for internal consistency.

From AA chapter 13.

Parameters:
α - The mean right ascension, in radians.
δ - The mean declination, in radians.
pos - An array { λ, β } in which the ecliptic longitude and the ecliptic latitude in radians will be placed.

angleAsDms

@Deprecated
public static java.lang.String angleAsDms(java.lang.Double ar)
Deprecated. 

Format an angle as a string in degrees, minutes and seconds. From section 21 / 8.

Parameters:
ar - The angle to format, in radians.
Returns:
The angle formatted in degrees, minutes and seconds.

angleAsHms

@Deprecated
public static java.lang.String angleAsHms(java.lang.Double ar)
Deprecated. 

Format an angle as a string in hours, minutes and seconds. This is appropriate for a right ascension. From section 8.

Parameters:
ar - The angle to format, in radians.
Returns:
The angle formatted in hours, minutes and seconds.