001 package edu.nrao.sss.geom;
002
003 import edu.nrao.sss.measure.Angle;
004 import edu.nrao.sss.measure.Distance;
005 import edu.nrao.sss.measure.Latitude;
006 import edu.nrao.sss.measure.Longitude;
007
008 /**
009 * A point in three dimensional space expressed in terms of
010 * latitude, longitude, and distance from an origin.
011 * <p>
012 * <b>Version Info:</b>
013 * <table style="margin-left:2em">
014 * <tr><td>$Revision: 1118 $</td></tr>
015 * <tr><td>$Date: 2008-02-26 10:52:29 -0700 (Tue, 26 Feb 2008) $</td></tr>
016 * <tr><td>$Author: dharland $ (last person to modify)</td></tr>
017 * </table></p>
018 *
019 * @author David M. Harland
020 * @since 2006-06-07
021 */
022 public interface SphericalPosition
023 extends Cloneable
024 {
025 /**
026 * Returns the current longitude of this position.
027 * <p>
028 * Classes that implement this interface are free to choose whether to return
029 * a reference to their internal longitudes, or to provide copies thereof.
030 * This means that clients of this interface should not write code that
031 * manipulates the returned object and relies on those changes being
032 * reflected in this object, unless they know they are using an
033 * implementation that returns internal references.</p>
034 *
035 * @return the current longitude of this position.
036 */
037 public Longitude getLongitude();
038
039 /**
040 * Returns the current latitude of this position.
041 * <p>
042 * Classes that implement this interface are free to choose whether to return
043 * a reference to their internal latitudes, or to provide copies thereof.
044 * This means that clients of this interface should not write code that
045 * manipulates the returned object and relies on those changes being
046 * reflected in this object, unless they know they are using an
047 * implementation that returns internal references.</p>
048 *
049 * @return the current latitude of this position.
050 */
051 public Latitude getLatitude();
052
053 /**
054 * Returns the current distance of this position from an origin.
055 * <p>
056 * Classes that implement this interface are free to choose whether to return
057 * a reference to their internal distances, or to provide copies thereof.
058 * This means that clients of this interface should not write code that
059 * manipulates the returned object and relies on those changes being
060 * reflected in this object, unless they know they are using an
061 * implementation that returns internal references.</p>
062 *
063 * @return the current distance of this position from an origin.
064 */
065 public Distance getDistance();
066
067 /**
068 * Returns the uncertainty in the longitude of this position.
069 * <p>
070 * Classes that implement this interface are free to choose whether to return
071 * a reference to their internal uncertainties, or to provide copies thereof.
072 * This means that clients of this interface should not write code that
073 * manipulates the returned object and relies on those changes being
074 * reflected in this object, unless they know they are using an
075 * implementation that returns internal references.</p>
076 *
077 * @return the uncertainty in the longitude of this position.
078 */
079 public Longitude getLongitudeUncertainty();
080
081 /**
082 * Returns the uncertainty in the latitude of this position.
083 * <p>
084 * Classes that implement this interface are free to choose whether to return
085 * a reference to their internal uncertainties, or to provide copies thereof.
086 * This means that clients of this interface should not write code that
087 * manipulates the returned object and relies on those changes being
088 * reflected in this object, unless they know they are using an
089 * implementation that returns internal references.</p>
090 *
091 * @return the uncertainty in the latitude of this position.
092 */
093 public Latitude getLatitudeUncertainty();
094
095 /**
096 * Returns the uncertainty in the distance of this position.
097 * <p>
098 * Classes that implement this interface are free to choose whether to return
099 * a reference to their internal uncertainties, or to provide copies thereof.
100 * This means that clients of this interface should not write code that
101 * manipulates the returned object and relies on those changes being
102 * reflected in this object, unless they know they are using an
103 * implementation that returns internal references.</p>
104 *
105 * @return the uncertainty in the distance of this position.
106 */
107 public Distance getDistanceUncertainty();
108
109 /**
110 * Calculates the current angular separation between this position and
111 * {@code other}.
112 * <p>
113 * The distances of the positions from the center of the sphere are
114 * <i>not</i> considered. The returned angle is the smallest possible
115 * such angle. It is the angular size of the arc of a great circle that
116 * passes through both the ray from the orgin to this position and the
117 * ray from the origin to {@code other}.</p>
118 * <p>
119 * The returned value is never negative. This means that the returned
120 * angle does not contain directional information. That is, the angle
121 * from A to B is exactly equal to the angle from B to A.</p>
122 *
123 * @param other a position from which this one is separated by the
124 * returned angle.
125 *
126 * @return the angle of separation between this position and {@code other}.
127 */
128 public Angle getAngularSeparation(SphericalPosition other);
129
130 /**
131 * Returns a copy of this position.
132 * @return a copy of this position.
133 */
134 public SphericalPosition clone();
135 }