#include <Position.hpp>
Inheritance diagram for Position:


Internally, the representation of Position consists of three coordinate values (double), two doubles from a geoid model (see below, storing these doubles is preferred over adding GeoidModel to calling arguments everywhere), a flag of type 'enum CoordinateSystem' giving the coordinate system, and a tolerance for use in comparing Positions. Class Position inherits from class Triple, which is how the coordinate values are stored (Triple actually uses std::valarray<double> of length 3). It is important to note that Triple:: routines are properly used by Positions ONLY in the Cartesian coordinate system.
Only geodetic coordinates depend on a geoid, and then (for an ellipsoidal geoid) only on the semi-major axis of the Earth and the square of its eccentricity. Input of this geoid information (usually a pointer to a GeoidModel) is required by functions involving constructors of, or transformation to or from, Geodetic coordinates. However since a default is supplied (WGS84), the user need never deal with geiods unless desired. In fact, if the geodetic coordinate system is avoided, the Position class can be interpreted simply as 3D vectors in any context, particularly since the class inherits from Triple, which includes many vector manipulation routines (although the Triple:: routines assume Cartesian coordinates). Even the requirement that lengths (radius, height and the cartesian coordinates) have units of meters is required only if geodetic coordinates are used (because the semi-major axis in GeoidModel is in meters); without using Geodetic one could apply the class using any units for length as long as setTolerance() is called appropriately.
Position relies on a series of fundamental routines to transform from one coordinate system to another, these include, for example void Position::convertGeodeticToCartesian(const Triple& llh, Triple& xyz, const double A, const double eccSq); void Position::convertSphericalToCartesian(const Triple& tpr, Triple& xyz); These functions use Triple in the calling arguments.
Position will throw exceptions (gpstk::GeometryException) on bad input (e.g. negative radius or latitude > 90 degrees); otherwise the class attempts to handle all points, even the pole and the origin, consistently and without throwing exceptions. At or very near the poles, the transformation routines will set latitude = +/-90 degrees, which is theta = 0 or 180, and (arbitrarily) longitude = 0. At or very near the origin, the transformation routines will set latitude = 0, which is theta = 90, and (arbitrarily) longitude = 0; radius will be set to zero and geodetic height will be set to -radius(Earth) (= -6378137.0 in WGS84). The tolerance used in testing 'at or near the pole or origin' is radius < POSITION_TOLERANCE/5. Note that this implies that a Position that is very near the origin may be SET to the exact origin by the transformation routines, and that thereby information about direction (e.g. latitude and longitude) may be LOST. The user is warned to be very careful when working near either the pole or the origin.
Position includes setToString() and printf() functions similar to those in gpstk::DayTime; this allows flexible and powerful I/O of Position to strings and streams.
Definition at line 118 of file Position.hpp.
Public Types | |
| enum | CoordinateSystem { Unknown = 0, Geodetic, Geocentric, Cartesian, Spherical } |
| The coordinate systems supported by Position. More... | |
Public Member Functions | |
| std::string | getSystemName () throw () |
| return string giving name of coordinate system | |
| Position & | setTolerance (const double tol) throw () |
| Sets the tolerance for output and comparisons, for this object only. | |
| Position () throw () | |
| Default constructor. | |
| Position (const double &a, const double &b, const double &c, CoordinateSystem s=Cartesian, GeoidModel *geoid=NULL) throw (GeometryException) | |
| Explicit constructor. | |
| Position (const double ABC[3], CoordinateSystem s=Cartesian, GeoidModel *geoid=NULL) throw (GeometryException) | |
| Explicit constructor. | |
| Position (const Triple &ABC, CoordinateSystem s=Cartesian, GeoidModel *geoid=NULL) throw (GeometryException) | |
| Explicit constructor. | |
| Position (const Xvt &xvt) throw () | |
| Explicit constructor from Xvt. | |
| ~Position () throw () | |
| Destructor. | |
| Position & | operator-= (const Position &right) throw () |
| Subtract a Position from this Position. | |
| Position & | operator+= (const Position &right) throw () |
| Add a Position to this Position. | |
| bool | operator== (const Position &right) const throw () |
| Equality operator. | |
| bool | operator!= (const Position &right) const throw () |
| Inequality operator. | |
| Position | transformTo (CoordinateSystem sys) throw () |
| Transform coordinate system. | |
| Position | asGeodetic () throw () |
| Convert to geodetic coordinates (does nothing if system == Geodetic already). | |
| Position | asGeodetic (GeoidModel *geoid) throw (GeometryException) |
| Convert to another geoid, then to geodetic coordinates. | |
| Position | asECEF () throw () |
| Convert to cartesian coordinates (does nothing if system == Cartesian already). | |
| double | X () const throw () |
| return X coordinate (meters) | |
| double | Y () const throw () |
| return Y coordinate (meters) | |
| double | Z () const throw () |
| return Z coordinate (meters) | |
| double | geodeticLatitude () const throw () |
| return geodetic latitude (degrees North). | |
| double | geocentricLatitude () const throw () |
| return geocentric latitude (degrees North); equal to 90 degress - theta in regular spherical coordinates. | |
| double | theta () const throw () |
| return spherical coordinate theta in degrees | |
| double | phi () const throw () |
| return spherical coordinate phi in degrees | |
| double | longitude () const throw () |
| return longitude (degrees East); equal to phi in regular spherical coordinates. | |
| double | radius () const throw () |
| return distance from the center of Earth (meters), Same as radius in spherical coordinates. | |
| double | height () const throw () |
| return height above ellipsoid (meters) (Geodetic). | |
| CoordinateSystem | getCoordinateSystem () const throw () |
| return the coordinate system for this Position | |
| double | getGeodeticLatitude () const throw () |
| return geodetic latitude (deg N) | |
| double | getGeocentricLatitude () const throw () |
| return geocentric latitude (deg N) | |
| double | getLongitude () const throw () |
| return longitude (deg E) (either geocentric or geodetic) | |
| double | getAltitude () const throw () |
| return height above ellipsoid (meters) | |
| double | getHeight () const throw () |
| return height above ellipsoid (meters) | |
| double | getX () const throw () |
| return ECEF X coordinate (meters) | |
| double | getY () const throw () |
| return ECEF Y coordinate (meters) | |
| double | getZ () const throw () |
| return ECEF Z coordinate (meters) | |
| double | getTheta () const throw () |
| return spherical coordinate angle theta (deg) (90 - geocentric latitude) | |
| double | getPhi () const throw () |
| return spherical coordinate angle phi (deg) (same as longitude) | |
| double | getRadius () const throw () |
| return radius | |
| void | setGeoidModel (const GeoidModel *geoid) throw (GeometryException) |
| Set the geoid values for this Position given a geoid. | |
| Position & | setGeodetic (const double lat, const double lon, const double ht, const GeoidModel *geoid=NULL) throw (GeometryException) |
| Set the Position given geodetic coordinates; system is set to Geodetic. | |
| Position & | setGeocentric (const double lat, const double lon, const double rad) throw (GeometryException) |
| Set the Position given geocentric coordinates; system is set to Geocentric. | |
| Position & | setSpherical (const double theta, const double phi, const double rad) throw (GeometryException) |
| Set the Position given spherical coordinates; system is set to Spherical. | |
| Position & | setECEF (const double X, const double Y, const double Z) throw () |
| Set the Position given ECEF coordinates; system is set to Cartesian. | |
| Position & | setECEF (const double XYZ[3]) throw () |
| Set the Position given an array of ECEF coordinates; system is set to Cartesian. | |
| Position & | setECEF (const Triple &XYZ) throw () |
| Set the Position given ECEF coordinates; system is set to Cartesian. | |
| Position & | setToString (const std::string &str, const std::string &fmt) throw (GeometryException, DayTime::FormatException, StringUtils::StringException) |
| setToString, similar to scanf, this function takes a string and a format describing string in order to define Position values. | |
| std::string | printf (const char *fmt) const throw (StringUtils::StringException) |
| Format this Position into a string. | |
| std::string | printf (const std::string &fmt) const throw (StringUtils::StringException) |
| Format this time into a string. | |
| std::string | asString () const throw (StringUtils::StringException) |
| Returns the string that operator<<() would print. | |
| double | radiusEarth () const throw () |
| A member function that calls the non-member radiusEarth() for this Position. | |
| double | elevation (const Position &Target) const throw (GeometryException) |
| A member function that computes the elevation of the input (Target) position as seen from this Position. | |
| double | elevationGeodetic (const Position &Target) const throw (GeometryException) |
| A member function that computes the elevation of the input (Target) position as seen from this Position, using a Geodetic (ellipsoidal) system. | |
| double | azimuth (const Position &Target) const throw (GeometryException) |
| A member function that computes the azimuth of the input (Target) position as seen from this Position. | |
| double | azimuthGeodetic (const Position &Target) const throw (GeometryException) |
| A member function that computes the azimuth of the input (Target) position as seen from this Position, using a Geodetic (ellipsoidal) system. | |
| Position | getIonosphericPiercePoint (const double elev, const double azim, const double ionoht) const throw () |
| A member function that computes the position at which a signal, which is received at this Position and there is observed at the (input) azimuth and elevation angles, crosses a model ionosphere that is taken to be a thin shell at constant (input) height. | |
Static Public Member Functions | |
| double | setPositionTolerance (const double tol) |
| Changes the POSITION_TOLERANCE for all Position objects. | |
| double | getPositionTolerance () |
| Returns the current POSITION_TOLERANCE. | |
| void | convertSphericalToCartesian (const Triple &tpr, Triple &xyz) throw () |
| Fundamental conversion from spherical to cartesian coordinates. | |
| void | convertCartesianToSpherical (const Triple &xyz, Triple &tpr) throw () |
| Fundamental routine to convert cartesian to spherical coordinates. | |
| void | convertCartesianToGeodetic (const Triple &xyz, Triple &llh, const double A, const double eccSq) throw () |
| Fundamental routine to convert ECEF (cartesian) to geodetic coordinates, (Geoid specified by semi-major axis and eccentricity squared). | |
| void | convertGeodeticToCartesian (const Triple &llh, Triple &xyz, const double A, const double eccSq) throw () |
| Fundamental routine to convert geodetic to ECEF (cartesian) coordinates, (Geoid specified by semi-major axis and eccentricity squared). | |
| void | convertCartesianToGeocentric (const Triple &xyz, Triple &llr) throw () |
| Fundamental routine to convert cartesian (ECEF) to geocentric The zero vector is converted to (0,0,0). | |
| void | convertGeocentricToCartesian (const Triple &llr, Triple &xyz) throw () |
| Fundamental routine to convert geocentric to cartesian (ECEF). | |
| void | convertGeocentricToGeodetic (const Triple &llr, Triple &geodeticllh, const double A, const double eccSq) throw () |
| Fundamental routine to convert geocentric to geodetic. | |
| void | convertGeodeticToGeocentric (const Triple &geodeticllh, Triple &llr, const double A, const double eccSq) throw () |
| Fundamental routine to convert geodetic to geocentric. | |
| double | radiusEarth (const double geolat, const double A, const double eccSq) throw () |
| Compute the radius of the ellipsoidal Earth, given the geodetic latitude. | |
Static Public Attributes | |
| const double | ONE_MM_TOLERANCE = 0.001 |
| One millimeter tolerance. | |
| const double | ONE_CM_TOLERANCE = 0.01 |
| One centimeter tolerance. | |
| const double | ONE_UM_TOLERANCE = 0.000001 |
| One micron tolerance. | |
| double | POSITION_TOLERANCE = Position::ONE_MM_TOLERANCE |
| Default tolerance for time equality in days. | |
Friends | |
| Position | operator- (const Position &left, const Position &right) throw () |
| Difference two Positions, returning result as a Position in Cartesian coordinates, the only system in which a position difference makes sense. | |
| Position | operator+ (const Position &left, const Position &right) throw () |
| Add two Positions, returning result as a Position in Cartesian coordinates, the only system in which a position sum makes sense. | |
| Position | operator * (const double &scale, const Position &right) |
| Multiply a Position by a double scalar on the left. | |
| Position | operator * (const Position &left, const double &scale) |
| Multiply a Position by a double scalar on the right. | |
| Position | operator * (const int &scale, const Position &right) |
| Multiply a Position by an integer scalar on the left. | |
| Position | operator * (const Position &left, const int &scale) |
| Multiply a Position by an integer scalar on the right. | |
| std::ostream & | operator<< (std::ostream &s, const Position &p) |
| Stream output for Position objects. | |
| double | range (const Position &A, const Position &B) throw (GeometryException) |
| Compute the range in meters between two Positions. | |
|
|
The coordinate systems supported by Position.
Definition at line 124 of file Position.hpp. |
|
|
Default constructor. Initializes to zero, Unknown coordinates Definition at line 87 of file Position.cpp. References Position::Unknown. |
|
||||||||||||||||||||||||
|
Explicit constructor. Coordinate system may be specified on input, but defaults to Cartesian. Pointer to GeoidModel may be specified, but default is NULL (in which case WGS84 values will be used).
Definition at line 94 of file Position.cpp. References gpstk::ge(), and GPSTK_RETHROW. |
|
||||||||||||||||
|
Explicit constructor. Coordinate system may be specified on input, but defaults to Cartesian. Pointer to GeoidModel may be specified, but default is NULL (in which case WGS84 values will be used).
Definition at line 109 of file Position.cpp. References gpstk::ge(), and GPSTK_RETHROW. |
|
||||||||||||||||
|
Explicit constructor. Coordinate system may be specified on input, but defaults to Cartesian. Pointer to GeoidModel may be specified, but default is NULL (in which case WGS84 values will be used).
Definition at line 125 of file Position.cpp. References gpstk::ge(), and GPSTK_RETHROW. |
|
|
Explicit constructor from Xvt. The coordinate system is Cartesian, and the velocity and time information in the input is ignored.
Definition at line 141 of file Position.cpp. |
|
|
Destructor.
Definition at line 231 of file Position.hpp. |
|
|
Convert to cartesian coordinates (does nothing if system == Cartesian already).
Definition at line 367 of file Position.hpp. |
|
|
Convert to another geoid, then to geodetic coordinates.
Definition at line 356 of file Position.hpp. References gpstk::ge(), and GPSTK_RETHROW. |
|
|
Convert to geodetic coordinates (does nothing if system == Geodetic already).
Definition at line 349 of file Position.hpp. |
|
|
Returns the string that operator<<() would print.
Definition at line 1016 of file Position.cpp. |
|
|
A member function that computes the azimuth of the input (Target) position as seen from this Position.
Definition at line 1352 of file Position.cpp. References Triple::azAngle(), gpstk::ge(), GPSTK_RETHROW, and Position::transformTo(). Referenced by main(). |
|
|
A member function that computes the azimuth of the input (Target) position as seen from this Position, using a Geodetic (ellipsoidal) system.
Definition at line 1379 of file Position.cpp. References gpstk::cos(), Triple::dot(), gpstk::ge(), Position::getGeodeticLatitude(), Position::getLongitude(), GPSTK_THROW, Triple::mag(), gpstk::sin(), Triple::theArray, and Position::transformTo(). |
|
||||||||||||
|
Fundamental routine to convert cartesian (ECEF) to geocentric The zero vector is converted to (0,0,0).
Definition at line 1131 of file Position.cpp. |
|
||||||||||||||||||||
|
Fundamental routine to convert ECEF (cartesian) to geodetic coordinates, (Geoid specified by semi-major axis and eccentricity squared). The zero vector is converted to (90,0,-R(earth)).
Definition at line 1075 of file Position.cpp. References gpstk::cos(), gpstk::sin(), and SQRT. |
|
||||||||||||
|
Fundamental routine to convert cartesian to spherical coordinates. The zero vector is converted to (90,0,0).
Definition at line 1044 of file Position.cpp. References gpstk::acos(), and gpstk::RSS(). |
|
||||||||||||
|
Fundamental routine to convert geocentric to cartesian (ECEF).
Definition at line 1142 of file Position.cpp. |
|
||||||||||||||||||||
|
Fundamental routine to convert geocentric to geodetic.
Definition at line 1157 of file Position.cpp. References gpstk::cos(), gpstk::sin(), and SQRT. |
|
||||||||||||||||||||
|
Fundamental routine to convert geodetic to ECEF (cartesian) coordinates, (Geoid specified by semi-major axis and eccentricity squared).
Definition at line 1113 of file Position.cpp. References gpstk::cos(), gpstk::sin(), and SQRT. |
|
||||||||||||||||||||
|
Fundamental routine to convert geodetic to geocentric.
Definition at line 1202 of file Position.cpp. References gpstk::acos(), gpstk::sin(), and SQRT. |
|
||||||||||||
|
Fundamental conversion from spherical to cartesian coordinates.
Definition at line 1030 of file Position.cpp. References gpstk::cos(), and gpstk::sin(). |
|
|
A member function that computes the elevation of the input (Target) position as seen from this Position.
Definition at line 1293 of file Position.cpp. References Triple::elvAngle(), gpstk::ge(), GPSTK_RETHROW, and Position::transformTo(). Referenced by main(). |
|
|
A member function that computes the elevation of the input (Target) position as seen from this Position, using a Geodetic (ellipsoidal) system.
Definition at line 1317 of file Position.cpp. References gpstk::cos(), Triple::dot(), gpstk::ge(), Position::getGeodeticLatitude(), Position::getLongitude(), GPSTK_THROW, Triple::mag(), gpstk::sin(), Triple::theArray, and Position::transformTo(). |
|
|
return geocentric latitude (degrees North); equal to 90 degress - theta in regular spherical coordinates.
Definition at line 385 of file Position.cpp. References Position::Geocentric, Triple::theArray, and Position::transformTo(). |
|
|
return geodetic latitude (degrees North).
Definition at line 373 of file Position.cpp. References Triple::theArray, and Position::transformTo(). |
|
|
return height above ellipsoid (meters)
Definition at line 440 of file Position.hpp. Referenced by MOPSTropModel::MOPSTropModel(), and NeillTropModel::NeillTropModel(). |
|
|
return the coordinate system for this Position
Definition at line 420 of file Position.hpp. |
|
|
return geocentric latitude (deg N)
Definition at line 430 of file Position.hpp. |
|
|
return geodetic latitude (deg N)
Definition at line 425 of file Position.hpp. Referenced by Position::azimuthGeodetic(), Position::elevationGeodetic(), MOPSTropModel::MOPSTropModel(), NeillTropModel::NeillTropModel(), NeillTropModel::setAllParameters(), MOPSTropModel::setAllParameters(), XYZ2NED::XYZ2NED(), and XYZ2NEU::XYZ2NEU(). |
|
|
return height above ellipsoid (meters)
Definition at line 445 of file Position.hpp. Referenced by NeillTropModel::setAllParameters(), and MOPSTropModel::setAllParameters(). |
|
||||||||||||||||
|
A member function that computes the position at which a signal, which is received at this Position and there is observed at the (input) azimuth and elevation angles, crosses a model ionosphere that is taken to be a thin shell at constant (input) height. This function will not transform this Position, and it will return a Position in the same system; the algorithm itself is done in the geocentric coordinate system.
Definition at line 1439 of file Position.cpp. References gpstk::asin(), gpstk::cos(), PI, gpstk::sin(), Triple::theArray, and Position::transformTo(). Referenced by main(). |
|
|
return longitude (deg E) (either geocentric or geodetic)
Definition at line 435 of file Position.hpp. Referenced by Position::azimuthGeodetic(), Position::elevationGeodetic(), XYZ2NED::XYZ2NED(), and XYZ2NEU::XYZ2NEU(). |
|
|
return spherical coordinate angle phi (deg) (same as longitude)
Definition at line 470 of file Position.hpp. |
|
|
Returns the current POSITION_TOLERANCE.
Definition at line 154 of file Position.hpp. |
|
|
return radius
Definition at line 475 of file Position.hpp. |
|
|
return string giving name of coordinate system
Definition at line 58 of file Position.cpp. Referenced by main(). |
|
|
return spherical coordinate angle theta (deg) (90 - geocentric latitude)
Definition at line 465 of file Position.hpp. |
|
|
return ECEF X coordinate (meters)
Definition at line 450 of file Position.hpp. |
|
|
return ECEF Y coordinate (meters)
Definition at line 455 of file Position.hpp. |
|
|
return ECEF Z coordinate (meters)
Definition at line 460 of file Position.hpp. |
|
|
return height above ellipsoid (meters) (Geodetic).
Definition at line 442 of file Position.cpp. References Triple::theArray, and Position::transformTo(). |
|
|
return longitude (degrees East); equal to phi in regular spherical coordinates.
Definition at line 419 of file Position.cpp. References Position::Spherical, Triple::theArray, and Position::transformTo(). |
|
|
Inequality operator. Return true if range between this Position and the input Position is greater than tolerance. Return true if geoid values differ. Definition at line 229 of file Position.cpp. References gpstk::operator==(). |
|
|
Add a Position to this Position. Perform the addition in Cartesian coordinates, but return this Position to the system it had originally.
Definition at line 169 of file Position.cpp. References Triple::theArray, and Position::transformTo(). |
|
|
Subtract a Position from this Position. Perform the subtraction in Cartesian coordinates, but return this Position to the system it had originally.
Definition at line 152 of file Position.cpp. References Triple::theArray, and Position::transformTo(). |
|
|
Equality operator. Return true if range between this Position and the input Position is less than tolerance. Return false if geoid values differ. Definition at line 217 of file Position.cpp. References gpstk::range(). |
|
|
return spherical coordinate phi in degrees
Definition at line 407 of file Position.cpp. References Position::Spherical, Triple::theArray, and Position::transformTo(). |
|
|
Format this time into a string.
Definition at line 658 of file Position.hpp. |
|
|
Format this Position into a string.
Generate and return a string containing formatted Position coordinates, formatted by the specification
|