planet.h - Astronomical routines to get the positions of planets More...

Functions
void	planet_setCurrent (int np)
	Stores the selected planet number np in internal storage for later use by planet_getApparent() or planet_getTopocentric() More...

void	planet_getApp2 (double t_cy, int np, const Sky1_Nut1980 nut, V3D_Vector appV, double *dist_au)
	This function calculates the specified planet's position in apparent coordinates, using the planet_getGeocentric() and planet_getHeliocentric() functions More...

void	planet_getApparent (double j2kTT_cy, Sky_TrueEquatorial *pos)
	Calculate the position of the currently selected planet as a unit vector and a distance, in apparent coordinates. More...

void	planet_getTopocentric (double j2kUtc_d, const Sky_DeltaTs deltas, const Sky_SiteProp site, Sky_SiteHorizon *topo)
	Calls planet_getApparent() to calculate the planet's position in apparent coordinates, and then converts this to topocentric horizon coordinates at the specified site. More...

void	planet_getGeocentric (double t_cy, int np, V3D_Vector p2V, double dist_au)
	Calculates an approximate position of the selected planet as seen from the centre of the earth. More...

int	planet_getHeliocentric (double t_cy, int np, V3D_Vector j2kV_au, V3D_Vector velV_aupd)
	Calculates an approximate heliocentric position of the selected planet. More...

Detailed Description

planet.h - Astronomical routines to get the positions of planets

Author: David Hoadley, based on a routine from the IAU's SOFA collection

Routines to obtain a specified planet's position and convert that position to apparent coordinates and/or topocentric coordinates.

Definition in file planet.h.

Function Documentation

◆ planet_setCurrent()

void planet_setCurrent ( int np )

Stores the selected planet number np in internal storage for later use by planet_getApparent() or planet_getTopocentric()

Parameters

[in] np Desired planet.
1=Mercury, 2=Venus, 3=Earth-Moon Barycentre, 4=Mars,
5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune
Numbers outside this range will cause an assertion failure

Definition at line 89 of file planet.c.

◆ planet_getApp2()

void planet_getApp2	(	double	t_cy,
		int	np,
		const Sky1_Nut1980 *	nut,
		V3D_Vector *	appV,
		double *	dist_au
	)

This function calculates the specified planet's position in apparent coordinates, using the planet_getGeocentric() and planet_getHeliocentric() functions

Parameters

[in]	t_cy	Julian centuries since J2000.0, TT timescale
[in]	np	Desired planet. 1=Mercury, 2=Venus, 3=Earth-Moon Barycentre, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune Numbers outside this range will cause an assertion failure
[in]	nut	Nutation terms and obliquity of the ecliptic, as returned by functions sky1_nutationIAU1980() and sky1_epsilon1980()
[out]	appV	Position vector of planet in apparent coordinates (unit vector i.e. direction cosines)
[out]	dist_au	Geocentric distance of the planet (Astronomical Units)

When to call this function: In most cases, you will want to call planet_getApparent() or planet_getTopocentric() instead, and those functions call this function for you.

Definition at line 105 of file planet.c.

◆ planet_getApparent()

void planet_getApparent	(	double	j2kTT_cy,
		Sky_TrueEquatorial *	pos
	)

Calculate the position of the currently selected planet as a unit vector and a distance, in apparent coordinates.

It calls planet_getApp2() to obtain the planet's position, after having called sky1_nutationIAU1980() to obtain the necessary nutation terms.
This function is designed to be callable by the skyfast_init() and skyfast_backgroundUpdate() functions in a tracking application.

Parameters

[in]	j2kTT_cy	Julian centuries since J2000.0, TT timescale
[out]	pos	Timestamped structure containing position data and the equation of the equinoxes

The planet whose coordinates are obtained with this function is the planet most recently specified with planet_setCurrent()

Definition at line 154 of file planet.c.

◆ planet_getTopocentric()

void planet_getTopocentric	(	double	j2kUtc_d,
		const Sky_DeltaTs *	deltas,
		const Sky_SiteProp *	site,
		Sky_SiteHorizon *	topo
	)

Calls planet_getApparent() to calculate the planet's position in apparent coordinates, and then converts this to topocentric horizon coordinates at the specified site.

Parameters

[in]	j2kUtc_d	UTC time in "J2KD" form - i.e days since J2000.0 (= JD - 2 451 545.0)
[in]	deltas	Delta T values, as set by the sky_initTime() (or sky_initTimeSimple() or sky_initTimeDetailed()) routines
[in]	site	Properties of the observing site, particularly its geometric location on the surface of the Earth, as set by the sky_setSiteLocation() function (or sky_setSiteLoc2())
[out]	topo	Topocentric position, in both rectangular (unit vector) form, and as Azimuth and Elevation (altitude) angles

You will need to call planet_setCurrent() before calling this function to select the planet whose coordinates you want.

When to call this function: Use this function if you are calculating the planet topocentric position once, for a single site. But if you are going to be calculating it repeatedly, or for multiple sites, use of this function will cause you to perform a great many needless recalculations. Use skyfast_getApprox(), followed by sky1_appToTirs() and sky_siteTirsToTopo() instead.

Definition at line 195 of file planet.c.

◆ planet_getGeocentric()

void planet_getGeocentric	(	double	t_cy,
		int	np,
		V3D_Vector *	p2V,
		double *	dist_au
	)

Calculates an approximate position of the selected planet as seen from the centre of the earth.

This function calls planet_getHeliocentric() for the desired planet. It then (as an approximation) calls this routine again for the position of the Earth and uses this to obtain the geocentric position of the planet.

Parameters

[in]	t_cy	Julian centuries since J2000.0, TT timescale
[in]	np	Desired planet. 1=Mercury, 2=Venus, 3=Earth-Moon Barycentre, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune Numbers outside this range will cause an assertion failure
[out]	p2V	Position vector of planet in J2000.0 coordinates (unit vector i.e. direction cosines)
[out]	dist_au	Geocentric distance of the planet (Astronomical Units)

Note: Calling planet_getHeliocentric() for the position of the Earth actually returns the position of the Earth-Moon barycenter, rather than the position of the Earth. But the error that is introduced by doing this seems to be relatively small, somewhere in the 10's of arcseconds. So long as a planetary position that is within an arcminute is all you need, this routine should be perfectly OK.; planet_getHeliocentric() uses an iterative approach to calculating planetary positions. If for some reason that does not converge, this function will set p2V and dist_au to zero.

Definition at line 242 of file planet.c.

◆ planet_getHeliocentric()

int planet_getHeliocentric	(	double	t_cy,
		int	np,
		V3D_Vector *	j2kV_au,
		V3D_Vector *	velV_aupd
	)

Calculates an approximate heliocentric position of the selected planet.

Returns: Error code:
0 = OK, 1 = warning, reduced precision: year outside 1000–3000, 2 = error, failed to converge.

Parameters

[in]	t_cy	Julian centuries since J2000.0, TDB (or TT) timescale
[in]	np	Desired planet. 1=Mercury, 2=Venus, 3=Earth-Moon Barycentre, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune Numbers outside this range will cause an assertion failure
[out]	j2kV_au	Heliocentric position of planet referred to J2000.0 mean equator and equinox.
[out]	velV_aupd	(Optional) Velocity vector of the planet (AU/day), also referred to J2000.0 equator and equinox. If you are not interested in this value, you can pass NULL to this argument.

Note

This function is a modified implementation of the iauPlan94() function from the International Astronomical Union's (IAU) Standards of Fundamental Astronomy (SOFA) collection. See the SOFA Software License at the end of this function's C source code. According to the requirements of that license, here are the required declarations.

Condition 3(a). This software is derived by David Hoadley from licensed SOFA code (i.e. routine iauPlan94()). It does not itself constitute software provided by and/or endorsed by SOFA.

Condition 3(b). This function differs from the original SOFA routine in that

The input and output arguments have been altered to match the conventions used elsewhere in this software.
time:
- here: time is input as Julian centuries since J2000.0, TT
- SOFA: time is input as a Julian date in two parts, TDB
outputs:
- here: a position vector scaled in AU, and an optional velocity vector in AU/d
- SOFA: a 2x3 element array giving both position and velocity in AU and AU/d respectively.
A requested planet outside the range 1–8 does not return an error code. Such a request is a programming error, so instead it generates a precondition failure (an assertion failure). Also, the output vectors are not zero'd if this precondition failure occurs.
The names of some constants have been changed to use the names we already have in use, and in the process "de-FORTRAN-ised", making them more comprehensible.
D2PI -> TWOPI
DAS2R -> ARCSEC2RAD
An assertion test added to check for a NULL pointer being passed for j2kV
Calls our own normalize() function instead of the SOFA routine iauAnp()

Condition 3(e). If you make any modification to this software, or copy any part of it for incorporation elsewhere, you must include the SOFA Software License exactly as it appears at the end of this function.

Definition at line 344 of file planet.c.

Functions

Detailed Description

Function Documentation

◆ planet_setCurrent()

◆ planet_getApp2()

◆ planet_getApparent()

◆ planet_getTopocentric()

◆ planet_getGeocentric()

◆ planet_getHeliocentric()