star.h - Astronomical conversion routines for stars and other objects beyond the Solar System More...

Data Structures
struct	Star_CatalogPosn
	Catalogue position of a celestial object. More...

Enumerations
enum	Star_CoordSys { APPARENT, INTERMEDIATE, FK4, FK5, ICRS }
	Coordinate system equator and origin. More...

enum	Star_CoordErrors { STAR_NORMAL, STAR_IVEPOCH, STAR_ERRINOBJ, STAR_NORA, STAR_ERRINRA, STAR_RARANERR, STAR_NODEC, STAR_ERRINDEC, STAR_DECRANERR, STAR_ERRINMURA, STAR_ERRINMUDEC, STAR_NOMUDEC, STAR_NOMURA, STAR_ERRINPARAL, STAR_PINEEDSPM, STAR_ERRINVR, STAR_VRNEEDSPM }
	Errors detected when decoding a text coordinate string or when filling a block of type Star_CatalogPosn with numerical data. More...

Functions
void	star_setCurrentObject (const Star_CatalogPosn *c)
	Copies the catalogue information in c to internal storage for later use by star_getApparent() More...

void	star_catalogToApp (const Star_CatalogPosn c, double j2kTT_cy, const Sky1_Nut1980 nut, V3D_Vector appV, double dist_au)
	Convert the catalogue coordinates for a star (or other object outside the Solar System) to apparent coordinates at time j2kTT_cy. More...

void	star_getApparent (double j2kTT_cy, Sky_TrueEquatorial *pos)
	Calculate the position of the currently selected star (or other object outside the solar system) as a unit vector and a distance, in apparent coordinates. More...

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

int	star_setCatalogPosn (const char objectName[], double ra_h, double dec_deg, Star_CoordSys coordSys, double equinoxYear, double epochYear, double muRaSplat_maspa, double muDec_maspa, double annParallax_as, double radVel_kmps, Star_CatalogPosn *coordBlock)
	This is one of three alternative routines for loading the information for a celestial object into a block of form Star_CatalogPosn. More...

int	star_setCatalogOldStyle (const char objectName[], double ra_h, double dec_deg, Star_CoordSys coordSys, double equinoxYear, double epochYear, double muRa_spcy, double muDec_aspcy, double annParallax_as, double radVel_kmps, Star_CatalogPosn *coordBlock)
	This is one of three alternative routines for loading the information for a celestial object into a block of form Star_CatalogPosn. More...

int	star_parseCoordString (const char inStr[], Star_CatalogPosn *coordBlock)
	This is one of three alternative routines for loading the information for a celestial object into a block of form Star_CatalogPosn. More...

void	star_catalogToVectors (const Star_CatalogPosn c, V3D_Vector pV, V3D_Vector *vV_radpcy)
	This routine takes the mean equatorial polar coordinate of an object and its proper motions, annual parallax (distance) and radial velocity, and computes the rectangular position and velocity vectors with respect to the same coordinate system. More...

void	star_earth (double t1_cy, const V3D_Matrix npM, V3D_Vector ebV_au, V3D_Vector ebdotV_aupd, V3D_Vector sbV_au)
	Calculate the position and velocity of the Earth, for use in making annual parallax and aberration corrections. More...

void	star_annAberr (const V3D_Vector p1V, const V3D_Vector earthVelV_aupd, V3D_Vector *p2V)
	Apply the annual aberration correction, to convert an object's coordinates from geocentric geometric direction to "proper" direction (still geocentric) More...

char *	star_equinoxToStr (const Star_CatalogPosn *coordBlock, char equinoxStr[], size_t eqnxStrSize)
	Write the coordinate system and equinox out in a standard form. More...

char *	star_epochToStr (const Star_CatalogPosn *coordBlock, char epochStr[], size_t epochStrSize)
	Write the epoch used for proper motion calculations out in a standard form. More...

Detailed Description

star.h - Astronomical conversion routines for stars and other objects beyond the Solar System

Author: David Hoadley

Routines to convert a celestial object's catalogue position (as seen from the Solar System Barycentre) to a geocentric apparent position (as seen from the centre of the Earth). This means

find the position and velocity of the Earth with respect to the Solar System Barycentre.
apply proper motion from the catalogue epoch to the desired epoch
offset the position by the position of the Earth (apply Annual Parallax)
use the velocity of the Earth to calculate the Annual Aberration correction

The geocentric position calculated is then converted from the coordinate system of the catalogue position to apparent coordinates. (Exception: if the catalogue position is already in Celestial Intermediate coordinates, then the resulting vector will still be in Celestial Intermediate coordinates.)

Definition in file star.h.

Enumeration Type Documentation

◆ Star_CoordSys

enum Star_CoordSys

Coordinate system equator and origin.

Enumerator
APPARENT	True equator and equinox of date.
INTERMEDIATE	True equator and CIO of date.
FK4	Mean equator and equinox of Besselian epoch.
FK5	Mean equator and equinox of Julian epoch.
ICRS	International Celestial Reference System.

Definition at line 69 of file star.h.

◆ Star_CoordErrors

enum Star_CoordErrors

Errors detected when decoding a text coordinate string or when filling a block of type Star_CatalogPosn with numerical data.

Enumerator
STAR_NORMAL	Normal successful completion.
STAR_IVEPOCH	Invalid epoch or equinox specification.
STAR_ERRINOBJ	Error extracting object name from the string. (comma missing at end?, or name started with a double quote char but there was no closing double-quote?)
STAR_NORA	Specification of Right Ascension is missing.
STAR_ERRINRA	Right Ascension can't be decoded.
STAR_RARANERR	Right Ascension out of range.
STAR_NODEC	Specification of Declination is missing.
STAR_ERRINDEC	Declination can't be decoded.
STAR_DECRANERR	Declination out of range.
STAR_ERRINMURA	Proper motion in RA can't be decoded.
STAR_ERRINMUDEC	Proper motion in Declination can't be decoded.
STAR_NOMUDEC	Specification of proper motion in Dec is missing when mu_ra was provided. Check commas in string
STAR_NOMURA	Specification of proper motion in RA is missing when mu_dec was provided. Check commas in string
STAR_ERRINPARAL	Parallax can't be decoded.
STAR_PINEEDSPM	Proper motion must be specified if specifying parallax.
STAR_ERRINVR	Radial Velocity can't be decoded.
STAR_VRNEEDSPM	Proper motion and parallax must be specified if specifying Radial Velocity.

Definition at line 98 of file star.h.

Function Documentation

◆ star_setCurrentObject()

void star_setCurrentObject ( const Star_CatalogPosn * c )

Copies the catalogue information in c to internal storage for later use by star_getApparent()

Parameters

[in] c The catalogue information for the star, as set by one of the three functions star_parseCoordString(), star_setCatalogPosn() or star_setCatalogOldStyle().

Definition at line 135 of file star.c.

◆ star_catalogToApp()

void star_catalogToApp	(	const Star_CatalogPosn *	c,
		double	j2kTT_cy,
		const Sky1_Nut1980 *	nut,
		V3D_Vector *	appV,
		double *	dist_au
	)

Convert the catalogue coordinates for a star (or other object outside the Solar System) to apparent coordinates at time j2kTT_cy.

Parameters

[in]	c	Catalogue position and motion of object, as set by one of the three functions star_parseCoordString(), star_setCatalogPosn() or star_setCatalogOldStyle().
[in]	j2kTT_cy	Julian centuries since J2000.0, TT timescale
[in]	nut	Nutation angles and obliquity of the ecliptic at time j2kTT_cy, as returned by functions sky1_nutationIAU1980() and sky1_epsilon1980()
[out]	appV	Unit vector of geocentric apparent direction of object, referred to the true equator and equinox at time (j2kTT_cy)
[out]	dist_au	Distance to object (AU) as derived from c->parallax_rad.

This routine is simplified, in that:

It uses an approximate position for the Earth (calling star_earth())
It does not apply relativistic corrections for gravitational light deflection; this effect is ignored.
Neither does it apply a relativistic annual aberration correction - it uses a simple vector sum of the earth's velocity to calculate annual aberration (calling star_annAberr()).

References:: Astronomical Almanac 1987 pages B39-40, or
Astronomical Almanac 2007 pages B66-67

Note: If the field c->cSys is equal to FK4, this routine will return zero for the vector and distance. FK4 stellar positions are not supported (yet).

Definition at line 148 of file star.c.

◆ star_getApparent()

void star_getApparent	(	double	j2kTT_cy,
		Sky_TrueEquatorial *	pos
	)

Calculate the position of the currently selected star (or other object outside the solar system) as a unit vector and a distance, in apparent coordinates.

It calls star_catalogToApp() to obtain the star's position, after having called sky1_nutationIAU1980() and sky1_epsilon1980() to obtain the necessary nutation terms.

The star whose coordinates are obtained with this function is the star most recently specified with star_setCurrentObject()

Parameters

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

This function is designed to be callable by the skyfast_init() and skyfast_backgroundUpdate() functions in a tracking application.

Definition at line 315 of file star.c.

◆ star_getTopocentric()

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

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

The star whose coordinates are obtained with this function is the star most recently specified with star_setCurrentObject()

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

When to call this function: Use this function if you are calculating the star 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 356 of file star.c.

◆ star_setCatalogPosn()

int star_setCatalogPosn	(	const char	objectName[],
		double	ra_h,
		double	dec_deg,
		Star_CoordSys	coordSys,
		double	equinoxYear,
		double	epochYear,
		double	muRaSplat_maspa,
		double	muDec_maspa,
		double	annParallax_as,
		double	radVel_kmps,
		Star_CatalogPosn *	coordBlock
	)

This is one of three alternative routines for loading the information for a celestial object into a block of form Star_CatalogPosn.

(The other two routines are star_setCatalogOldStyle() and star_parseCoordString().)

Returns: An error code containing one of the values in Star_CoordErrors

Parameters

[in]	objectName	Name of the object (optional)
[in]	ra_h	Right ascension (hours)
[in]	dec_deg	Declination (degrees)
[in]	coordSys	Coordinate system for RA and Dec
[in]	equinoxYear	Year of epoch of the mean equinox (if coordSys is FK4 or FK5)
[in]	epochYear	Year of epoch for proper motion (if coordSys is ICRS, FK4 or FK5)
[in]	muRaSplat_maspa	μα* - proper motion in RA, including the cos(δ) factor (milliarcseconds/year)
[in]	muDec_maspa	μδ - proper motion in declination (milliarcseconds/year)
[in]	annParallax_as	π - annual parallax (arcseconds)
[in]	radVel_kmps	ν - radial velocity (km/s), positive away from the Earth
[out]	coordBlock	The block containing the data from all the input parameters, basically scaled into radians

The difference between this routine and star_setCatalogOldStyle() is in the way the proper motions in RA and Dec are specified. In this routine, μα* is specified in milliarcseconds per year, after scaling to absolute displacement on the sky by multiplying by cos(δ). μδ is also specified in milliarcseconds per year.

Definition at line 763 of file star.c.

◆ star_setCatalogOldStyle()

int star_setCatalogOldStyle	(	const char	objectName[],
		double	ra_h,
		double	dec_deg,
		Star_CoordSys	coordSys,
		double	equinoxYear,
		double	epochYear,
		double	muRa_spcy,
		double	muDec_aspcy,
		double	annParallax_as,
		double	radVel_kmps,
		Star_CatalogPosn *	coordBlock
	)

This is one of three alternative routines for loading the information for a celestial object into a block of form Star_CatalogPosn.

(The other two routines are star_setCatalogPosn() and star_parseCoordString().)

Returns: An error code containing one of the values in Star_CoordErrors

Parameters

[in]	objectName	Name of the object (optional)
[in]	ra_h	Right ascension (hours)
[in]	dec_deg	Declination (degrees)
[in]	coordSys	Coordinate system for RA and Dec
[in]	equinoxYear	Year of epoch of the mean equinox (if coordSys is FK4 or FK5)
[in]	epochYear	Year of epoch for proper motion (if coordSys is ICRS, FK4 or FK5)
[in]	muRa_spcy	μα - proper motion in RA, not including the cos(δ) factor (seconds/century)
[in]	muDec_aspcy	μδ - proper motion in declination (arcseconds/century)
[in]	annParallax_as	π - annual parallax (arcseconds)
[in]	radVel_kmps	ν - radial velocity (km/s), positive away from the Earth
[out]	coordBlock	The block containing the data from all the input parameters, basically scaled into radians

The difference between this routine and star_setCatalogPosn() is in the way the proper motions in RA and Dec are specified. In this routine, μα is specified in seconds (of time) per century, and is not scaled to absolute displacement on the sky. μδ is specified in arcseconds per century.

Definition at line 868 of file star.c.

◆ star_parseCoordString()

int star_parseCoordString	(	const char	inStr[],
		Star_CatalogPosn *	coordBlock
	)

This is one of three alternative routines for loading the information for a celestial object into a block of form Star_CatalogPosn.

(The other two routines are star_setCatalogPosn() and star_setCatalogOldStyle().)

Returns: An error code containing one of the values in Star_CoordErrors

Parameters

[in]	inStr	The input string.
[out]	coordBlock	The block containing the data from the input string, basically scaled into radians

This routine decodes an input string which is of the form

    [name], RA, DEC[, Coords,[Epoch][, Mu_ra*, Mu_dec[, Pi[, Vr]]]]

where the items shown inside square brackets are optional. This is basically a comma separated value (CSV) format. The text fields are as follows:

name - Object name. If the name is longer than the field Star_CatalogPosn.objectName, the extra characters will be lost.
RA - Right Ascension. This has one to three numeric subfields, depending upon where the decimal point (if any) is placed. So it may be in the form of
- decimal hours (e.g. 12.582) (one subfield only)
- hours and decimal minutes (e.g. 12:34.933 or 12 34.933) (two subfields)
- hours, minutes and seconds (e.g. 12:34:56 or 12 34 56, or 12:34:56.78 or 12:34:56:78)
DEC - Declination. This also has one to three numeric subfields, as above. it may be in the form of
- decimal degrees (e.g. ±21.625 or ±21.625°)
- degrees and decimal arcminutes (e.g. ±21 37.5 or ±21°37.5′)
- degrees, arcminutes and arcseconds (e.g. ±21 37 30 or ±21°37′30″, or ±21 37 30.0 or ±21°37′30.0″)

In both of the above cases, the subfields may be separated by spaces, colons, degree, minute and seconds symbols, single and double quotes, or anything really. The parser is not fussy, and does not check.

Coords - the coordinate system reference for the coordinates. Valid values for this field are
- Apparent - referred to true equinox and equator of date
- Jnnnn.n - FK5 position referred to mean equator and equinox of the specified Julian epoch (e.g. J2000)
- Bnnnn.n - FK4 position referred to mean equator and equinox of the specified Besselian epoch (e.g. B1950)
- nnnn.n - If not specified with a B or a J, values here before 1984.0 will be assumed to be FK4 (Besselian) and those after to be FK5 (Julian)
- Intermediate - Celestial Intermediate Reference System. This is referred to the true equator of date and the Celestial Intermediate Origin (CIO).
- ICRS - International Celestial Reference System
If this field is not specified, it will be assumed to be Apparent, and all following fields will be ignored.
Epoch - Initial epoch for proper motion. If this field is omitted, the epoch is assumed to be the same as the coordinate system specification that precedes it. If that coordinate system is ICRS, then the epoch is assumed to be J2000.0 if is not specified. If the coordinate system is Apparent or Intermediate, the Epoch is ignored.
Mu_ra* - proper motion in right ascension (milliarcseconds/year), including the cos(DEC) factor. This field will be ignored if Coords is set to Apparent or Intermediate
Mu_dec - proper motion in declination (milliarcseconds/year). This field will be ignored if Coords is set to Apparent or Intermediate
Pi - annual parallax (arcseconds) This field will be ignored if Coords is set to Apparent or Intermediate
Vr - radial velocity (km/s), positive for objects moving away. This field will be ignored if Coords is set to Apparent or Intermediate

The string format is fairly flexible. For example, fields may be separated with spaces rather than commas, so long as any omitted fields are at the end of the string. But if any fields not at the end are omitted, commas must be used to indicate the empty fields.

Note

The facilities provided by the C language for text handling are rudimentary, and as a result, this routine is slightly fragile. In trying to be flexible but not too complex, the following limitation applies: Do not ever have white space immediately preceding a comma. If you do, the routine may go wrong. So, in particular this means that omitted fields (not at the end of the string) must be denoted by two successive commas with no space in between.

    Dummy, 12:34:56.789, +89°56′43.210″, J2000.0,, 23.455, 12.766
    Barnard's star, 17 57 48.500 +04 41 36.111 ICRS,, -802.803, 10362.542, 0.5474506, -110.353

Definition at line 972 of file star.c.

◆ star_catalogToVectors()

void star_catalogToVectors	(	const Star_CatalogPosn *	c,
		V3D_Vector *	pV,
		V3D_Vector *	vV_radpcy
	)

This routine takes the mean equatorial polar coordinate of an object and its proper motions, annual parallax (distance) and radial velocity, and computes the rectangular position and velocity vectors with respect to the same coordinate system.

Parameters

[in]	c	Catalog position and motion of object
[out]	pV	Unit position vector (direction cosines)
[out]	vV_radpcy	Space velocity vector (radian/Julian century)

Reference:: Astronomical Almanac 2007, pages B66 and B67

Definition at line 403 of file star.c.

◆ star_earth()

void star_earth	(	double	t1_cy,
		const V3D_Matrix *	npM,
		V3D_Vector *	ebV_au,
		V3D_Vector *	ebdotV_aupd,
		V3D_Vector *	sbV_au
	)

Calculate the position and velocity of the Earth, for use in making annual parallax and aberration corrections.

Parameters

[in]	t1_cy	Epoch of time of observation (Julian centuries since J2000.0, TT timescale)
[in]	npM	Combined precession and nutation matrix NP that will be used to convert the coordinates of the star of interest from its catalogue mean place to apparent coordinates. It will be used in this routine to do the reverse - convert the apparent coordinates of the Earth's position back into mean coordinates at the catalogue epoch of the star.
[out]	ebV_au	Barycentric position of the Earth (AU) (vector Eb in Astronomical Almanac)
[out]	ebdotV_aupd	Velocity of the Earth (AU/day) (vector Ėb in Astronomical Almanac)
[out]	sbV_au	Barycentric position of the Sun (AU) (vector Sb in Astronomical Almanac)

In theory, this is the barycentric position, and the values are referred to the same system as is used for the catalogue position of the star (such as J2000, or the Barycentric Celestial Reference System/ICRS). This can be obtained from the IAU SOFA routine iauEpv00(), calculated in fabulously complicated detail. But the parallax and aberration corrections are small, which means that the accuracy required of this routine is not actually that high.

So to save on computing resources in a tracking application, this routine uses instead the simple algorithm in the Astronomical Almanac for the Sun's position, entitled "Low-precision formulas for the Sun's coordinates..." It differentiates the position vector to obtain the Earth's velocity. So there are a few approximations here:

It calculates a heliocentric position, rather than a barycentric position
The algorithm itself is approximate - accurate to 0.01° between 1950 and 2050.
It does not calculate the barycentric position of the Sun at all. So sbV_au will be returned as a zero vector.

But nonetheless, the effect on the final star position is very small. For example, the Almanac gives an example of stellar reduction calculations for a fictitious star, (which appears to be very close to Alpha Centauri). This star has about as much parallax as one is ever likely to see.

In the 2007 Almanac, page B68, the apparent position of this star at 2007 January 1, 0h TT , after performing a rigorous reduction, is

RA = 14 40 03.4343 (hms), Dec = -60°51′37.770″

The position obtained by using the approximations of star_catalogToApp() (which calls this routine) and converts to apparent coordinates is

RA = 14:40:03.4276 (hms), Dec = -60°51'37.782"

which is clearly good enough for tracking.

In the 1987 Almanac, page B41, the apparent position of a (very slightly different) fictitious star at 1987 January 1, 0h TT is

RA = 14 38 40.164 (hms), Dec = -60°46′44.82″

The position obtained using the routines here (as above) is

RA = 14:38:40.157 (hms), Dec = -60°46'44.84"

For a more detailed look at this, see Stellar reduction accuracy

References:: Astronomical Almanac 1987 pages B39 (method), B41 (example) and C24 (Sun position) or
Astronomical Almanac 2007 pages B66 (method), B68 (example) and C24 (Sun position).

Definition at line 461 of file star.c.

◆ star_annAberr()

void star_annAberr	(	const V3D_Vector *	p1V,
		const V3D_Vector *	earthVelV_aupd,
		V3D_Vector *	p2V
	)

Apply the annual aberration correction, to convert an object's coordinates from geocentric geometric direction to "proper" direction (still geocentric)

Parameters

[in]	p1V	Unit vector pointing to object's geometric direction as viewed from the centre of the earth.
[in]	earthVelV_aupd	Earth velocity vector, referred to the J2000 mean equator and equinox, as returned by routine star_earth() (AU/day - not a unit vector)
[out]	p2V	Unit vector pointing to object's proper direction

Definition at line 603 of file star.c.

◆ star_equinoxToStr()

char* star_equinoxToStr	(	const Star_CatalogPosn *	coordBlock,
		char	equinoxStr[],
		size_t	eqnxStrSize
	)

Write the coordinate system and equinox out in a standard form.

Parameters

[in]	coordBlock	Coordinate block describing the celestial object
[out]	equinoxStr	String to contain the coordinate system and equinox
[in]	eqnxStrSize	Size of equinoxStr (i.e. maximum number of characters available for the output

The output form depends upon the value of coordBlock->cSys:

coordBlock->cSys	Output
APPARENT	Apparent
INTERMEDIATE	Intermediate
FK4	Bnnnn.n (n is numeric)
FK5	Jnnnn.n (n is numeric)
ICRS	ICRS

Definition at line 632 of file star.c.

◆ star_epochToStr()

char* star_epochToStr	(	const Star_CatalogPosn *	coordBlock,
		char	epochStr[],
		size_t	epochStrSize
	)

Write the epoch used for proper motion calculations out in a standard form.

Parameters

[in]	coordBlock	Coordinate block describing the celestial object
[out]	epochStr	String to contain the coordinate system and epoch
[in]	epochStrSize	Size of epochStr (i.e. maximum number of characters available for the output

The output form depends upon the value of coordBlock->cSys:

coordBlock->cSys	Output
APPARENT	(empty string - epoch is irrelevant)
INTERMEDIATE	(empty string - epoch is irrelevant)
FK4	Bnnnn.n (n is numeric)
FK5	Jnnnn.n (n is numeric)
ICRS	Jnnnn.n (n is numeric)

Definition at line 698 of file star.c.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ Star_CoordSys

◆ Star_CoordErrors

Function Documentation

◆ star_setCurrentObject()

◆ star_catalogToApp()

◆ star_getApparent()

◆ star_getTopocentric()

◆ star_setCatalogPosn()

◆ star_setCatalogOldStyle()

◆ star_parseCoordString()

◆ star_catalogToVectors()

◆ star_earth()

◆ star_annAberr()

◆ star_equinoxToStr()

◆ star_epochToStr()