skyfast.h File Reference

skyfast.h - set up and use interpolation for rapid calculation of a celestial object's apparent coordinates. More...

Go to the source code of this file.

Functions
void	skyfast_init (double tStartUtc_d, int fullRecalcInterval_mins, const Sky_DeltaTs *deltas, void(*getApparent)(double j2kTT_cy, Sky_TrueEquatorial *pos))
	Initialise those items that take a long time to calculate, but which do not need to be recalculated frequently. More...
void	skyfast_backgroundUpdate (void)
	Recalculation of the low frequency quantities. More...
void	skyfast_getApprox (double t_cy, Sky_TrueEquatorial *approx)
	Get the best approximation to the celestial object's apparent coordinates and distance, and the equation of the equinoxes, based on an interpolation between two sets of such data that we have previously calculated. More...

Detailed Description

skyfast.h - set up and use interpolation for rapid calculation of a celestial object's apparent coordinates.

Author

David Hoadley

Routines to set up interpolation for celestial tracking, get the interpolated position at a given time, and to update the endpoints used by the interpolation algorithm. The error introduced by using interpolation rather than fully calculating each and every position can be very small - see Interpolation and its errors (the end of this source file)

---

Definition in file skyfast.h.

Function Documentation

skyfast_init()

void skyfast_init	(	double	tStartUtc_d,
		int	fullRecalcInterval_mins,
		const Sky_DeltaTs *	deltas,
		void(*)(double j2kTT_cy, Sky_TrueEquatorial *pos)	getApparent
	)

Initialise those items that take a long time to calculate, but which do not need to be recalculated frequently.

This routine calls a function that you supply to calculate the apparent coordinates of a celestial object, its distance, and the Equation of the Equinoxes, as derived from nutation calculations. This routine calls that function

1. for the time specified by tStartUtc_d,
2. for time tStartUtc_d + fullRecalcalcInterval_mins, and
3. for time tStartUtc_d + 2 x fullRecalcalcInterval_mins.

For example, to track the Sun, specify the function sun_nrelApparent() when calling this routine. To track the Moon, specify the function moon_nrelApparent().

The routine skyfast_getApprox() can then be called (at a high frequency if required) to calculate the current position of the object, using these values to do it.

Parameters

[in]	tStartUtc_d	Time for first full calculation using function getApparent(). UTC time in "J2KD" form - i.e days since J2000.0 (= JD - 2 451 545.0)
[in]	fullRecalcInterval_mins	Interval of time between full recalculation of the object's position using the function supplied to getApparent (minutes). This value must be greater than zero. (Otherwise you will get a precondition failure.)
[in]	deltas	Delta T values, as set by the sky_initTime() (or sky_initTimeSimple() or sky_initTimeDetailed()) routines
	getApparent	Function to get the position of a celestial object in apparent coordinates (i.e. referred to the true equinox and equator at the time), in rectangular form.

When to call this function

At program initialisation time.

Note

Although the parameter name getApparent suggests that you must supply a function which calculates an object's position in apparent coordinates, it is also possible to supply a function which returns the position in Celestial Intermediate coordinates (i.e. referred to the true equator and the Celestial Intermediate Origin (CIO) at time t_cy) instead. If so, the function does not need to fill in the eqEq_rad field of struct Sky_TrueEquatorial.

---

Examples

demo2_sun_tracking.c, and demo4_multiple_sites.c.

Definition at line 111 of file skyfast.c.

skyfast_backgroundUpdate()

void skyfast_backgroundUpdate

(

void

)

Recalculation of the low frequency quantities.

Checks whether the calculations of the celestial object's apparent coordinates and the equation of the equinoxes have been performed for the time called "oneAfter" (i.e. the time after the time called "next"). If they have not, this function performs those calculations.

This function calls the function that you previously supplied to function skyfast_init() (parameter getApparent).

When to call this function

This function is designed to be called in a low priority loop, or at background level, using any available leftover processor time to slowly precalculate values for the "time after next". It needs to have been called before the high frequency routine skyfast_getApprox() (which is interpolating between time "last" and time "next") arrives at time "next" and therefore needs to access the data for time "oneAfter".

---

Definition at line 199 of file skyfast.c.

skyfast_getApprox()

void skyfast_getApprox	(	double	t_cy,
		Sky_TrueEquatorial *	approx
	)

Get the best approximation to the celestial object's apparent coordinates and distance, and the equation of the equinoxes, based on an interpolation between two sets of such data that we have previously calculated.

Parameters

[in]	t_cy	Julian centuries since J2000.0, TT timescale. This must specify a time no earlier than the time specified in argument tStartUtc_d in the call to skyfast_init().
[out]	approx	position vector, distance, etc, obtained by interpolation

Although the position is described as approximate, the position returned can be very accurate, as shown in Interpolation and its errors, depending on the interpolation interval that was specified to routine skyfast_init().

Note

This function will return an approximate position in apparent coordinates (i.e. referred to the true equator and equinox at time t_cy) if the function that you passed to the skyfast_init() function returned apparent coordinates. This function will return an approximate position in Celestial Intermediate coordinates (i.e. referred to the true equator and the Celestial Intermediate Origin (CIO)) at time t_cy) if the function that you passed to the skyfast_init() function returned CIRS coordinates.

---

Examples

demo4_multiple_sites.c.

Definition at line 234 of file skyfast.c.