edu.nrao.sss.geom
Class EarthPosition

java.lang.Object
  edu.nrao.sss.geom.EarthPosition

All Implemented Interfaces:

SphericalPosition, Cloneable

public class EarthPosition
extends Object
implements SphericalPosition

A position on, in, or above the earth. The most common use of this class is for surface positions, where the position is given in terms of longitude, latitude, and elevation above mean sea level. The time zone for this position may also be specified.

Instances of this class are immutable. The mutable objects contained within this class are always cloned before being accepted or passed out.

Version Info:

$Revision: 1625 $

$Date: 2008-10-16 09:28:49 -0600 (Thu, 16 Oct 2008) $

$Author: dharland $ (last person to modify)

Since:

2008-02-25

Author:

David M. Harland

Constructor Summary

EarthPosition()
Creates a null-like position in which all component values are zero.

EarthPosition(Longitude longitude, Latitude latitude, Distance distance, TimeZone timeZone)
Creates a new position at the given location.

EarthPosition(Longitude lon, Latitude lat, Distance dist, TimeZone tz, Longitude lonUncertainty, Latitude latUncertainty, Distance distUncertainty)
Creates a new position at the given location.

EarthPosition(Longitude longitude, Latitude latitude, TimeZone timeZone)
Creates a new position at the given location.

Method Summary

static LinearVelocity	calcRevolutionVelocityToward(uk.ac.starlink.pal.AngleDR positionOfDate, Date calcDate, boolean useHelio) Calculates the velocity in the direction of the given sky position due to the revolution of the earth around the sun or barycenter.
static Angle	calculateAngularSeparation(Latitude latitude1, Latitude latitude2, Longitude longitude1, Longitude longitude2) Calculates the angular separation between two positions.
LinearVelocity	calcVelocityRelativeTo(SkyPosition skyPosition, Date calcTime, VelocityFrame referenceFrame) Returns the velocity of this position to the given sky position at a particular point in time and with respect to the given frame of reference.
EarthPosition	clone() Returns a copy of this position.
boolean	equals(Object o) Returns true if o is equal to this position.
Angle	getAngularSeparation(SphericalPosition other) Calculates the current angular separation between this position and other.
Distance	getDistance() Returns a copy of this position's distance.
Distance	getDistanceUncertainty() Returns a copy of the uncertainty in this position's distance.
Latitude	getLatitude() Returns a copy of this position's latitude.
Latitude	getLatitudeUncertainty() Returns a copy of the uncertainty in this position's latitude.
LocalSiderealTime	getLocalSiderealTime() Returns the current local sidereal time at this location.
Longitude	getLongitude() Returns a copy of this position's longitude.
Longitude	getLongitudeUncertainty() Returns a copy of the uncertainty in this position's longitude.
Angle	getParallacticAngle(Longitude rightAscension, Latitude declination, Date dateTime) Returns the parallactic angle to the given sky coordinates from this location at the specified time.
TimeZone	getTimeZone() Returns a copy of the time zone in effect at this position.
int	hashCode() Returns a hash code value for this position.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

EarthPosition

public EarthPosition(Longitude lon,
                     Latitude lat,
                     Distance dist,
                     TimeZone tz,
                     Longitude lonUncertainty,
                     Latitude latUncertainty,
                     Distance distUncertainty)

Creates a new position at the given location.

Any parameter that is null will be treated as a value of zero. Values that are not null will be copied into this class, not referenced. This means changes made to a parameter object after creation of an instance of this class will not be reflected herein.

Parameters:

lon - the longitude of this position. A value of null will be treated as a value of zero.

lat - the latitude of this position. A value of null will be treated as a value of zero.

dist - the distance (normally a height above or below sea level) of this position. A value of null will be treated as a value of zero.

tz - the time zone of this position. If this value is null, a simple algorithm based on the longitude will be used to create a time zone value. It is very likely that this calculated time zone will not be the true time zone of this position.

lonUncertainty - the uncertainty in the longitude of this position. A value of null will be treated as a value of zero.

latUncertainty - the uncertainty in the latitude of this position. A value of null will be treated as a value of zero.

distUncertainty - the uncertainty in the distance of this position. A value of null will be treated as a value of zero.

EarthPosition

public EarthPosition(Longitude longitude,
                     Latitude latitude,
                     Distance distance,
                     TimeZone timeZone)

Creates a new position at the given location.

Parameters:

longitude - the longitude of this position. A value of null will be treated as a value of zero.

latitude - the latitude of this position. A value of null will be treated as a value of zero.

distance - the distance (normally a height above or below sea level) of this position. A value of null will be treated as a value of zero.

timeZone - the time zone of this position. If this value is null, a simple algorithm based on the longitude will be used to create a time zone value. It is very likely that this calculated time zone will not be the true time zone of this position.

EarthPosition

public EarthPosition(Longitude longitude,
                     Latitude latitude,
                     TimeZone timeZone)

Creates a new position at the given location. The distance value of this position will be zero.

Parameters:

longitude - the longitude of this position. A value of null will be treated as a value of zero.

latitude - the latitude of this position. A value of null will be treated as a value of zero.

timeZone - the time zone of this position. If this value is null, a simple algorithm based on the longitude will be used to create a time zone value. It is very likely that this calculated time zone will not be the true time zone of this position.

EarthPosition

public EarthPosition()

Creates a null-like position in which all component values are zero.

Method Detail

getLongitude

public Longitude getLongitude()

Returns a copy of this position's longitude.

Specified by:

getLongitude in interface SphericalPosition

Returns:

the current longitude of this position.

getLatitude

public Latitude getLatitude()

Returns a copy of this position's latitude.

Specified by:

getLatitude in interface SphericalPosition

Returns:

the current latitude of this position.

getDistance

public Distance getDistance()

Returns a copy of this position's distance. What this distance represents is the responsibility of the client. By convention, however, the distance for this class usually represents a distance above mean sea level.

Specified by:

getDistance in interface SphericalPosition

Returns:

the current distance of this position from an origin.

getTimeZone

public TimeZone getTimeZone()

Returns a copy of the time zone in effect at this position. Note that this value is only as accurate as the value that was passed into the constructor of this object. This class does not know which time zones are associated with which positions on the earth.

Returns:

a copy of the time zone in effect at this position.

getLongitudeUncertainty

public Longitude getLongitudeUncertainty()

Returns a copy of the uncertainty in this position's longitude.

Specified by:

getLongitudeUncertainty in interface SphericalPosition

Returns:

the uncertainty in the longitude of this position.

getLatitudeUncertainty

public Latitude getLatitudeUncertainty()

Returns a copy of the uncertainty in this position's latitude.

Specified by:

getLatitudeUncertainty in interface SphericalPosition

Returns:

the uncertainty in the latitude of this position.

getDistanceUncertainty

public Distance getDistanceUncertainty()

Returns a copy of the uncertainty in this position's distance.

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.

calculateAngularSeparation

public static Angle calculateAngularSeparation(Latitude latitude1,
                                               Latitude latitude2,
                                               Longitude longitude1,
                                               Longitude longitude2)

Calculates the angular separation between two positions.

The preferred means of getting the angular separation between one position and another is getAngularSeparation(SphericalPosition). This method is made available to other classes that might need to embed this algorithm into their own logic.

Note that this method does not consider distance, but only the angular components of a spherical position.

Parameters:

latitude1 - the latitude of the first position.

latitude2 - the latitude of the second position.

longitude1 - the longitude of the first position.

longitude2 - the longitude of the second position.

Returns:

the angle of separation between the two positions.

calcVelocityRelativeTo

public LinearVelocity calcVelocityRelativeTo(SkyPosition skyPosition,
                                             Date calcTime,
                                             VelocityFrame referenceFrame)
                                      throws CoordinateConversionException

Returns the velocity of this position to the given sky position at a particular point in time and with respect to the given frame of reference. A positive velocity indicates that this earth position is moving away from the given sky position.

Parameters:

skyPosition - a position in the sky toward or from which velocity is to be calculated.

calcTime - the point in time at which the velocity is calculated.

referenceFrame - the frame of reference used in the velocity calculation. The skyPosition is assumed to be motionless relative to this frame. The UNKNOWN and COSMIC_MICROWAVE_BACKGROUND types are unsupported and will result in an IllegalArgumentException.

Returns:

the radial velocity of this position toward or away from a point in space.

Throws:

CoordinateConversionException - if skyPosition cannot be converted to an equatorial RA / Dec position.

IllegalArgumentException - if the referenceFrame is either UNKNOWN or COSMIC_MICROWAVE_BACKGROUND.

Since:

2008-07-29

calcRevolutionVelocityToward

public static LinearVelocity calcRevolutionVelocityToward(uk.ac.starlink.pal.AngleDR positionOfDate,
                                                          Date calcDate,
                                                          boolean useHelio)

Calculates the velocity in the direction of the given sky position due to the revolution of the earth around the sun or barycenter.

This method was originally intended for the private use of this class. It was made public so that a test program could display the value.

getLocalSiderealTime

public LocalSiderealTime getLocalSiderealTime()

Returns the current local sidereal time at this location. The returned object is newly created and is not referenced by this position, so clients are free to manipulate it.

Returns:

the current local sidereal time at this location.

Since:

2008-09-04

getParallacticAngle

public Angle getParallacticAngle(Longitude rightAscension,
                                 Latitude declination,
                                 Date dateTime)

Returns the parallactic angle to the given sky coordinates from this location at the specified time.

Some links:

• Parallactic Angle
• GBT Memo 52

Parameters:

rightAscension - the right ascension of the sky position for which the parallactic angle is desired.

declination - the declination of the sky position for which the parallactic angle is desired.

dateTime - the time for which the parallactic angle is desired.

Returns:

the parallactic angle to the given sky position at the given time.

Since:

2008-09-04

toString

public String toString()

Overrides:

toString in class Object

clone

public EarthPosition clone()

Returns a copy of this position.

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

Specified by:

clone in interface SphericalPosition

Overrides:

clone in class Object

Returns:

a copy of this position.

equals

public boolean equals(Object o)

Returns true if o is equal to this position. The time zone attribute is not taken into account by this method.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this position.

Overrides:

hashCode in class Object