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

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

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

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

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

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

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