Loading...
Searching...
No Matches
supernovas::Site Class Reference
Observer location

An Earth-based (geodetic) observer site location, or a momentary airborne observer location. More...

`#include <supernovas.h>`

Inheritance diagram for supernovas::Site:

## Public Member Functions

| Site (const Angle &longitude, const Angle &latitude, const Coordinate &altitude=Coordinate::zero(), enum novas_reference_ellipsoid ellipsoid=NOVAS_GRS80_ELLIPSOID)
| Constructs a new observing site with the specified geodetic location on the reference ellipsoid of choice.
| Site (const Position &xyz)
| Instantiates a new observing site with the specified geocentric position vector.
| Site (const std::string &longitude, const std::string &latitude, const Coordinate &altitude=Coordinate::zero(), enum novas_reference_ellipsoid ellipsoid=NOVAS_GRS80_ELLIPSOID)
| Constructs a new observing site with the specified geodetic location on the reference ellipsoid of choice.
| Site (double longitude_rad, double latitude_rad, double altitude_m=0.0, enum novas_reference_ellipsoid ellipsoid=NOVAS_GRS80_ELLIPSOID)
| Instantiates a new observing site with the specified geodetic location on the reference ellipsoid of choice.
const on_surface * | _on_surface () const
| Returns a pointer to the the NOVAS C on_surface data structure stored in this site data.
const Coordinate | altitude () const
| Returns a new distance containing the altitude of this site above the GRS80 reference ellipsoid (ie, above sea level).
Weather | average_weather () const
| Returns a default mean annual weather for this site based on a simple global model.
Position | enu_to_itrs (const Position &p) const
| Converts an East-Noth-Up (ENU) position vector at the site to an ITRF vector.
Velocity | enu_to_itrs (const Velocity &p) const
| Converts an East-Noth-Up (ENU) velocity vector at the site to an ITRF vector.
bool | equals (const Site &site, const Coordinate &tol) const
| Checks if this site is the same as another site, within the specified precision.
bool | equals (const Site &site, double tol_m=1e-3) const
| Checks if this site is the same as another site, within the specified precision.
Site | itrf_transformed (int from_year, int to_year) const
| Returns a new site transformed into a different ITRF realization.
Position | itrs_to_enu (const Position &p) const
| Converts an ITRF position vector to a local East-Noth-Up (ENU) vector at the site.
Velocity | itrs_to_enu (const Velocity &p) const
| Converts an ITRF velocity vector to a local East-Noth-Up (ENU) vector at the site.
const Angle | latitude () const
| Returns a new angle containing the geodetic latitude of this site on the GRS80 reference ellipsoid.
const Angle | longitude () const
| Returns a new angle containing the geodetic longitude of this site on the GRS80 reference ellipsoid.
bool | operator!= (const Site &site) const
| Checks if this site differs from another site, by more than 1 mm.
bool | operator== (const Site &site) const
| Checks if this site is the same as another site, within 1 mm.
GeodeticObserver | to_observer (const EOP &eop=EOP::undefined()) const
| Returns an observer location for this observing site and the specified IERS Earth Orientation Parameters (EOP).
std::string | to_string (enum novas_separator_type separator=NOVAS_SEP_UNITS_AND_SPACES, int decimals=3) const
| Returns a string representation of this observing site.
Position | xyz () const
| Returns the geocentric position of this site in ITRS rectangular coordinates.
Public Member Functions inherited from supernovas::Validating
bool | is_valid () const
| Returns the previously set 'valid' state of the implementing instance.
| operator bool () const
| Objects that implement Validating can be used in conditionals directly, without explicitly calling is_valid().

## Static Public Member Functions

static Site | from_GPS (const Angle &longitude, const Angle &latitude, const Coordinate &altitude=Coordinate::zero())
| Returns an observing site for its geodetic GPS location.
static Site | from_GPS (const std::string &longitude, const std::string &latitude, const Coordinate &altitude=Coordinate::zero())
| Returns an observing site for its geodetic GPS location, with the longitude and latitude provided in decimal or DMS string representations.
static Site | from_GPS (double longitude, double latitude, double altitude=0.0)
| Returns an observing site for its geodetic GPS location.
static const Site & | undefined ()
| Returns a reference to a statically allocated undefined observing site instance.

## Additional Inherited Members

Protected Member Functions inherited from supernovas::Validating
| Validating ()
| dummy constructor;
Protected Attributes inherited from supernovas::Validating
bool | _valid = false
| the state variable.

## Detailed Description

An Earth-based (geodetic) observer site location, or a momentary airborne observer location.

Positions may be defined as GPS / WGS84 or else as ITRF / GRS80 geodetic locations, or as Cartesian geocentric xyz positions in the International Terrestrial Reference Frame (ITRF).

The class provides the means to convert between ITRF realizations, e.g. to match the ITRF realization used for the Eath Orientation Parameters (EOP) obtained from IERS, for μas precision. (This is really only necessary for VLBI interferometry). Alternatively, one may also transform the EOP values to match the ITRF realization of the site.

Since
  1.6

See also
  GeodeticObserver, EOP

## Constructor & Destructor Documentation

## Site() [1/4]

supernovas::Site::Site | ( | double | longitude_rad,
|  | double | latitude_rad,
|  | double | altitude_m = 0.0,
|  | enum novas_reference_ellipsoid | ellipsoid = NOVAS_GRS80_ELLIPSOID )

Instantiates a new observing site with the specified geodetic location on the reference ellipsoid of choice.

Parameters

  longitude_rad | [rad] Observer's geodetic longitude
  latitude_rad | [rad] Observer's geodetic latitude
  altitude_m | [m] (optional) Observers's altitude above sea level (default: 0 m)
  ellipsoid | (optional) reference ellipsoid to use (default: NOVAS_GRS80_ELLIPSOID)

Since
  1.6

See also
  from_xyz(), from_GPS()

References supernovas::Validating::_valid, supernovas::Unit::deg, supernovas::Constant::half_pi, make_itrf_site(), novas_geodetic_transform_site(), NOVAS_GRS80_ELLIPSOID, and NOVAS_REFERENCE_ELLIPSOIDS.

## Site() [2/4]

supernovas::Site::Site | ( | const Angle & | longitude,
|  | const Angle & | latitude,
|  | const Coordinate & | altitude = Coordinate::zero(),
|  | enum novas_reference_ellipsoid | ellipsoid = NOVAS_GRS80_ELLIPSOID )

Constructs a new observing site with the specified geodetic location on the reference ellipsoid of choice.

Parameters

  longitude | Observer's geodetic longitude
  latitude | Observer's geodetic latitude
  altitude | (optional) Observers's altitude above sea level (default: 0 m)
  ellipsoid | (optional) reference ellipsoid to use (default: NOVAS_GRS80_ELLIPSOID)

Since
  1.6

See also
  from_xyz(), Site::from_GPS()

References altitude(), latitude(), and longitude().

## Site() [3/4]

supernovas::Site::Site | ( | const std::string & | longitude,
|  | const std::string & | latitude,
|  | const Coordinate & | altitude = Coordinate::zero(),
|  | enum novas_reference_ellipsoid | ellipsoid = NOVAS_GRS80_ELLIPSOID )

Constructs a new observing site with the specified geodetic location on the reference ellipsoid of choice.

Parameters

  longitude | String represenration of observer's geodetic longitude, as DMS or decimal degrees.
  latitude | String representation of observer's geodetic latitude, as DMS or decimal degrees.
  altitude | (optional) Observers's altitude above sea level (default: 0 m)
  ellipsoid | (optional) reference ellipsoid to use (default: NOVAS_GRS80_ELLIPSOID)

Since
  1.6

See also
  from_xyz(), Site::from_GPS()

References altitude(), latitude(), and longitude().

## Site() [4/4]

supernovas::Site::Site | ( | const Position & | xyz | ) |

explicit

Instantiates a new observing site with the specified geocentric position vector.

Parameters

  xyz | Observers geocentric position vector in rectangular coordinates.

Since
  1.6

References supernovas::Validating::_valid, novas_cartesian_to_geodetic(), NOVAS_GRS80_ELLIPSOID, and xyz().

## Member Function Documentation

## _on_surface()

const on_surface * supernovas::Site::_on_surface | ( |  | ) | const

Returns a pointer to the the NOVAS C on_surface data structure stored in this site data.

Returns
  The pointer to the NOVAS C on_surface data structure.

Since
  1.6

See also
  xyz()

Referenced by supernovas::Observer::Observer().

## altitude()

const Coordinate supernovas::Site::altitude | ( |  | ) | const

Returns a new distance containing the altitude of this site above the GRS80 reference ellipsoid (ie, above sea level).

Returns
  The altitude above sea level (GRS80 reference ellipsoid).

Since
  1.6

See also
  longitude(), latitude()

References supernovas::Validating::is_valid(), and supernovas::Unit::m.

Referenced by Site(), Site(), from_GPS(), from_GPS(), and from_GPS().

## enu_to_itrs() [1/2]

Position supernovas::Site::enu_to_itrs | ( | const Position & | p | ) | const

Converts an East-Noth-Up (ENU) position vector at the site to an ITRF vector.

Parameters

  p | position vector in East-North-Up (ENU) directions at the site.

Returns
  the same position vector in ITRF.

Since
  1.6

See also
  itrf_to_enu()

References supernovas::Vector::_array(), supernovas::Validating::is_valid(), and novas_enu_to_itrs().

## enu_to_itrs() [2/2]

Velocity supernovas::Site::enu_to_itrs | ( | const Velocity & | v | ) | const

Converts an East-Noth-Up (ENU) velocity vector at the site to an ITRF vector.

Parameters

  v | velocity vector in East-North-Up (ENU) directions at the site.

Returns
  the same position vector in ITRF.

Since
  1.6

See also
  itrf_to_enu()

References supernovas::Vector::_array(), supernovas::Validating::is_valid(), and novas_enu_to_itrs().

## equals() [1/2]

bool supernovas::Site::equals | ( | const Site & | site,
|  | const Coordinate & | tol ) const

Checks if this site is the same as another site, within the specified precision.

Parameters

  site | another site
  tol | distance tolerance for equality (default: 1 mm).

Returns
  true if the two sites are equal within the tolerance, or else false.

Since
  1.6

See also
  operator==()

References equals(), and supernovas::Coordinate::m().

## equals() [2/2]

bool supernovas::Site::equals | ( | const Site & | site,
|  | double | tol_m = 1e-3 ) const

Checks if this site is the same as another site, within the specified precision.

Parameters

  site | another site
  tol_m | [m] distance tolerance for equality (default: 1 mm).

Returns
  true if the two sites are equal within the tolerance, or else false.

Since
  1.6

See also
  operator==()

References supernovas::Position::equals(), and xyz().

Referenced by equals(), and operator==().

## from_GPS() [1/3]

Site supernovas::Site::from_GPS | ( | const Angle & | longitude,
|  | const Angle & | latitude,
|  | const Coordinate & | altitude = Coordinate::zero() )

static

Returns an observing site for its geodetic GPS location.

Parameters

  longitude | GPS longitude angle (East positive)
  latitude | GPS latitude angle
  altitude | (optional) GPS altitude (default: 0 m)

Returns
  a new observing site at the specified GSP location.

Since
  1.6

See also
  Site(), from_xyz()

References altitude(), from_GPS(), latitude(), and longitude().

## from_GPS() [2/3]

Site supernovas::Site::from_GPS | ( | const std::string & | longitude,
|  | const std::string & | latitude,
|  | const Coordinate & | altitude = Coordinate::zero() )

static

Returns an observing site for its geodetic GPS location, with the longitude and latitude provided in decimal or DMS string representations.

Parameters

  longitude | string representation of GPS longitude as DSM or decimal degrees.
  latitude | string representation of GPS latitude as DSM or decimal degrees.
  altitude | (optional) GPS altitude (default: 0 m)

Returns
  a new observing site at the specified GSP location.

Since
  1.6

See also
  Site(), from_xyz(), Angle()

References altitude(), from_GPS(), latitude(), and longitude().

## from_GPS() [3/3]

Site supernovas::Site::from_GPS | ( | double | longitude,
|  | double | latitude,
|  | double | altitude = 0.0 )

static

Returns an observing site for its geodetic GPS location.

Parameters

  longitude | [rad] GPS longitude (East positive)
  latitude | [rad] GPS latitude
  altitude | [m] (optional) GPS altitude (default: 0 m)

Returns
  a new observing site at the specified GSP location.

Since
  1.6

See also
  Site(), from_xyz()

References altitude(), supernovas::Validating::is_valid(), latitude(), longitude(), and NOVAS_WGS84_ELLIPSOID.

Referenced by from_GPS(), and from_GPS().

## itrf_transformed()

Site supernovas::Site::itrf_transformed | ( | int | from_year,
|  | int | to_year ) const

Returns a new site transformed into a different ITRF realization.

The ITRF realizations are defined by a year. While it is best practice to use years with actual ITRF realizations, any year will be interpreted as to pick the last ITRF realization preceding it (or in case of years before thefirst ITRF realization, the initial ITR realizatio will be used).

Parameters

  from_year | [yr] The original ITRF realization year of this site, e.g. 2008.
  to_year | [yr] The ITRF realization year of the returned new Site, e.g. 2014.

Returns
  a new observing site after transforming between ITRF realizations.

Since
  1.6

See also
  EOP::itrf_transformed()

References supernovas::Unit::deg, novas_on_surface::height, supernovas::Validating::is_valid(), novas_on_surface::latitude, novas_on_surface::longitude, supernovas::Unit::m, and novas_itrf_transform_site().

## itrs_to_enu() [1/2]

Position supernovas::Site::itrs_to_enu | ( | const Position & | p | ) | const

Converts an ITRF position vector to a local East-Noth-Up (ENU) vector at the site.

Parameters

  p | xyz position vector in ITRF.

Returns
  the same vector in East-North-Up (ENU) directions at the site.

Since
  1.6

See also
  enu_to_itrf()

References supernovas::Vector::_array(), supernovas::Validating::is_valid(), and novas_itrs_to_enu().

## itrs_to_enu() [2/2]

Velocity supernovas::Site::itrs_to_enu | ( | const Velocity & | v | ) | const

Converts an ITRF velocity vector to a local East-Noth-Up (ENU) vector at the site.

Parameters

  v | xyz velocity vector in ITRF.

Returns
  the same vector in East-North-Up (ENU) directions at the site.

Since
  1.6

See also
  enu_to_itrf()

References supernovas::Vector::_array(), supernovas::Validating::is_valid(), and novas_itrs_to_enu().

## latitude()

const Angle supernovas::Site::latitude | ( |  | ) | const

Returns a new angle containing the geodetic latitude of this site on the GRS80 reference ellipsoid.

Returns
  The geodetic longitude on the GRS80 reference ellipsoid.

Since
  1.6

See also
  longitude(), altitude()

References supernovas::Unit::deg, and supernovas::Validating::is_valid().

Referenced by Site(), Site(), from_GPS(), from_GPS(), and from_GPS().

## longitude()

const Angle supernovas::Site::longitude | ( |  | ) | const

Returns a new angle containing the geodetic longitude of this site on the GRS80 reference ellipsoid.

Returns
  The geodetic longitude on the GRS80 reference ellipsoid.

Since
  1.6

See also
  latitude(), altitude()

References supernovas::Unit::deg, and supernovas::Validating::is_valid().

Referenced by Site(), Site(), from_GPS(), from_GPS(), from_GPS(), and supernovas::Time::lst().

## operator!=()

bool supernovas::Site::operator!= | ( | const Site & | site | ) | const

Checks if this site differs from another site, by more than 1 mm.

Parameters

  site | another site

Returns
  true if the two sites differ by more than 1 mm, or else false.

Since
  1.6

See also
  operator==()

## operator==()

bool supernovas::Site::operator== | ( | const Site & | site | ) | const

Checks if this site is the same as another site, within 1 mm.

Parameters

  site | another site

Returns
  true if the two sites are equal within 1 mm, or else false.

Since
  1.6

See also
  equals(), operator!=()

References equals().

## to_observer()

GeodeticObserver supernovas::Site::to_observer | ( | const EOP & | eop = EOP::undefined() | ) | const

Returns an observer location for this observing site and the specified IERS Earth Orientation Parameters (EOP).

Parameters

  eop | (optional) Earth Orientation Parameters (EOP) from IERS, for the same ITRF realization as this site (if μas precision is required), or EOP::undefined() to fetch current (presently ITRF2020) values from IERS if possible and allowed (default: undefined).

Returns
  A geodetic observer location for this site.

Since
  1.6

See also
  Observer::on_earth(), novas_set_auto_fetch_eop()

References supernovas::Validating::is_valid(), and supernovas::Observer::on_earth().

## to_string()

std::string supernovas::Site::to_string | ( | enum novas_separator_type | separator = NOVAS_SEP_UNITS_AND_SPACES,
|  | int | decimals = 3 ) const

Returns a string representation of this observing site.

Parameters

  separator | (optional) the separator to use for the representation of angles (default: NOVAS_SEP_UNITS_AND_SPACES).
  decimals | (optional) the number of decimal places to print (default: 3).

Returns
  a new string representation of this observing site.

Since
  1.6

References supernovas::Unit::deg, and supernovas::Angle::to_string().

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

## undefined()

const Site & supernovas::Site::undefined | ( |  | ) |

static

Returns a reference to a statically allocated undefined observing site instance.

Returns
  a static reference to an undefined observing site.

Since
  1.6

## xyz()

Position supernovas::Site::xyz | ( |  | ) | const

Returns the geocentric position of this site in ITRS rectangular coordinates.

Returns
  a new position with the geocentric rectangular coordinates of the site.

Since
  1.6

References supernovas::Validating::is_valid(), novas_geodetic_to_cartesian(), and NOVAS_GRS80_ELLIPSOID.

Referenced by Site(), and equals().