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

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

## 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 an the 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, otherwise 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, otherwise 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 observer::near_earth, NOVAS_AIRBORNE_OBSERVER, NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_SOLAR_SYSTEM_OBSERVER, observer::on_surf, in_space::sc_vel, and observer::where.

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