PCL
pcl::Position Class Reference

Reduction of planetary and stellar positions. More...

#include <Position.h>

Public Member Functions

 Position (TimePoint t, const IsoString &timescale="TT")
 
 Position (const Position &)=default
 
 Position (Position &&)=default
 
Vector Apparent (EphemerisFile::Handle &H)
 
Vector Apparent (const StarPosition &S)
 
Optional< double > ApparentVisualMagnitude (EphemerisFile::Handle &H)
 
Vector Astrometric (EphemerisFile::Handle &H)
 
Vector Astrometric (const StarPosition &S)
 
Vector BarycentricPositionOfEarth () const
 
Vector BarycentricPositionOfSun () const
 
Vector BarycentricVelocityOfEarth () const
 
bool CanComputeApparentVisualMagnitude (const EphemerisFile::Handle &H) const
 
double CIO ()
 
Matrix CIOBiasPrecessionNutationInverseMatrix ()
 
Matrix CIOBiasPrecessionNutationMatrix ()
 
Vector CIP ()
 
Vector CIP_ITRS () const
 
void DisablePolarMotion (bool disable=true)
 
void EnablePolarMotion (bool enable=true)
 
double EO ()
 
double EpsA () const
 
Matrix EquinoxBiasPrecessionNutationInverseMatrix ()
 
Matrix EquinoxBiasPrecessionNutationMatrix ()
 
double ERA ()
 
double GAST ()
 
Vector Geometric (EphemerisFile::Handle &H)
 
Vector Geometric (const StarPosition &S)
 
Vector HeliocentricPositionOfEarth () const
 
void InitCIOBasedParameters ()
 
void InitEquinoxBasedParameters ()
 
Vector Intermediate (EphemerisFile::Handle &H)
 
Vector Intermediate (const StarPosition &S)
 
bool IsPolarMotionEnabled () const
 
bool IsTopocentric () const
 
DPoint NutationAngles ()
 
ObserverPosition Observer () const
 
Positionoperator= (const Position &)=default
 
Positionoperator= (Position &&)=default
 
Vector Proper (EphemerisFile::Handle &H)
 
Vector Proper (const StarPosition &S)
 
void SetGeocentric ()
 
void SetObserver (const ObserverPosition &observer)
 
TimePoint TDB () const
 
TimePoint Teph () const
 
Vector True (EphemerisFile::Handle &H)
 
Vector True (const StarPosition &S)
 
double TrueDistance (EphemerisFile::Handle &H)
 
double TrueDistance (const StarPosition &S)
 
TimePoint TT () const
 
TimePoint UT1 () const
 

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)
 

Detailed Description

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 equinox-based and CIO-based paradigms have been implemented for calculation of positions that depend on Earth's rotation. The apparent and intermediate places include the following corrections:

  • Light-travel time for solar system bodies.
  • Space motion for stars, including parallax, radial velocity and proper motions, with corrections for the relativistic Doppler effect that takes into account the change in light-travel time for stars.
  • Relativistic deflection of light due to solar gravitation.
  • Aberration of light, relativistic model.
  • Frame bias, precession and nutation. (equinox-based and CIO-based).
  • Accurate topocentric places with polar motion 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 precession-nutation theory is implemented (adjusted model with corrections to nutation angles, IAU 2006/2000AR). 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.

Constructor & Destructor Documentation

◆ Position() [1/3]

pcl::Position::Position ( TimePoint  t,
const IsoString timescale = "TT" 
)

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 case-sensitive.

All necessary timescale conversions to compute ephemerides and reduction of positions are performed automatically.

◆ Position() [2/3]

pcl::Position::Position ( const Position )
default

Copy constructor.

◆ Position() [3/3]

pcl::Position::Position ( Position &&  )
default

Move constructor.

Member Function Documentation

◆ Apparent() [1/2]

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:

  • Light-travel time.
  • Relativistic deflection of light due to solar gravitation (except for the Sun, the Moon, and any object closer from Earth than the Sun at the time of observation.
  • Aberration of light, including relativistic terms.
  • Frame bias, precession and nutation. The origin of right ascension is the true equinox of date.
Note
The declination coordinate is identical in both equinox-based (apparent) and CIO-based (intermediate) positions. Only the origin of right ascensions differs between both systems.
Warning
If a valid observer location has been defined by calling the SetObserver() member function, and the specified ObserverPosition structure requires CIO-based transformations (see the ObserverPosition::cioBased member), this function will throw an Error exception.

◆ Apparent() [2/2]

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:

  • Space motion, including parallax, radial velocity and proper motions, with corrections for the relativistic Doppler effect.
  • Relativistic deflection of light due to solar gravitation.
  • Aberration of light, including relativistic terms.
  • Frame bias, precession and nutation. The origin of right ascension is the true equinox of date.
Note
The declination coordinate is identical in both equinox-based (apparent) and CIO-based (intermediate) positions. Only the origin of right ascensions differs between both systems.
Warning
If a valid observer location has been defined by calling the SetObserver() member function, and the specified ObserverPosition structure requires CIO-based transformations (see the ObserverPosition::cioBased member), this function will throw an Error exception.

◆ ApparentVisualMagnitude()

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°.

See also
CanComputeApparentVisualMagnitude()

◆ Astrometric() [1/2]

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:

  • Light-travel time.
  • Relativistic deflection of light due to solar gravitation (except for the Sun, the Moon, and any object closer from Earth than the Sun at the time of observation).

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.

◆ Astrometric() [2/2]

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:

  • Space motion, including parallax, radial velocity and proper motions, with corrections for the relativistic Doppler effect.
  • Relativistic deflection of light due to solar gravitation.

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.

◆ BarycentricPositionOfEarth()

Vector pcl::Position::BarycentricPositionOfEarth ( ) const
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.

◆ BarycentricPositionOfSun()

Vector pcl::Position::BarycentricPositionOfSun ( ) const
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.

◆ BarycentricVelocityOfEarth()

Vector pcl::Position::BarycentricVelocityOfEarth ( ) const
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.

◆ CanComputeApparentVisualMagnitude()

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:

  • Objects providing valid H and G parameters (absolute magnitude and slope coefficient). This happens for most asteroids included in standard XEPH files.
  • Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto.
  • The four Galilean satellites of Jupiter: Io, Europa, Ganymede and Callisto.
See also
ApparentVisualMagnitude()

◆ CIO()

double pcl::Position::CIO ( )
inline

The Celestial Intermediate Origin (CIO) locator, in radians.

This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinox-based reduction of positions is available.

Definition at line 1042 of file Position.h.

◆ CIOBiasPrecessionNutationInverseMatrix()

Matrix pcl::Position::CIOBiasPrecessionNutationInverseMatrix ( )
inline

Returns the inverse of the CIO-based combined bias-precession-nutation matrix.

This member function calls InitCIOBasedParameters() to ensure that all data required for equinox-based and CIO-based reduction of positions is available.

Definition at line 997 of file Position.h.

◆ CIOBiasPrecessionNutationMatrix()

Matrix pcl::Position::CIOBiasPrecessionNutationMatrix ( )
inline

Returns the CIO-based combined bias-precession-nutation matrix.

This member function calls InitCIOBasedParameters() to ensure that all data required for equinox-based and CIO-based reduction of positions is available.

Definition at line 983 of file Position.h.

◆ CIP()

Vector pcl::Position::CIP ( )
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 equinox-based reduction of positions is available.

Definition at line 1010 of file Position.h.

◆ CIP_ITRS()

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 thread-safe 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 two-dimensional vector with zero components.

The components of the returned 2-D vector are the coordinates xp, yp of the CIP with respect to the ITRS, expressed in radians.

◆ DisablePolarMotion()

void pcl::Position::DisablePolarMotion ( bool  disable = true)
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.

◆ EnablePolarMotion()

void pcl::Position::EnablePolarMotion ( bool  enable = true)
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.

◆ EO()

double pcl::Position::EO ( )
inline

Equation of the origins, expressed in radians.

This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinox-based reduction of positions is available.

Definition at line 1054 of file Position.h.

◆ EpsA()

double pcl::Position::EpsA ( ) const
inline

Mean obliquity of the ecliptic, in radians.

Definition at line 1087 of file Position.h.

References pcl::AsRad(), and pcl::Poly().

◆ EquatorialToEcliptic() [1/4]

static Vector pcl::Position::EquatorialToEcliptic ( const Vector q,
double  se,
double  ce 
)
inlinestatic

Conversion from rectangular equatorial to rectangular ecliptic coordinates.

Parameters
qRectangular equatorial coordinates.
seSine of the obliquity of the ecliptic.
ceCosine 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.

◆ EquatorialToEcliptic() [2/4]

static Vector pcl::Position::EquatorialToEcliptic ( const Vector q,
double  eps 
)
inlinestatic

Conversion from rectangular equatorial to rectangular ecliptic coordinates.

Parameters
qRectangular equatorial coordinates.
epsOliquity 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().

◆ EquatorialToEcliptic() [3/4]

static DPoint pcl::Position::EquatorialToEcliptic ( const DPoint q,
double  se,
double  ce 
)
inlinestatic

Conversion from spherical equatorial to spherical ecliptic coordinates.

Parameters
qSpherical equatorial coordinates in radians, where q.x is the right ascension and q.y is the declination.
seSine of the obliquity of the ecliptic.
ceCosine 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.

◆ EquatorialToEcliptic() [4/4]

static DPoint pcl::Position::EquatorialToEcliptic ( const DPoint q,
double  eps 
)
inlinestatic

Conversion from spherical equatorial to spherical ecliptic coordinates.

Parameters
qSpherical equatorial coordinates in radians, where q.x is the right ascension and q.y is the declination.
epsOliquity 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().

◆ EquinoxBiasPrecessionNutationInverseMatrix()

Matrix pcl::Position::EquinoxBiasPrecessionNutationInverseMatrix ( )
inline

Returns the inverse of the equinox-based combined bias-precession-nutation matrix.

This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinox-based reduction of positions is available.

Definition at line 970 of file Position.h.

◆ EquinoxBiasPrecessionNutationMatrix()

Matrix pcl::Position::EquinoxBiasPrecessionNutationMatrix ( )
inline

Returns the equinox-based combined bias-precession-nutation matrix.

This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinox-based reduction of positions is available.

Definition at line 957 of file Position.h.

◆ ERA()

double pcl::Position::ERA ( )
inline

Earth rotation angle, expressed in radians.

This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinox-based reduction of positions is available.

Definition at line 1066 of file Position.h.

◆ GAST()

double pcl::Position::GAST ( )
inline

Greenwich apparent sidereal time, expressed in radians.

This member function calls InitEquinoxBasedParameters() to ensure that all data required for equinox-based reduction of positions is available.

Definition at line 1078 of file Position.h.

◆ Geometric() [1/2]

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 light-travel time, for the body defined by the specified ephemeris handle H.

The implemented reduction algorithm includes just the correction for light-travel 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.

◆ Geometric() [2/2]

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.

◆ HeliocentricPositionOfEarth()

Vector pcl::Position::HeliocentricPositionOfEarth ( ) const
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.

◆ ICRSEquatorialToGalactic() [1/2]

static Vector pcl::Position::ICRSEquatorialToGalactic ( const Vector q)
inlinestatic

Conversion from ICRS rectangular equatorial to rectangular galactic coordinates.

Parameters
qRectangular 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:

Jia-Cheng 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:

α = 17h45m40s.0400 δ = –29°00'28".138

The equatorial coordinates of the galactic pole, coherent with the ICRS, are:

αp = 12h51m36s.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.

◆ ICRSEquatorialToGalactic() [2/2]

static DPoint pcl::Position::ICRSEquatorialToGalactic ( const DPoint q)
inlinestatic

Conversion from ICRS spherical equatorial to spherical galactic coordinates.

Parameters
qSpherical 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.

◆ InitCIOBasedParameters()

void pcl::Position::InitCIOBasedParameters ( )

Calculates all parameters and data structures necessary for CIO-based reduction of positions.

This member function starts by calling InitEquinoxBasedParameters(), so it implicitly calculates all equinox-based parameters. Then it calculates the CIO-based combined bias-precession-nutation 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.

◆ InitEquinoxBasedParameters()

void pcl::Position::InitEquinoxBasedParameters ( )

Calculates all parameters and data structures necessary for equinox-based reduction of positions.

This member function calculates the following structures:

  • Precession+bias angles, IAU 2006 precession model, Fukushima-Williams parameterization. See ESAsA sections 6.6.2.2 and 7.2.5.1.
  • Mean obliquity of the ecliptic, IAU 2006 precession model. See ESAsA section 7.2.5.1.
  • Nutation angles, IAU 2006/2000A_R nutation model. See ESAsA section 6.6.1.
  • Combined bias-precession-nutation matrix, equinox-based. See ESAsA sections 6.7 and 7.2.5.1.
  • Position of the Celestial Intermediate Pole (CIP). ESAsA section 6.7.
  • Celestial Intermediate Origin (CIO) locator. ESAsA section 6.7.
  • Equation of the origins (EO). See Wallace, P. & Capitaine, N., 2006, Astron.Astrophys. 459, 981, and ESAsA section 6.4.
  • Earth rotation angle (ERA) for the UT1 time of calculation. See IERS Technical Note No. 32, 2003, Section 5.4.4.
  • Greenwich Apparent Sidereal Time (GAST), IAU 2006. ESAsA 6.8.5.

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.

◆ Intermediate() [1/2]

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:

  • Light-travel time.
  • Relativistic deflection of light due to solar gravitation (except for the Sun, the Moon, and any object closer from Earth than the Sun at the time of observation.
  • Aberration of light, including relativistic terms.
  • Frame bias, precession and nutation. The origin of right ascension is the Celestial Intermediate Origin (CIO), following the IAU recommendations since January 2003.
Note
The declination coordinate is identical in both equinox-based (apparent) and CIO-based (intermediate) positions. Only the origin of right ascensions differs between both systems.
Warning
If a valid observer location has been defined by calling the SetObserver() member function, and the specified ObserverPosition structure requires equinox-based transformations (see the ObserverPosition::cioBased member), this function will throw an Error exception.

◆ Intermediate() [2/2]

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:

  • Space motion, including parallax, radial velocity and proper motions, with corrections for the relativistic Doppler effect.
  • Relativistic deflection of light due to solar gravitation.
  • Aberration of light, including relativistic terms.
  • Frame bias, precession and nutation. The origin of right ascension is the Celestial Intermediate Origin (CIO), following the IAU recommendations since January 2003.
Note
The declination coordinate is identical in both equinox-based (apparent) and CIO-based (intermediate) positions. Only the origin of right ascensions differs between both systems.
Warning
If a valid observer location has been defined by calling the SetObserver() member function, and the specified ObserverPosition structure requires equinox-based transformations (see the ObserverPosition::cioBased member), this function will throw an Error exception.

◆ IsPolarMotionEnabled()

bool pcl::Position::IsPolarMotionEnabled ( ) const
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.

◆ IsTopocentric()

bool pcl::Position::IsTopocentric ( ) const
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.

◆ NutationAngles()

DPoint pcl::Position::NutationAngles ( )
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 equinox-based reduction of positions is available.

Definition at line 1102 of file Position.h.

◆ Observer()

ObserverPosition pcl::Position::Observer ( ) const
inline

Returns the current observer. If no observer has been defined for this object, returns a default-constructed structure for a fictitious observer at the geocenter.

Definition at line 746 of file Position.h.

◆ operator=() [1/2]

Position& pcl::Position::operator= ( const Position )
default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

Position& pcl::Position::operator= ( Position &&  )
default

Move assignment operator. Returns a reference to this object.

◆ Proper() [1/2]

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:

  • Light-travel time.
  • Relativistic deflection of light due to solar gravitation (except for the Sun, the Moon, and any object closer from Earth than the Sun at the time of observation.
  • Aberration of light, including relativistic terms.

A proper place does not include nutation and precession corrections, hence it is referred to the reference coordinate system: GCRS J2000.0.

◆ Proper() [2/2]

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:

  • Space motion, including parallax, radial velocity and proper motions, with corrections for the relativistic Doppler effect.
  • Relativistic deflection of light due to solar gravitation.
  • Aberration of light, including relativistic terms.

A proper place does not include nutation and precession corrections, hence it is referred to the reference coordinate system: GCRS J2000.0.

◆ SetGeocentric()

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 bias-precession-nutation 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.

◆ SetObserver()

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 bias-precession-nutation 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, equinox-based places cannot be calculated, and any of the Apparent() member functions will throw an exception if called. Conversely, if cioBased is false, CIO-based 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.

◆ TDB()

TimePoint pcl::Position::TDB ( ) const
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.

◆ Teph()

TimePoint pcl::Position::Teph ( ) const
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.

◆ True() [1/2]

Vector pcl::Position::True ( EphemerisFile::Handle 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 light-travel 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.

◆ True() [2/2]

Vector pcl::Position::True ( const StarPosition S)
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 light-travel time is implicitly included in the space motion equations.

Definition at line 402 of file Position.h.

◆ TrueDistance() [1/2]

double pcl::Position::TrueDistance ( EphemerisFile::Handle 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 light-travel time correction.

Definition at line 415 of file Position.h.

◆ TrueDistance() [2/2]

double pcl::Position::TrueDistance ( const StarPosition S)
inline

Computes the true distance of a star.

The returned value is just the norm of the geometric position vector, that is:

Geometric( S ).L2Norm()

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.

◆ TT()

TimePoint pcl::Position::TT ( ) const
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.

◆ UT1()

TimePoint pcl::Position::UT1 ( ) const
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.


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