Loading...
Searching...
No Matches
transform.c File Reference

Various functions to transform rectangular equatorial vectors (positions or velocities) between different equatorial coordinate systems. More...

## Functions

double | app_to_cirs_ra (double jd_tt, enum novas_accuracy accuracy, double ra)
| Converts an apparent right ascension coordinate (measured from the true equinox of date) to a CIRS R.A., measured from the CIO.
short | cel2ter (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, enum novas_equatorial_class coordType, double xp, double yp, const double *in, double *out)
double | cirs_to_app_ra (double jd_tt, enum novas_accuracy accuracy, double ra)
| Converts a CIRS right ascension coordinate (measured from the CIO) to an apparent R.A.
int | cirs_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) frame at the given epoch to the ICRS / GCRS.
int | cirs_to_itrs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the dynamical CIRS frame of date to the Earth-fixed ITRS frame (IAU 2000 standard method).
int | cirs_to_tod (double jd_tt, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) at the given epoch to the True of Date (TOD) reference system.
int | frame_tie (const double *in, enum novas_frametie_direction direction, double *out)
| Transforms a vector from the dynamical reference system to the International Celestial Reference System (ICRS), or vice versa.
short | gcrs2equ (double jd_tt, enum novas_dynamical_type sys, enum novas_accuracy accuracy, double rag, double decg, double *restrict ra, double *restrict dec)
| Converts GCRS right ascension and declination to coordinates with respect to the equator of date (mean or true).
int | gcrs_to_cirs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the Celestial Intermediate Reference System (CIRS) frame at the given epoch.
int | gcrs_to_j2000 (const double *in, double *out)
| Changes ICRS / GCRS coordinates to J2000 coordinates.
int | gcrs_to_mod (double jd_tdb, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the Mean of Date (MOD) reference frame at the given epoch.
int | gcrs_to_tod (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the True of Date (TOD) reference frame at the given epoch.
int | itrs_to_cirs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the Earth-fixed ITRS frame to the dynamical CIRS frame of date (IAU 2000 standard method).
int | itrs_to_tod (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the Earth-fixed ITRS frame to the dynamical True of Date (TOD) frame of date (pre IAU 2000 method).
int | j2000_to_gcrs (const double *in, double *out)
| Change J2000 coordinates to ICRS / GCRS coordinates.
int | j2000_to_tod (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from J2000 coordinates to the True of Date (TOD) reference frame at the given epoch.
int | mod_to_gcrs (double jd_tdb, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from Mean of Date (MOD) reference frame at the given epoch to the ICRS / GCRS.
short | ter2cel (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, enum novas_equatorial_class coordType, double xp, double yp, const double *in, double *out)
int | tod_to_cirs (double jd_tt, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the True of Date (TOD) reference system to the Celestial Intermediate Reference System (CIRS) at the given epoch to the .
int | tod_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the ICRS / GCRS.
int | tod_to_itrs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the dynamical True of Date (TOD) frame of date the Earth-fixed ITRS frame (pre IAU 2000 method).
int | tod_to_j2000 (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the J2000 coordinates.

## Detailed Description

Various functions to transform rectangular equatorial vectors (positions or velocities) between different equatorial coordinate systems.

The implementations follow the latest standard for high-precision astrometry as described the IAU 2000 / IAU 2006 and IERS 2010 conventions. See Figure 1 below for an overview of the various coordinate reference systems, and the functions, which can be used to tansform position and/or velocoty vectors among them,

Figure 1. Reference systems and transformations

The same transformations are also available for the new frame-based approach via a novas_transform, often with significantly higher computational efficiency.

For the conversion between GCRS and CIRS, the IERS Conventions 2010, Chapter 5 (Section 5.9) describes two equivalent methods:

- Method 1 is the more direct method and involves calculating the position of the Celestial Intermediate Pole (CIP) of date in GCRS, using a harmonic series containing some 2825 lunisolar and planetary terms (IERS Conventions 2010, Tables 5.2a and 5.2b).
- Method 2 is more roundabout, transforming GCRS to J2000 first, then using the IAU 2006 (P03) precession-nutation model to calculate True-of-Date coordinates, which are then transformed to CIRS by a simple rotation with the CIO's position relative to the true-equinox of date. The IAU2006 nutation series uses 2414 lunisolar and planetary terms (IERS Conventions 2010, Tables 5.3a and 5.3b).

The two methods are equivalent both in terms of accuracy, down to the μas level, and in terms of computational cost. Neither is 'superior' to the other in any measurable way. In SuperNOVAS we choose to follow Method 2, since its implementation is more readily given with the existing framework of related functions.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, especially Section 5.9
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.

Date
  Created on Mar 6, 2025

Author
  Attila Kovacs and G. Kaplan

See also
  frames.c, system.c, cio.c

## Function Documentation

## cel2ter()

short cel2ter | ( | double | jd_ut1_high,
|  | double | jd_ut1_low,
|  | double | ut1_to_tt,
|  | enum novas_earth_rotation_measure | erot,
|  | enum novas_accuracy | accuracy,
|  | enum novas_equatorial_class | coordType,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Deprecated
  This function can be confusing to use due to the input coordinate system being specified by a combination of two options. Use itrs_to_cirs() or itrs_to_tod() instead. You can then follow these with other conversions to GCRS (or whatever else) as appropriate.

Rotates a vector from the celestial to the terrestrial system. Specifically, it transforms a vector in the GCRS, or the dynamical (CIRS or TOD) frames to the ITRS (a rotating Earth-fixed system) by applying rotations for the GCRS-to-dynamical frame tie, precession, nutation, Earth rotation, and polar motion.

If 'system' is NOVAS_CIRS then method EROT_ERA must be used. Similarly, if 'system' is NOVAS_TOD then method must be EROT_ERA. Otherwise an error 3 is returned.

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

  | jd_ut1_high | [day] High-order part of UT1 Julian date.
  | jd_ut1_low | [day] Low-order part of UT1 Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | erot | Unused.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | coordType | Input coordinate class, NOVAS_REFERENCE_CLASS (0) or NOVAS_DYNAMICAL_CLASS (1). Use the former if the input coordinates are in the GCRS, and the latter if they are CIRS or TOD (the 'erot' parameter selects which dynamical system the input is specified in.)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole. If you have defined pole offsets the old (pre IAU2000) way, via cel_pole(), then use 0 here.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole. If you have defined pole offsets the old (pre IAU2000) way, via cel_pole(), then use 0 here.
  | in | Input position vector, geocentric equatorial rectangular coordinates in the specified input coordinate system (GCRS if 'class' is NOVAS_REFERENCE_CLASS; or else either CIRS if 'erot' is EROT_ERA, or TOD if 'erot' is EROT_GST).
  [out] | out | ITRS position vector, geocentric equatorial rectangular coordinates (terrestrial system). It can be the same vector as the input.

Returns
  0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also
  novas_app_to_hor(), gcrs_to_cirs(), cirs_to_itrs(), frame_tie(), j2000_to_tod(), tod_to_itrs(), ter2cel()

References era(), EROT_ERA, EROT_GST, gcrs_to_cirs(), gcrs_to_tod(), NOVAS_DYNAMICAL_CLASS, NOVAS_FULL_ACCURACY, novas_gast(), NOVAS_REDUCED_ACCURACY, spin(), wobble(), WOBBLE_PEF_TO_ITRS, and WOBBLE_TIRS_TO_ITRS.

## ter2cel()

short ter2cel | ( | double | jd_ut1_high,
|  | double | jd_ut1_low,
|  | double | ut1_to_tt,
|  | enum novas_earth_rotation_measure | erot,
|  | enum novas_accuracy | accuracy,
|  | enum novas_equatorial_class | coordType,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Deprecated
  This function can be confusing to use due to the output coordinate system being specified by a combination of two options. Use itrs_to_cirs() or itrs_to_tod() instead. You can then follow these with other conversions to GCRS (or whatever else) as appropriate.

Rotates a vector from the terrestrial to the celestial system. Specifically, it transforms a vector in the ITRS (rotating earth-fixed system) to the True of Date (TOD), CIRS, or GCRS (a local space-fixed system) by applying rotations for polar motion, Earth rotation (for TOD); and nutation, precession, and the dynamical-to-GCRS frame tie (for GCRS).

If 'system' is NOVAS_CIRS then method EROT_ERA must be used. Similarly, if 'system' is NOVAS_TOD then method must be EROT_ERA. Otherwise an error 3 is returned.

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

  | jd_ut1_high | [day] High-order part of UT1 Julian date.
  | jd_ut1_low | [day] Low-order part of UT1 Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | erot | Unused.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | coordType | Output coordinate class NOVAS_REFERENCE_CLASS (0, or any value other than 1) or NOVAS_DYNAMICAL_CLASS (1). Use the former if the output coordinates are to be in the GCRS, and the latter if they are to be in CIRS or TOD (the 'erot' parameter selects which dynamical system to use for the output.)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole. If you have defined pole offsets the old (pre IAU2000) way, via cel_pole(), then use 0 here.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole. If you have defined pole offsets the old (pre IAU2000) way, via cel_pole(), then use 0 here.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system) in the normal case where 'option' is NOVAS_GCRS (0).
  [out] | out | Position vector, equatorial rectangular coordinates in the specified output system (GCRS if 'class' is NOVAS_REFERENCE_CLASS; or else either CIRS if 'erot' is EROT_ERA, or TOD if 'erot' is EROT_GST). It may be the same vector as the input.

Returns
  0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid 10–20, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also
  novas_hor_to_app(), itrs_to_cirs(), cirs_to_gcrs(), itrs_to_tod(), tod_to_j2000(), frame_tie(), cel2ter()

References cirs_to_gcrs(), era(), EROT_ERA, EROT_GST, NOVAS_DYNAMICAL_CLASS, NOVAS_FULL_ACCURACY, novas_gast(), NOVAS_REDUCED_ACCURACY, spin(), tod_to_gcrs(), wobble(), WOBBLE_ITRS_TO_PEF, and WOBBLE_ITRS_TO_TIRS.