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

Transformations of station coordinates, velocities, and Earth orinetation parameters (EOP) between various ITRF realizations, and conversion between Cartesian (x, y, z) and geodetic (longitude, latitude, altitude) coordinates w.r.t. More...

## Functions

int | novas_cartesian_to_geodetic (const double *restrict xyz, enum novas_reference_ellipsoid ellipsoid, double *restrict lon, double *restrict lat, double *restrict alt)
| Converts geocentric Cartesian site coordinates to geodetic coordinates on the given reference ellipsoid.
int | novas_geodetic_to_cartesian (double lon, double lat, double alt, enum novas_reference_ellipsoid ellipsoid, double *xyz)
| Converts geodetic site coordinates to geocentric Cartesian coordinates, using the specified reference ellipsoid.
int | novas_geodetic_transform_site (enum novas_reference_ellipsoid from_ellipsoid, const on_surface *in, enum novas_reference_ellipsoid to_ellipsoid, on_surface *out)
| Transforms a geodetic location from one reference ellipsoid to another.
int | novas_itrf_transform (int from_year, const double *restrict from_coords, const double *restrict from_rates, int to_year, double *to_coords, double *to_rates)
| Converts ITRF coordinates between different realizations of the ITRF coordinate system.
int | novas_itrf_transform_eop (int from_year, double from_xp, double from_yp, double from_dut1, int to_year, double *restrict to_xp, double *restrict to_yp, double *restrict to_dut1)
| Transforms Earth orientation parameters (xp, yp, dUT1) from one ITRF realization to another.
int | novas_itrf_transform_site (int from_year, const on_surface *in, int to_year, on_surface *out)
| Transforms a geodetic location between two International Terrestrial Reference Frame (ITRF) realizations.

## Detailed Description

Transformations of station coordinates, velocities, and Earth orinetation parameters (EOP) between various ITRF realizations, and conversion between Cartesian (x, y, z) and geodetic (longitude, latitude, altitude) coordinates w.r.t.

the reference ellipsoid.

REFERENCES:

1. ITRS Conventions Chapter 4, see https://iers-conventions.obspm.fr/content/chapter4/icc4.pdf

Date
  Created on Aug 26, 2025

Author
  Attila Kovacs

Since
  1.5

See also
  observer.c

## Function Documentation

## novas_cartesian_to_geodetic()

int novas_cartesian_to_geodetic | ( | const double *restrict | xyz,
|  | enum novas_reference_ellipsoid | ellipsoid,
|  | double *restrict | lon,
|  | double *restrict | lat,
|  | double *restrict | alt )

Converts geocentric Cartesian site coordinates to geodetic coordinates on the given reference ellipsoid.

NOTES:

1. Adapted from the IERS GCONV2.F source code, see https://iers-conventions.obspm.fr/content/chapter4/software/GCONV2.F.

REFERENCES:

1. Fukushima, T., "Transformation from Cartesian to geodetic coordinates accelerated by Halley's method", J. Geodesy (2006), 79(12): 689-693
2. Petit, G. and Luzum, B. (eds.), IERS Conventions (2010), IERS Technical Note No. 36, BKG (2010)

Parameters

  [in] | xyz | [m] Input geocentric Cartesian coordinates (x, y, z) 3-vector.
  | ellipsoid | Reference ellipsoid to use. For ITRF use NOVAS_GRS80_ELLIPSOID, for GPS related applications use NOVAS_WGS84_ELLIPSOID.
  [out] | lon | [deg] Geodetic longitude. It may be NULL if not required.
  [out] | lat | [deg] Geodetic latitude. It may be NULL if not required.
  [out] | alt | [m] Geodetic altitude (i.e. above sea level). It may be NULL if not required.

Returns
  0 if successful, or else -1 if the input vector is NULL (errno is set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_geodetic_to_cartesian()
  novas_itrf_transform(), novas_itrf_transform_site()

References M_PI, NOVAS_GRS80_FLATTENING, and NOVAS_GRS80_RADIUS.

Referenced by supernovas::Site::Site(), make_gps_site(), make_xyz_site(), novas_geodetic_transform_site(), and novas_itrf_transform_site().

## novas_geodetic_to_cartesian()

int novas_geodetic_to_cartesian | ( | double | lon,
|  | double | lat,
|  | double | alt,
|  | enum novas_reference_ellipsoid | ellipsoid,
|  | double * | xyz )

Converts geodetic site coordinates to geocentric Cartesian coordinates, using the specified reference ellipsoid.

Parameters

  [in] | lon | [deg] Geodetic longitude
  [in] | lat | [deg] Geodetic latitude
  [in] | alt | [m] Geodetic altitude (i.e. above sea level).
  | ellipsoid | Reference ellipsoid to use. For ITRF use NOVAS_GRS80_ELLIPSOID, for GPS related applications use NOVAS_WGS84_ELLIPSOID.
  [out] | xyz | [m] Corresponding geocentric Cartesian coordinates (x, y, z) 3-vector.

Returns
  0 if successful, or else -1 if the output vector is NULL (errno is set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_cartesian_to_geodetic()
  novas_itrf_transform_site(), novas_itrf_transform()

References NOVAS_GRS80_FLATTENING, and NOVAS_GRS80_RADIUS.

Referenced by make_gps_site(), novas_geodetic_transform_site(), novas_itrf_transform_site(), and supernovas::Site::xyz().

## novas_geodetic_transform_site()

int novas_geodetic_transform_site | ( | enum novas_reference_ellipsoid | from_ellipsoid,
|  | const on_surface * | in,
|  | enum novas_reference_ellipsoid | to_ellipsoid,
|  | on_surface * | out )

Transforms a geodetic location from one reference ellipsoid to another.

For example to transform a GPS location (defined on the WGS84 ellipsoid) to an International Terrestrial Reference Frame (ITRF) location (defined on the GRS80 ellipsoid), or vice versa.

Parameters

  | from_ellipsoid | Reference ellipsoid of the input coordinates.
  [in] | in | Input site, defined on the original reference ellipsoid.
  | to_ellipsoid | Reference ellipsoid for which to calculate output coordinates.
  [out] | out | Output site, calculated for the final reference ellipsoid. It may be the same as the input.

Returns
  0 if successful, or else -1 if either site pointer is NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_itrf_transform_site(), make_gps_site(), make_itrf_site()

References novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::longitude, novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by supernovas::Site::Site().

## novas_itrf_transform()

int novas_itrf_transform | ( | int | from_year,
|  | const double *restrict | from_coords,
|  | const double *restrict | from_rates,
|  | int | to_year,
|  | double * | to_coords,
|  | double * | to_rates )

Converts ITRF coordinates between different realizations of the ITRF coordinate system.

It does not account for station motions, which the user should apply separately. For example, consider the use case when input coordinates are given in ITRF88, for measurement in the epoch 1994.36, and output is expected in ITRF2000 for measurements at 2006.78. This function simply translates the input, measured in epoch 1994.36, to ITRF2000. Proper motion between the epochs (2006.78 and 1994.36) can be calculated with the input rates before conversion, e.g.:

// Apply station motion in ITRF88
for(i = 0; i < 3; i++)
from_coords[i] += from_rates[i] * (2006.78 - 1994.36)
// Convert ITRF88 coordinates to ITRF2000
novas_itrf_transform(1988, from_coords, from_rates, 2000, ...);
novas_itrf_transform
int novas_itrf_transform(int from_year, const double *restrict from_coords, const double *restrict from_rates, int to_year, double *to_coords, double *to_rates)
Converts ITRF coordinates between different realizations of the ITRF coordinate system.
Definition itrf.c:222

or equivalently, after the transformation to ITRF2000, as:

// Convert ITRF88 coordinates to ITRF2000
novas_itrf_transform(1988, from_coords, from_rates, 2000, to_coords, to_rates);
// Apply station motion in ITRF2000
for(i = 0; i < 3; i++)
to_coords[i] += to_rates[i] * (2006.78 - 1994.36)

REFERENCES:

1. IERS Conventions, Chapter 4, Eq. 4.13 and Table 4.1. See https://iers-conventions.obspm.fr/content/chapter4/icc4.pdf

Parameters

  | from_year | [yr] ITRF realization year of input coordinates / rates. E.g. 1992 for ITRF92.
  [in] | from_coords | [m] input ITRF coordinates.
  [in] | from_rates | [m/yr] input ITRF coordinate rates, or NULL if not known or needed.
  | to_year | [yr] ITRF realization year of output coordinates / rates. E.g. 2014 for ITRF2014.
  [out] | to_coords | [m] ITRF coordinates at final year, or NULL if not required. It may be the same as either of the inputs.
  [out] | to_rates | [m/yr] ITRF coordinate rates at final year, or NULL if not known or needed. It may be the same as either of the inputs.

Returns
  0 if successful, or else -1 (errno set to EINVAL) if the input coordinates are NULL, or if input rates are NULL but output_rates are not NULL.

Since
  1.5

Author
  Attila Kovacs

See also
  novas_itrf_transform_site(), novas_itrf_transform_eop()
  novas_geodetic_to_cartesian()

Referenced by novas_itrf_transform_site().

## novas_itrf_transform_eop()

int novas_itrf_transform_eop | ( | int | from_year,
|  | double | from_xp,
|  | double | from_yp,
|  | double | from_dut1,
|  | int | to_year,
|  | double *restrict | to_xp,
|  | double *restrict | to_yp,
|  | double *restrict | to_dut1 )

Transforms Earth orientation parameters (xp, yp, dUT1) from one ITRF realization to another.

For the highest precision applications, observing sites should be defined in the same ITRF realization as the IERS Earth orientation parameters (EOP). To reconcile you may transform either the site location or the EOP between different realizations to match.

REFERENCES:

1. IERS Conventions, Chapter 4, Eq. 4.14 and Table 4.1. See https://iers-conventions.obspm.fr/content/chapter4/icc4.pdf

Parameters

  | from_year | [yr] ITRF realization year of input coordinates / rates. E.g. 1992 for ITRF92.
  [in] | from_xp | [arcsec] x-pole Earth orientation parameter (angle) in the input ITRF realization.
  [in] | from_yp | [arcsec] y-pole Earth orientation parameter (angle) in the input ITRF realization.
  [in] | from_dut1 | [s] UT1-UTC time difference in the input ITRF realization.
  | to_year | [yr] ITRF realization year of input coordinates / rates. E.g. 2000 for ITRF2000.
  [out] | to_xp | [arcsec] x-pole Earth orientation parameter (angle) in the output ITRF realization, or NULL if not required.
  [out] | to_yp | [arcsec] y-pole Earth orientation parameter (angle) in the output ITRF realization, or NULL if not required.
  [out] | to_dut1 | [s] UT1-UTC time difference in the output ITRF realization, or NULL if not required.

Returns
  0

Since
  1.5

Author
  Attila Kovacs

See also
  novas_itrf_transform(), novas_itrf_transform_site(), novas_get_eop_itrf_year()
  novas_make_frame(), novas_timespec, wobble()

References NOVAS_DAY, NOVAS_EARTH_FLATTENING, and TWOPI.

Referenced by supernovas::EOP::itrf_transformed().

## novas_itrf_transform_site()

int novas_itrf_transform_site | ( | int | from_year,
|  | const on_surface * | in,
|  | int | to_year,
|  | on_surface * | out )

Transforms a geodetic location between two International Terrestrial Reference Frame (ITRF) realizations.

ITRF realizations differ at the mm / μas level. Thus for the highest accuracy astrometry, from e.g. VLBI sites, it may be desirable to ensure that the site coordinates are defined for the same ITRF realization, as the one in which Earth-orientation parameters (EOP) are provided for novas_make_frame(), novas_timespec, or wobble().

Parameters

  | from_year | [yr] ITRF realization year of input coordinates / rates. E.g. 1992 for ITRF92.
  [in] | in | Input site, defined in the original ITRF realization.
  | to_year | [yr] ITRF realization year of input coordinates / rates. E.g. 2000 for ITRF2000.
  [out] | out | Output site, calculated for the final ITRF realization. It may be the same as the input.

Returns
  0 if successful, or else -1 if either site pointer is NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_geodetic_transform_site(), novas_itrf_transform_eop(), novas_itrf_transform(), make_itrf_site(), make_itrf_observer()

References novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::longitude, novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, novas_itrf_transform(), novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by supernovas::Site::itrf_transformed().