pcl::Position Class Reference

Reduction of planetary and stellar positions. More...

#include <Position.h>

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

Static Public Member Functions
static DPoint	EclipticToEquatorial (const DPoint &q, double eps)
static DPoint	EclipticToEquatorial (const DPoint &q, double se, double ce)
static Vector	EclipticToEquatorial (const Vector &q, double eps)
static Vector	EclipticToEquatorial (const Vector &q, double se, double ce)
static DPoint	EquatorialToEcliptic (const DPoint &q, double eps)
static DPoint	EquatorialToEcliptic (const DPoint &q, double se, double ce)
static Vector	EquatorialToEcliptic (const Vector &q, double eps)
static Vector	EquatorialToEcliptic (const Vector &q, double se, double ce)
static DPoint	GalacticToICRSEquatorial (const DPoint &g)
static Vector	GalacticToICRSEquatorial (const Vector &g)
static DPoint	ICRSEquatorialToGalactic (const DPoint &q)
static Vector	ICRSEquatorialToGalactic (const Vector &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, last updated June 2024), the IAU 2006/2000A precession-nutation theory is implemented (adjusted model with corrections to nutation angles, IAU 2006/2000A_R). The standard fundamental ephemerides are JPL's DE440.

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 345 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

(

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.

Apparent() [2/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.

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 objects with known M1 or M2 parameters (absolute total or nuclear comet magnitudes), the apparent visual magnitude is calculated as either the total comet magnitude (nucleus+coma) or, if only M2 is known, the comet nucleus magnitude. The algorithms are described in the documentation for the EphemerisFile::Handle::M1() member function.

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

(

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.

Astrometric() [2/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.

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 907 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 928 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 918 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.

• Objects providing valid M1 or M2 parameters (absolute total or nuclear comet magnitudes). This happens for most comets 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()

CanComputeCometApparentVisualNuclearMagnitude()

bool pcl::Position::CanComputeCometApparentVisualNuclearMagnitude

(

const EphemerisFile::Handle &

H

)

const

Returns true iff the comet's apparent visual nuclear magnitude can be calculated at the calculation time defined by this instance for the object represented by the specified handle H.

This function returns true only if the object provides a valid M2 parameter, the absolute nuclear comet magnitude. This is the case for many comets included in standard XEPH files.

CanComputeCometApparentVisualTotalMagnitude()

bool pcl::Position::CanComputeCometApparentVisualTotalMagnitude

(

const EphemerisFile::Handle &

H

)

const

Returns true iff the comet's apparent visual total magnitude can be calculated at the calculation time defined by this instance for the object represented by the specified handle H.

This function returns true only if the object provides a valid M1 parameter, the absolute total comet magnitude (nucleus and coma). This is the case for most comets included in standard XEPH files.

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 1094 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 1049 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 1035 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 1062 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 x_p, y_p of the CIP with respect to the ITRS, expressed in radians.

CometApparentVisualNuclearMagnitude()

Optional<double> pcl::Position::CometApparentVisualNuclearMagnitude

(

EphemerisFile::Handle &

H

)

Returns the comet's apparent visual nuclear magnitude.

Nuclear comet magnitudes include the observed brightness of the comet's nucleus, excluding the coma. For information on the calculation of comet magnitudes, see the EphemerisFile::Handle::M1() member function.

If the required data are not available for the specified object, this member function returns an undefined Optional object.

CometApparentVisualTotalMagnitude()

Optional<double> pcl::Position::CometApparentVisualTotalMagnitude

(

EphemerisFile::Handle &

H

)

Returns the comet's apparent visual total magnitude.

Total comet magnitudes include the observed brightness of the comet nucleus and coma. For information on the calculation of comet magnitudes, see the EphemerisFile::Handle::M1() member function.

If the required data are not available for the specified object, this member function returns an undefined Optional object.

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 835 of file Position.h.

EclipticToEquatorial() [1/4]

static DPoint pcl::Position::EclipticToEquatorial ( const DPoint &  q, double  eps  )

inlinestatic

Conversion from spherical ecliptic to spherical equatorial coordinates.

Parameters

q	Spherical ecliptic coordinates in radians, where q.x is the longitude and q.y is the latitude.
eps	Oliquity of the ecliptic in radians.

Returns the equatorial coordinates in radians as a point p, where p.x is the right ascension in the range [0,2pi) and p.y is the declination in [-pi/2,+pi/2].

Definition at line 1499 of file Position.h.

References pcl::SinCos().

EclipticToEquatorial() [2/4]

static DPoint pcl::Position::EclipticToEquatorial ( const DPoint &  q, double  se, double  ce  )

inlinestatic

Conversion from spherical ecliptic to spherical equatorial coordinates.

Parameters

q	Spherical ecliptic coordinates in radians, where q.x is the longitude and q.y is the latitude.
se	Sine of the obliquity of the ecliptic.
ce	Cosine of the obliquity of the ecliptic.

Returns the equatorial coordinates in radians as a point p, where p.x is the right ascension in the range [0,2pi) and p.y is the declination in [-pi/2,+pi/2].

Definition at line 1480 of file Position.h.

References pcl::GenericVector< T >::FromSpherical(), pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.

EclipticToEquatorial() [3/4]

static Vector pcl::Position::EclipticToEquatorial ( const Vector &  q, double  eps  )

inlinestatic

Conversion from rectangular ecliptic to rectangular equatorial coordinates.

Parameters

q	Rectangular ecliptic coordinates.
eps	Oliquity of the ecliptic in radians.

Returns a vector whose components are the rectangular equatorial coordinates corresponding to the specified ecliptic position q at the epoch where the specified obliquity has been calculated.

Definition at line 1460 of file Position.h.

References pcl::SinCos().

EclipticToEquatorial() [4/4]

static Vector pcl::Position::EclipticToEquatorial ( const Vector &  q, double  se, double  ce  )

inlinestatic

Conversion from rectangular ecliptic to rectangular equatorial coordinates.

Parameters

q	Rectangular ecliptic 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 equatorial coordinates corresponding to the specified ecliptic position q at the epoch where the specified obliquity has been calculated.

Definition at line 1442 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 826 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 1106 of file Position.h.

EpsA()

double pcl::Position::EpsA ( ) const

inline

Mean obliquity of the ecliptic, in radians.

Definition at line 1139 of file Position.h.

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

EquatorialToEcliptic() [1/4]

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

inlinestatic

Conversion from spherical equatorial to spherical ecliptic coordinates.

Parameters

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 1422 of file Position.h.

References pcl::SinCos().

EquatorialToEcliptic() [2/4]

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

inlinestatic

Conversion from spherical equatorial to spherical ecliptic coordinates.

Parameters

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 1403 of file Position.h.

References pcl::GenericVector< T >::FromSpherical(), pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.

EquatorialToEcliptic() [3/4]

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

inlinestatic

Conversion from rectangular equatorial to rectangular ecliptic coordinates.

Parameters

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 1383 of file Position.h.

References pcl::SinCos().

EquatorialToEcliptic() [4/4]

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

inlinestatic

Conversion from rectangular equatorial to rectangular ecliptic coordinates.

Parameters

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 1365 of file Position.h.

EquatorialToHorizontal() [1/2]

DPoint pcl::Position::EquatorialToHorizontal ( const DPoint &  q )

inline

Conversion from spherical equatorial to spherical local horizontal coordinates (azimuth and altitude).

Parameters

q	Spherical equatorial coordinates in radians, where q.x is the right ascension and q.y is the declination.

Returns the horizontal coordinates in radians as a point p, where p.x is the azimuth in the range [0,2pi) and p.y is the altitude in [-pi/2,+pi/2]. The horizontal coordinates are calculated at the current local hour angle for the specified right ascension.

This function requires valid geodetic coordinates of the observer set through a previous call to SetObserver(). If no valid observer coordinates have been defined, this function returns zero horizontal coordinates conventionally.

Local hour angles are calculated either from the Greenwich Apparent Sidereal Time (GAST) or the Earth Rotation Angle (ERA), respectively for equinox-based and CIO-based observers.

For accurate results, apparent topocentric coordinates should be specified, including corrections for diurnal parallax and diurnal aberration.

Definition at line 1318 of file Position.h.

References pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.

EquatorialToHorizontal() [2/2]

DPoint pcl::Position::EquatorialToHorizontal ( double  ra, double  dec  )

inline

Conversion from spherical equatorial to spherical local horizontal coordinates (azimuth and altitude).

Parameters

ra	Right ascension in radians.
dec	Declination in radians.

Calling this function is equivalent to:

EquatorialToHorizontal( DPoint( ra, dec ) ) 

Definition at line 1335 of file Position.h.

References pcl::ArcSin(), pcl::ArcTan(), pcl::Norm2Pi(), pcl::Rad(), and 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 1022 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 1009 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 1118 of file Position.h.

GalacticToICRSEquatorial() [1/2]

static DPoint pcl::Position::GalacticToICRSEquatorial ( const DPoint &  g )

inlinestatic

Conversion from spherical galactic to ICRS spherical equatorial coordinates.

Parameters

g	Spherical galactic coordinates in radians, where p.x is the galactic longitude and p.y is the galactic latitude.

Returns the ICRS equatorial coordinates in radians as a point p, where p.x is the right ascension in the range [0,2pi) and p.y is the declination in [-pi/2,+pi/2].

See the documentation for ICRSEquatorialToGalactic( const Vector& ) for detailed information.

Definition at line 1598 of file Position.h.

References pcl::GenericVector< T >::FromSpherical(), pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.

GalacticToICRSEquatorial() [2/2]

static Vector pcl::Position::GalacticToICRSEquatorial ( const Vector &  g )

inlinestatic

Conversion from rectangular galactic to ICRS rectangular equatorial coordinates.

Parameters

g	Rectangular galactic coordinates.

Returns a vector whose components are the calculated rectangular equatorial coordinates in the ICRS.

See ICRSEquatorialToGalactic( const Vector& ) for detailed information.

Definition at line 1577 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 1130 of file Position.h.

Geometric() [1/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.

Geometric() [2/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.

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 939 of file Position.h.

ICRSEquatorialToGalactic() [1/2]

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

inlinestatic

Conversion from ICRS spherical equatorial to spherical galactic coordinates.

Parameters

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 1559 of file Position.h.

References pcl::GenericVector< T >::FromSpherical(), pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.

ICRSEquatorialToGalactic() [2/2]

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

inlinestatic

Conversion from ICRS rectangular equatorial to rectangular galactic coordinates.

Parameters

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:

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:

α = 17^h45^m40^s.0400 δ = –29°00'28".138

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

α^p = 12^h51^m36^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 June 2024) galactic coordinate system was defined by the IAU in 1959 in the FK4 B1950.0 reference system.

Definition at line 1538 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 ESAA 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 ESAA sections 6.6.2.2 and 7.2.5.1.

• Mean obliquity of the ecliptic, IAU 2006 precession model. See ESAA section 7.2.5.1.

• Nutation angles, IAU 2006/2000A_R nutation model. See ESAA section 6.6.1.

• Combined bias-precession-nutation matrix, equinox-based. See ESAA sections 6.7 and 7.2.5.1.

• Position of the Celestial Intermediate Pole (CIP). ESAA section 6.7.

• Celestial Intermediate Origin (CIO) locator. ESAA section 6.7.

• Equation of the origins (EO). See Wallace, P. & Capitaine, N., 2006, Astron.Astrophys. 459, 981, and ESAA 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. ESAA 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

(

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.

Intermediate() [2/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.

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 817 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 797 of file Position.h.

LightTravelTime()

double pcl::Position::LightTravelTime ( EphemerisFile::Handle &  H )

inline

Computes the light-travel time for a solar system body.

The returned value is the light-travel time in days for the instant of calculation defined by this object in the TT timescale, calculated for the body defined by the specified ephemeris handle H.

Definition at line 472 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 1154 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 786 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.

PhaseAngle() [1/2]

double pcl::Position::PhaseAngle

(

const StarPosition &

S

)

The observed phase angle of a star, in radians.

The phase angle of a star is the angle between the observer-star and Sun-star vectors.

PhaseAngle() [2/2]

double pcl::Position::PhaseAngle

(

EphemerisFile::Handle &

H

)

The observed phase angle of a solar system body, in radians.

The phase angle of a solar system body is the angle between the observer-body and Sun-body vectors.

Proper() [1/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.

Proper() [2/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.

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 computed by the class constructor.

Definition at line 847 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 computed by the class constructor.

Definition at line 860 of file Position.h.

True() [1/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 429 of file Position.h.

True() [2/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 415 of file Position.h.

TrueDistance() [1/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 460 of file Position.h.

TrueDistance() [2/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 442 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 computed by the class constructor.

Definition at line 872 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 computed by the class constructor.

Definition at line 896 of file Position.h.

UTC()

TimePoint pcl::Position::UTC ( ) const

inline

Returns the time of calculation for this object in the Coordinated Universal Time (UTC) timescale.

The times of calculation in different timescales are computed by the class constructor.

Definition at line 884 of file Position.h.

---

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

• Position.h