Loading...
Searching...
No Matches
Observer location

## Data Structures

struct | in_space
| data for an observer's location on Earth orbit More...
struct | observer
| Observer location. More...
struct | on_surface
| Data for an observer's location on the surface of the Earth, and optional local weather data for refraction calculations only. More...

## Macros

#define | IN_SPACE_INIT
| Initializer for a NOVAS in_space structure.
#define | NOVAS_EARTH_FLATTENING NOVAS_GRS80_FLATTENING
| [m] Earth ellipsoid flattening (ITRF / GRS80_MODEL)
#define | NOVAS_EARTH_RADIUS NOVAS_GRS80_RADIUS
| [m] Equatorial radius of Earth (ITRF / GRS80 model)
#define | NOVAS_GRS80_FLATTENING (1.0 / 298.257222101)
| [m] WGS84 Earth flattening
#define | NOVAS_GRS80_RADIUS 6378137.0
| [m] Equatorial radius of the WGS84 reference ellipsoid.
#define | NOVAS_IERS_EARTH_FLATTENING (1.0 / 298.25642)
| [m] Earth ellipsoid flattening from IERS Conventions (2003).
#define | NOVAS_IERS_EARTH_RADIUS 6378136.6
| [m] Equatorial radius of Earth in meters from IERS Conventions (2003).
#define | NOVAS_WGS84_FLATTENING (1.0 / 298.257223563)
| [m] WGS84 Earth flattening
#define | NOVAS_WGS84_RADIUS 6378137.0
| [m] Equatorial radius of the WGS84 reference ellipsoid.
#define | OBSERVER_INIT
| Empty initializer for observer.
#define | ON_SURFACE_INIT
| Initializer for a NOVAS on_surface data structure.
#define | ON_SURFACE_LOC(lon, lat, alt)
| Initializer for a NOVAS on_surface data structure at a specified geodetic location.

## Enumerations

enum | novas_observer_place { NOVAS_OBSERVER_AT_GEOCENTER = 0 , NOVAS_OBSERVER_ON_EARTH , NOVAS_OBSERVER_IN_EARTH_ORBIT , NOVAS_AIRBORNE_OBSERVER , NOVAS_SOLAR_SYSTEM_OBSERVER }
| Types of places on and around Earth that may serve a a reference position for the observation. More...
enum | novas_reference_ellipsoid { NOVAS_GRS80_ELLIPSOID = 0 , NOVAS_WGS84_ELLIPSOID , NOVAS_IERS_1989_ELLIPSOID , NOVAS_IERS_2003_ELLIPSOID }
| Type of Earth reference ellipsoid. More...

## Functions

int | make_airborne_observer (const on_surface *location, const double *vel, observer *obs)
| Populates an 'observer' data structure for an observer moving relative to the surface of Earth, such as an airborne observer.
int | make_gps_observer (double latitude, double longitude, double height, observer *obs)
| Initializes an observer data structure for a ground-based observer with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.
int | make_gps_site (double latitude, double longitude, double height, on_surface *site)
| Initializes an observing site with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.
int | make_in_space (const double *sc_pos, const double *sc_vel, in_space *loc)
| Populates an 'in_space' data structure, for an observer situated on a near-Earth spacecraft, with the provided position and velocity components.
int | make_itrf_observer (double latitude, double longitude, double height, observer *obs)
| Initializes an observer data structure for a ground-based observer with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.
int | make_itrf_site (double latitude, double longitude, double height, on_surface *site)
| Initializes an observing site with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.
int | make_observer_at_geocenter (observer *restrict obs)
| Populates an 'observer' data structure for a hypothetical observer located at Earth's geocenter.
int | make_observer_at_site (const on_surface *restrict site, observer *restrict obs)
| Initializes an observer data structure for a ground-based observer at the specified observing site, and sets mean (annual) weather parameters based on that location.
int | make_observer_in_space (const double *sc_pos, const double *sc_vel, observer *obs)
| Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.
int | make_observer_on_surface (double latitude, double longitude, double height, double temperature, double pressure, observer *restrict obs)
int | make_solar_system_observer (const double *sc_pos, const double *sc_vel, observer *obs)
| Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.
int | make_xyz_site (const double *restrict xyz, on_surface *restrict site)
| Initializes an observing site with the specified Cartesian geocentric xyz location, and sets mean (annual) weather parameters based on that location.
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_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.
int | novas_set_default_weather (on_surface *site)
| Sets default weather parameters based on an approximate global model to the mean annualized temperatures, based on Feulner et al.

## Detailed Description

## Macro Definition Documentation

## IN_SPACE_INIT

#define IN_SPACE_INIT

Initializer for a NOVAS in_space structure.

Since
  1.1.1

Author
  Attila Kovacs

See also
  in_space

## NOVAS_EARTH_FLATTENING

#define NOVAS_EARTH_FLATTENING NOVAS_GRS80_FLATTENING

[m] Earth ellipsoid flattening (ITRF / GRS80_MODEL)

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_EARTH_RADIUS

#define NOVAS_EARTH_RADIUS NOVAS_GRS80_RADIUS

[m] Equatorial radius of Earth (ITRF / GRS80 model)

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_GRS80_FLATTENING

#define NOVAS_GRS80_FLATTENING (1.0 / 298.257222101)

[m] WGS84 Earth flattening

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_GRS80_RADIUS

#define NOVAS_GRS80_RADIUS 6378137.0

[m] Equatorial radius of the WGS84 reference ellipsoid.

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_IERS_EARTH_FLATTENING

#define NOVAS_IERS_EARTH_FLATTENING (1.0 / 298.25642)

[m] Earth ellipsoid flattening from IERS Conventions (2003).

Value is 1 / 298.25642.

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_IERS_EARTH_RADIUS

#define NOVAS_IERS_EARTH_RADIUS 6378136.6

[m] Equatorial radius of Earth in meters from IERS Conventions (2003).

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_WGS84_FLATTENING

#define NOVAS_WGS84_FLATTENING (1.0 / 298.257223563)

[m] WGS84 Earth flattening

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_WGS84_RADIUS

#define NOVAS_WGS84_RADIUS 6378137.0

[m] Equatorial radius of the WGS84 reference ellipsoid.

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## OBSERVER_INIT

#define OBSERVER_INIT

Empty initializer for observer.

Since
  1.3

Author
  Attila Kovacs

See also
  observer

## ON_SURFACE_INIT

#define ON_SURFACE_INIT

Initializer for a NOVAS on_surface data structure.

Since
  1.2

Author
  Attila Kovacs

See also
  on_surface, ON_SURFACE_LOC

## ON_SURFACE_LOC

#define ON_SURFACE_LOC | ( |  | lon,
|  |  | lat,
|  |  | alt )

Initializer for a NOVAS on_surface data structure at a specified geodetic location.

Parameters

  lon | [deg] Geodetic longitude of observer (East is positive)
  lat | [deg] Geodetic latitude of observer (North is positive)
  alt | [m] Observer altitude above sea level.

Since
  1.2

Author
  Attila Kovacs

See also
  on_surface, make_itrf_site(), make_gps_site(), make_xyz_site(), ON_SURFACE_INIT

## Enumeration Type Documentation

## novas_observer_place

enum novas_observer_place

Types of places on and around Earth that may serve a a reference position for the observation.

See also
  observer, NOVAS_OBSERVER_PLACES

Enumerator

NOVAS_OBSERVER_AT_GEOCENTER

Calculate coordinates as if observing from the geocenter for location and Earth rotation independent coordinates.

See also
  make_observer_at_geocenter()

NOVAS_OBSERVER_ON_EARTH

Stationary observer in the corotating frame of Earth.

See also
  make_gps_observer(), make_itrf_observer(), make_site_observer()

NOVAS_OBSERVER_IN_EARTH_ORBIT

Observer is on Earth orbit, with a position and velocity vector relative to geocenter.

This may also be appropriate for observatories at the L2 or other Earth-based Langrange points.

See also
  make_observer_in_space()

NOVAS_AIRBORNE_OBSERVER

Observer airborne, moving relative to the surface of Earth.

Since
  1.1

See also
  make_airborne_observer()

NOVAS_SOLAR_SYSTEM_OBSERVER

Observer is orbiting the Sun.

Since
  1.1

See also
  make_solar_system_observer()

## novas_reference_ellipsoid

enum novas_reference_ellipsoid

Type of Earth reference ellipsoid.

Only ellipsoids commonly in use today are listed, ommitting many obsoleted historical variants.

Since
  1.5

See also
  novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), novas_geodetic_transform_site()

Enumerator
NOVAS_GRS80_ELLIPSOID | GRS80 reference ellipsoid, used for the International Terrestrial Reference System (ITRS).
NOVAS_WGS84_ELLIPSOID | WGS84 reference ellipsoid, used for GPS navigation.
NOVAS_IERS_1989_ELLIPSOID | IERS (1989) reference ellipsoid, formerly used by the IERS conventions (but not for ITRS, which uses the GRS80 model).
NOVAS_IERS_2003_ELLIPSOID | IERS (2003) reference ellipsoid, used by the IERS conventions (but not for ITRS, which uses the GRS80 model).

## Function Documentation

## make_airborne_observer()

int make_airborne_observer | ( | const on_surface * | location,
|  | const double * | vel,
|  | observer * | obs )

Populates an 'observer' data structure for an observer moving relative to the surface of Earth, such as an airborne observer.

Airborne observers have an earth fixed momentary location, defined by longitude, latitude, and altitude, the same was as for a stationary observer on Earth, but are moving relative to the surface, such as in an aircraft or balloon observatory.

Parameters

  | location | Current geodetic location, e.g. as populated with make_gps_site() or similar.
  | vel | [km/s] Surface velocity.
  [out] | obs | Pointer to data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_itrf_site(), make_gps_site(), make_xyz_site()
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_observer_in_space(), make_solar_system_observer(), make_observer_at geocenter(), novas_make_frame()

Since
  1.1

Author
  Attila Kovacs

References IN_SPACE_INIT, make_observer(), NOVAS_AIRBORNE_OBSERVER, and in_space::sc_vel.

## make_gps_observer()

int make_gps_observer | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | observer * | obs )

Initializes an observer data structure for a ground-based observer with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.

For the highest (μas / mm level) precision, you probably should use an ITRF location instead of a GPS based location.

Parameters

  | latitude | [deg] Geodetic (GPS / WGS84) latitude north positive.
  | longitude | [deg] Geodetic (GPS / WGS84) longitude east positive.
  | height | [m] Geodetic (GPS / WGS84) altitude above sea level of the observer.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_observer_at_geocenter(), make_solar_system_observer()
  make_gps_site(), novas_set_default_weather(), novas_make_frame(), novas_geodetic_transform_site()

References make_gps_site(), and make_observer_at_site().

## make_gps_site()

int make_gps_site | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | on_surface * | site )

Initializes an observing site with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.

For the highest (μas / mm level) precision, you probably should use an ITRF location instead of a GPS based location.

Parameters

  | latitude | [deg] Geodetic (GPS / WGS84) latitude; north positive.
  | longitude | [deg] Geodetic (GPS / WGS84) longitude; east positive.
  | height | [m] Geodetic (GPS / WGS84) altitude above sea level of the observer.
  [out] | site | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_site(), make_xyz_site()
  make_itrf_observer(), make_observer_at_site(), novas_set_default_weather()

References make_itrf_site(), novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, and NOVAS_WGS84_ELLIPSOID.

## make_in_space()

int make_in_space | ( | const double * | sc_pos,
|  | const double * | sc_vel,
|  | in_space * | loc )

Populates an 'in_space' data structure, for an observer situated on a near-Earth spacecraft, with the provided position and velocity components.

Both input vectors are assumed with respect to true equator and equinox of date.

Parameters

  | sc_pos | [km] Geocentric (x, y, z) position vector. NULL defaults to the origin
  | sc_vel | [km/s] Geocentric (x, y, z) velocity vector. NULL defaults to zero speed.
  [out] | loc | Pointer to earth-orbit location data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_observer_in_space(), IN_SPACE_INIT

References in_space::sc_pos, and in_space::sc_vel.

## make_itrf_observer()

int make_itrf_observer | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | observer * | obs )

Initializes an observer data structure for a ground-based observer with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.

For the highest precision (μas level) applications you should make sure that the location provided here and the Earth-orientation parameters (EOP) used (in setting novas_timescale and in novas_make_frame()) are provided in the same ITRF realization. You can use novas_itrf_transform_eop() to change the ITRF realization for the EOP values, if necessary.

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GRS80) altitude above sea level of the observer.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_observer_at_geocenter(), make_solar_system_observer()
  make_itrf_site(), novas_itrf_transform_site(), novas_set_default_weather(), novas_make_frame()

References make_itrf_site(), and make_observer_at_site().

## make_itrf_site()

int make_itrf_site | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | on_surface * | site )

Initializes an observing site with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.

For the highest precision (μas level) applications you should make sure that the location provided here and the Earth-orientation parameters (EOP) used (in setting novas_timescale and in novas_make_frame()) are provided in the same ITRF realization. You can use novas_itrf_transform_eop() to change the ITRF realization for the EOP values, if necessary.

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GRS80) altitude above sea level of the observer.
  [out] | site | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_site(), make_xyz_site()
  make_itrf_observer(), make_observer_at_site(), novas_set_default_weather(), novas_itrf_transform_site(), novas_itrf_transform_eop()

References on_surface::height, on_surface::latitude, on_surface::longitude, and novas_set_default_weather().

## make_observer_at_geocenter()

int make_observer_at_geocenter | ( | observer *restrict | obs | ) |

Populates an 'observer' data structure for a hypothetical observer located at Earth's geocenter.

The output data structure may be used an the the inputs to NOVAS-C functions, such as make_frame() or place().

Parameters

  [out] | obs | Pointer to data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_solar_system_observer()
  novas_make_frame()

References make_observer(), and NOVAS_OBSERVER_AT_GEOCENTER.

## make_observer_at_site()

int make_observer_at_site | ( | const on_surface *restrict | site,
|  | observer *restrict | obs )

Initializes an observer data structure for a ground-based observer at the specified observing site, and sets mean (annual) weather parameters based on that location.

Parameters

  | site | Pointer to observing site data structure.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the either argument is NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  make_itrf_observer(), make_gps_observer(), make_airborne_observer(), make_observer_in_space(), make_observer_at_geocenter(), make_solar_system_observer()
  make_itrf_site(), make_gps_site(), make_xyz_site(), novas_make_frame()

References NOVAS_OBSERVER_ON_EARTH.

## make_observer_in_space()

int make_observer_in_space | ( | const double * | sc_pos,
|  | const double * | sc_vel,
|  | observer * | obs )

Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.

Both input vectors are with respect to true equator and equinox of date. The output data structure may be used an the the inputs to NOVAS-C functions, such as make_frame() or place().

Parameters

  | sc_pos | [km] Geocentric (x, y, z) position vector.
  | sc_vel | [km/s] Geocentric (x, y, z) velocity vector.
  [out] | obs | Pointer to the data structure to populate

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_at_geocenter(), make_solar_system_observer()
  novas_make_frame()

References make_in_space(), make_observer(), and NOVAS_OBSERVER_IN_EARTH_ORBIT.

## make_observer_on_surface()

int make_observer_on_surface | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | double | temperature,
|  | double | pressure,
|  | observer *restrict | obs )

Deprecated
  This old NOVAS C function has a few too many caveats. It is recommended that you use make_itrf_observer(), make_gps_observer(), or make_observer_at_site() instead (all of which set default mean annual weather parameters for approximate refraction correction), and optionally set actual weather data afterwards, based on the measurements available. This function will be available for the foreseeable future also.

Initializes an observer data structure with the specified ITRF / GRS80 location, and he specified local pressure and temperature. This old NOVAS C function does not set humidity. Thus, if humidity is needed for refraction correction, then you should set it explicitly after this call.

NOTES:

1. You can convert coordinates among ITRF realization using novas_itrf_transform(), possibly after novas_geodetic_to_cartesian() with NOVAS_GRS80_ELLIPSOID as necessary for polar ITRF coordinates.
2. You can convert ITRF Cartesian xyz locations to geodetic locations by using novas_cartesian_to_geodetic() with NOVAS_GRS80_ELLIPSOID as the reference ellipsoid parameter.
3. If you have longitude, latitude, and height defined as GPS (WGS84) values, you might want to use make_gps_observer() intead

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GRS80) altitude above sea level of the observer.
  | temperature | [C] Temperature (degrees Celsius).
  | pressure | [mbar] Atmospheric pressure.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL, or if the latitude is outside of the [-90:90] range, or if the temperature or pressure values are impossible for an Earth based observer (errno set to ERANGE).

See also
  make_itrf_observer(), make_gps_observer(), make_observer_at_site()
  novas_set_weather(), novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, novas_make_frame()

References make_observer(), make_on_surface(), and NOVAS_OBSERVER_ON_EARTH.

## make_solar_system_observer()

int make_solar_system_observer | ( | const double * | sc_pos,
|  | const double * | sc_vel,
|  | observer * | obs )

Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.

Solar-system observers are similar to observers in Earth-orbit but their momentary position and velocity is defined relative to the Solar System Barycenter, instead of the geocenter.

Parameters

  | sc_pos | [AU] Solar-system barycentric (x, y, z) position vector in ICRS.
  | sc_vel | [AU/day] Solar-system barycentric (x, y, z) velocity vector in ICRS.
  [out] | obs | Pointer to the data structure to populate

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_solar_system_observer()
  novas_make_frame()

Since
  1.1

Author
  Attila Kovacs

References make_in_space(), make_observer(), and NOVAS_SOLAR_SYSTEM_OBSERVER.

## make_xyz_site()

int make_xyz_site | ( | const double *restrict | xyz,
|  | on_surface *restrict | site )

Initializes an observing site with the specified Cartesian geocentric xyz location, and sets mean (annual) weather parameters based on that location.

For the highest precision (μas level) applications you should make sure that the site coordinates and the Earth-orientation parameters (EOP) used (in setting novas_timescale and in novas_make_frame()) are provided in the same ITRF realization. You can use novas_itrf_transform() or novas_itrf_transform_eop() to change the ITRF realization for the site coordinates and/or the EOP values, if necessary.

Parameters

  | xyz | [m] Cartesian geocentric position.
  [out] | site | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if either of the arguments is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_site(), make_itrf_site(), make_xyz_site()
  make_observer_at_site(), novas_itrf_transform(), novas_itrf_transform_eop(), novas_set_default_weather()

References make_itrf_site(), novas_cartesian_to_geodetic(), and NOVAS_GRS80_ELLIPSOID.

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

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

## novas_set_default_weather()

int novas_set_default_weather | ( | on_surface * | site | ) |

Sets default weather parameters based on an approximate global model to the mean annualized temperatures, based on Feulner et al.

(2013), and scaling relations with altitude (up to 12 km).

Humidity is set to 70% at sea level (which is a typical value globally), and adjusted to decrease with altitude linearly at a rate of 7.5% per km up to 8000 meters. Above that a quadratic model is assumed, peaking at 45% at 14 km – based on the measured distribution by Mendez-Astudillo et al. (2021). Finally above 20.8 km, zero humidity is assumed.

These parameters are all very approximate, but in the absence of measured data, they represent a best guess default model of sorts.

REFERENCES:

1. Feulner, G., Rahmstorf, S., Levermann, A., and Volkwardt, S. (2013), Journal of Climate 26, 7136
2. Mendez-Astudillo, J., et al. (2021), Urban Heat Island (UHI) Mitigation (pp.43-59), DOI:10.1007/978-981-33-4050-3_3

Parameters

  [in,out] | site | Site containing geodetic loation as input, and poulated with typical mean weather parameters for the output.

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

Since
  1.5

Author
  Attila Kovacs

See also
  make_itrf_site(), make_gps_site(), make_xyz_site(), make_itrf_observer(), make_gps_observer(), NOVAS_STANDARD_ATMOSPHERE

References on_surface::height, on_surface::humidity, on_surface::latitude, on_surface::pressure, and on_surface::temperature.