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.
int | novas_icrs_to_sys (const double *in, double jd_tdb, enum novas_accuracy accuracy, enum novas_reference_system sys, double *out)
| Converts a rectangular equatorial vector from the International Coordinate Reference System (ICRS) or equivalent, such as GCRS, to the desired output equatorial coordinate reference system of choice.
int | novas_sys_to_icrs (enum novas_reference_system sys, const double *in, double jd_tdb, enum novas_accuracy accuracy, double *out)
| Converts a rectangular equatorial vector from the specified equatorial coordinate reference system of choice to the International Coordinate Reference System (ICRS) or equivalent, such as 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 transform position and/or velocity 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

## app_to_cirs_ra()

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.

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  ra | [h] the apparent R.A. coordinate measured from the true equinox of date.

Returns
  [h] The CIRS right ascension coordinate, measured from the CIO [0:24], or NAN if the accuracy is invalid, or if there was an error from cio_ra().

Since
  1.0.1

Author
  Attila Kovacs

See also
  cirs_to_app_ra(), tod_to_cirs()

References cio_ra().

## 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(), gcrs_to_cirs(), gcrs_to_tod(), NOVAS_FULL_ACCURACY, novas_gast(), NOVAS_REDUCED_ACCURACY, spin(), wobble(), WOBBLE_PEF_TO_ITRS, and WOBBLE_TIRS_TO_ITRS.

Referenced by cirs_to_itrs(), and tod_to_itrs().

## cirs_to_app_ra()

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.

measured from the true equinox of date.

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  ra | [h] The CIRS right ascension coordinate, measured from the CIO.

Returns
  [h] the apparent R.A. coordinate measured from the true equinox of date [0:24], or NAN if the accuracy is invalid, or if there was an error from cio_ra().

Since
  1.0.1

Author
  Attila Kovacs

See also
  app_to_cirs_ra(), cirs_to_tod()

References cio_ra().

## cirs_to_gcrs()

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.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

This function uses Method 2 of the IERS Conventions 2010 (Chapter 5, Section 5.9), converting CIRS to TOD first via a rotation by the equation of origins, then using the IAU 2006 precession-nutation model (P03; Capitaine et al. 2003) to convert to J2000, and finally correcting for the frame bias to arrive at GCRS.

REFERENCES:

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

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | CIRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the ICRS / GCRS coordinate frame. It can be the same vector as the input.

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

Since
  1.0

Author
  Attila Kovacs

See also
  tod_to_gcrs(), gcrs_to_cirs(), cirs_to_itrs(), cirs_to_tod(), novas_sys_to_icrs()

References cirs_to_tod(), and tod_to_gcrs().

Referenced by novas_sys_to_icrs(), and ter2cel().

## cirs_to_itrs()

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

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

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

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_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to CIRS axes (celestial system).
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system).

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, 3 if the method and option are mutually incompatible, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  tod_to_itrs(), itrs_to_cirs(), gcrs_to_cirs(), cirs_to_gcrs(), cirs_to_tod()

References cel2ter().

## cirs_to_tod()

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.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | CIRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True of Date (TOD) frame. It can be the same vector as the input.

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

Since
  1.1

Author
  Attila Kovacs

See also
  tod_to_cirs(), cirs_to_app_ra(), cirs_to_gcrs(), cirs_to_itrs()

References ira_equinox(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, and spin().

Referenced by cirs_to_gcrs().

## frame_tie()

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.

The dynamical reference system is based on the dynamical mean equator and equinox of J2000.0. The ICRS is based on the space-fixed ICRS axes defined by the radio catalog positions of several hundred extragalactic objects.

For geocentric coordinates, the same transformation is used between the dynamical reference system and the GCRS.

NOTES:

1. More efficient 3D rotation implementation for small angles by A. Kovacs

REFERENCES:

1. Hilton, J. and Hohenkerk, C. (2004), Astronomy and Astrophysics 413, 765-770, eq. (6) and (8).
2. IERS (2003) Conventions, Chapter 5.

Parameters

  | in | Position vector, equatorial rectangular coordinates.
  | direction | <0 for dynamical to ICRS transformation, or else >=0 for ICRS to dynamical transformation. Alternatively you may use the constants J2000_TO_ICRS (-1; or negative) or ICRS_TO_J2000 (0; or positive).
  [out] | out | Position vector, equatorial rectangular coordinates. It can be the same vector as the input.

Returns
  0 if successfor or -1 if either of the vector arguments is NULL.

See also
  j2000_to_gcrs(), gcrs_to_j2000()

Referenced by ecl2equ_vec(), equ2ecl_vec(), gcrs_to_j2000(), gcrs_to_mod(), gcrs_to_tod(), j2000_to_gcrs(), mod_to_gcrs(), tod_to_gcrs(), and transform_cat().

## gcrs2equ()

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

For coordinates with respect to the true equator of date, the origin of right ascension can be either the true equinox or the celestial intermediate origin (CIO). This function only supports the CIO-based method.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_ICRS_EQUATOR)
  | sys | Dynamical equatorial system type
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1) (unused if 'coord_sys' is not NOVAS_ICRS [3])
  | rag | [h] GCRS right ascension in hours.
  | decg | [deg] GCRS declination in degrees.
  [out] | ra | [h] Right ascension in hours, referred to specified equator and right ascension origin of date.
  [out] | dec | [deg] Declination in degrees, referred to specified equator of date.

Returns
  0 if successful, or -1 with errno set to EINVAL if the output pointers are NULL, or sys and/or accuracy is invalid; otherwise <0 if an error from vector2radec(); 10–20 error is 10 + error cio_location(); or else 20 + error from cio_basis()

See also
  gcrs_to_tod(), gcrs_to_mod(), gcrs_to_cirs(), novas_transform_sky_pos()

References gcrs_to_cirs(), gcrs_to_mod(), gcrs_to_tod(), NOVAS_DYNAMICAL_CIRS, NOVAS_DYNAMICAL_MOD, NOVAS_DYNAMICAL_TOD, radec2vector(), and vector2radec().

## gcrs_to_cirs()

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.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

This function uses Method 2 of the IERS Conventions 2010 (Chapter 5, Section 5.9), first applying the frame bias to convert GCRS to J2000, then using the IAU 2006 precession-nutation model (P03; Capitaine et al. 2003) to convert to TOD, and finally to CIRS via a rotation by the equation of origins.

REFERENCES:

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

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | ICRS / GCRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

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

Since
  1.0

Author
  Attila Kovacs

See also
  gcrs_to_j2000(), cirs_to_gcrs(), novas_icrs_to_sys()

References gcrs_to_tod(), and tod_to_cirs().

Referenced by cel2ter(), gcrs2equ(), novas_icrs_to_sys(), and place().

## gcrs_to_j2000()

int gcrs_to_j2000 | ( | const double * | in,
|  | double * | out )

Changes ICRS / GCRS coordinates to J2000 coordinates.

Same as frame_tie() called with ICRS_TO_J2000. (We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | in | ICRS / GCRS input 3-vector
  [out] | out | J2000 output 3-vector

Returns
  0 if successful, or else an error from frame_tie()

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_gcrs(), tod_to_j2000(), novas_icrs_to_sys()

References frame_tie(), and ICRS_TO_J2000.

Referenced by novas_icrs_to_sys().

## gcrs_to_mod()

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.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | in | ICRS / GCRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the Mean wquinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL.

Since
  1.2

Author
  Attila Kovacs

See also
  mod_to_gcrs(), gcrs_to_tod(), novas_icrs_to_sys()

References frame_tie(), ICRS_TO_J2000, NOVAS_JD_J2000, and precession().

Referenced by gcrs2equ(), and novas_icrs_to_sys().

## gcrs_to_tod()

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.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | ICRS / GCRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL, or if the accuracy argument is invalid.

Since
  1.2

Author
  Attila Kovacs

See also
  gcrs_to_cirs(), tod_to_gcrs(), j2000_to_tod(), novas_icrs_to_sys()

References frame_tie(), ICRS_TO_J2000, and j2000_to_tod().

Referenced by cel2ter(), gcrs2equ(), gcrs_to_cirs(), and novas_icrs_to_sys().

## itrs_to_cirs()

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

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

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

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_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system)
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to CIRS axes (celestial system).

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

Since
  1.0

Author
  Attila Kovacs

See also
  itrs_to_tod(), cirs_to_itrs(), cirs_to_gcrs()

References ter2cel().

## itrs_to_tod()

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

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

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

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_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system)
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to True of Date (TOD) axes (celestial system)

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

Since
  1.0

Author
  Attila Kovacs

See also
  itrs_to_cirs(), tod_to_itrs(), tod_to_j2000()

References ter2cel().

Referenced by novas_site_gcrs_posvel().

## j2000_to_gcrs()

int j2000_to_gcrs | ( | const double * | in,
|  | double * | out )

Change J2000 coordinates to ICRS / GCRS coordinates.

Same as frame_tie() called with J2000_TO_ICRS. (We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | in | J2000 input 3-vector
  [out] | out | ICRS / GCRS output 3-vector

Returns
  0 if successful, or else an error from frame_tie()

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_tod(), gcrs_to_j2000(), novas_sys_to_icrs()

References frame_tie(), and J2000_TO_ICRS.

Referenced by novas_sys_to_icrs().

## j2000_to_tod()

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.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Input (x, y, z) position or velocity vector in rectangular equatorial coordinates at J2000
  [out] | out | Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid.

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_gcrs(), tod_to_j2000(), gcrs_to_j2000()

References NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NUTATE_MEAN_TO_TRUE, nutation(), and precession().

Referenced by gcrs_to_tod().

## mod_to_gcrs()

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.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | in | Input (x, y, z) position or velocity 3-vector in the Mean equinox of Date coordinate frame.
  [out] | out | Output ICRS / GCRS position or velocity vector. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL.

Since
  1.2

Author
  Attila Kovacs

See also
  gcrs_to_mod(), tod_to_gcrs(), novas_sys_to_icrs()

References frame_tie(), J2000_TO_ICRS, NOVAS_JD_J2000, and precession().

Referenced by novas_sys_to_icrs().

## novas_icrs_to_sys()

int novas_icrs_to_sys | ( | const double * | in,
|  | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | enum novas_reference_system | sys,
|  | double * | out )

Converts a rectangular equatorial vector from the International Coordinate Reference System (ICRS) or equivalent, such as GCRS, to the desired output equatorial coordinate reference system of choice.

Note, that this function does not support conversion to an Earth rotating system, such as TIRS or ITRS.

Parameters

  | in | Input ICRS / GCRS vector (double[3]).
  | jd_tdb | Barycentric Dynamical Time (TDB) based Julian Date. (Unused if output system is ICRS / GCRS or J2000). TT-based Julian Dates may be used also without loss of precision.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).
  | sys | Iutput coordinate system. It cannot be NOVAS_TIRS or NOVAS_ITRS, or else the function will return an error (-1 / ENOSYS).
  [out] | out | Output vector (double[3]) to be populated. It may be the same vector as the input.

Returns
  0 if successful or else -1 if any of the vectors is NULL or (errno set to EINVAL), or the coordinate system is unsupported (errno set to ENOSYS) or out of range (errno set to ERANGE).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_sys_to_icrs()

References gcrs_to_cirs(), gcrs_to_j2000(), gcrs_to_mod(), gcrs_to_tod(), NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_TIRS, and NOVAS_TOD.

Referenced by place(), and supernovas::Equatorial::to_system().

## novas_sys_to_icrs()

int novas_sys_to_icrs | ( | enum novas_reference_system | sys,
|  | const double * | in,
|  | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | double * | out )

Converts a rectangular equatorial vector from the specified equatorial coordinate reference system of choice to the International Coordinate Reference System (ICRS) or equivalent, such as GCRS.

Note, that this function does not support conversion from an Earth rotating system, such as TIRS or ITRS.

Parameters

  sys | Input coordinate system. It cannot be NOVAS_TIRS or NOVAS_ITRS, or else the function will return an error (-1 / ENOSYS).
  in | Input vector in system (double[3]).
  jd_tdb | Barycentric Dynamical Time (TDB) based Julian Date. (Unused if input system is ICRS / GCRS or J2000). TT-based Julian Dates may be used also without loss of precision.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).
  out | Output ICRS / GCRS vector (double[3]) to be populated. It may be the same vector as the input.

Returns
  0 if successful or else -1 if any of the vectors is NULL or (errno set to EINVAL), or the coordinate system is unsupported (errno set to ENOSYS) or out of range (errno set to ERANGE).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_icrs_to_sys()

References cirs_to_gcrs(), j2000_to_gcrs(), mod_to_gcrs(), NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_TIRS, NOVAS_TOD, and tod_to_gcrs().

Referenced by supernovas::Equatorial::to_system().

## 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(), NOVAS_FULL_ACCURACY, novas_gast(), NOVAS_REDUCED_ACCURACY, spin(), tod_to_gcrs(), wobble(), WOBBLE_ITRS_TO_PEF, and WOBBLE_ITRS_TO_TIRS.

Referenced by equ2hor(), itrs_to_cirs(), and itrs_to_tod().

## tod_to_cirs()

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 .

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | CIRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True of Date (TOD) frame. It can be the same vector as the input.

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

Since
  1.1

Author
  Attila Kovacs

See also
  cirs_to_tod(), app_to_cirs_ra(), tod_to_gcrs(), tod_to_j2000(), tod_to_itrs()

References ira_equinox(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, and spin().

Referenced by gcrs_to_cirs().

## tod_to_gcrs()

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.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Input (x, y, z) position or velocity 3-vector in the True equinox of Date coordinate frame.
  [out] | out | Output ICRS / GCRS position or velocity vector. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL.

Since
  1.2

Author
  Attila Kovacs

See also
  j2000_to_tod(), tod_to_cirs(), tod_to_j2000(), tod_to_itrs(), novas_sys_to_icrs()

References frame_tie(), J2000_TO_ICRS, and tod_to_j2000().

Referenced by cio_basis(), cirs_to_gcrs(), geo_posvel(), novas_site_gcrs_posvel(), novas_site_uvw(), novas_sys_to_icrs(), and ter2cel().

## tod_to_itrs()

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

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

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

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_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to True of Date (TOD) axes (celestial system).
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system).

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, 3 if the method and option are mutually incompatible, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  cirs_to_itrs(), itrs_to_tod(), j2000_to_tod(), tod_to_gcrs(), tod_to_j2000(), tod_to_cirs()

References cel2ter().

## tod_to_j2000()

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.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Input (x, y, z) position or velocity 3-vector in the True equinox of Date coordinate frame.
  [out] | out | Output position or velocity vector in rectangular equatorial coordinates at J2000. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the 'accuracy' is invalid.

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_tod(), j2000_to_gcrs(), tod_to_gcrs(), tod_to_cirs(), tod_to_itrs()

References NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NUTATE_TRUE_TO_MEAN, nutation(), and precession().

Referenced by tod_to_gcrs().