Functions
int	ecl2equ (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, double elon, double elat, double restrict ra, double restrict dec)

short	ecl2equ_vec (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, const double in, double out)

short	equ2ecl (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, double ra, double dec, double restrict elon, double restrict elat)

short	equ2ecl_vec (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, const double in, double out)

int	equ2gal (double ra, double dec, double restrict glon, double restrict glat)

int	equ2hor (double jd_ut1, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const on_surface restrict location, double ra, double dec, enum novas_refraction_model ref_option, double restrict zd, double restrict az, double restrict rar, double *restrict decr)

int	gal2equ (double glon, double glat, double restrict ra, double restrict dec)

int	hor_to_itrs (const on_surface restrict location, double az, double za, double restrict itrs)

int	itrs_to_hor (const on_surface restrict location, const double restrict itrs, double restrict az, double restrict za)

Detailed Description

Date: Created on Mar 5, 2025

Author: G. Kaplan and Attila Kovacs

Various transformations between different coordinate systems

Function Documentation

◆ ecl2equ()

int ecl2equ	(	double	jd_tt,
		enum novas_equator_type	coord_sys,
		enum novas_accuracy	accuracy,
		double	elon,
		double	elat,
		double *restrict	ra,
		double *restrict	dec
	)

Convert ecliptic longitude and latitude to right ascension and declination. To convert GCRS ecliptic coordinates (mean ecliptic and equinox of J2000.0), set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at'jd_tt'.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
	coord_sys	The astrometric reference system of the coordinates. If 'coord_sys' is NOVAS_GCRS_EQUATOR(2), the input GCRS coordinates are converted to J2000 ecliptic coordinates.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	elon	[deg] Ecliptic longitude in degrees, referred to specified ecliptic and equinox of date.
	elat	[deg] Ecliptic latitude in degrees, referred to specified ecliptic and equinox of date.
[out]	ra	[h] Right ascension in hours, referred to specified equator and equinox of date.
[out]	dec	[deg] Declination in degrees, referred to specified equator and equinox of date.

Returns: 0 if successful, or else 1 if the value of 'coord_sys' is invalid.

See also: ecl2equ_vec(); equ2ecl()

Since: 1.0

Author: Attila Kovacs

References ecl2equ_vec().

◆ ecl2equ_vec()

short ecl2equ_vec	(	double	jd_tt,
		enum novas_equator_type	coord_sys,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Converts an ecliptic position vector to an equatorial position vector. To convert ecliptic coordinates (mean ecliptic and equinox of J2000.0) to GCRS RA and dec to, set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at 'jd_tt'.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
	coord_sys	The astrometric reference system type of the coordinates
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	Position vector, referred to specified ecliptic and equinox of date.
[out]	out	Position vector, referred to specified equator and equinox of date. It can be the same vector as the input.

Returns: 0 if successful, -1 if either vector argument is NULL or the accuracy is invalid, or else 1 if the value of 'coord_sys' is invalid.

See also: ecl2equ(); equ2ecl_vec()

References e_tilt(), frame_tie(), J2000_TO_ICRS, mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_GCRS_EQUATOR, NOVAS_MEAN_EQUATOR, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUATOR, and tt2tdb().

◆ equ2ecl()

short equ2ecl	(	double	jd_tt,
		enum novas_equator_type	coord_sys,
		enum novas_accuracy	accuracy,
		double	ra,
		double	dec,
		double *restrict	elon,
		double *restrict	elat
	)

Convert right ascension and declination to ecliptic longitude and latitude. To convert GCRS RA and dec to ecliptic coordinates (mean ecliptic and equinox of J2000.0), set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at 'jd_tt'.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
	coord_sys	The astrometric reference system of the coordinates. If 'coord_sys' is NOVAS_GCRS_EQUATOR(2), the input GCRS coordinates are converted to J2000 ecliptic coordinates.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	ra	[h] Right ascension in hours, referred to specified equator and equinox of date.
	dec	[deg] Declination in degrees, referred to specified equator and equinox of date.
[out]	elon	[deg] Ecliptic longitude in degrees, referred to specified ecliptic and equinox of date.
[out]	elat	[deg] Ecliptic latitude in degrees, referred to specified ecliptic and equinox of date.

Returns: 0 if successful, or else 1 if the value of 'coord_sys' is invalid.

See also: equ2ecl_vec(); ecl2equ()

References equ2ecl_vec().

◆ equ2ecl_vec()

short equ2ecl_vec	(	double	jd_tt,
		enum novas_equator_type	coord_sys,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Converts an equatorial position vector to an ecliptic position vector. To convert ICRS RA and dec to ecliptic coordinates (mean ecliptic and equinox of J2000.0), set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at 'jd_tt'.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
	coord_sys	The astrometric reference system type of the coordinates.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	Position vector, referred to specified equator and equinox of date.
[out]	out	Position vector, referred to specified ecliptic and equinox of date. It can be the same vector as the input. If 'coord_sys' is NOVAS_GCRS_EQUATOR(2), the input GCRS coordinates are converted to J2000 ecliptic coordinates.

Returns: 0 if successful, -1 if either vector argument is NULL or the accuracy is invalid, or else 1 if the value of 'coord_sys' is invalid.

See also: equ2ecl(); ecl2equ_vec()

References e_tilt(), frame_tie(), ICRS_TO_J2000, mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_GCRS_EQUATOR, NOVAS_MEAN_EQUATOR, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUATOR, and tt2tdb().

◆ equ2gal()

int equ2gal	(	double	ra,
		double	dec,
		double *restrict	glon,
		double *restrict	glat
	)

Converts ICRS right ascension and declination to galactic longitude and latitude.

REFERENCES:

Hipparcos and Tycho Catalogues, Vol. 1, Section 1.5.3.

Parameters

	ra	[h] ICRS right ascension in hours.
	dec	[deg] ICRS declination in degrees.
[out]	glon	[deg] Galactic longitude in degrees.
[out]	glat	[deg] Galactic latitude in degrees.

Returns: 0 if successful, or -1 if either of the output pointer arguments are NULL.

See also: gal2equ()

◆ equ2hor()

int equ2hor	(	double	jd_ut1,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		double	xp,
		double	yp,
		const on_surface *restrict	location,
		double	ra,
		double	dec,
		enum novas_refraction_model	ref_option,
		double *restrict	zd,
		double *restrict	az,
		double *restrict	rar,
		double *restrict	decr
	)

Transforms topocentric (TOD) right ascension and declination to zenith distance and azimuth. This method should not be used to convert CIRS apparent coordinates (IAU 2000 standard) – for those you should use cirs_to_itrs() followed by itrs_to_hor() instead.

It uses a method that properly accounts for polar motion, which is significant at the sub-arcsecond level. This function can also adjust coordinates for atmospheric refraction.

Deprecated:: The name of this function does not reveal what type of equatorial coordinates it requires. To make it less ambiguous, you should use tod_to_itrs() followed by itrs_to_hor() instead, possibly following it with refract_astro() if you also want to apply optical refraction.

NOTES:

'xp' and 'yp' can be set to zero if sub-arcsecond accuracy is not needed.
The directions 'zd'= 0 (zenith) and 'az'= 0 (north) are here considered fixed in the terrestrial system. Specifically, the zenith is along the geodetic normal, and north is toward the ITRS pole.
If 'ref_option' is NOVAS_STANDARD_ATMOSPHERE (1), then 'rar'='ra' and 'decr'='dec'.

REFERENCES:

Kaplan, G. (2008). USNO/AA Technical Note of 28 Apr 2008, "Refraction as a Vector."

Parameters

	jd_ut1	[day] UT1 based Julian date
	ut1_to_tt	[s] TT - UT1 Time difference in seconds
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	xp	[arcsec] Conventionally-defined x coordinate of celestial intermediate pole with respect to ITRS reference pole, in arcseconds.
	yp	[arcsec] Conventionally-defined y coordinate of celestial intermediate pole with respect to ITRS reference pole, in arcseconds.
	location	The observer location
	ra	[h] Topocentric right ascension of object of interest, in hours, referred to true equator and equinox of date.
	dec	[deg] Topocentric declination of object of interest, in degrees, referred to true equator and equinox of date.
	ref_option	NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2) if to use the weather
[out]	zd	[deg] Topocentric zenith distance in degrees (unrefracted).
[out]	az	[deg] Topocentric azimuth (measured east from north) in degrees.
[out]	rar	[h] Topocentric right ascension of object of interest, in hours, referred to true equator and equinox of date, affected by refraction if 'ref_option' is non-zero. (It may be NULL if not required)
[out]	decr	[deg] Topocentric declination of object of interest, in degrees, referred to true equator and equinox of date. (It may be NULL if not required)

Returns: 0 if successful, or -1 if one of the 'zd' or 'az' output pointers are NULL.

See also: itrs_to_hor(); tod_to_itrs(); NOVAS_TOD

References EROT_GST, NOVAS_DYNAMICAL_CLASS, refract_astro(), and ter2cel().

◆ gal2equ()

int gal2equ	(	double	glon,
		double	glat,
		double *restrict	ra,
		double *restrict	dec
	)

Converts galactic longitude and latitude to ICRS right ascension and declination.

REFERENCES:

Hipparcos and Tycho Catalogues, Vol. 1, Section 1.5.3.

Parameters

	glon	[deg] Galactic longitude in degrees.
	glat	[deg] Galactic latitude in degrees.
[out]	ra	[h] ICRS right ascension in hours.
[out]	dec	[deg] ICRS declination in degrees.

Returns: 0 if successful, or -1 if either of the output pointer arguments are NULL.

See also: equ2gal()

Since: 1.0

Author: Attila Kovacs

◆ hor_to_itrs()

int hor_to_itrs	(	const on_surface *restrict	location,
		double	az,
		double	za,
		double *restrict	itrs
	)

Converts astrometric (unrefracted) azimuth and zenith angles at the specified observer location to a unit position vector in the Earth-fixed ITRS frame.

Parameters

	location	Observer location on Earth
	az	[deg] astrometric azimuth angle at observer location [0:360]. It may be NULL if not required.
	za	[deg] astrometric zenith angle at observer location [0:180]. It may be NULL if not required.
[out]	itrs	Unit 3-vector direction in Earth-fixed ITRS frame

Returns: 0 if successful, or else -1 if the location or the input vector is NULL.

See also: itrs_to_hor(); itrs_to_cirs(); itrs_to_tod(); refract()

Since: 1.0

Author: Attila Kovacs

◆ itrs_to_hor()

int itrs_to_hor	(	const on_surface *restrict	location,
		const double *restrict	itrs,
		double *restrict	az,
		double *restrict	za
	)

Converts a position vector in the Earth-fixed ITRS frame to astrometric (unrefracted) azimuth and zenith angles at the specified observer location.

Parameters

	location	Observer location on Earth
	itrs	3-vector position in Earth-fixed ITRS frame
[out]	az	[deg] astrometric azimuth angle at observer location [0:360]. It may be NULL if not required.
[out]	za	[deg] astrometric zenith angle at observer location [0:180]. It may be NULL if not required.

Returns: 0 if successful, or else -1 if the location or the input vector is NULL.

See also: hor_to_itrs(); cirs_to_itrs(); tod_to_itrs(); refract_astro()

Since: 1.0

Author: Attila Kovacs

Functions

Detailed Description

Function Documentation

◆ ecl2equ()

◆ ecl2equ_vec()

◆ equ2ecl()

◆ equ2ecl_vec()

◆ equ2gal()

◆ equ2hor()

◆ gal2equ()

◆ hor_to_itrs()

◆ itrs_to_hor()