Loading...
Searching...
No Matches
Observing frame

Observing frames are a combination of an observer place, and a specific time of observation. More...

## Classes

struct | novas_frame
| A set of parameters that uniquely define the place and time of observation. More...
struct | novas_matrix
| A 3x3 matrix for coordinate transformations. More...
struct | novas_transform
| A transformation between two astronomical coordinate systems for the same observer location and time. More...

## Macros

#define | NOVAS_FRAME_INIT
| Empty initializer for novas_frame.
#define | NOVAS_TRANSFORM_INIT
| Empty initializer for NOVAS_TRANSFORM.

## Typedefs

typedef struct novas_frame | novas_frame
| A set of parameters that uniquely define the place and time of observation.
typedef struct novas_matrix | novas_matrix
| A 3x3 matrix for coordinate transformations.
typedef struct novas_transform | novas_transform
| A transformation between two astronomical coordinate systems for the same observer location and time.

## Enumerations

enum | novas_accuracy { NOVAS_FULL_ACCURACY = 0 , NOVAS_REDUCED_ACCURACY }
| Constants to control the precision of NOVAS nutation calculations. More...

## Functions

int | novas_change_observer (const novas_frame *orig, const observer *obs, novas_frame *out)
| Change the observer location for an observing frame.
int | novas_equals_frame (const novas_frame *a, const novas_frame *b)
| Checks if two observing frames are essentially the same, within typical tolerances.
int | novas_invert_transform (const novas_transform *transform, novas_transform *inverse)
| Inverts a novas coordinate transformation matrix.
int | novas_make_frame (enum novas_accuracy accuracy, const observer *obs, const novas_timespec *time, double xp, double yp, novas_frame *frame)
| Sets up a observing frame for a specific observer location, time of observation, and accuracy requirement.
int | novas_make_transform (const novas_frame *frame, enum novas_reference_system from_system, enum novas_reference_system to_system, novas_transform *transform)
| Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.

## Detailed Description

Observing frames are a combination of an observer place, and a specific time of observation.

SuperNOVAS observing frames are not to be confused with coordinate reference frames, even if the two do have aspects in common. Both are referenced to an observer location and a specific time of observation. But, a coordinate reference frame (such as ICRF) also implies a particular choice of a coordinate system, whereas a SuperNOVAS observing frame does not.

The power of observing frames is that they make it easy to express locations on the celestial sphere in any coordinate system, and allow to convert apparent places and geometric coordinates between different coordinate systems with superior efficiency.

## Macro Definition Documentation

## NOVAS_FRAME_INIT

#define NOVAS_FRAME_INIT

Empty initializer for novas_frame.

Since
  1.3

See also
  novas_frame

## NOVAS_TRANSFORM_INIT

#define NOVAS_TRANSFORM_INIT

Empty initializer for NOVAS_TRANSFORM.

Since
  1.3

See also
  novas_transform

## Typedef Documentation

## novas_frame

typedef struct novas_frame novas_frame

A set of parameters that uniquely define the place and time of observation.

The user may initialize the frame with novas_make_frame(). Once the observer frame is set up, it can be used repeatedly to perform efficient calculations of multiple objects in the coordinate system of choice, much faster than what place() can do. Frames also allow for transforming coordinates calculated for one coordinate syste, into another coordinate system with little effort.

You should never set or change fields in this structure manually. Instead the structure should always be initialized by an appropriate call to novas_make_frame(). After that you may change the observer location, if need be, with novas_change_observer().

The structure may expand with additional field in the future. Thus neither its size nor its particular layout should be assumed fixed over SuperNOVAS releases.

Since
  1.1

See also
  novas_make_frame(), novas_change_observer(), novas_make_transform(), NOVAS_FRAME_INIT
  novas_sky_pos(), novas_geom_posvel(), novas_geom_to_app(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), novas_rises_above(), novas_sets_below(), novas_transit_time()

## novas_matrix

typedef struct novas_matrix novas_matrix

A 3x3 matrix for coordinate transformations.

Since
  1.1

See also
  novas_transform, NOVAS_MATRIX_INIT, NOVAS_MATRIX_IDENTITY

## novas_transform

typedef struct novas_transform novas_transform

A transformation between two astronomical coordinate systems for the same observer location and time.

This allows for more elegant, generic, and efficient coordinate transformations than the low-level NOVAS functions.

The transformation can be (should be) initialized via novas_make_transform(), or via novas_invert_transform().

Since
  1.1

See also
  novas_make_transform(), novas_invert_transform(), NOVAS_TRANSFORM_INIT
  novas_transform_vector(), novas_transform_sky_pos()

## Enumeration Type Documentation

## novas_accuracy

enum novas_accuracy

Constants to control the precision of NOVAS nutation calculations.

See also
  novas_make_frame()

Enumerator
NOVAS_FULL_ACCURACY | Use full precision calculations to micro-arcsecond accuracy. It can be computationally intensive when using the dynamical equator.
NOVAS_REDUCED_ACCURACY | Calculate with truncated terms. It can be significantly faster if a few milliarcsecond accuracy is sufficient.

## Function Documentation

## novas_change_observer()

int novas_change_observer | ( | const novas_frame * | orig,
|  | const observer * | obs,
|  | novas_frame * | out )

Change the observer location for an observing frame.

Parameters

  | orig | Pointer to original observing frame
  | obs | New observer location
  [out] | out | Observing frame to populate with a original frame data and new observer location. It can be the same as the input.

Returns
  0 if successful or else an error code from geo_posvel() (errno will also indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_make_frame()

References grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_TDB, obs_planets(), and out.

Referenced by novas_make_frame().

## novas_equals_frame()

int novas_equals_frame | ( | const novas_frame * | a,
|  | const novas_frame * | b )

Checks if two observing frames are essentially the same, within typical tolerances.

Two frames are considered equal, if they are both:

- initialized,
- represent the same accuracy,
- for the same observer,
- at the same time,
- same polar offsets (for geodetic observers or if defined),
- and contain the same planetary ephemeris data

all within the typical tolerances associated to these. For non-geodetic observers two frames are considered equal also if both have all NAN (undefined) polar offsets – since polar offsets are not generally required for non-geodetic observing frames.

NOTES:

- this function does not check the calculated fields of the observing frames, which are assumed to have been left untouched after the called to novas_make_frame(). If the user modifies the calculated fields, they may need additional checks to ensure 'equality' accordingly.
- Two NULL (undefined) observing frames are considered not equal.
- An observing frame may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | an observing frame
  b | another observing frame

Returns
  TRUE (1) if the two observing frames are effectively the same, given the tolerances, or else false.

Since
  1.7

Author
  Attila Kovacs

References novas_frame::accuracy, novas_frame::dx, novas_frame::dy, novas_equals_observer(), novas_equals_planet_bundle(), novas_equals_timespec(), novas_frame::observer, novas_frame::planets, and novas_frame::time.

## novas_invert_transform()

int novas_invert_transform | ( | const novas_transform * | transform,
|  | novas_transform * | inverse )

Inverts a novas coordinate transformation matrix.

Parameters

  | transform | Pointer to a coordinate transformation matrix.
  [out] | inverse | Pointer to a coordinate transformation matrix to populate with the inverse transform. It may be the same as the input.

Returns
  0 if successful, or else -1 if the was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_make_transform()

References novas_transform::matrix.

## novas_make_frame()

int novas_make_frame | ( | enum novas_accuracy | accuracy,
|  | const observer * | obs,
|  | const novas_timespec * | time,
|  | double | xp,
|  | double | yp,
|  | novas_frame * | frame )

Sets up a observing frame for a specific observer location, time of observation, and accuracy requirement.

The frame is initialized using the currently configured planet ephemeris provider function (see set_planet_provider() and set_planet_provider_hp()), and in case of reduced accuracy mode, the currently configured IAU nutation model provider (see set_nutation_lp_provider()).

Note, that to construct full accuracy frames, you will need a high-precision ephemeris provider for the major planets (not just the default Earth/Sun), as without it, gravitational bending around massive plannets cannot be accounted for, and therefore μas accuracy cannot be ensured, in general. Attempting to construct a high-accuracy frame without a high-precision ephemeris provider for the major planets will result in an error in the 10–40 range from the required ephemeris() call.

NOTES:

1. This function expects the Earth polar wobble parameters to be defined on a per-frame basis and will not use the legacy global (undated) orientation parameters set via cel_pole().
2. The Earth orientation parameters xp, yp should be provided in the same ITRF realization as the observer location for an Earth-based observer. You can use novas_itrf_transform_eop() to convert the EOP values as necessary.
3. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the polar offsets is not possible. You must set xp and yp appropriately explicitly.

Parameters

  | accuracy | Accuracy requirement, NOVAS_FULL_ACCURACY (0) for the utmost precision or NOVAS_REDUCED_ACCURACY (1) if ~1 mas accuracy is sufficient.
  | obs | Observer location
  | time | Time of observation
  | xp | [mas] Earth orientation parameter, mean polar offset in x, e.g. from the IERS Bulletins, without diurnal libration and ocean tides. (The global, undated, value set by cel_pole() is not not used here.) You can use 0.0 if sub-arcsecond accuracy is not required.
  | yp | [mas] Earth orientation parameter, mean polar offset in y, e.g. from the IERS Bulletins, without diurnal libration and ocean tides. (The global, undated, value set by cel_pole() is not not used here.) You can use 0.0 if sub-arcsecond accuracy is not required.
  [out] | frame | Pointer to the observing frame to configure.

Returns
  0 if successful, 10–40: error is 10 + the error from ephemeris(), 40–50: error is 40 + the error from geo_posvel(), or else -1 if there was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_change_observer(), novas_sky_pos(), novas_geom_posvel(), novas_make_transform()
  set_planet_provider(), set_planet_provider_hp(), set_nutation_lp_provider(), novas_itrf_transform_eop(), novas_set_auto_fetch_eop()

References novas_frame::accuracy, novas_frame::deps0, novas_frame::dpsi0, novas_frame::dx, novas_frame::dy, novas_frame::earth_pos, novas_frame::earth_vel, novas_frame::ee, ephemeris(), era(), novas_frame::era, novas_timespec::fjd_tt, novas_frame::gst, novas_timespec::ijd_tt, mean_obliq(), novas_frame::mobl, NOVAS_BARYCENTER, novas_change_observer(), novas_diurnal_eop_at_time(), NOVAS_EARTH_INIT, novas_fetch_eop(), NOVAS_FULL_ACCURACY, novas_get_split_time(), novas_get_time(), novas_is_auto_fetch_eop(), NOVAS_JD_J2000, NOVAS_OBSERVER_PLACES, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_UT1, NOVAS_UTC, nutation_angles(), novas_frame::state, novas_frame::sun_pos, novas_frame::sun_vel, novas_frame::time, novas_frame::tobl, novas_timespec::tt2tdb, novas_observer::where, novas_eop::xp, and novas_eop::yp.

Referenced by novas_equ_track(), and novas_hor_track().

## novas_make_transform()

int novas_make_transform | ( | const novas_frame * | frame,
|  | enum novas_reference_system | from_system,
|  | enum novas_reference_system | to_system,
|  | novas_transform * | transform )

Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.

Parameters

  | frame | Observer frame, defining the location and time of observation
  | from_system | Original coordinate reference system
  | to_system | New coordinate reference system
  [out] | transform | Pointer to the transform data structure to populate.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_transform_vector(), novas_transform_sky_pos(), novas_invert_transform()
  novas_geom_posvel(), novas_app_to_geom()

References novas_frame::era, novas_transform::frame, novas_transform::from_system, novas_frame::gcrs_to_cirs, novas_frame::icrs_to_j2000, novas_matrix::M, novas_transform::matrix, NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REFERENCE_SYSTEMS, NOVAS_TIRS, NOVAS_TOD, novas_frame::nutation, novas_frame::precession, and novas_transform::to_system.

Referenced by novas_moon_elp_posvel_fp(), and novas_moon_elp_sky_pos_fp().