The JavaScript implementation, available through the PJSR runtime in the PixInsight core application, uses the PCL/C++ implementation as its back end. For information on the entire functionality available with detailed descriptions of the implemented algorithms, see the corresponding sections of the official PCL documentation:

C++ documentation for the integrated solar system ephemerides system.

C++ documentation for the Position class.

**StarPosition**

This object is a simple structure to define positional data of a star. Positions and proper motions must be referred to ICRS/J2000.0. If out-of-range coordinates are specified, their values will be constrained to their proper ranges: right ascension to [0?,360?) and declination to [-90?,+90?].

Code:

` Number StarPosition.alpha`

Code:

` Number StarPosition.delta`

Code:

` Date StarPosition.epoch`

Code:

` Number StarPosition.muAlpha`

Code:

` Number StarPosition.muDelta`

Code:

` Number StarPosition.parallax`

Code:

` Number StarPosition.radialVelocity`

**ObserverPosition**

Geodetic coordinates of a terrestrial observer.

This structure provides the data necessary to calculate topocentric places of solar system bodies and stars. Typically, the values used should be WGS84 coordinates (for example, as distributed by GPS) or ITRF coordinates?both systems close together at the level of a few centimeters.

Geographic longitudes grow eastward, so longitudes are positive to the east and negative to the west of the central meridian. For ease of calculation, the

Code:

`ObserverPosition.longitude`

If out-of-range coordinates are specified, their values will be constrained to their proper ranges: longitude to [0?,360?), and latitude to [-90?,+90?].

Code:

` Boolean ObserverPosition.cioBased`

Code:

` Number ObserverPosition.equatorialRadius`

Code:

` Number ObserverPosition.flattening`

Code:

` Number ObserverPosition.height`

Code:

` Number ObserverPosition.latitude`

Code:

` Number ObserverPosition.longitude`

Code:

` Vector ObserverPosition.regionalCenter`

**Position**

This object 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 document (January 2019), 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.

**Constructor**

Code:

```
new Position( Date t[, String timescale="TT"] )
new Position( String isoTime[, String timescale="TT"] )
new Position( Number jd1[, Number jd2=0[, String timescale="TT"]] )
```

Code:

`Date`

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

**Properties**

Code:

` ObserverPosition Position.observer`

By default, an instance of the

Code:

`Position`

By assigning a value to this property, 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

Code:

`ObserverPosition.cioBased`

Code:

`cioBased`

Code:

`cioBased`

If polar motion corrections are enabled, the position of the Celestial Intermediate Pole (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

Code:

`polarMotionEnabled`

Code:

` Boolean Position.polarMotionEnabled`

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

Code:

`ObserverPosition`

Code:

` Number Position.epsA`

**Methods**

Code:

` Vector Position.apparent( EphemerisHandle H )`

Code:

`H`

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

Code:

` Vector Position.apparent( StarPosition S )`

Code:

`S`

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

Code:

` Number|null Position.apparentVisualMagnitude( EphemerisHandle H )`

For objects with known H and G values (absolute magnitude and slope parameters, respectively; see

Code:

`EphemerisHandle.H`

Code:

`EphemerisHandle.G`

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.

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 method returns

Code:

`null`

A

Code:

`null`

*i*? 170?. For Venus, the magnitude is only calculated for 0? <

*i*? 163?.7. The valid range for Mars is

*i*? 50?.

See also

Code:

`Position.canComputeApparentVisualMagnitude()`

Code:

` Vector Position.astrometric( EphemerisHandle H )`

Code:

`H`

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

Code:

` Vector Position.astrometric( StarPosition S )`

Code:

`S`

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

Code:

` Boolean Position.canComputeApparentVisualMagnitude( EphemerisHandle H )`

Code:

`H`

Code:

`Position`

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 is true 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.

Code:

` Vector Position.geometric( EphemerisHandle H )`

Code:

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

Code:

` Vector Position.geometric( StarPosition S )`

Code:

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

Code:

` void Position.initCIOBasedParameters()`

Code:

`initEquinoxBasedParameters()`

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.

Code:

` void Position.initEquinoxBasedParameters()`

- Precession+bias angles, IAU 2006 precession model, Fukushima-Williams parameterization.
- Mean obliquity of the ecliptic, IAU 2006 precession model.
- Nutation angles, IAU 2006/2000AR nutation model.
- Combined bias-precession-nutation matrix, equinox-based.
- Position of the Celestial Intermediate Pole (CIP).
- Celestial Intermediate Origin (CIO) locator.
- Equation of the origins (EO).
- Earth rotation angle (ERA) for the UT1 time of calculation.
- Greenwich Apparent Sidereal Time (GAST), IAU 2006.

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.

Code:

` Vector Position.intermediate( EphemerisHandle H )`

Code:

`H`

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

Code:

` Vector Position.intermediate( StarPosition S )`

Code:

`S`

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

Code:

` Array Position.nutationAngles()`

Code:

`Array`

Code:

`P`

Code:

`P[0]`

Code:

`P[1]`

Code:

`initEquinoxBasedParameters()`

Code:

` Vector Position.proper( EphemerisHandle H )`

Code:

`H`

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

Code:

` Vector Position.proper( StarPosition S )`

Code:

`S`

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

Code:

` Vector Position.true( EphemerisHandle H )`

*without accounting for light-travel time,*for the body defined by the specified ephemeris handle

Code:

`H`

This function calls

Code:

`Position.geometric( EphemerisHandle )`

Code:

` Vector Position.true( StarPosition S )`

Code:

`Position.geometric( StarPosition )`

Code:

` Number Position.trueDistance( EphemerisHandle H )`

Code:

` Number Position.trueDistance( StarPosition S )`

Code:

` Position.geometric( S ).l2norm()`

*direction cosines.*

**Static Methods**

Code:

` Vector Position.equatorialToEcliptic( Vector r, Number eps )`

Code:

`r`

Code:

`eps`

Returns a vector whose components are the rectangular ecliptic coordinates corresponding to the specified equatorial position

Code:

`r`

Code:

` Vector Position.equatorialToEcliptic( Vector r, Number se, Number ce )`

Code:

`Position.equatorialToEcliptic( Vector, Number )`

Code:

`se`

Code:

`ce`

Code:

` Vector Position.icrsEquatorialToGalactic( Vector r )`

Code:

`r`

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:

alpha = 17h45m40s.0400

delta = ?29?00'28".138

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

alphap = 12h51m36s.7151981

deltap = +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.