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:

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

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

REFERENCES:

Fukushima, T., "Transformation from Cartesian to geodetic coordinates accelerated by Halley's method", J. Geodesy (2006), 79(12): 689-693
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:

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:

Feulner, G., Rahmstorf, S., Levermann, A., and Volkwardt, S. (2013), Journal of Climate 26, 7136
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.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IN_SPACE_INIT

◆ NOVAS_EARTH_FLATTENING

◆ NOVAS_EARTH_RADIUS

◆ NOVAS_GRS80_FLATTENING

◆ NOVAS_GRS80_RADIUS

◆ NOVAS_IERS_EARTH_FLATTENING

◆ NOVAS_IERS_EARTH_RADIUS

◆ NOVAS_WGS84_FLATTENING

◆ NOVAS_WGS84_RADIUS

◆ OBSERVER_INIT

◆ ON_SURFACE_INIT

◆ ON_SURFACE_LOC

Enumeration Type Documentation

◆ novas_observer_place

◆ novas_reference_ellipsoid

Function Documentation

◆ make_airborne_observer()

◆ make_gps_observer()

◆ make_gps_site()

◆ make_in_space()

◆ make_itrf_observer()

◆ make_itrf_site()

◆ make_observer_at_geocenter()

◆ make_observer_at_site()

◆ make_observer_in_space()

◆ make_observer_on_surface()

◆ make_solar_system_observer()

◆ make_xyz_site()

◆ novas_cartesian_to_geodetic()

◆ novas_geodetic_to_cartesian()

◆ novas_geodetic_transform_site()

◆ novas_itrf_transform()

◆ novas_itrf_transform_site()

◆ novas_set_default_weather()