![]() |
SuperNOVAS v1.5
The NOVAS C library, made better
|
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. | |
#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).
Value is 1 / 298.25642.
#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 |
#define ON_SURFACE_INIT |
#define ON_SURFACE_LOC | ( | lon, | |
lat, | |||
alt ) |
Initializer for a NOVAS on_surface
data structure at a specified geodetic location.
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. |
enum novas_observer_place |
Types of places on and around Earth that may serve a a reference position for the observation.
Enumerator | |
---|---|
NOVAS_OBSERVER_AT_GEOCENTER | Calculate coordinates as if observing from the geocenter for location and Earth rotation independent coordinates.
|
NOVAS_OBSERVER_ON_EARTH | Stationary observer in the corotating frame of Earth.
|
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.
|
NOVAS_AIRBORNE_OBSERVER | Observer airborne, moving relative to the surface of Earth.
|
NOVAS_SOLAR_SYSTEM_OBSERVER | Observer is orbiting the Sun.
|
Type of Earth reference ellipsoid.
Only ellipsoids commonly in use today are listed, ommitting many obsoleted historical variants.
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.
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. |
References IN_SPACE_INIT, make_observer(), NOVAS_AIRBORNE_OBSERVER, and in_space::sc_vel.
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.
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. |
References make_gps_site(), and make_observer_at_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.
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. |
References make_itrf_site(), novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, and NOVAS_WGS84_ELLIPSOID.
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.
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. |
References in_space::sc_pos, and in_space::sc_vel.
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.
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. |
References make_itrf_site(), and make_observer_at_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.
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. |
References on_surface::height, on_surface::latitude, on_surface::longitude, and novas_set_default_weather().
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()
.
[out] | obs | Pointer to data structure to populate. |
References make_observer(), and NOVAS_OBSERVER_AT_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.
site | Pointer to observing site data structure. | |
[out] | obs | Pointer to the data structure to populate. |
References NOVAS_OBSERVER_ON_EARTH.
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()
.
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 |
References make_in_space(), make_observer(), and NOVAS_OBSERVER_IN_EARTH_ORBIT.
int make_observer_on_surface | ( | double | latitude, |
double | longitude, | ||
double | height, | ||
double | temperature, | ||
double | pressure, | ||
observer *restrict | obs ) |
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:
novas_itrf_transform()
, possibly after novas_geodetic_to_cartesian()
with NOVAS_GRS80_ELLIPSOID
as necessary for polar ITRF coordinates. novas_cartesian_to_geodetic()
with NOVAS_GRS80_ELLIPSOID
as the reference ellipsoid parameter. 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. |
References make_observer(), make_on_surface(), and NOVAS_OBSERVER_ON_EARTH.
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.
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 |
References make_in_space(), make_observer(), and NOVAS_SOLAR_SYSTEM_OBSERVER.
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.
xyz | [m] Cartesian geocentric position. | |
[out] | site | Pointer to the data structure to populate. |
References make_itrf_site(), novas_cartesian_to_geodetic(), and NOVAS_GRS80_ELLIPSOID.
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:
GCONV2.F
source code, see https://iers-conventions.obspm.fr/content/chapter4/software/GCONV2.F. REFERENCES:
[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. |
References M_PI, NOVAS_GRS80_FLATTENING, and NOVAS_GRS80_RADIUS.
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.
[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. |
References NOVAS_GRS80_FLATTENING, and NOVAS_GRS80_RADIUS.
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.
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. |
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.
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.:
or equivalently, after the transformation to ITRF2000, as:
REFERENCES:
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. |
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()
.
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. |
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.
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:
[in,out] | site | Site containing geodetic loation as input, and poulated with typical mean weather parameters for the output. |
References on_surface::height, on_surface::humidity, on_surface::latitude, on_surface::pressure, and on_surface::temperature.