Detailed Description

A position representation class for common 3D geographic position formats, including geodetic (geodetic latitude, longitude, and height above the ellipsoid) geocentric (geocentric latitude, longitude, and radius from Earth's center), cartesian (Earth-centered, Earth-fixed) and spherical (theta,phi,radius).

Internally, the representation of Position consists of three coordinate values (double), two doubles from a ellipsoid model (see below, storing these doubles is preferred over adding EllipsoidModel 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 ellipsoid, and then only on the semi-major axis of the Earth and the square of its eccentricity. Input of this ellipsoid information (usually a pointer to a EllipsoidModel) 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 EllipsoidModel 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 (gnsstk::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 gnsstk::CommonTime; this allows flexible and powerful I/O of Position to strings and streams.

See also: positiontest.cpp for examples.

Definition at line 136 of file Position.hpp.

#include <Position.hpp>

Inheritance diagram for gnsstk::Position:

[legend]

Public Types
enum	CoordinateSystem { Unknown =0, Geodetic, Geocentric, Cartesian, Spherical }
	The coordinate systems supported by Position. More...

Public Member Functions
Position &	asECEF () noexcept

Position &	asGeodetic () noexcept

Position &	asGeodetic (EllipsoidModel *ell)

std::string	asString () const

double	azimuth (const Position &Target) const

double	azimuthGeodetic (const Position &Target) const

void	copyEllipsoidModelFrom (const Position &src)

double	elevation (const Position &Target) const

double	elevationGeodetic (const Position &Target) const

double	geocentricLatitude () const noexcept

double	geodeticLatitude () const noexcept
	return geodetic latitude (degrees North). More...

double	getAEarth () const

double	getAltitude () const noexcept
	return height above ellipsoid (meters) More...

CoordinateSystem	getCoordinateSystem () const noexcept
	return the coordinate system for this Position More...

double	getCurvMeridian () const noexcept

double	getCurvPrimeVertical () const noexcept

double	getGeocentricLatitude () const noexcept
	return geocentric latitude (deg N) More...

double	getGeodeticLatitude () const noexcept
	return geodetic latitude (deg N) More...

double	getHeight () const noexcept
	return height above ellipsoid (meters) More...

Position	getIonosphericPiercePoint (const double elev, const double azim, const double ionoht) const noexcept

double	getLongitude () const noexcept
	return longitude (deg E) (either geocentric or geodetic) More...

double	getPhi () const noexcept
	return spherical coordinate angle phi (deg) (same as longitude) More...

double	getRadius () const noexcept
	return radius More...

Position	getRayPerigee (const Position &target) const

Position	getRayPosition (double dist, const Position &target) const

const RefFrame &	getReferenceFrame () const noexcept
	return coordinate RefFrame More...

std::string	getSystemName () noexcept
	return string giving name of coordinate system More...

double	getTheta () const noexcept

double	getX () const noexcept
	return ECEF X coordinate (meters) More...

double	getY () const noexcept
	return ECEF Y coordinate (meters) More...

double	getZ () const noexcept
	return ECEF Z coordinate (meters) More...

Angle	getZenithAngle (const Position &target, AngleReduced &delta) const

double	height () const noexcept
	return height above ellipsoid (meters) (Geodetic). More...

double	longitude () const noexcept

bool	operator!= (const Position &right) const noexcept

Position &	operator+= (const Position &right) noexcept

Position &	operator-= (const Position &right) noexcept

bool	operator== (const Position &right) const noexcept

double	phi () const noexcept
	return spherical coordinate phi in degrees More...

	Position () noexcept

	Position (const double &a, const double &b, const double &c, CoordinateSystem s=Cartesian, const EllipsoidModel *ell=nullptr, const RefFrame &frame=RefFrame())

	Position (const double ABC[3], CoordinateSystem s=Cartesian, const EllipsoidModel *ell=nullptr, const RefFrame &frame=RefFrame())

	Position (const Triple &ABC, CoordinateSystem s=Cartesian, const EllipsoidModel *ell=nullptr, const RefFrame &frame=RefFrame())

	Position (const Xvt &xvt) noexcept

std::string	printf (const char *fmt) const

std::string	printf (const std::string &fmt) const

double	radius () const noexcept

double	radiusEarth () const noexcept

Position &	setECEF (const double X, const double Y, const double Z) noexcept

Position &	setECEF (const double XYZ[3]) noexcept

Position &	setECEF (const Triple &XYZ) noexcept

void	setEllipsoidModel (const EllipsoidModel *ell)

Position &	setGeocentric (const double lat, const double lon, const double rad)

Position &	setGeodetic (const double lat, const double lon, const double ht, const EllipsoidModel *ell=nullptr)

void	setReferenceFrame (const RefFrame &frame) noexcept

Position &	setSpherical (const double theta, const double phi, const double rad)

Position &	setTolerance (const double tol) noexcept

Position &	setToString (const std::string &str, const std::string &fmt)

double	theta () const noexcept
	return spherical coordinate theta in degrees More...

Position &	transformTo (CoordinateSystem sys) noexcept

double	X () const noexcept
	return X coordinate (meters) More...

double	Y () const noexcept
	return Y coordinate (meters) More...

double	Z () const noexcept
	return Z coordinate (meters) More...

	~Position () noexcept
	Destructor. More...

Public Member Functions inherited from gnsstk::Triple
double	azAngle (const Triple &right) const

double	cosVector (const Triple &right) const

Triple	cross (const Triple &right) const noexcept

double	dot (const Triple &right) const noexcept

double	elvAngle (const Triple &right) const

double	mag () const noexcept

Triple	operator+ (const Triple &right) const

Triple	operator- (const Triple &right) const

Triple &	operator= (const std::valarray< double > &right)

Triple &	operator= (const Triple &right)
	Assignment operator. More...

bool	operator== (const Triple &right) const

double &	operator[] (const size_t index)

double	operator[] (const size_t index) const

Triple	R1 (const double &angle) const noexcept

Triple	R2 (const double &angle) const noexcept

Triple	R3 (const double &angle) const noexcept

size_t	size (void) const
	Return the size of this object. More...

double	slantRange (const Triple &right) const noexcept

std::vector< double >	toStdVector ()
	Return the data as a std::vector object. More...

Vector< double >	toVector ()
	Return the data as a Vector<double> object. More...

	Triple ()
	Default constructor, initialize as triple. More...

	Triple (const Triple &right)
	Copy constructor. More...

	Triple (double a, double b, double c)
	Construct from three doubles. More...

Triple	unitVector () const

virtual	~Triple ()
	Destructor. More...

Static Public Member Functions
static void	convertCartesianToGeocentric (const Triple &xyz, Triple &llr) noexcept

static void	convertCartesianToGeodetic (const Triple &xyz, Triple &llh, const double A, const double eccSq) noexcept

static void	convertCartesianToSpherical (const Triple &xyz, Triple &tpr) noexcept

static void	convertGeocentricToCartesian (const Triple &llr, Triple &xyz) noexcept

static void	convertGeocentricToGeodetic (const Triple &llr, Triple &geodeticllh, const double A, const double eccSq) noexcept

static void	convertGeodeticToCartesian (const Triple &llh, Triple &xyz, const double A, const double eccSq) noexcept

static void	convertGeodeticToGeocentric (const Triple &geodeticllh, Triple &llr, const double A, const double eccSq) noexcept

static void	convertSphericalToCartesian (const Triple &tpr, Triple &xyz) noexcept

static double	getPositionTolerance ()
	Returns the current POSITION_TOLERANCE. More...

static Angle	getZenithAngle (const Angle &phi1, const Angle &lambda1, const Angle &phi2, const Angle &lambda2, double r1, double r2, AngleReduced &delta)

static double	radiusEarth (const double geolat, const double A, const double eccSq) noexcept

static double	setPositionTolerance (const double tol)
	Changes the POSITION_TOLERANCE for all Position objects. More...

Static Public Attributes
static const GNSSTK_EXPORT double	ONE_CM_TOLERANCE = 0.01
	One centimeter tolerance. More...

static const GNSSTK_EXPORT double	ONE_MM_TOLERANCE = 0.001
	One millimeter tolerance. More...

static const GNSSTK_EXPORT double	ONE_UM_TOLERANCE = 0.000001
	One micron tolerance. More...

static GNSSTK_EXPORT double	POSITION_TOLERANCE = Position::ONE_MM_TOLERANCE
	Default tolerance for time equality in days. More...

Private Member Functions
void	initialize (const double a, const double b, const double c, CoordinateSystem s=Cartesian, const EllipsoidModel *ell=nullptr, const RefFrame &frame=RefFrame())

Private Attributes
double	AEarth
	semi-major axis of Earth (meters) More...

double	eccSquared
	square of ellipsoid eccentricity More...

RefFrame	refFrame

CoordinateSystem	system
	see CoordinateSystem More...

double	tolerance
	tolerance used in comparisons More...

Friends
Position	operator* (const double &scale, const Position &right)

Position	operator* (const int &scale, const Position &right)

Position	operator* (const Position &left, const double &scale)

Position	operator* (const Position &left, const int &scale)

Position	operator+ (const Position &left, const Position &right) noexcept

Position	operator- (const Position &left, const Position &right) noexcept

std::ostream &	operator<< (std::ostream &s, const Position &p)

double	range (const Position &A, const Position &B)

Additional Inherited Members
Public Attributes inherited from gnsstk::Triple
std::valarray< double >	theArray

Member Enumeration Documentation

◆ CoordinateSystem

enum gnsstk::Position::CoordinateSystem

The coordinate systems supported by Position.

Enumerator
Unknown	unknown coordinate system
Geodetic	geodetic latitude, longitude, and height above ellipsoid
Geocentric	geocentric (regular spherical coordinates)
Cartesian	cartesian (Earth-centered, Earth-fixed)
Spherical	spherical coordinates (theta,phi,radius)

Definition at line 142 of file Position.hpp.

Constructor & Destructor Documentation

◆ Position() [1/5]

gnsstk::Position::Position ( )

noexcept

Default constructor. Initializes to zero, Unknown coordinates

Definition at line 92 of file Position.cpp.

◆ Position() [2/5]

gnsstk::Position::Position	(	const double &	a,
		const double &	b,
		const double &	c,
		Position::CoordinateSystem	s = `Cartesian`,
		const EllipsoidModel *	ell = `nullptr`,
		const RefFrame &	frame = `RefFrame()`
	)

Explicit constructor. Coordinate system may be specified on input, but defaults to Cartesian. Pointer to EllipsoidModel may be specified, but default is NULL (in which case WGS84 values will be used).

Parameters

a	first coordinate [ X(m), or latitude (degrees N) ]
b	second coordinate [ Y(m), or longitude (degrees E) ]
c	third coordinate [ Z, height above ellipsoid or radius, in m ]
s	coordinate system
ell	pointer to EllipsoidModel

Exceptions

GeometryException on invalid input.

Definition at line 99 of file Position.cpp.

◆ Position() [3/5]

gnsstk::Position::Position	(	const double	ABC[3],
		CoordinateSystem	s = `Cartesian`,
		const EllipsoidModel *	ell = `nullptr`,
		const RefFrame &	frame = `RefFrame()`
	)

Explicit constructor. Coordinate system may be specified on input, but defaults to Cartesian. Pointer to EllipsoidModel may be specified, but default is NULL (in which case WGS84 values will be used).

Parameters

ABC	double array[3] coordinate values
s	CoordinateSystem
ell	pointer to EllipsoidModel

Exceptions

GeometryException on invalid input.

Definition at line 114 of file Position.cpp.

◆ Position() [4/5]

gnsstk::Position::Position	(	const Triple &	ABC,
		CoordinateSystem	s = `Cartesian`,
		const EllipsoidModel *	ell = `nullptr`,
		const RefFrame &	frame = `RefFrame()`
	)

Explicit constructor. Coordinate system may be specified on input, but defaults to Cartesian. Pointer to EllipsoidModel may be specified, but default is NULL (in which case WGS84 values will be used).

Parameters

ABC	coordinate values
s	CoordinateSystem
ell	pointer to EllipsoidModel

Exceptions

GeometryException on invalid input.

Definition at line 130 of file Position.cpp.

◆ Position() [5/5]

gnsstk::Position::Position ( const Xvt & xvt )

noexcept

Explicit constructor from Xvt. The coordinate system is Cartesian, and the velocity and time information in the input is ignored.

Parameters

xvt	Input Xvt object, xvt.x contains the Cartesian coordinates

Definition at line 145 of file Position.cpp.

◆ ~Position()

gnsstk::Position::~Position ( )

inlinenoexcept

Destructor.

Definition at line 253 of file Position.hpp.

Member Function Documentation

◆ asECEF()

Position& gnsstk::Position::asECEF ( )

inlinenoexcept

Convert to cartesian coordinates (does nothing if system == Cartesian already).

Definition at line 390 of file Position.hpp.

◆ asGeodetic() [1/2]

Position& gnsstk::Position::asGeodetic ( )

inlinenoexcept

Convert to geodetic coordinates (does nothing if system == Geodetic already).

Definition at line 373 of file Position.hpp.

◆ asGeodetic() [2/2]

Position& gnsstk::Position::asGeodetic ( EllipsoidModel * ell )

inline

Convert to another ell, then to geodetic coordinates.

Returns: a reference to this.

Exceptions

GeometryException if input is NULL.

Definition at line 380 of file Position.hpp.

◆ asString()

string gnsstk::Position::asString ( ) const

Returns the string that operator<<() would print.

Exceptions

StringUtils::StringException

Definition at line 1031 of file Position.cpp.

◆ azimuth()

double gnsstk::Position::azimuth ( const Position & Target ) const

A member function that computes the azimuth of the input (Target) position as seen from this Position.

Parameters

Target the Position which is observed to have the computed azimuth, as seen from this Position.

Returns: the azimuth in degrees

Exceptions

GeometryException

Definition at line 1365 of file Position.cpp.

◆ azimuthGeodetic()

double gnsstk::Position::azimuthGeodetic ( const Position & Target ) const

A member function that computes the azimuth of the input (Target) position as seen from this Position, using a Geodetic (ellipsoidal) system.

Parameters

Target the Position which is observed to have the computed azimuth, as seen from this Position.

Returns: the azimuth in degrees

Exceptions

GeometryException

Definition at line 1391 of file Position.cpp.

◆ convertCartesianToGeocentric()

void gnsstk::Position::convertCartesianToGeocentric	(	const Triple &	xyz,
		Triple &	llr
	)

staticnoexcept

Fundamental routine to convert cartesian (ECEF) to geocentric The zero vector is converted to (0,0,0).

Parameters

[in]	xyz	X,Y,Z
[out]	llr	geocentric lat(deg N), lon(deg E), radius (units of input)

Definition at line 1144 of file Position.cpp.

◆ convertCartesianToGeodetic()

void gnsstk::Position::convertCartesianToGeodetic	(	const Triple &	xyz,
		Triple &	llh,
		const double	A,
		const double	eccSq
	)

staticnoexcept

Fundamental routine to convert ECEF (cartesian) to geodetic coordinates, (Ellipsoid specified by semi-major axis and eccentricity squared). The zero vector is converted to (90,0,-R(earth)).

Parameters

[in]	xyz	X,Y,Z in meters
[out]	llh	geodetic lat(deg N), lon(deg E), height above ellipsoid (meters)
[in]	A	Earth semi-major axis
[in]	eccSq	square of Earth eccentricity Algorithm references: Leick, "GPS Satellite Surveying," 2nd edition.

Definition at line 1087 of file Position.cpp.

◆ convertCartesianToSpherical()

void gnsstk::Position::convertCartesianToSpherical	(	const Triple &	xyz,
		Triple &	tpr
	)

staticnoexcept

Fundamental routine to convert cartesian to spherical coordinates. The zero vector is converted to (90,0,0).

Parameters

[in]	xyz	X,Y,Z
[out]	tpr	theta, phi (degrees), radius (units of input) Algorithm references: standard geometry.

Definition at line 1058 of file Position.cpp.

◆ convertGeocentricToCartesian()

void gnsstk::Position::convertGeocentricToCartesian	(	const Triple &	llr,
		Triple &	xyz
	)

staticnoexcept

Fundamental routine to convert geocentric to cartesian (ECEF)

Parameters

[in]	llr	geocentric lat(deg N),lon(deg E),radius
[out]	xyz	X,Y,Z (units of radius)

Definition at line 1155 of file Position.cpp.

◆ convertGeocentricToGeodetic()

void gnsstk::Position::convertGeocentricToGeodetic	(	const Triple &	llr,
		Triple &	geodeticllh,
		const double	A,
		const double	eccSq
	)

staticnoexcept

Fundamental routine to convert geocentric to geodetic

Parameters

[in]	llr	geocentric lat(deg N),lon(deg E),radius (meters)
[out]	geodeticllh	geodetic latitude (deg N), longitude (deg E), and height above ellipsoid (meters)
[in]	A	Earth semi-major axis
[in]	eccSq	square of Earth eccentricity

Definition at line 1170 of file Position.cpp.

◆ convertGeodeticToCartesian()

void gnsstk::Position::convertGeodeticToCartesian	(	const Triple &	llh,
		Triple &	xyz,
		const double	A,
		const double	eccSq
	)

staticnoexcept

Fundamental routine to convert geodetic to ECEF (cartesian) coordinates, (Ellipsoid specified by semi-major axis and eccentricity squared).

Parameters

[in]	llh	geodetic lat(deg N), lon(deg E), height above ellipsoid (meters)
[in]	A	Earth semi-major axis
[out]	xyz	X,Y,Z in meters
[in]	eccSq	square of Earth eccentricity Algorithm references: Leick, "GPS Satellite Surveying," 2nd edition.

Definition at line 1126 of file Position.cpp.

◆ convertGeodeticToGeocentric()

void gnsstk::Position::convertGeodeticToGeocentric	(	const Triple &	geodeticllh,
		Triple &	llr,
		const double	A,
		const double	eccSq
	)

staticnoexcept

Fundamental routine to convert geodetic to geocentric

Parameters

[in]	geodeticllh	geodetic latitude (deg N), longitude (deg E), and height above ellipsoid (meters)
[out]	llr	geocentric lat (deg N),lon (deg E),radius (meters)
[in]	A	Earth semi-major axis
[in]	eccSq	square of Earth eccentricity

Definition at line 1216 of file Position.cpp.

◆ convertSphericalToCartesian()

void gnsstk::Position::convertSphericalToCartesian	(	const Triple &	tpr,
		Triple &	xyz
	)

staticnoexcept

Fundamental conversion from spherical to cartesian coordinates.

Parameters

[in]	tpr	theta, phi (degrees), radius
[out]	xyz	X,Y,Z in units of radius Algorithm references: standard geometry.

Definition at line 1044 of file Position.cpp.

◆ copyEllipsoidModelFrom()

void gnsstk::Position::copyEllipsoidModelFrom ( const Position & src )

inline

This is a bit of a kludge to deal with the fact that Position doesn't store the actual ellipsoid model but rather a couple of terms from it. It works by copying those terms from another object into this one.

Todo:: Modify Position to store a shared_ptr<EllipsoidModel> instead of AEarth, eccSquared etc.

Parameters

[in] src The Position object from which to copy ellipsoid model parameters.

Postcondition: AEarth=src.AEarth and eccSquared=src.eccSquared.

Definition at line 1018 of file Position.hpp.

◆ elevation()

double gnsstk::Position::elevation ( const Position & Target ) const

A member function that computes the elevation of the input (Target) position as seen from this Position.

Parameters

Target the Position which is observed to have the computed elevation, as seen from this Position.

Returns: the elevation in degrees

Exceptions

GeometryException

Definition at line 1308 of file Position.cpp.

◆ elevationGeodetic()

double gnsstk::Position::elevationGeodetic ( const Position & Target ) const

A member function that computes the elevation of the input (Target) position as seen from this Position, using a Geodetic (ellipsoidal) system.

Parameters

Target the Position which is observed to have the computed elevation, as seen from this Position.

Returns: the elevation in degrees

Exceptions

GeometryException

Definition at line 1331 of file Position.cpp.

◆ geocentricLatitude()

double gnsstk::Position::geocentricLatitude ( ) const

noexcept

return geocentric latitude (degrees North); equal to 90 degress - theta in regular spherical coordinates.

Definition at line 398 of file Position.cpp.

◆ geodeticLatitude()

double gnsstk::Position::geodeticLatitude ( ) const

noexcept

return geodetic latitude (degrees North).

Definition at line 386 of file Position.cpp.

◆ getAEarth()

double gnsstk::Position::getAEarth ( ) const

inline

Return the Earth semi-major axis (in meters) currently used for coordinate conversion

Definition at line 1026 of file Position.hpp.

◆ getAltitude()

double gnsstk::Position::getAltitude ( ) const

inlinenoexcept

return height above ellipsoid (meters)

Definition at line 469 of file Position.hpp.

◆ getCoordinateSystem()

CoordinateSystem gnsstk::Position::getCoordinateSystem ( ) const

inlinenoexcept

return the coordinate system for this Position

Definition at line 449 of file Position.hpp.

◆ getCurvMeridian()

double gnsstk::Position::getCurvMeridian ( ) const

noexcept

A member function that computes the radius of curvature of the meridian (Rm) corresponding to this Position.

Returns: radius of curvature of the meridian (in meters)

Definition at line 1487 of file Position.cpp.

◆ getCurvPrimeVertical()

double gnsstk::Position::getCurvPrimeVertical ( ) const

noexcept

A member function that computes the radius of curvature in the prime vertical (Rn) corresponding to this Position.

Returns: radius of curvature in the prime vertical (in meters)

Definition at line 1503 of file Position.cpp.

◆ getGeocentricLatitude()

double gnsstk::Position::getGeocentricLatitude ( ) const

inlinenoexcept

return geocentric latitude (deg N)

Definition at line 459 of file Position.hpp.

◆ getGeodeticLatitude()

double gnsstk::Position::getGeodeticLatitude ( ) const

inlinenoexcept

return geodetic latitude (deg N)

Definition at line 454 of file Position.hpp.

◆ getHeight()

double gnsstk::Position::getHeight ( ) const

inlinenoexcept

return height above ellipsoid (meters)

Definition at line 474 of file Position.hpp.

◆ getIonosphericPiercePoint()

Position gnsstk::Position::getIonosphericPiercePoint	(	const double	elev,
		const double	azim,
		const double	ionoht
	)		const

noexcept

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.

Parameters

elev	elevation angle in degrees of the signal at reception
azim	azimuth angle in degrees of the signal at reception
ionoht	height of the ionosphere, in meters

Returns: Position IPP the position of the ionospheric pierce point, in the same coordinate system as *this; *this is not modified.

Definition at line 1450 of file Position.cpp.

◆ getLongitude()

double gnsstk::Position::getLongitude ( ) const

inlinenoexcept

return longitude (deg E) (either geocentric or geodetic)

Definition at line 464 of file Position.hpp.

◆ getPhi()

double gnsstk::Position::getPhi ( ) const

inlinenoexcept

return spherical coordinate angle phi (deg) (same as longitude)

Definition at line 500 of file Position.hpp.

◆ getPositionTolerance()

static double gnsstk::Position::getPositionTolerance ( )

inlinestatic

Returns the current POSITION_TOLERANCE.

Definition at line 172 of file Position.hpp.

◆ getRadius()

double gnsstk::Position::getRadius ( ) const

inlinenoexcept

return radius

Definition at line 505 of file Position.hpp.

◆ getRayPerigee()

Position gnsstk::Position::getRayPerigee ( const Position & target ) const

Compute the ray-perigee position for the ray between this position and another. This position (P1) is expected to be a surface observer, while the target position (P2) is expected to be that of a satellite in orbit.

Precondition: In order to correctly compute the radius from the center of the earth, the ellipsoid model for both this object and target should be set via setEllipsoidModel prior to calling this method. Specifically, if one is using this method in the context of Galileo ionospheric modeling, one should have set the ellipsoid to an instance of GalileoIonoEllipsoid.

Note: This method will create a geodetic version of the two objects if they are not already in Geodetic coordinates.

Parameters

[in] target The orbital satellite position.

Returns: the ray-perigee geodetic position on the ellipsoid surface.

Definition at line 1552 of file Position.cpp.

◆ getRayPosition()

Position gnsstk::Position::getRayPosition	(	double	dist,
		const Position &	target
	)		const

Compute the coordinates at a given distance along a path between two positions.

Parameters

[in]	dist	The distance in METERS along the path between this and target.
[in]	target	The target position of the ray (e.g. ray perigee coordinates).

Returns: The position along the ray.

< Great circle angle from ray-perigee to satellite

< azimuth of satellite as seen from ray-perigee pp

Definition at line 1604 of file Position.cpp.

◆ getReferenceFrame()

const RefFrame & gnsstk::Position::getReferenceFrame ( ) const

noexcept

return coordinate RefFrame

Definition at line 346 of file Position.cpp.

◆ getSystemName()

string gnsstk::Position::getSystemName ( )

noexcept

return string giving name of coordinate system

Definition at line 63 of file Position.cpp.

◆ getTheta()

double gnsstk::Position::getTheta ( ) const

inlinenoexcept

Returns: spherical coordinate angle theta (deg) (90 - geocentric latitude)

Definition at line 495 of file Position.hpp.

◆ getX()

double gnsstk::Position::getX ( ) const

inlinenoexcept

return ECEF X coordinate (meters)

Definition at line 479 of file Position.hpp.

◆ getY()

double gnsstk::Position::getY ( ) const

inlinenoexcept

return ECEF Y coordinate (meters)

Definition at line 484 of file Position.hpp.

◆ getZ()

double gnsstk::Position::getZ ( ) const

inlinenoexcept

return ECEF Z coordinate (meters)

Definition at line 489 of file Position.hpp.

◆ getZenithAngle() [1/2]

Angle gnsstk::Position::getZenithAngle	(	const Angle &	phi1,
		const Angle &	lambda1,
		const Angle &	phi2,
		const Angle &	lambda2,
		double	r1,
		double	r2,
		AngleReduced &	delta
	)

static

Compute the zenith angle ζ between P1=(phi1,lambda1,r1) and P2=(phi2,lambda2,r2). With the center of Earth C, this is the angle between CP1 and P1P2. This position (P1) is expected to be a surface observer, while the target position (P2) is expected to be that of a satellite in orbit.

Parameters

[in]	phi1	The geodetic latitude of the surface observer.
[in]	lambda1	The longitude of the surface observer.
[in]	phi2	The geodetic latitude of the target satellite.
[in]	lambda2	The longitude of the target satellite.
[in]	r1	The distance from Earth center of the surface observer (units must be consistent with r2).
[in]	r2	The distance from Earth center of the surface observer (units must be consistent with r1).
[out]	delta	The computed delta angle, being the Earth angle on the great circle connecting receiver antenna P1 and the satellite P2. This is used to compute the zenith angle, but is also used to compute the ray perigee, so it is output as an extra variable here.

Returns: the zenith angle between this and target.

Definition at line 1535 of file Position.cpp.

◆ getZenithAngle() [2/2]

Angle gnsstk::Position::getZenithAngle	(	const Position &	target,
		AngleReduced &	delta
	)		const

Compute the zenith angle ζ from this position to another. With the center of the earth C, this position being P1, and the second position being P2, This is the angle between CP1 and P1P2. This position (P1) is expected to be a surface observer, while the target position (P2) is expected to be that of a satellite in orbit.

Precondition: In order to correctly compute the radius from the center of the earth, the ellipsoid model for both this object and target should be set via setEllipsoidModel prior to calling this method. Specifically, if one is using this method in the context of Galileo ionospheric modeling, one should have set the ellipsoid to an instance of GalileoIonoEllipsoid.

Note: This method will create a geodetic version of the two objects if they are not already in Geodetic coordinates.

Parameters

[in]	target	The orbital satellite position.
[out]	delta	The angle between CP1 and CP2.

Returns: the zenith angle between this and target.

Definition at line 1514 of file Position.cpp.

◆ height()

double gnsstk::Position::height ( ) const

noexcept

return height above ellipsoid (meters) (Geodetic).

Definition at line 455 of file Position.cpp.

◆ initialize()

void gnsstk::Position::initialize	(	const double	a,
		const double	b,
		const double	c,
		Position::CoordinateSystem	s = `Cartesian`,
		const EllipsoidModel *	ell = `nullptr`,
		const RefFrame &	frame = `RefFrame()`
	)

private

Initialization function, used by the constructors.

Parameters

a	coordinate [ X(m), or latitude (degrees N) ]
b	coordinate [ Y(m), or longitude (degrees E) ]
c	coordinate [ Z, height above ellipsoid or radius, in m ]
s	CoordinateSystem, defaults to Cartesian
ell	pointer to a EllipsoidModel, default NULL (WGS84)

Exceptions

GeometryException on invalid input.

Definition at line 1701 of file Position.cpp.

◆ longitude()

double gnsstk::Position::longitude ( ) const

noexcept

return longitude (degrees East); equal to phi in regular spherical coordinates.

Definition at line 432 of file Position.cpp.

◆ operator!=()

bool gnsstk::Position::operator!= ( const Position & right ) const

noexcept

Inequality operator. Return true if range between this Position and the input Position is greater than tolerance. Return true if ellipsoid values differ.

Parameters

right Position to be compared to this Position

Definition at line 235 of file Position.cpp.

◆ operator+=()

Position & gnsstk::Position::operator+= ( const Position & right )

noexcept

Add a Position to this Position. Perform the addition in Cartesian coordinates, but return this Position to the system it had originally.

Parameters

right Position to add to this one.

Returns: new Position, in the original system.

Definition at line 173 of file Position.cpp.

◆ operator-=()

Position & gnsstk::Position::operator-= ( const Position & right )

noexcept

Subtract a Position from this Position. Perform the subtraction in Cartesian coordinates, but return this Position to the system it had originally.

Parameters

right Position to subtract from this one.

Returns: new Position, in the original system.

Definition at line 156 of file Position.cpp.

◆ operator==()

bool gnsstk::Position::operator== ( const Position & right ) const

noexcept

Equality operator. Return true if range between this Position and the input Position is less than tolerance. Return false if ellipsoid values differ.

Parameters

right Position to be compared to this Position

Definition at line 221 of file Position.cpp.

◆ phi()

double gnsstk::Position::phi ( ) const

noexcept

return spherical coordinate phi in degrees

Definition at line 420 of file Position.cpp.

◆ printf() [1/2]

std::string gnsstk::Position::printf ( const char * fmt ) const

Format this Position into a string.

Generate and return a string containing formatted Position coordinates, formatted by the specification fmt.

%x X() (meters)
%y Y() (meters)
%z Z() (meters)
%X X()/1000 (kilometers)
%Y Y()/1000 (kilometers)
%Z Z()/1000 (kilometers)
%A geodeticLatitude() (degrees North)
%a geocentricLatitude() (degrees North)
%L longitude() (degrees East)
%l longitude() (degrees East)
%w longitude() (degrees West)
%W longitude() (degrees West)
%t theta() (degrees)
%T theta() (radians)
%p phi() (degrees)
%P phi() (radians)
%r radius() meters
%R radius()/1000 kilometers
%h height() meters
%H height()/1000 kilometers

Parameters

fmt	format to use for this time.

Returns: a string containing this Position in the representation specified by fmt.

Exceptions

StringUtils::StringException

Definition at line 982 of file Position.cpp.

◆ printf() [2/2]

std::string gnsstk::Position::printf ( const std::string & fmt ) const

inline

Format this time into a string.

See also: printf(const char*)

Exceptions

StringUtils::StringException

Definition at line 694 of file Position.hpp.

◆ radius()

double gnsstk::Position::radius ( ) const

noexcept

return distance from the center of Earth (meters), Same as radius in spherical coordinates.

Definition at line 444 of file Position.cpp.

◆ radiusEarth() [1/2]

double gnsstk::Position::radiusEarth ( ) const

inlinenoexcept

A member function that calls the non-member radiusEarth() for this Position.

Returns: the Earth radius (in meters)

Definition at line 841 of file Position.hpp.

◆ radiusEarth() [2/2]

double gnsstk::Position::radiusEarth	(	const double	geolat,
		const double	A,
		const double	eccSq
	)

staticnoexcept

Compute the radius of the ellipsoidal Earth, given the geodetic latitude.

Parameters

geolat geodetic latitude in degrees

Returns: the Earth radius (in meters)

Definition at line 1292 of file Position.cpp.

◆ setECEF() [1/3]

Position & gnsstk::Position::setECEF	(	const double	X,
		const double	Y,
		const double	Z
	)

noexcept

Set the Position given ECEF coordinates; system is set to Cartesian.

Parameters

X	ECEF X coordinate in meters.
Y	ECEF Y coordinate in meters.
Z	ECEF Z coordinate in meters.

Returns: a reference to this object.

Definition at line 601 of file Position.cpp.

◆ setECEF() [2/3]

Position& gnsstk::Position::setECEF ( const double XYZ[3] )

inlinenoexcept

Set the Position given an array of ECEF coordinates; system is set to Cartesian.

Parameters

XYZ	array[3] ECEF X,Y,Z coordinate in meters.

Returns: a reference to this object.

Definition at line 584 of file Position.hpp.

◆ setECEF() [3/3]

Position& gnsstk::Position::setECEF ( const Triple & XYZ )

inlinenoexcept

Set the Position given ECEF coordinates; system is set to Cartesian.

Parameters

XYZ	ECEF X,Y,Z coordinates in meters.

Returns: a reference to this object.

Definition at line 594 of file Position.hpp.

◆ setEllipsoidModel()

void gnsstk::Position::setEllipsoidModel ( const EllipsoidModel * ell )

Set the ellipsoid values for this Position given a ellipsoid.

Parameters

ell	Pointer to the EllipsoidModel.

Exceptions

GeometryException if input is NULL.

Definition at line 478 of file Position.cpp.

◆ setGeocentric()

Position & gnsstk::Position::setGeocentric	(	const double	lat,
		const double	lon,
		const double	rad
	)

Set the Position given geocentric coordinates; system is set to Geocentric

Parameters

lat	geocentric latitude in degrees North
lon	geocentric longitude in degrees East
rad	radius from the Earth's center in meters

Returns: a reference to this object.

Exceptions

GeometryException on invalid input

Definition at line 531 of file Position.cpp.

◆ setGeodetic()

Position & gnsstk::Position::setGeodetic	(	const double	lat,
		const double	lon,
		const double	ht,
		const EllipsoidModel *	ell = `nullptr`
	)

Set the Position given geodetic coordinates; system is set to Geodetic.

Parameters

lat	geodetic latitude in degrees North
lon	geodetic longitude in degrees East
ht	height above the ellipsoid in meters

Returns: a reference to this object.

Exceptions

GeometryException on invalid input

Definition at line 495 of file Position.cpp.

◆ setPositionTolerance()

static double gnsstk::Position::setPositionTolerance ( const double tol )

inlinestatic

Changes the POSITION_TOLERANCE for all Position objects.

Definition at line 168 of file Position.hpp.

◆ setReferenceFrame()

void gnsstk::Position::setReferenceFrame ( const RefFrame & frame )

noexcept

Set the RefFrame that this position is in.

Parameters

frame The RefFrame to set to.

Definition at line 467 of file Position.cpp.

◆ setSpherical()

Position & gnsstk::Position::setSpherical	(	const double	theta,
		const double	phi,
		const double	rad
	)

Set the Position given spherical coordinates; system is set to Spherical

Parameters

theta	angle from the Z-axis (degrees)
phi	angle from the X-axis in the XY plane (degrees)
rad	radius from the center in meters

Returns: a reference to this object.

Exceptions

GeometryException on invalid input

Definition at line 566 of file Position.cpp.

◆ setTolerance()

Position & gnsstk::Position::setTolerance ( const double tol )

noexcept

Sets the tolerance for output and comparisons, for this object only. See the constants in this file (e.g. ONE_MM_TOLERANCE) for some easy to use tolerance values.

Parameters

tol	Tolerance in meters to be used by comparison operators.

See also: Position-Specific Definitions

Definition at line 82 of file Position.cpp.

◆ setToString()

Position & gnsstk::Position::setToString	(	const std::string &	str,
		const std::string &	fmt
	)

setToString, similar to scanf, this function takes a string and a format describing string in order to define Position values. The parameters it can take are listed below and described above with the printf() function.

The specification must be sufficient to define a Position. The following table lists combinations that give valid Positions. Anything more or other combinations will give unknown (read as: "bad") results so don't try it. Anything less will throw an exception.

%X %Y %Z  (cartesian or ECEF in kilometers)
%x %y %z  (cartesian or ECEF in meters)
%a %l %r  (geocentric lat,lon,radius, longitude E, radius in meters)
%A %L %h  (geodetic lat,lon,height, longitude E, height in meters)
%a %w %R  (geocentric lat,lon,radius, longitude W, radius in kilometers)
%A %W %H  (geodetic lat,lon,height, longitude W, height in kilometers)
%t %p %r  (spherical theta, phi, radius, degrees and meters)
%T %P %R  (spherical theta, phi, radius, radians and kilometers)

So

pos.setToString("123.4342,9328.1982,-128987.399", "%X,%Y,%Z");

works but

pos.setToString("123.4342,9328.1982", "%X,%Y");

doesn't work (incomplete specification because it doesn't specify a Position).

Whitespace is unimportant here; the function will handle it. The caller must ensure that that the extra characters in the format string (ie '.' ',') are in the same relative location as they are in the actual string; see the example above.

Parameters

str	string from which to get the Position coordinates
fmt	format to use to parse `str`.

Exceptions

GeometryException	if `fmt` is an incomplete or invalid specification
StringException	if an error occurs manipulating the `str` or `fmt` strings.

Returns: a reference to this object.

Definition at line 658 of file Position.cpp.

◆ theta()

double gnsstk::Position::theta ( ) const

noexcept

return spherical coordinate theta in degrees

Definition at line 409 of file Position.cpp.

◆ transformTo()

Position & gnsstk::Position::transformTo ( CoordinateSystem sys )

noexcept

Transform coordinate system. Does nothing if sys already matches the current value of member CoordinateSystem 'system'.

Parameters

sys	CoordinateSystem into which this Position is transformed

Definition at line 247 of file Position.cpp.

◆ X()

double gnsstk::Position::X ( ) const

noexcept

return X coordinate (meters)

Definition at line 353 of file Position.cpp.

◆ Y()

double gnsstk::Position::Y ( ) const

noexcept

return Y coordinate (meters)

Definition at line 364 of file Position.cpp.

◆ Z()

double gnsstk::Position::Z ( ) const

noexcept

return Z coordinate (meters)

Definition at line 375 of file Position.cpp.

Friends And Related Function Documentation

◆ operator* [1/4]

Position operator*	(	const double &	scale,
		const Position &	right
	)

friend

Multiply a Position by a double scalar on the left.

Parameters

right	Position to be multiplied by the scalar
scale	the (double) scalar

Returns: The new Position.

Definition at line 303 of file Position.hpp.

◆ operator* [2/4]

Position operator*	(	const int &	scale,
		const Position &	right
	)

friend

Multiply a Position by an integer scalar on the left.

Parameters

right	Position to be multiplied by the scalar
scale	the (int) scalar

Returns: The new Position.

Definition at line 327 of file Position.hpp.

◆ operator* [3/4]

Position operator*	(	const Position &	left,
		const double &	scale
	)

friend

Multiply a Position by a double scalar on the right.

Parameters

left	Position to be multiplied by the scalar
scale	the (double) scalar

Returns: The new Position.

Definition at line 316 of file Position.hpp.

◆ operator* [4/4]

Position operator*	(	const Position &	left,
		const int &	scale
	)

friend

Multiply a Position by an integer scalar on the right.

Parameters

left	Position to be multiplied by the scalar
scale	the (int) scalar

Returns: The new Position.

Definition at line 338 of file Position.hpp.

◆ operator+

Position operator+	(	const Position &	left,
		const Position &	right
	)

friend

Add two Positions, returning result as a Position in Cartesian coordinates, the only system in which a position sum makes sense.

Parameters

right Position to add to this one.

Returns: The new Position.

Definition at line 204 of file Position.cpp.

◆ operator-

Position operator-	(	const Position &	left,
		const Position &	right
	)

friend

Difference two Positions, returning result as a Position in Cartesian coordinates, the only system in which a position difference makes sense.

Parameters

right Position to subtract from this one.

Returns: difference as Position.

Definition at line 190 of file Position.cpp.

◆ operator<<

std::ostream& operator<<	(	std::ostream &	s,
		const Position &	p
	)

friend

Stream output for Position objects.

Parameters

s	stream to append formatted Position to.
p	Position to append to stream `s`.

Returns: reference to s.

◆ range

double range	(	const Position &	A,
		const Position &	B
	)

friend

Compute the range in meters between two Positions. Input Positions are not modified.

Parameters

A,B	Positions between which to find the range

Returns: the range (in meters)

Exceptions

GeometryException	if ellipsoid values differ. or if transformTo(Cartesian) fails
GeometryException

Definition at line 1273 of file Position.cpp.

Member Data Documentation

◆ AEarth

double gnsstk::Position::AEarth

private

semi-major axis of Earth (meters)

Definition at line 1062 of file Position.hpp.

◆ eccSquared

double gnsstk::Position::eccSquared

private

square of ellipsoid eccentricity

Definition at line 1065 of file Position.hpp.

◆ ONE_CM_TOLERANCE

const double gnsstk::Position::ONE_CM_TOLERANCE = 0.01

static

One centimeter tolerance.

Definition at line 160 of file Position.hpp.

◆ ONE_MM_TOLERANCE

const double gnsstk::Position::ONE_MM_TOLERANCE = 0.001

static

One millimeter tolerance.

Definition at line 158 of file Position.hpp.

◆ ONE_UM_TOLERANCE

const double gnsstk::Position::ONE_UM_TOLERANCE = 0.000001

static

One micron tolerance.

Definition at line 162 of file Position.hpp.

◆ POSITION_TOLERANCE

double gnsstk::Position::POSITION_TOLERANCE = Position::ONE_MM_TOLERANCE

static

Default tolerance for time equality in days.

Definition at line 165 of file Position.hpp.

◆ refFrame

RefFrame gnsstk::Position::refFrame

private

Definition at line 1073 of file Position.hpp.

◆ system

CoordinateSystem gnsstk::Position::system

private

see CoordinateSystem

Definition at line 1068 of file Position.hpp.

◆ tolerance

double gnsstk::Position::tolerance

private

tolerance used in comparisons

Definition at line 1071 of file Position.hpp.

The documentation for this class was generated from the following files:

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Member Enumeration Documentation

◆ CoordinateSystem

Constructor & Destructor Documentation

◆ Position() [1/5]

◆ Position() [2/5]

◆ Position() [3/5]

◆ Position() [4/5]

◆ Position() [5/5]

◆ ~Position()

Member Function Documentation

◆ asECEF()

◆ asGeodetic() [1/2]

◆ asGeodetic() [2/2]

◆ asString()

◆ azimuth()

◆ azimuthGeodetic()

◆ convertCartesianToGeocentric()

◆ convertCartesianToGeodetic()

◆ convertCartesianToSpherical()

◆ convertGeocentricToCartesian()

◆ convertGeocentricToGeodetic()

◆ convertGeodeticToCartesian()

◆ convertGeodeticToGeocentric()

◆ convertSphericalToCartesian()

◆ copyEllipsoidModelFrom()

◆ elevation()

◆ elevationGeodetic()

◆ geocentricLatitude()

◆ geodeticLatitude()

◆ getAEarth()

◆ getAltitude()

◆ getCoordinateSystem()

◆ getCurvMeridian()

◆ getCurvPrimeVertical()

◆ getGeocentricLatitude()

◆ getGeodeticLatitude()

◆ getHeight()

◆ getIonosphericPiercePoint()

◆ getLongitude()

◆ getPhi()

◆ getPositionTolerance()

◆ getRadius()

◆ getRayPerigee()

◆ getRayPosition()

◆ getReferenceFrame()

◆ getSystemName()

◆ getTheta()

◆ getX()

◆ getY()

◆ getZ()

◆ getZenithAngle() [1/2]

◆ getZenithAngle() [2/2]

◆ height()

◆ initialize()

◆ longitude()

◆ operator!=()

◆ operator+=()

◆ operator-=()

◆ operator==()

◆ phi()

◆ printf() [1/2]

◆ printf() [2/2]

◆ radius()

◆ radiusEarth() [1/2]

◆ radiusEarth() [2/2]

◆ setECEF() [1/3]

◆ setECEF() [2/3]

◆ setECEF() [3/3]

◆ setEllipsoidModel()

◆ setGeocentric()

◆ setGeodetic()