Loading...
Searching...
No Matches
supernovas::Frame Class Reference
Observing frame

An observing frame, defined by an observer location and precise time of observation. More...

`#include <supernovas.h>`

Inheritance diagram for supernovas::Frame:

## Public Member Functions

| Frame (const Frame &frame)
| Custom copy constructor, that points to a copy of the observer.
| Frame (const Observer &obs, const Time &time, enum novas_accuracy accuracy=NOVAS_FULL_ACCURACY, const EOP &eop=EOP::undefined())
| Instantiates a new observer frame, given the observer location and time of observation, and optionally the required accuracy.
| ~Frame ()
const novas_frame * | _novas_frame () const
| Returns the pointer to the underlying C data structure of this observing frame.
enum novas_accuracy | accuracy () const
| Returns the accuracy type of this observing frame.
Apparent | apparent_moon_elp2000 (double limit_term=0.0) const
| Returns the Moon's apparent position using the ELP/MPP02 model by Chapront & Francou (2003) down to the specified limiting term amplitude.
double | clock_skew (enum novas_timescale=NOVAS_TT) const
| Returns the instantaneous incremental rate at which the observer's clock (i.e.
const EOP | eop () const
| Returns the Earth Orientation Parameters contained in this frame.
bool | equals (const Frame &other) const
| Checks if this observing frame is essentially the same as another, given typical tolerances.
Geometric | geometric (const Position &p, const Velocity &v, enum novas_reference_system system=NOVAS_TOD) const
| Returns new geometric coordinates, relative to the observer in this frame, in the equatorial coordinate reference system of choice.
Geometric | geometric_moon_elp2000 (double limit_term=0.0) const
| Returns the Moon's geometric position using the ELP/MPP02 model by Chapront & Francou (2003), down to the specified limiting term amplitude.
double | jd (enum novas_timescale=NOVAS_TT) const
| Returns the precise Julian Date of this observing frame, in the specific timescale of choice.
const Observer & | observer () const
| Returns the observer location (and motion) of this observing frame.
Position | observer_ssb_position () const
| Returns the observer's ICRS position relative to the Solar System Barycenter (SSB).
Velocity | observer_ssb_velocity () const
| Returns the observer's ICRS velocity relative to the Solar System Barycenter (SSB).
bool | operator!= (const Frame &other) const
| Checks if this observing frame differs from another, given typical tolerances.
Frame & | operator= (const Frame &frame)
| Custom copy-assignment operator, which updates the observer pointer to a copy of the original frame's observer.
bool | operator== (const Frame &other) const
| Checks if this observing frame is essentially the same as another, given typical tolerances.
const Time & | time () const
| Returns the astrometric time of observation of this observing frame.
std::string | to_string () const
| Returns a human-readable string representation of this observing frame.
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 Frame | reduced_accuracy (const Observer &obs, const Time &time, const EOP &eop=EOP::undefined())
| Returns a reduced accuracy observing frame for the specified observer at the specified time.
static const Frame & | undefined ()
| Returns a reference to a statically defined standard invalid observing frame.

## 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 observing frame, defined by an observer location and precise time of observation.

Frames can be created with full (default) and reduced accuracy, supporting calculations with mas, or μas precisions typically. However, note that full accuracy frames require SuperNOVAS to be configured with an appropriate high-precision planet ephemeris provider (see Solar-system ephemeris providers), or else the resulting full-accuracy frame will be invalid.

Reduced accuracy frames may also be invalid if the low precision planet ephemeris provider ( which, by default, calculates approximate positions for the Earth and Sun only) cannot provide position for the Earth, Sun, or the observer.

Therefore, one is strongly advised to check the validity of an observing frame after instantiation (using the is_valid() method).

Since
  1.6

See also
  Source, Solar-system ephemeris providers

## Constructor & Destructor Documentation

## Frame() [1/2]

supernovas::Frame::Frame | ( | const Observer & | obs,
|  | const Time & | time,
|  | enum novas_accuracy | accuracy = NOVAS_FULL_ACCURACY,
|  | const EOP & | eop = EOP::undefined() )

Instantiates a new observer frame, given the observer location and time of observation, and optionally the required accuracy.

After the new frame is returned you should check that it's valid:

Frame f = Frame(obs, time);
if(!f.is_valid()) {
// This did not work as expected...
...
}
supernovas::Frame::time
const Time & time() const
Returns the astrometric time of observation of this observing frame.
Definition Frame.cpp:232
supernovas::Validating::is_valid
bool is_valid() const
Returns the previously set 'valid' state of the implementing instance.
Definition supernovas.h:278

The returned new frame may be invalid for multiple reasons, such as:

- the input observer or time is invalid.
- the accuracy parameter is outside of the enum range.
- SuperNOVAS had no suitable planet provider function for the given accuracy. (By default SuperNOVAS has only a reduced accuracy Earth-Sun calculator configured.)
- The currently configured planet provider function, for the given accuracy, cannot provide positions and velocities for the Earth, Sun, observer location, or one of the major planets configured for gravitational deflection calculations.

In either case, you can obtain more information on why things went wrong, when they do, by enabling debug mode is enabled via novas_debug() prior to constructing a Frame.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of EOP is not possible. You must define a valid EOP explicitly.

Parameters

  obs | observer location
  time | time of observation
  accuracy | (optional) NOVAS_FULL_ACCURACY (default) or NOVAS_REDUCED_ACCURACY.

  eop

  (optional) Earth Orientation Parameters (polar offsets) to assume for non geodetic observers. Typically, an observer that is not referenced to Earth's surface should not need EOP. However, the user may supply the polar offsets xp, yp here to use in the unlikely case they want to transform geometric positions for a space-based observer to/from the Earth-fixed ITRS with sub-arcsecond level accuracy (since 1.7).

Since
  1.6

See also
  Observer::frame_at(), reduced_accuracy(), Solar-system ephemeris providers
  novas_set_auto_fetch_eop()

References supernovas::Observer::_novas_observer(), supernovas::Validating::_valid, accuracy(), eop(), supernovas::Observer::is_geodetic(), supernovas::Validating::is_valid(), novas_make_frame(), and time().

## Frame() [2/2]

supernovas::Frame::Frame | ( | const Frame & | frame | ) |

Custom copy constructor, that points to a copy of the observer.

Parameters

  frame | the frame to be copied.

Since
  1.6

References supernovas::Validating::Validating(), and time().

## ~Frame()

supernovas::Frame::~Frame | ( |  | ) |

inline

## Member Function Documentation

## _novas_frame()

const novas_frame * supernovas::Frame::_novas_frame | ( |  | ) | const

Returns the pointer to the underlying C data structure of this observing frame.

Returns
  pointer to the underlying C data structure.

Since
  1.6

Referenced by supernovas::Source::angle_to(), supernovas::Source::apparent_in(), apparent_moon_elp2000(), supernovas::Planet::approx_apparent_in(), supernovas::Planet::approx_geometric_in(), supernovas::Source::equatorial_track(), supernovas::Source::geometric_in(), geometric_moon_elp2000(), supernovas::Source::horizontal_track(), supernovas::Source::moon_angle(), observer_ssb_position(), observer_ssb_velocity(), supernovas::Source::rises_above(), supernovas::Source::sets_below(), supernovas::SolarSystemSource::solar_illumination(), supernovas::Source::sun_angle(), supernovas::Horizontal::to_apparent(), and supernovas::Source::transits_in().

## accuracy()

enum novas_accuracy supernovas::Frame::accuracy | ( |  | ) | const

Returns the accuracy type of this observing frame.

Returns
  NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).

Since
  1.6

Referenced by Frame(), and supernovas::Observer::to_interferometric().

## clock_skew()

double supernovas::Frame::clock_skew | ( | enum novas_timescale | timescale = NOVAS_TT | ) | const

Returns the instantaneous incremental rate at which the observer's clock (i.e.

proper time τ) ticks faster than a clock in the specified timescale in this observing frame. I.e., it returns D, which is defined by:

dτobs / dttimescale = (1 + D)

The instantaneous difference in clock rate includes tiny diurnal or orbital variations for Earth-bound observers as the they cycle through the tidal potential around the geocenter (mainly due to the Sun and Moon). For a closer match to Earth-based timescales (TCG, TT, TAI, GPS, or UTC) you may want to exclude the periodic tidal effects and calculate the averaged observer clock rate over the geocentric cycle (see Eqs. 10.6 and 10.8 of the IERS Conventions 2010), which is provided by novas_mean_clock_skew() instead.

For reduced accuracy frames, the result will be approximate, because the gravitational effect of the Sun and Earth alone may be accounted for.

NOTES:

1. Based on the IERS Conventions 2010, Chapter 10, Eqs. 10.6 / 10.8 but also including the near-Earth tidal effects, and modified for relativistic observer motion.
2. The potential for an observer inside 0.9 planet radii of a major Solar-system body's center will not include the term for that body in the calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 10, see at https://iers-conventions.obspm.fr/content/chapter10/tn36_c10.pdf

Parameters

  timescale | Reference timescale for the comparison. All timescales except NOVAS_UT1 are supported. (UT1 advances at an irregular rate).

Returns
  The incremental rate at which the observer's proper time clock ticks faster than the specified timescale, or else NAN if the input frame is NULL or uninitialized, or if the timescale is not supported (errno set to EINVAL), or if the frame is configured for full accuracy but it does not have sufficient planet position information to evaluate the local gravitational potential with precision (errno set to EAGAIN).

Since
  1.6

See also
  novas_clock_skew(), Time::timescale_offset()

References novas_clock_skew(), and NOVAS_TIMESCALES.

## eop()

const EOP supernovas::Frame::eop | ( |  | ) | const

Returns the Earth Orientation Parameters contained in this frame.

The returned parameters include diurnal variations for libration and ocean tides, and are valid only if this frame was defined for a geodetic observer location such as an observer at a fixed site on Earth or an airborne observer location.

Returns
  The Earth orientation parameters of this observing frame, including diurnal variations for libration and ocean tides; or else an undefined (invalid) EOP if the observer is not on or near Earth's surface.

Since
  1.6

See also
  GeodeticObserver

References eop(), supernovas::Unit::mas, and novas_time_leap().

Referenced by Frame(), eop(), reduced_accuracy(), supernovas::Source::rises_above(), supernovas::Source::sets_below(), and supernovas::Source::transits_in().

## equals()

bool supernovas::Frame::equals | ( | const Frame & | other | ) | const

Checks if this observing frame is essentially the same as another, given typical tolerances.

See Observer::equals() and Time::equals() for details. Beyond the matching the observers and times, mathing frames must also match:

- accuracy setting
- polar offsets (for geodetic observers, or else if defined) to 1 μas.
- stored planet position and velocity data to 1 m and 1 mm/s, respectively.

Note, that an observing frame may not equal itself if it contains NAN or infinite components. The exception is polar offsets for non-geodetic observing frames, where NAN values are considered 'normal', and hence don't spoil the effective equality so long as both frames leave these undefined.

Parameters

  other | the other observing frame

Returns
  true if this frame and the argument describe essentially the same observing frame, within the typical tolerances.

Since
  1.7

See also
  operator==(), operator!=()

References novas_equals_frame().

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

## geometric()

Geometric supernovas::Frame::geometric | ( | const Position & | p,
|  | const Velocity & | v,
|  | enum novas_reference_system | system = NOVAS_TOD ) const

Returns new geometric coordinates, relative to the observer in this frame, in the equatorial coordinate reference system of choice.

Parameters

  p | equatorial position vector, with respect to the observer
  v | equatorial velocity vector, with respect to the observer
  system | equatorial coordinate reference_system, in which position and velocity vectors are defined

Since
  1.6

References supernovas::Validating::is_valid().

## jd()

double supernovas::Frame::jd | ( | enum novas_timescale | timescale = NOVAS_TT | ) | const

Returns the precise Julian Date of this observing frame, in the specific timescale of choice.

It is but a shorthand for time().jd(timescale).

Parameters

  timescale | (optional) the timescale in which to return the result (default: TT).

Returns
  [day] the precise Julian date in the requested timescale.

Since
  1.6

See also
  Time::jd(), time()

Referenced by supernovas::Planet::approx_geometric_in().

## observer()

const Observer & supernovas::Frame::observer | ( |  | ) | const

Returns the observer location (and motion) of this observing frame.

Returns
  the observer location (and motion).

Since
  1.6

See also
  time()

Referenced by supernovas::Source::horizontal_track(), and supernovas::Observer::to_interferometric().

## observer_ssb_position()

Position supernovas::Frame::observer_ssb_position | ( |  | ) | const

Returns the observer's ICRS position relative to the Solar System Barycenter (SSB).

Returns
  The Solar system barycentric position of the observer at the time of observation.

Since
  1.6

See also
  observer_ssb_velocity(), observer()

References _novas_frame(), supernovas::Unit::AU, supernovas::Validating::is_valid(), and supernovas::Position::undefined().

## observer_ssb_velocity()

Velocity supernovas::Frame::observer_ssb_velocity | ( |  | ) | const

Returns the observer's ICRS velocity relative to the Solar System Barycenter (SSB).

Returns
  The Solar system barycentric velocity of the observer at the time of observation.

Since
  1.6

See also
  observer_ssb_position(), observer()

References _novas_frame(), supernovas::Unit::AU_per_day, supernovas::Validating::is_valid(), and supernovas::Velocity::undefined().

## operator!=()

bool supernovas::Frame::operator!= | ( | const Frame & | other | ) | const

Checks if this observing frame differs from another, given typical tolerances.

Same as !equals().

Parameters

  other | the other observing frame

Returns
  true if this frame and the argument describe essentially the same observing frame, within the typical tolerances.

Since
  1.7

See also
  equals(), operator!=()

References equals().

## operator=()

Frame & supernovas::Frame::operator= | ( | const Frame & | frame | ) |

Custom copy-assignment operator, which updates the observer pointer to a copy of the original frame's observer.

Parameters

  frame | the frame to be copied.

Returns
  itself

Since
  1.6

References supernovas::Validating::_valid, and supernovas::Observer::copy().

## operator==()

bool supernovas::Frame::operator== | ( | const Frame & | other | ) | const

Checks if this observing frame is essentially the same as another, given typical tolerances.

Same as equals().

Parameters

  other | the other observing frame

Returns
  true if this frame and the argument describe essentially the same observing frame, within the typical tolerances.

Since
  1.7

See also
  equals(), operator!=()

References equals().

## reduced_accuracy()

Frame supernovas::Frame::reduced_accuracy | ( | const Observer & | obs,
|  | const Time & | time,
|  | const EOP & | eop = EOP::undefined() )

static

Returns a reduced accuracy observing frame for the specified observer at the specified time.

Reduced accuracy frames provide 1 mas accuracy typically, and do not require a planet provider to be configured. As such, they offer a simplest way for obtaining astrometric positions for catalog and orbital sources at the 1 mas level.

Note, that the returned frame may be invalid, if the this observer or the time argument themselves are invalid.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of EOP is not possible. You must define a valid EOP explicitly.

Parameters

  obs | Observer location
  time | Astrometric time of observation
  eop | (optional) Mean (preferably interpolated) Earth Orientation Parameters (EOP) appropriate around the time of observation, such as obtained from the IERS bulletins or data service, or EOP::undefined() to let Frame fetch polar offsets from IERS as needed (default: undefined).

Returns
  A reduced accuracy observing frame for the specified time of observation.

Since
  1.6

See also
  Observer::reduced_accuracy_frame_at()

References eop(), supernovas::Validating::is_valid(), NOVAS_REDUCED_ACCURACY, and time().

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

## time()

const Time & supernovas::Frame::time | ( |  | ) | const

Returns the astrometric time of observation of this observing frame.

Returns
  the astrometric time of observation

Since
  1.6

See also
  jd(), observer()

Referenced by Frame(), Frame(), supernovas::Source::equatorial_track(), reduced_accuracy(), and supernovas::Observer::to_interferometric().

## to_string()

std::string supernovas::Frame::to_string | ( |  | ) | const

Returns a human-readable string representation of this observing frame.

Returns
  a string representation of this observing frame.

Since
  1.6

References to_string().

Referenced by to_string().

## undefined()

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

static

Returns a reference to a statically defined standard invalid observing frame.

This invalid frame may be used inside any object that is invalid itself.

Returns
  a reference to a static standard invalid equatorial coordinates.

Since
  1.6