itrf.c File Reference

Functions
int	novas_cartesian_to_geodetic (const double *restrict xyz, enum novas_reference_ellipsoid ellipsoid, double *restrict lon, double *restrict lat, double *restrict alt)
int	novas_geodetic_to_cartesian (double lon, double lat, double alt, enum novas_reference_ellipsoid ellipsoid, double *xyz)
int	novas_geodetic_transform_site (enum novas_reference_ellipsoid from_ellipsoid, const on_surface *in, enum novas_reference_ellipsoid to_ellipsoid, on_surface *out)
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)
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)
int	novas_itrf_transform_site (int from_year, const on_surface *in, int to_year, on_surface *out)

Detailed Description

Date

Created on Aug 26, 2025

Author

Attila Kovacs

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

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.

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.

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 on_surface::height, on_surface::humidity, on_surface::latitude, on_surface::longitude, novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), on_surface::pressure, and on_surface::temperature.

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

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

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_make_frame(), novas_timespec, wobble()

References NOVAS_DAY, NOVAS_EARTH_FLATTENING, and TWOPI.

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_itrf_transform_eop(), novas_itrf_transform(), make_itrf_site(), make_itrf_observer()

novas_transform_ellipsoid()

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