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

This module provides a set of functions that define an astronomical observer location, or ones that relate to observer location. More...

## Functions

int | aberration (const double *pos, const double *vobs, double lighttime, double *out)
| Corrects position vector for aberration of light.
int | bary2obs (const double *pos, const double *pos_obs, double *out, double *restrict lighttime)
| Moves the origin of coordinates from the barycenter of the solar system to the observer (or the geocenter); i.e., this function accounts for parallax (annual+geocentric or just annual).
short | geo_posvel (double jd_tt, double ut1_to_tt, enum novas_accuracy accuracy, const observer *restrict obs, double *restrict pos, double *restrict vel)
| Computes the geocentric GCRS position and velocity of an observer.
short | light_time (double jd_tdb, const object *restrict body, const double *pos_obs, double tlight0, enum novas_accuracy accuracy, double *pos_src_obs, double *restrict tlight)
| Computes the geocentric position of a solar system body, as antedated for light-time.
int | light_time2 (double jd_tdb, const object *restrict body, const double *restrict pos_obs, double tlight0, enum novas_accuracy accuracy, double *p_src_obs, double *restrict v_ssb, double *restrict tlight)
| Computes the geocentric position and velocity of a solar system body, as antedated for light-time.
int | make_airborne_observer (const on_surface *location, const double *itrs_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.
short | make_observer (enum novas_observer_place where, const on_surface *loc_surface, const in_space *loc_space, observer *obs)
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_on_surface (double latitude, double longitude, double height, double temperature, double pressure, on_surface *restrict loc)
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_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.
int | novas_site_gcrs_posvel (const novas_timespec *restrict ts, const on_surface *restrict site, const double *restrict v_itrs, double xp, double yp, enum novas_accuracy accuracy, double *restrict pos, double *restrict vel)
| Returns precise GCRS position and velocity vectors for an observer located on or near Earth's surface.
int | novas_site_uvw (const novas_timespec *restrict ts, const on_surface *restrict station, const double *restrict geocentric_source, double xp, double yp, enum novas_accuracy accuracy, double *restrict uvw)
| Returns geocentric u,v,w coordinates for a ground-based interferometer station.
int | novas_uvw (const double *restrict station_pos, const double *restrict station_vel, const double *restrict phase_center, double *restrict uvw)
| Returns u,v,w coordinates for a space-based interferometer station.
int | obs_planets (double jd_tdb, enum novas_accuracy accuracy, const double *restrict pos_obs, int pl_mask, novas_planet_bundle *restrict planets)
| Calculates the positions and velocities for the Solar-system bodies, e.g.
int | obs_posvel (double jd_tdb, double ut1_to_tt, enum novas_accuracy accuracy, const observer *restrict obs, const double *restrict geo_pos, const double *restrict geo_vel, double *restrict pos, double *restrict vel)
| Calculates the ICRS position and velocity of the observer relative to the Solar System Barycenter (SSB).

## Detailed Description

This module provides a set of functions that define an astronomical observer location, or ones that relate to observer location.

The following type of observer locations are supported:

1. Geodetic Earth-based observer locations: a. ground-based observer sites:
   - GPS locations via make_gps_observer()
   - ITRF / GRS80 locations via make_itrs_observer()
   - Cartesian x, y, z coordinates via make_xyz_site() and make_site_observer() b. airborne observers, via a location (e.g. make_gps_site(), make_itrf_site() or make_xyz_site()), and a ground velocity using make_airborne_observer().
2. Near Earth Orbit (NEO) locations, via make_observer_in_space() specifying momentary position and velocity w.r.t. the geocenter.
3. Virtual observer at the geocenter via make_observer_at_geocecenter().
4. Solar-system locations via make_solar_system_observer(), specifying a momentary barycentric (that is w.r.t. the SSB) position and velocity vector.

Once an observer is defined, it maybe used to set up an observing frame for a specific time of observation. Observing frames allow efficient and precise position calculations from an observer's point-of-view.

Date
  Created on Mar 6, 2025

Author
  Attila Kovacs and G. Kaplan

See also
  timescale.c, frame.c, system.c, itrf.c

## Function Documentation

## aberration()

int aberration | ( | const double * | pos,
|  | const double * | vobs,
|  | double | lighttime,
|  | double * | out )

Corrects position vector for aberration of light.

Algorithm includes relativistic terms.

NOTES:

1. This function is called by place() to account for aberration when calculating the position of the source.

REFERENCES:

1. Murray, C. A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
2. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | pos | [AU] Position vector of source relative to observer
  | vobs | [AU/day] Velocity vector of observer, relative to the solar system barycenter.
  | lighttime | [day] Light time from object to Earth (if known). Or set to 0, and this function will compute it as needed.
  [out] | out | [AU] Position vector, referred to origin at center of mass of the Earth, corrected for aberration. It can be the same vector as one of the inputs.

Returns
  0 if successful, or -1 if any of the vector arguments are NULL.

See also
  frame_aberration()

References novas_vlen().

Referenced by novas_moon_elp_sky_pos_fp(), novas_uvw(), and place().

## bary2obs()

int bary2obs | ( | const double * | pos,
|  | const double * | pos_obs,
|  | double * | out,
|  | double *restrict | lighttime )

Moves the origin of coordinates from the barycenter of the solar system to the observer (or the geocenter); i.e., this function accounts for parallax (annual+geocentric or just annual).

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | pos | [AU] Position vector, referred to origin at solar system barycenter.
  | pos_obs | [AU] Position vector of observer (or the geocenter), with respect to origin at solar system barycenter.
  [out] | out | [AU] Position vector, referred to origin at center of mass of the Earth. It may be NULL if not required, or be the same vector as either of the inputs.
  [out] | lighttime | [day] Light time from object to Earth. It may be NULL if not required.

Returns
  0 if successful, or -1 if any of the essential pointer arguments is NULL.

See also
  novas_make_frame(), light_time2()

References novas_vlen().

Referenced by light_time2(), novas_geom_posvel(), and place().

## geo_posvel()

short geo_posvel | ( | double | jd_tt,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | const observer *restrict | obs,
|  | double *restrict | pos,
|  | double *restrict | vel )

Computes the geocentric GCRS position and velocity of an observer.

NOTES:

- For Earth-based observers, this function does not include polar wobble corrections, so the returned GCRS positions are accurate at the tens of meters level only. You might use novas_site_gcrs_posvel() instead if higher accuracy is required for Earth-based observers.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | obs | observer location.
  [out] | pos | [AU] Position 3-vector of observer, with respect to origin at geocenter, referred to GCRS axes, components in AU. (It may be NULL if not required.)
  [out] | vel | [AU/day] Velocity 3-vector of observer, with respect to origin at geocenter, referred to GCRS axes, components in AU/day. (It must be distinct from the pos output vector, and may be NULL if not required)

Returns
  0 if successful, -1 if the 'obs' is NULL or the two output vectors are the same, or else 1 if 'accuracy' is invalid, or 2 if 'obserrver->where' is invalid.

See also
  novas_site_gcrs_posvel(), novas_make_frame(), make_observer(), get_ut1_to_tt()

References ephemeris(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_DEBUG_EXTRA, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, novas_gast(), novas_get_debug_mode(), NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_REDUCED_ACCURACY, NOVAS_SOLAR_SYSTEM_OBSERVER, terra(), tod_to_gcrs(), and tt2tdb().

Referenced by supernovas::Observer::gcrs_position_at(), supernovas::Observer::gcrs_velocity_at(), and obs_posvel().

## light_time()

short light_time | ( | double | jd_tdb,
|  | const object *restrict | body,
|  | const double * | pos_obs,
|  | double | tlight0,
|  | enum novas_accuracy | accuracy,
|  | double * | pos_src_obs,
|  | double *restrict | tlight )

Computes the geocentric position of a solar system body, as antedated for light-time.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | body | Pointer to structure containing the designation for the solar system body
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
  | tlight0 | [day] First approximation to light-time (can be set to 0.0 if not readily available – it will then be computed as needed).
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | pos_src_obs | [AU] Position 3-vector of body, with respect to origin at observer (or the geocenter), referred to ICRS axes. It can be the same vector as either of the inputs.
  [out] | tlight | [day] Calculated light time

Returns
  0 if successful, -1 if any of the pointer arguments is NULL, 1 if the algorithm failed to converge after 10 iterations, or 10 + the error from ephemeris().

See also
  light_time2(), novas_make_frame()

References light_time2().

## light_time2()

int light_time2 | ( | double | jd_tdb,
|  | const object *restrict | body,
|  | const double *restrict | pos_obs,
|  | double | tlight0,
|  | enum novas_accuracy | accuracy,
|  | double * | p_src_obs,
|  | double *restrict | v_ssb,
|  | double *restrict | tlight )

Computes the geocentric position and velocity of a solar system body, as antedated for light-time.

It is effectively the same as the original NOVAS C light_time(), except that this returns the antedated source velocity vector also.

NOTES:

1. This function is called by novas_geom_posvel() or place() to calculate observed positions, radial velocity, and distance for the time when the observed light originated from the source.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | body | Pointer to structure containing the designation for the solar system body
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
  | tlight0 | [day] First approximation to light-time (can be set to 0.0 if not readily available – so it will be calculated as needed).
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | p_src_obs | [AU] Position 3-vector of body, relative to observer, referred to ICRS axes, components in AU.
  [out] | v_ssb | [AU/day] Velocity 3-vector of body, with respect to the Solar-system barycenter, referred to ICRS axes.
  [out] | tlight | [day] Calculated light time, or NAN when returning with an error code.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vectors are the same or if they are the same as pos_obs, 1 if the algorithm failed to converge after 10 iterations, or 10 + the error from ephemeris().

See also
  light_time()
  novas_sky_pos()

Since
  1.0

Author
  Attila Kovacs

References bary2obs(), ephemeris(), NOVAS_BARYCENTER, NOVAS_FULL_ACCURACY, and novas_inv_max_iter.

Referenced by light_time(), novas_geom_posvel(), obs_planets(), and place().

## make_airborne_observer()

int make_airborne_observer | ( | const on_surface * | location,
|  | const double * | itrs_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.
  | itrs_vel | [km/s] Surface velocity (in ITRS).
  [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

See also
  novas_enu_to_itrs()

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

Referenced by supernovas::GeodeticObserver::GeodeticObserver().

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

Referenced by make_gps_observer().

## 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 novas_in_space::sc_pos, and novas_in_space::sc_vel.

Referenced by make_observer_in_space(), and make_solar_system_observer().

## 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 novas_on_surface::height, novas_on_surface::latitude, novas_on_surface::longitude, and novas_set_default_weather().

Referenced by supernovas::Site::Site(), make_gps_site(), make_itrf_observer(), make_on_surface(), and make_xyz_site().

## make_observer()

short make_observer | ( | enum novas_observer_place | where,
|  | const on_surface * | loc_surface,
|  | const in_space * | loc_space,
|  | observer * | obs )

Deprecated
  It is recommended that you use one of the more specific ways of initializing the observer data structure, e.g. with make_itrf_observer(), make_gps_observer(), make_observer_at_site(), make_airborne_observer() make_solar_system_observer(), or make_observer_at_geocenter(). This function will be available for the foreseeable future also.

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

Parameters

  | where | The location type of the observer
  | loc_surface | Pointer to data structure that defines a location on Earth's surface. Used only if 'where' is NOVAS_OBSERVER_ON_EARTH or NOVAS_AIRBORNE_OBSERVER. Otherwise, it can be NULL.
  | loc_space | Pointer to data structure that defines a near-Earth location in space. Used only if 'where' is NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_AIRBORNE_OBSERVER, or NOVAS_SOLAR_SYSTEM_OBSERVER. Otherwise, it can be NULL.
  [out] | obs | Pointer to observer data structure to populate.

Returns
  0 if successful, -1 if a required argument is NULL, or 1 if the 'where' argument is invalid.

See also
  make_observer_at_geocenter(), make_itrf_observer(), make_gps_observer(), make_airborne_observer(), make_observer_in_space(), make_solar_system_observer()

References novas_observer::near_earth, NOVAS_AIRBORNE_OBSERVER, NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_SOLAR_SYSTEM_OBSERVER, novas_observer::on_surf, novas_in_space::sc_vel, and novas_observer::where.

Referenced by make_airborne_observer(), make_observer_at_geocenter(), make_observer_in_space(), make_observer_on_surface(), and make_solar_system_observer().

## 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 as 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.

Referenced by place().

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

Referenced by local_planet(), local_star(), make_gps_observer(), make_itrf_observer(), topo_planet(), and topo_star().

## 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 as 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_on_surface()

int make_on_surface | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | double | temperature,
|  | double | pressure,
|  | on_surface *restrict | loc )

Deprecated
  This old NOVAS C function has a few too many caveats. It is recommended that you use make_itrf_site() or make_gps_site() instead (both 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.

Populates an 'on_surface' data structure, for an observer on the surface of the Earth, with the given parameters.

Note, that because this is an original NOVAS C routine, it does not have an argument to set a humidity value (e.g. for radio refraction). As such, the humidity is set to a default mean annual value for the location. To set an actual humidity, set the output structure's field after calling this funcion.

NOTES:

1. This implementation breaks strict v1.0 ABI compatibility since it writes to (initializes) a field (humidity) that was not yet part of the on_surface structure in v1.0. As such, linking SuperNOVAS v1.1 or later with application code compiled for SuperNOVAS v1.0 can result in memory corruption or segmentation fault when this function is called. To be safe, make sure your application has been (re)compiled against SuperNOVAS v1.1 or later.
2. 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.
3. You can convert Cartesian xyz locations to geodetic locations by using novas_cartesian_to_geodetic() with NOVAS_GRS80_ELLIPSOID as the reference ellipsoid parameter.
4. If you have longitude, latitude, and height defined as GPS (WGS84) values, you might want to use make_gps_site() instead, and then set weather parameters afterwards as necessary.

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GSR80) altitude above sea level of the observer.
  | temperature | [C] Temperature (degrees Celsius) [-120:70].
  | pressure | [mbar] Atmospheric pressure [0:1200].
  [out] | loc | Pointer to Earth location 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, or if the temperature or pressure values are impossible for an Earth based observer (errno set to ERANGE).

See also
  make_itrf_site(), make_gps_site(), make_xyz_site()
  novas_set_default_weather(), novas_cartesian_to_geodetic(), ON_SURFACE_INIT, ON_SURFACE_LOC, NOVAS_GRS80_ELLIPSOID

References make_itrf_site().

Referenced by make_observer_on_surface().

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

Referenced by supernovas::SolarSystemObserver::SolarSystemObserver(), and supernovas::SolarSystemObserver::SolarSystemObserver().

## 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_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 novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by supernovas::Site::average_weather(), make_itrf_site(), and refract().

## novas_site_gcrs_posvel()

int novas_site_gcrs_posvel | ( | const novas_timespec *restrict | ts,
|  | const on_surface *restrict | site,
|  | const double *restrict | v_itrs,
|  | double | xp,
|  | double | yp,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns precise GCRS position and velocity vectors for an observer located on or near Earth's surface.

NOTES:

1. unlike the original NOVAS geo_posvel(), this implementation takes the polar offsets into account.

Parameters

  | ts | Astrometric time of oservation
  | site | ITRF / GRS80 geodetic location on Earth
  | v_itrs | [km/s] surface velocity vector in ITRS, or NULL if observing from a fixed Earth location.
  | xp | [arcsec] Earth orientation parameter, polar offset in x, e.g. from the IERS Bulletins, and including diurnal libration and ocean tides. You can use 0.0 if sub-arcsecond accuracy is not required.
  | yp | [arcsec] Earth orientation parameter, polar offset in y, e.g. from the IERS Bulletins, and including diurnal libration and ocean tides. You can use 0.0 if sub-arcsecond accuracy is not required.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | pos | GCRS position vector of observer. It may be NULL if not required.
  [out] | vel | GCRS velocity vector of observer. It may be NULL if not required.

Returns
  0 if successful, or else -1 if any of the input pointers is NULL or if both output pointers are NULL (errno will be set to EINVAL).

Author
  Attila Kovacs

Since
  1.6

See also
  geo_posvel()

References itrs_to_tod(), NOVAS_AU_PER_DAY, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_KMS, NOVAS_REDUCED_ACCURACY, NOVAS_TDB, terra(), and tod_to_gcrs().

Referenced by supernovas::GeodeticObserver::gcrs_position_at(), supernovas::GeodeticObserver::gcrs_velocity_at(), and novas_site_uvw().

## novas_site_uvw()

int novas_site_uvw | ( | const novas_timespec *restrict | ts,
|  | const on_surface *restrict | station,
|  | const double *restrict | geocentric_source,
|  | double | xp,
|  | double | yp,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | uvw )

Returns geocentric u,v,w coordinates for a ground-based interferometer station.

That is, it returns u,v,w coordinates, for a geodetic station, relative to the geocenter, for a given apparent line-of-sight on the sky, observed at the specified time. The u and v coordinates are the projections of the site in the GCRS direction of the local East and North respectively, as seen from the source, relative to the geocenter, while w is the distance (inverse delay) from the geocenter along the line of sight.

For interferometers, each station is its own specific site, and the array is usually referenced to one of the stations, or to some other reference location (a virtual site). As such, one is typically interested in uvw coordinates relative to the reference position, which can be obtained from the geocentric uvw provided by this method, via simple vector differencing.

NOTES:

1. This method supports down to nanometer precision for sites on Earth or in Low Earth Orbit (LEO), and sub-micron (<μm) precision even at the distance of the Moon. However, because its calculations are based on geocentric positions, the precision degrades with increasing distance from Earth, and may not be suitable for interferometers far from Earth. When precision is a concern, you might use the more generic novas_uvw() instead, with positions (and velocities) of the stations defined relative to the array center – enabling higher precision projections than this function.

Parameters

  | ts | Astrometric time of observation.
  | station | Interferometric station site.
  | geocentric_source | [AU] Apparent true-of-date (TOD) position of a source, as seen from the geocenter at the time of observation.
  | xp | [arcsec] IERS polar offset xp, such as obtained from the IERS bulletins or online service.
  | yp | [arcsec] IERS polar offset yp, such as obtained from the IERS bulletins or online service.
  | accuracy | NOVAS_FULL_ACCYRACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | uvw | [m] output u, v, w coordinates, relative to geocenter, the u, and v coordinates are aligned with the local East and North directions in the GCRS.

Returns
  0 if successful or else -1 if any of the pointer arguments are NULL or if the accuracy is invalid (errno will be set to EINVAL).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_uvw()

References novas_get_time(), novas_site_gcrs_posvel(), NOVAS_TDB, novas_uvw(), and tod_to_gcrs().

## novas_uvw()

int novas_uvw | ( | const double *restrict | station_pos,
|  | const double *restrict | station_vel,
|  | const double *restrict | phase_center,
|  | double *restrict | uvw )

Returns u,v,w coordinates for a space-based interferometer station.

That is, it returns the u,v,w coordinates of this astrometric place (of a station), measured relative to a reference point (array reference), for a given apparent line-of-sight on the sky (source) at the same time as when the station location is defined. The u and v coordinates are the projections of the site in the direction of the local East and North respectively, as seen from the source, relative to the array reference, while w is the distance (inverse delay) from the array reference along the line of sight.

For space-based interferometers, this astrometric place can represent the momentary position of a station, relative to the array reference. As such, the returned uvw coordinates are relative to the array reference.

Parameters

  | station_pos | [AU] 3D position vector of interferometric station, relative to the array reference. It can be defined in any system, as long as the phase center is defined in the same coordinate reference system.
  | station_vel | [AU/day] 3D position vector of interferometric station, relative to the array reference, in the same coordinate reference system as the position. It may be NULL for a station that is not moving relative to the array reference.
  | phase_center | [AU] Apparent position vector of the interferometric phase center (observed source), as seen from the reference location at the time of observation, in the same coordinate reference system, in which the station vectors are defined.
  [out] | uvw | [m] output u, v, w coordinates, relative to reference place. The u, and v coordinates are aligned with the local East and North directions in the system, in which the coordinates were specified.

Returns
  0 if successful or else -1 if the station position or phase center is NULL (errno will be set to EINVAL).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_site_uvw()

References aberration(), NOVAS_AU, novas_xyz_to_los(), and vector2radec().

Referenced by novas_site_uvw(), supernovas::AstrometricPosition::to_interferometric(), and supernovas::Observer::to_interferometric().

## obs_planets()

int obs_planets | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double *restrict | pos_obs,
|  | int | pl_mask,
|  | novas_planet_bundle *restrict | planets )

Calculates the positions and velocities for the Solar-system bodies, e.g.

for use for gravitational deflection calculations. The planet positions are calculated relative to the observer location, while velocities are w.r.t. the SSB. Both positions and velocities are antedated for light travel time, so they accurately reflect the apparent position (and barycentric motion) of the bodies from the observer's perspective.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1). In full accuracy mode, it will calculate the deflection due to the Sun, Jupiter, Saturn and Earth. In reduced accuracy mode, only the deflection due to the Sun is calculated.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
  | pl_mask | Bitwise (1 << planet-number) mask indicating which planets to request data for. See enum novas_planet for the enumeration of planet numbers.
  [out] | planets | Pointer to apparent planet data to populate. The planets with non-zero mask bits will have have positions and velocities calculated. See enum novas_planet for the enumeration of planet numbers.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vector is the same as pos_obs, or the error from ephemeris().

See also
  enum novas_planet, grav_planets(), grav_undo_planets(), set_planet_provider(), set_planet_provider_hp()

Since
  1.1

Author
  Attila Kovacs

References light_time2(), make_planet(), novas_debug(), NOVAS_DEBUG_EXTRA, NOVAS_DEBUG_OFF, novas_get_debug_mode(), NOVAS_PLANETS, and NOVAS_SUN.

Referenced by grav_def(), grav_undef(), novas_change_observer(), and place().

## obs_posvel()

int obs_posvel | ( | double | jd_tdb,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | const observer *restrict | obs,
|  | const double *restrict | geo_pos,
|  | const double *restrict | geo_vel,
|  | double *restrict | pos,
|  | double *restrict | vel )

Calculates the ICRS position and velocity of the observer relative to the Solar System Barycenter (SSB).

NOTES:

1. This implementation does not take polar wobble corrections into account for Earth-based (ITRS) observing locations. For those, it provides position vectors at the tens of meters level only.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | ut1_to_tt | [s] TT - UT1 time difference. Used only when 'location->where' is NOVAS_OBSERVER_ON_EARTH (1) or NOVAS_OBSERVER_IN_EARTH_ORBIT (2), or NOVAS_AIRBORNE_OBSERVER (3).
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | obs | The observer location, relative to which the output positions and velocities are to be calculated
  | geo_pos | [AU] ICRS position vector of the geocenter w.r.t. the Solar System Barycenter (SSB). If either geo_pos or geo_vel is NULL, it will be calculated when needed.
  | geo_vel | [AU/day] ICRS velocity vector of the geocenter w.r.t. the Solar System Barycenter (SSB). If either geo_pos or geo_vel is NULL, it will be calculated when needed.
  [out] | pos | [AU] Position 3-vector of the observer w.r.t. the Solar System Barycenter (SSB). It may be NULL if not required.
  [out] | vel | [AU/day] Velocity 3-vector of the observer w.r.t. the Solar System Barycenter (SSB). It must be distinct from the pos output vector, and may be NULL if not required.

Returns
  0 if successful, or the error from geo_posvel(), or else -1 (with errno indicating the type of error).

Author
  Attila Kovacs

Since
  1.3

See also
  novas_make_frame()

References ephemeris(), geo_posvel(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_EARTH_INIT, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_OBSERVER_PLACES, NOVAS_SOLAR_SYSTEM_OBSERVER, and tt2tdb().

Referenced by place().