edu.nrao.sss.astronomy
Class SolarSystemBodyPosition

java.lang.Object
  edu.nrao.sss.astronomy.SolarSystemBodyPosition

All Implemented Interfaces:

SkyPosition, SphericalPosition, Cloneable

public class SolarSystemBodyPosition
extends Object
implements SkyPosition

Position information for a solar system body.

Version Info:

$Revision: 1256 $

$Date: 2008-04-29 15:55:50 -0600 (Tue, 29 Apr 2008) $

$Author: dharland $

Since:

2007-04-18

Author:

David M. Harland

Constructor Summary

SolarSystemBodyPosition(String nameOfBody)
Creates a new instance.

Method Summary

SolarSystemBodyPosition	clone() Returns a copy of this body.
boolean	equals(Object o) Returns true if o is equal to this body.
Angle	getAngularSeparation(SphericalPosition other) Calculates the current angular separation between this position and other.
Angle	getAngularSeparation(SphericalPosition other, Date time) Calculates current angular separation between this position and other at the given time.
String	getBodyName() Returns the name of the solar system body this position represents.
CelestialCoordinateSystem	getCoordinateSystem() Returns the coordinate system to use when interpreting the latitude and longitude values of this position.
Distance	getDistance() Returns the current distance of this position.
Distance	getDistance(Date time) Returns the distance of this position at the given point in time.
Distance	getDistanceUncertainty() Returns the uncertainty in the distance of this position.
Epoch	getEpoch() Returns the epoch on which this position is based.
Latitude	getLatitude() Returns the current latitude of this position.
Latitude	getLatitude(Date time) Returns the latitude of this position at the given point in time.
Latitude	getLatitudeUncertainty() Returns the uncertainty in the latitude of this position.
Longitude	getLongitude() Returns the current longitude of this position.
Longitude	getLongitude(Date time) Returns the longitude of this position at the given point in time.
Longitude	getLongitudeUncertainty() Returns the uncertainty in the longitude of this position.
String	getOriginOfInformation() Returns the origin of this position's information.
TimeDuration	getRefreshRate() Returns a copy of this position's refresh rate (see setRefreshRate(TimeDuration) for a description).
SkyPositionType	getType() Provides a hint as to how this position stores its information.
int	hashCode() Returns a hash code value for this body.
boolean	isMoving() Returns true if this position has different properties at time T than it does at time U ≠ T.
void	reset() Resets the internals of this position, except for its body name.
void	setLocator(SourceLocator newLocator) Sets the locator that this position will use for determining the location of the object whose name is given by getBodyName().
void	setRefreshRate(TimeDuration newRate) Sets the refresh rate for this position to newRate.
SkyPosition	toPosition(CelestialCoordinateSystem system, Epoch epoch, EarthPosition observer, LocalSiderealTime lst) Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position.
SkyPosition	toPosition(CelestialCoordinateSystem system, Epoch epoch, EarthPosition observer, LocalSiderealTime lst, CelestialCoordinateConverter converter) Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SolarSystemBodyPosition

public SolarSystemBodyPosition(String nameOfBody)

Creates a new instance.

Method Detail

reset

public void reset()

Resets the internals of this position, except for its body name.

getBodyName

public String getBodyName()

Returns the name of the solar system body this position represents.

Returns:

the name of the solar system body this position represents.

setLocator

public void setLocator(SourceLocator newLocator)

Sets the locator that this position will use for determining the location of the object whose name is given by getBodyName(). If newLocator is null, this method does nothing.

Parameters:

newLocator - the locator to use for getting position information for this body.

setRefreshRate

public void setRefreshRate(TimeDuration newRate)

Sets the refresh rate for this position to newRate. If newRate is null, the refresh rate will be set to zero.

The refresh rate refers to the amount of time that must pass before this position will request new information from its source locator. Each time the source locator is successfully queried, the position and time of the query are cached. If a subsequent request is made in the interval [queryTime...queryTime + newRate] (or in the interval [queryTime - newRate...queryTime], the reported position is the cached position. Clients can ensure that cached values are never used by setting the refresh rate to zero, which is the default state for this object.

Parameters:

newRate - the refresh rate for locating this body's position.

getRefreshRate

public TimeDuration getRefreshRate()

Returns a copy of this position's refresh rate (see setRefreshRate(TimeDuration) for a description).

Returns:

a copy of this position's refresh rate.

isMoving

public boolean isMoving()

Description copied from interface: SkyPosition

Returns true if this position has different properties at time T than it does at time U ≠ T.

The determination of motion will be made with respect to the coordinate system in which this position is expressed. For example, a position that is expressed in the equatorial system, and that is holding steady at its position in that system, will said to be not moving, even though in other coordinate systems it may be moving quite rapidly.

Specified by:

isMoving in interface SkyPosition

Returns:

true if this position is moving.

getType

public SkyPositionType getType()

Description copied from interface: SkyPosition

Provides a hint as to how this position stores its information.

Specified by:

getType in interface SkyPosition

Returns:

a hint as to how this position stores its information.

getCoordinateSystem

public CelestialCoordinateSystem getCoordinateSystem()

Description copied from interface: SkyPosition

Returns the coordinate system to use when interpreting the latitude and longitude values of this position.

Specified by:

getCoordinateSystem in interface SkyPosition

Returns:

the system of latitude and longitude used by this position.

getEpoch

public Epoch getEpoch()

Description copied from interface: SkyPosition

Returns the epoch on which this position is based.

Specified by:

getEpoch in interface SkyPosition

Returns:

the epoch on which this position is based.

getOriginOfInformation

public String getOriginOfInformation()

Description copied from interface: SkyPosition

Returns the origin of this position's information.

Specified by:

getOriginOfInformation in interface SkyPosition

Returns:

the origin of this position's information.

getLongitude

public Longitude getLongitude()

Returns the current longitude of this position.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLongitude in interface SphericalPosition

Returns:

the current longitude of this position.

getLatitude

public Latitude getLatitude()

Returns the current latitude of this position.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLatitude in interface SphericalPosition

Returns:

the current latitude of this position.

getDistance

public Distance getDistance()

Returns the current distance of this position.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getDistance in interface SphericalPosition

Returns:

the current distance of this position.

getLongitude

public Longitude getLongitude(Date time)

Returns the longitude of this position at the given point in time.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLongitude in interface SkyPosition

Parameters:

time - the point in time for which the longitude is sought.

Returns:

the longitude of this position at the given point in time.

getLatitude

public Latitude getLatitude(Date time)

Returns the latitude of this position at the given point in time.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLatitude in interface SkyPosition

Parameters:

time - the point in time for which the latitude is sought.

Returns:

the latitude of this position at the given point in time.

getDistance

public Distance getDistance(Date time)

Returns the distance of this position at the given point in time.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getDistance in interface SkyPosition

Parameters:

time - the point in time for which the distance is sought.

Returns:

the distance of this position at the given point in time.

getLongitudeUncertainty

public Longitude getLongitudeUncertainty()

Returns the uncertainty in the longitude of this position.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLongitudeUncertainty in interface SphericalPosition

Returns:

the uncertainty in the longitude of this position.

getLatitudeUncertainty

public Latitude getLatitudeUncertainty()

Returns the uncertainty in the latitude of this position.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLatitudeUncertainty in interface SphericalPosition

Returns:

the uncertainty in the latitude of this position.

getDistanceUncertainty

public Distance getDistanceUncertainty()

Returns the uncertainty in the distance of this position.

The returned value is guaranteed to be non-null. Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getDistanceUncertainty in interface SphericalPosition

Returns:

the uncertainty in the distance of this position.

getAngularSeparation

public Angle getAngularSeparation(SphericalPosition other)

Description copied from interface: SphericalPosition

Calculates the current angular separation between this position and other.

The distances of the positions from the center of the sphere are not considered. The returned angle is the smallest possible such angle. It is the angular size of the arc of a great circle that passes through both the ray from the orgin to this position and the ray from the origin to other.

The returned value is never negative. This means that the returned angle does not contain directional information. That is, the angle from A to B is exactly equal to the angle from B to A.

Specified by:

getAngularSeparation in interface SphericalPosition

Parameters:

other - a position from which this one is separated by the returned angle.

Returns:

the angle of separation between this position and other.

getAngularSeparation

public Angle getAngularSeparation(SphericalPosition other,
                                  Date time)

Description copied from interface: SkyPosition

Calculates current angular separation between this position and other at the given time.

The distances of the positions from the center of the sphere are not considered. The returned angle is the smallest possible such angle. It is the angular size of the arc of a great circle that passes through both the ray from the orgin to this position and the ray from the origin to other.

The returned value is never negative. This means that the returned angle does not contain directional information. That is, the angle from A to B is exactly equal to the angle from B to A.

Specified by:

getAngularSeparation in interface SkyPosition

Parameters:

other - a position from which this one is separated by the returned angle.

time - the point in time for which the separation is sought.

Returns:

the angle of separation between this position and other.

toPosition

public SkyPosition toPosition(CelestialCoordinateSystem system,
                              Epoch epoch,
                              EarthPosition observer,
                              LocalSiderealTime lst)
                       throws CoordinateConversionException

Description copied from interface: SkyPosition

Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position. This position is not changed by this method.

Specified by:

toPosition in interface SkyPosition

Parameters:

system - the celestial coordinate system of the returned position.

epoch - the epoch of the returned position.

observer - the location of the observer. This value is used almost exclusively for conversions to or from the HORIZONTAL (az/el) coordinate system. If a given conversion does not require this parameter, a null value will do no harm.

lst - the local sidereal time at the observer's location. This parameter serves two purposes. First, it is integral in conversions to or from the HORIZONTAL (az/el) coordinate system. Second, even for conversions that do not depend on the observer's location, the conversion method will use the UTC time represented by this LST to determine the exact location of this position before converting it to another system. When used this way the location associated with the LST is immaterial. If this value is null it will be replaced with the current time. Using a null value is not recommended when dealing with the HORIZONTAL system because the LST may not be for the location of interest.

Returns:

a new position with a coordinate system of system, and epoch of epoch, and coordinates that represent a conversion from those of this position.

Throws:

CoordinateConversionException - if anything goes wrong with the conversion.

toPosition

public SkyPosition toPosition(CelestialCoordinateSystem system,
                              Epoch epoch,
                              EarthPosition observer,
                              LocalSiderealTime lst,
                              CelestialCoordinateConverter converter)
                       throws CoordinateConversionException

Description copied from interface: SkyPosition

Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position. This position is not changed by this method.

Specified by:

toPosition in interface SkyPosition

Parameters:

system - the celestial coordinate system of the returned position.

epoch - the epoch of the returned position.

observer - the location of the observer. This value is used almost exclusively for conversions to or from the HORIZONTAL (az/el) coordinate system.

lst - the local sidereal time at the observer's location. This parameter serves two purposes. First, it is integral in conversions to or from the HORIZONTAL (az/el) coordinate system. Second, even for conversions that do not depend on the observer's location, the conversion method will use the UTC time represented by this LST to determine the exact location of this position before converting it to another system. When used this way the location associated with the LST is immaterial. If this value is null it will be replaced with the current time. Using a null value is not recommended when dealing with the HORIZONTAL system because the LST may not be for the location of interest.

converter - the converter used to perform the transformation.

Returns:

a new position with a coordinate system of system, and epoch of epoch, and coordinates that represent a conversion from those of this position.

Throws:

CoordinateConversionException - if anything goes wrong with the conversion.

clone

public SolarSystemBodyPosition clone()

Returns a copy of this body.

The object returned is almost a deep-copy of this position. The source locator used by the returned copy, however, is a reference to the same locator used by this position.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Specified by:

clone in interface SkyPosition

Specified by:

clone in interface SphericalPosition

Overrides:

clone in class Object

Returns:

a copy of this sky position.

equals

public boolean equals(Object o)

Returns true if o is equal to this body.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this body.

Overrides:

hashCode in class Object