Loading...
Searching...
No Matches
frames.c File Reference

High-level and efficient astrometric calculations using observing frames. More...

## Functions

int | novas_app_to_geom (const novas_frame *restrict frame, enum novas_reference_system sys, double ra, double dec, double dist, double *restrict geom_icrs)
| Converts an observed apparent sky position of a source to an ICRS geometric position, by undoing the gravitational deflection and aberration corrections.
int | novas_app_to_hor (const novas_frame *restrict frame, enum novas_reference_system sys, double ra, double dec, RefractionModel ref_model, double *restrict az, double *restrict el)
| Converts an observed apparent position vector in the specified coordinate system to local horizontal coordinates in the specified observer frame.
int | novas_change_observer (const novas_frame *orig, const observer *obs, novas_frame *out)
| Change the observer location for an observing frame.
int | novas_equ_track (const object *restrict source, const novas_frame *restrict frame, double dt, novas_track *restrict track)
| Calculates equatorial tracking position and motion (first and second time derivatives) for the specified source in the given observing frame.
double | novas_frame_lst (const novas_frame *restrict frame)
| Returns the Local (apparent) Sidereal Time for an observing frame of an Earth-bound observer.
int | novas_geom_posvel (const object *restrict source, const novas_frame *restrict frame, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
| Calculates the geometric position and velocity vectors, relative to the observer, for a source in the given observing frame, in the specified coordinate system of choice.
int | novas_geom_to_app (const novas_frame *restrict frame, const double *restrict pos, enum novas_reference_system sys, sky_pos *restrict out)
| Converts an geometric position in ICRS to an apparent position on sky, by applying appropriate corrections for aberration and gravitational deflection for the observer's frame.
int | novas_hor_to_app (const novas_frame *restrict frame, double az, double el, RefractionModel ref_model, enum novas_reference_system sys, double *restrict ra, double *restrict dec)
| Converts an observed azimuth and elevation coordinate to right ascension (R.A.) and declination coordinates expressed in the coordinate system of choice.
int | novas_hor_track (const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model, novas_track *restrict track)
| Calculates horizontal tracking position and motion (first and second time derivatives) for the specified source in the given 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.
double | novas_moon_angle (const object *restrict source, const novas_frame *restrict frame)
| Returns the apparent angular distance of a source from the Moon from the observer's point of view.
double | novas_object_sep (const object *source1, const object *source2, const novas_frame *restrict frame)
| Returns the angular separation of two objects from the observer's point of view.
double | novas_rises_above (double el, const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model)
| Returns the UTC date at which a distant source appears to rise above the specified elevation angle.
double | novas_sets_below (double el, const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model)
| Returns the UTC date at which a distant source appears to set below the specified elevation angle.
int | novas_sky_pos (const object *restrict object, const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict out)
| Calculates an apparent location on sky for the source.
double | novas_solar_illum (const object *restrict source, const novas_frame *restrict frame)
| Returns the Solar illumination fraction of a source, assuming a spherical geometry for the observed body.
double | novas_sun_angle (const object *restrict source, const novas_frame *restrict frame)
| Returns the apparent angular distance of a source from the Sun from the observer's point of view.
int | novas_track_pos (const novas_track *track, const novas_timespec *time, double *restrict lon, double *restrict lat, double *restrict dist, double *restrict z)
| Calculates a projected position, distance, and redshift for a source, given its near-term trajectory on sky, in the system for which the track was calculated.
int | novas_transform_sky_pos (const sky_pos *in, const novas_transform *restrict transform, sky_pos *out)
| Transforms a position or velocity 3-vector from one coordinate reference system to another.
int | novas_transform_vector (const double *in, const novas_transform *restrict transform, double *out)
| Transforms a position or velocity 3-vector from one coordinate reference system to another.
double | novas_transit_time (const object *restrict source, const novas_frame *restrict frame)
| Returns the UTC date at which a source transits the local meridian.

## Detailed Description

High-level and efficient astrometric calculations using observing frames.

An observing frame represents an observer location at a specific astronomical time (instant), which can be re-used again and again to calculate or transform positions of celestial sources in a a range of astronomical coordinate systems.

To use frames, you start with novas_make_frame() with an astrometric time and an observer location, and optionally Earth-orientation parameters if precision below the arcsecond level is needed. E.g.:

observer obs; // observer location
novas_timespec time; // astrometric time
novas_frame frame; // observing frame
// Specify an observer, with GPS coordinates
make_gps_observer(gps_lat, gps_lon, gps_alt, &obs);
// Specify time, e.g. current time with leap seconds and UT1-UTC time difference:
novas_set_current_time(leap_seconds, dut1, &time);
// Set up a frame with the desired accuracy and Earth orientation parameters xp, yp.
novas_make_frame(NOVAS_REDUCED_ACCURACY, &obs, &time, xp, yp, &frame);
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 require...
Definition frames.c:519
NOVAS_REDUCED_ACCURACY
@ NOVAS_REDUCED_ACCURACY
Calculate with truncated terms.
Definition novas.h:859
make_gps_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 loc...
Definition observer.c:282
novas_set_current_time
int novas_set_current_time(int leap, double dut1, novas_timespec *restrict time)
Sets the time eith the UNIX time obtained from the system clock.
Definition timescale.c:913
novas_frame
A set of parameters that uniquely define the place and time of observation.
Definition novas.h:1768
novas_timespec
A structure, which defines a precise instant of time that can be extpressed in any of the astronomica...
Definition novas.h:1672
observer
Observer location.
Definition novas.h:1560

Once a frame is defined, you can perform various astrometric calculation within it efficiently. For example, calculate apparent positions, in the coordinate system of choice, to predict where objects would be seen by the observer:

object source = ...; // observed source
sky_pos app; // apparent position to calculate.
// Calculate True-of-Date apparent coordinates for a source.
novas_sky_pos(&source, &frame, NOVAS_TOD, &app);
novas_sky_pos
int novas_sky_pos(const object *restrict object, const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict out)
Calculates an apparent location on sky for the source.
Definition frames.c:832
NOVAS_TOD
@ NOVAS_TOD
True equinox Of Date: dynamical system of the 'true' equator, with its origin at the 'true' equinox (...
Definition novas.h:759
sky_pos
Celestial object's place on the sky; contains the output from place().
Definition novas.h:1591

If your observer was defined on Earth (ground-based or airborne), you might continue to calculate Az/El positions using novas_app_to_hor(), or you might just want to know the same position in another reference system also:

novas_transform T; // Transformation between reference systems
sky_pos tirs; // calculated apparent position in TIRS
// Transform from True-of-Date to TIRS coordinates
novas_make_transform(&frame, NOVAS_TOD, NOVAS_TIRS, &T);
// Transform the above position to TIRS...
novas_transform_sky_pos(&app, T, &tirs);
novas_transform_sky_pos
int novas_transform_sky_pos(const sky_pos *in, const novas_transform *restrict transform, sky_pos *out)
Transforms a position or velocity 3-vector from one coordinate reference system to another.
Definition frames.c:1460
NOVAS_TIRS
@ NOVAS_TIRS
Terrestrial Intermediate Reference System.
Definition novas.h:783
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 coor...
Definition frames.c:1257
novas_transform
A transformation between two astronomical coordinate systems for the same observer location and time.
Definition novas.h:1829

Or, you can calculate geometric positions, which are not corrected for aberration or gravitational deflection (but still corrected for light travel time in case of Solar-system sources):

object source = ...; // observed source
double pos[3], vel[3]; // geometric position and velocity vectors to calculate.
// Calculate geometric positions / velocities, say in ICRS
novas_geom_posvel(&source, &frame, NOVAS_ICRS, pos, vel);
NOVAS_ICRS
@ NOVAS_ICRS
International Celestial Reference system.
Definition novas.h:767
novas_geom_posvel
int novas_geom_posvel(const object *restrict source, const novas_frame *restrict frame, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
Calculates the geometric position and velocity vectors, relative to the observer, for a source in the...
Definition frames.c:717

You can also transform geometric positions / velocities to other reference frames using the same novas_transform as above.

Or, perhaps you are interested when the source will rise (or transit, or set) next, for a ground-based or airborne observer:

object source = ...; // observed source
// UTC-based Julian date when source rises above 20 degrees given a refraction model.
double jd_rise = novas_rises_above(20.0, &source, &frame, novas_standard_refraction);
novas_standard_refraction
double novas_standard_refraction(double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
Returns an optical refraction correction for a standard atmosphere.
Definition refract.c:263
novas_rises_above
double novas_rises_above(double el, const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model)
Returns the UTC date at which a distant source appears to rise above the specified elevation angle.
Definition frames.c:1677

Or, you might simply want to know how far your source is from the Sun or Moon (or another source) on the sky:

object source = ...; // observed source
// Calculate the angular distance, in degrees, of the source from the Sun.
double angle_deg = novas_sun_angle(&source, &frame);
novas_sun_angle
double novas_sun_angle(const object *restrict source, const novas_frame *restrict frame)
Returns the apparent angular distance of a source from the Sun from the observer's point of view.
Definition frames.c:1846

These are just some of the common use-case scenarios. There is even more possibilities with frames...

Date
  Created on Jun 23, 2024

Author
  Attila Kovacs

Since
  1.1

See also
  timescale.c, observer.c, target.c, ephemeris.c