PCL

Reduction of planetary and stellar positions. More...
#include <Position.h>
Static Public Member Functions  
static Vector  EquatorialToEcliptic (const Vector &q, double se, double ce) 
static Vector  EquatorialToEcliptic (const Vector &q, double eps) 
static DPoint  EquatorialToEcliptic (const DPoint &q, double se, double ce) 
static DPoint  EquatorialToEcliptic (const DPoint &q, double eps) 
static Vector  ICRSEquatorialToGalactic (const Vector &q) 
static DPoint  ICRSEquatorialToGalactic (const DPoint &q) 
This class implements algorithms for reduction of positions of solar system bodies and stars. It allows for calculation of geometric, astrometric, proper, apparent and intermediate places, including geocentric and topocentric coordinates.
The implemented vector astrometry and ephemeris calculation algorithms are rigorous and compliant with current IAU and IERS resolutions. Both equinoxbased and CIObased paradigms have been implemented for calculation of positions that depend on Earth's rotation. The apparent and intermediate places include the following corrections:
Vector components are expressed in astronomical units (au) for stars and all solar system bodies except the Moon, for which positions are given in kilometers.
As of writing this documentation (October 2018), the IAU 2006/2000A precessionnutation theory is implemented (adjusted model with corrections to nutation angles, IAU 2006/2000A_{R}). The standard fundamental ephemerides are JPL's DE438/LE438.
Most of the reference publications and material used are cited in source code comments and the documentation. The main authoritative resource is:
Urban, Sean E., Kenneth Seidelmann, P., ed. (2013), The Explanatory Supplement to the Astronomical Almanac 3rd Edition.
Definition at line 318 of file Position.h.
Constructs a Position object initialized for the specified time of calculation t in the specified timescale.
The supported time scales are:
TT  Terrestrial Time. This is the default timescale. 
TDB  Barycentric Dynamical Time. 
Teph  Ephemeris time, as defined by JPL DE/LE numerical integrations. For all purposes, this is equivalent to TDB. 
UTC  Coordinated Universal Time. 
TAI  Atomic International Time. 
UT1  Universal Time. 
UT  Universal Time (same as UT1). 
timescale string values are considered casesensitive.
All necessary timescale conversions to compute ephemerides and reduction of positions are performed automatically.

default 
Copy constructor.

default 
Move constructor.
Vector pcl::Position::Apparent  (  EphemerisFile::Handle &  H  ) 
Computes the apparent place of a solar system body.
The returned vector is the apparent place of the object defined by the specified ephemeris handle H in geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
Vector pcl::Position::Apparent  (  const StarPosition &  S  ) 
Computes the apparent place of a star.
The returned vector is the apparent place calculated for the positional star data defined by the specified object S. Its components are geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
Optional<double> pcl::Position::ApparentVisualMagnitude  (  EphemerisFile::Handle &  H  ) 
Returns the observed visual magnitude of a solar system body.
For objects with known H and G values (absolute magnitude and slope parameters, respectively; see EphemerisFile::Handle::H() and EphemerisFile::Handle::G()), the apparent visual magnitude is calculated applying the algorithm for minor planets described in Bowell et al. (1989). See also The Explanatory Supplement, Section 10.4.3.
For Mercury, Venus, Mars, Jupiter, Saturn and Neptune, we apply the equations described in the following paper:
Anthony Mallama, James L. Hilton, Computing Apparent Planetary Magnitudes for The Astronomical Almanac, revised 2018 June 21.
As of writing this documentation, the above paper is available online at: https://arxiv.org/pdf/1808.01973.pdf
For Saturn, we compute the apparent visual magnitude taking into account the planet's rings.
For Uranus, Pluto and the Galilean satellites of Jupiter, data from various sources are taken from Table 10.6 of the Explanatory Supplement.
If the required data are not available, or if no algorithm is known for the calculation of the apparent visual magnitude of the specified object, this member function returns an undefined Optional object.
An undefined object is also returned when the phase angle of the object at the time of calculation is beyond the limits of the set of observations used to generate the underlying models. For Mercury, apparent magnitudes are only calculated for phase angles 2° ≤ i ≤ 170°. For Venus, the magnitude is only calculated for 0° < i ≤ 163°.7. The valid range for Mars is i ≤ 50°.
Vector pcl::Position::Astrometric  (  EphemerisFile::Handle &  H  ) 
Computes the astrometric place of a solar system body.
The returned vector is the astrometric place of the object defined by the specified ephemeris handle H in geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
An astrometric place does not include annual aberration, nutation and precession corrections. Hence it is referred to an 'hybrid' reference system, but similar to GCRS J2000.0.
Vector pcl::Position::Astrometric  (  const StarPosition &  S  ) 
Computes the astrometric place of a star.
The returned vector is the astrometric place calculated for the positional star data defined by the specified object S. Its components are geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
An astrometric place does not include annual aberration, nutation and precession corrections. Hence it is referred to an 'hybrid' reference system, but similar to GCRS J2000.0.

inline 
Returns the ICRS barycentric position of the Earth (barycentric rectangular equatorial coordinates), computed for the TDB time of calculation by the class constructor. The components of the returned vector are expressed in au.
Definition at line 855 of file Position.h.

inline 
Returns the ICRS barycentric position of the Sun (barycentric rectangular equatorial coordinates), computed for the TDB time of calculation by the class constructor. The components of the returned vector are in au.
Definition at line 876 of file Position.h.

inline 
Returns the ICRS barycentric velocity of the Earth (barycentric rectangular equatorial coordinates), computed for the TDB time of calculation by the class constructor. The components of the returned vector are expressed in au/day.
Definition at line 866 of file Position.h.
bool pcl::Position::CanComputeApparentVisualMagnitude  (  const EphemerisFile::Handle &  H  )  const 
Returns true iff the apparent visual magnitude of the object represented by the specified handle H can be calculated with the current implementation, at the calculation time defined by this instance.
Currently apparent visual magnitudes can be calculated for the following solar system bodies:

inline 
The Celestial Intermediate Origin (CIO) locator, in radians.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 1042 of file Position.h.

inline 
Returns the inverse of the CIObased combined biasprecessionnutation matrix.
This member function calls InitCIOBasedParameters() to ensure that all data required for equinoxbased and CIObased reduction of positions is available.
Definition at line 997 of file Position.h.

inline 
Returns the CIObased combined biasprecessionnutation matrix.
This member function calls InitCIOBasedParameters() to ensure that all data required for equinoxbased and CIObased reduction of positions is available.
Definition at line 983 of file Position.h.

inline 
Coordinates of the Celestial Intermediate Pole (CIP) in the GCRS, in radians.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 1010 of file Position.h.
Vector pcl::Position::CIP_ITRS  (  )  const 
Coordinates of the Celestial Intermediate Pole (CIP) in the ITRS.
If possible, this member function returns an interpolated value from the global CIP_ITRS database, which will be loaded and parsed upon the first call to this function as a threadsafe procedure. See EphemerisFile::CIP_ITRSDataFilePath() and EphemerisFile::OverrideCIP_ITRSDataFilePath() for more information. See also IsPolarMotionEnabled() for some practical considerations.
Otherwise, if the time of calculation for this object falls outside the CIP_ITRS database time span, this function will return a twodimensional vector with zero components.
The components of the returned 2D vector are the coordinates x_{p}, y_{p} of the CIP with respect to the ITRS, expressed in radians.

inline 
Disables polar motion corrections for calculation of topocentric places. See the CIP_ITRS() and IsPolarMotionEnabled() functions for more details.
Definition at line 795 of file Position.h.

inline 
Enables polar motion corrections for calculation of topocentric places. See the CIP_ITRS() and IsPolarMotionEnabled() functions for more details.
Definition at line 786 of file Position.h.

inline 
Equation of the origins, expressed in radians.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 1054 of file Position.h.

inline 
Mean obliquity of the ecliptic, in radians.
Definition at line 1087 of file Position.h.
References pcl::AsRad(), and pcl::Poly().

inlinestatic 
Conversion from rectangular equatorial to rectangular ecliptic coordinates.
q  Rectangular equatorial coordinates. 
se  Sine of the obliquity of the ecliptic. 
ce  Cosine of the obliquity of the ecliptic. 
Returns a vector whose components are the rectangular ecliptic coordinates corresponding to the specified equatorial position q at the epoch where the specified obliquity has been calculated.
Definition at line 1183 of file Position.h.
Conversion from rectangular equatorial to rectangular ecliptic coordinates.
q  Rectangular equatorial coordinates. 
eps  Oliquity of the ecliptic in radians. 
Returns a vector whose components are the rectangular ecliptic coordinates corresponding to the specified equatorial position q at the epoch where the specified obliquity has been calculated.
Definition at line 1201 of file Position.h.
References pcl::SinCos().

inlinestatic 
Conversion from spherical equatorial to spherical ecliptic coordinates.
q  Spherical equatorial coordinates in radians, where q.x is the right ascension and q.y is the declination. 
se  Sine of the obliquity of the ecliptic. 
ce  Cosine of the obliquity of the ecliptic. 
Returns the ecliptic coordinates in radians as a point p, where p.x is the longitude in the range [0,2pi) and p.y is the latitude in [pi/2,+pi/2].
Definition at line 1221 of file Position.h.
Conversion from spherical equatorial to spherical ecliptic coordinates.
q  Spherical equatorial coordinates in radians, where q.x is the right ascension and q.y is the declination. 
eps  Oliquity of the ecliptic in radians. 
Returns the ecliptic coordinates in radians as a point p, where p.x is the longitude in the range [0,2pi) and p.y is the latitude in [pi/2,+pi/2].
Definition at line 1240 of file Position.h.
References pcl::SinCos().

inline 
Returns the inverse of the equinoxbased combined biasprecessionnutation matrix.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 970 of file Position.h.

inline 
Returns the equinoxbased combined biasprecessionnutation matrix.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 957 of file Position.h.

inline 
Earth rotation angle, expressed in radians.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 1066 of file Position.h.

inline 
Greenwich apparent sidereal time, expressed in radians.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 1078 of file Position.h.
Vector pcl::Position::Geometric  (  EphemerisFile::Handle &  H  ) 
Computes the geometric position of a solar system body.
The components of the returned vector are the geocentric or topocentric rectangular equatorial coordinates for the instant of calculation defined by this object in the TT timescale, accounting for lighttravel time, for the body defined by the specified ephemeris handle H.
The implemented reduction algorithm includes just the correction for lighttravel time, but no corrections for light deflection, annual aberration, nutation, or precession. The position so calculated allows to plot the specified body directly on an existing sky chart referred to GCRS/J2000.0. Note however, that for generation of new graphical representations for a given date using star catalog data, astrometric or proper places should be used instead.
Vector pcl::Position::Geometric  (  const StarPosition &  S  ) 
Computes the geometric position of a star.
The components of the returned vector are the geocentric or topocentric rectangular equatorial coordinates for the instant of calculation defined by this object in the TT timescale, for the positional star data defined by the specified object S.
The implemented reduction algorithm includes just the corrections for space motion: parallax, radial velocity and proper motions, when the corresponding data items are nonzero in the specified object S. The space motion vector includes terms to account for the relativistic Doppler effect.

inline 
Returns the ICRS heliocentric position of the Earth (heliocentric rectangular equatorial coordinates), computed for the TDB time of calculation by the class constructor. The components of the returned vector are expressed in au.
Definition at line 887 of file Position.h.
Conversion from ICRS rectangular equatorial to rectangular galactic coordinates.
q  Rectangular equatorial coordinates in the ICRS. 
Returns a vector whose components are the calculated rectangular galactic coordinates.
In this routine we adopt the proposed ICRS coordinates of the galactic pole in:
JiaCheng Liu, Zi Zhu, and Hong Zhang, Reconsidering the galactic coordinate system, Astronomy & Astrophysics manuscript no. AA2010, October 26, 2018.
The applied conventional definitions are as follows. The ICRS equatorial coordinates of the zero point of galactic coordinates are:
α = 17^{h}45^{m}40^{s}.0400 δ = –29°00'28".138
The equatorial coordinates of the galactic pole, coherent with the ICRS, are:
α^{p} = 12^{h}51^{m}36^{s}.7151981 δ^{p} = +27°06'11".193172
Note that these definitions are not consistent with the conventional values currently accepted by the IAU. The current (as of October 2018) galactic coordinate system was defined by the IAU in 1959 in the FK4 B1950.0 reference system.
Definition at line 1279 of file Position.h.
Conversion from ICRS spherical equatorial to spherical galactic coordinates.
q  Spherical ICRS equatorial coordinates in radians, where q.x is the right ascension and q.y is the declination. 
Returns the galactic coordinates in radians as a point p, where p.x is the longitude in the range [0,2pi) and p.y is the latitude in [pi/2,+pi/2].
See the documentation for ICRSEquatorialToGalactic( const Vector& ) for critical information on the adopted galactic coordinate system.
Definition at line 1300 of file Position.h.
void pcl::Position::InitCIOBasedParameters  (  ) 
Calculates all parameters and data structures necessary for CIObased reduction of positions.
This member function starts by calling InitEquinoxBasedParameters(), so it implicitly calculates all equinoxbased parameters. Then it calculates the CIObased combined biasprecessionnutation matrix. See ESAsA sections 6.7 and 7.2.5.2.
Since all of these items depend exclusively on time, they are computed only once in the first call to this function, and subsequent calls will have no effect.
Normally, you don't have to call this function directly because it is invoked automatically when necessary by the different position reduction routines.
void pcl::Position::InitEquinoxBasedParameters  (  ) 
Calculates all parameters and data structures necessary for equinoxbased reduction of positions.
This member function calculates the following structures:
Since all of these items depend exclusively on time, they are computed only once in the first call to this function, and subsequent calls will have no effect.
Normally, you don't have to call this function directly because it is invoked automatically when necessary by the different position reduction routines.
Vector pcl::Position::Intermediate  (  EphemerisFile::Handle &  H  ) 
Computes the intermediate place of a solar system body.
The returned vector is the intermediate place of the object defined by the specified ephemeris handle H in geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
Vector pcl::Position::Intermediate  (  const StarPosition &  S  ) 
Computes the intermediate place of a star.
The returned vector is the intermediate place calculated for the positional star data defined by the specified object S. Its components are geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:

inline 
Returns true iff topocentric places take into account polar motion corrections to compute the geocentric position and velocity of the observer. This involves calculation of CIP coordinates with respect to the ITRS, as well as access to a database of CIP/ITRS positions. See the CIP_ITRS() member function for more details.
Polar motion introduces changes at the mas level for calculation of topocentric coordinates of the Moon. For the rest of objects, the effect of polar motion corrections is completely negligible. For topocentric positions of the Moon, polar motion can be necessary to achieve the highest accuracy, but in such case one may also have to take into account a regional geoid referred to the Earth's reference ellipsoid. See the ObserverPosition structure.
Definition at line 777 of file Position.h.

inline 
Returns true iff a valid observer location has been defined for this object in a previous call to SetObserver().
Definition at line 757 of file Position.h.

inline 
Returns the nutation angles in radians as a point p, where p.x is the nutation in longitude and p.y is the nutation in obliquity.
This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinoxbased reduction of positions is available.
Definition at line 1102 of file Position.h.

inline 
Returns the current observer. If no observer has been defined for this object, returns a defaultconstructed structure for a fictitious observer at the geocenter.
Definition at line 746 of file Position.h.
Copy assignment operator. Returns a reference to this object.
Move assignment operator. Returns a reference to this object.
Vector pcl::Position::Proper  (  EphemerisFile::Handle &  H  ) 
Computes the proper place of a solar system body.
The returned vector is the proper place of the object defined by the specified ephemeris handle H in geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
A proper place does not include nutation and precession corrections, hence it is referred to the reference coordinate system: GCRS J2000.0.
Vector pcl::Position::Proper  (  const StarPosition &  S  ) 
Computes the proper place of a star.
The returned vector is the proper place calculated for the positional star data defined by the specified object S. Its components are geocentric or topocentric rectangular equatorial coordinates, calculated for the instant defined by this object in the TT timescale.
The implemented reduction algorithm includes the following corrections:
A proper place does not include nutation and precession corrections, hence it is referred to the reference coordinate system: GCRS J2000.0.
void pcl::Position::SetGeocentric  (  ) 
Removes the current observer, if a valid one has been defined by a previous call to SetObserver(). In such case, all previously computed positional data will be invalidated, with the exception of fundamental ephemerides and existing biasprecessionnutation matrices.
If no observer has been defined for this object, calling this member function has no effect.
After calling this member function, all subsequently calculated geometric, proper, astrometric, apparent and intermediate places will be geocentric.
void pcl::Position::SetObserver  (  const ObserverPosition &  observer  ) 
Defines the geodetic positional and reference data necessary for calculation of topocentric positions of solar system objects and stars.
By default, an instance of the Position class calculates geocentric coordinates. After calling this member function, subsequently calculated geometric, proper, astrometric, apparent and intermediate places will be topocentric, that is, will be referred to the location of the observer with respect to the center of the Earth.
By calling this member function, all previously computed positional data will be erased with the exception of fundamental ephemerides and existing biasprecessionnutation matrices, which can always be preserved.
The ObserverPosition::cioBased data member of the specified observer structure selects the celestial system and paradigm to be used in the calculation of positions that depend on Earth's rotation. If the cioBased member is true, equinoxbased places cannot be calculated, and any of the Apparent() member functions will throw an exception if called. Conversely, if cioBased is false, CIObased places cannot be calculated and no call to an Intermediate() member function will be allowed.
If polar motion corrections are enabled, the position of the CIP with respect to the ITRS is interpolated from the global CIP_ITRS database, if it provides data for the current time of calculation. In such case, polar motion is taken into account in the calculation of the observer's geocentric position and velocity. For the geocentric velocity a standard constant value for the rotation rate of the Earth is used; the velocity component due to precession and nutation is not taken into account since its effect is negligible. See the IsPolarMotionEnabled() and CIP_ITRS() member functions for more information and additional references.

inline 
Returns the time of calculation for this object in the Barycentric Dynamical Time (TDB) timescale.
The times of calculation in different timescales are calculated by the class constructor.
Definition at line 807 of file Position.h.

inline 
Returns the time of calculation for this object in the ephemeris timescale defined by the JPL DE/LE numerical integration. For all purposes this is equivalent to TDB.
The times of calculation in different timescales are calculated by the class constructor.
Definition at line 820 of file Position.h.

inline 
Computes the true position of a solar system body.
The components of the returned vector are the geocentric or topocentric rectangular equatorial coordinates for the calculation instant defined by this object in the TT timescale, without accounting for lighttravel time, for the body defined by the specified ephemeris handle H.
This function calls Geometric( EphemerisFile::Handle& ) internally to compute, if necessary, the geometric position with correction for light time, that is, no separate calculation routine is implemented for true positions. The returned vector is only useful to compute the true geocentric or topocentric distance, and for verification purposes.
Definition at line 388 of file Position.h.

inline 
Computes the geometric position of a star.
This function has been implemented for completeness. It is a synonym for Geometric( const StarPosition& ). There are no known 'true' positions of stars, since their lighttravel time is implicitly included in the space motion equations.
Definition at line 402 of file Position.h.

inline 
Computes the true distance of a solar system body.
The true distance is the actual distance from the body to the observer, geocentric or topocentric, at the instant of calculation. This excludes the lighttravel time correction.
Definition at line 415 of file Position.h.

inline 
Computes the true distance of a star.
The returned value is just the norm of the geometric position vector, that is:
This should be an actual distance in au only for stars with known parallaxes. For stars where the parallax is unknown or undefined, this value is meaningless because in such cases position vectors are unit vectors, whose components are also known as direction cosines.
Definition at line 433 of file Position.h.

inline 
Returns the time of calculation for this object in the Terrestrial Time (TT) timescale.
The times of calculation in different timescales are calculated by the class constructor.
Definition at line 832 of file Position.h.

inline 
Returns the time of calculation for this object in the Universal Time (UT1) timescale.
The times of calculation in different timescales are calculated by the class constructor.
Definition at line 844 of file Position.h.