Loading...
Searching...
No Matches
Observing frames

## Data Structures

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...
struct | sky_pos
| Celestial object's place on the sky; contains the output from place(). More...

## Macros

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

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

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

## 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 successfule or else an 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 novas_frame::accuracy, grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_TDB, obs_planets(), novas_frame::obs_pos, novas_frame::observer, novas_frame::planets, novas_frame::state, 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.

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

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_FULL_ACCURACY, novas_get_split_time(), NOVAS_JD_J2000, NOVAS_OBSERVER_PLACES, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_UT1, nutation_angles(), novas_frame::state, novas_frame::sun_pos, novas_frame::sun_vel, novas_frame::time, novas_frame::tobl, novas_timespec::tt2tdb, and observer::where.

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