system.c File Reference

Various transformations between different coordinate systems used in astronomy, such as equatorial, ecliptic, Galactic, or local horizontal coordinate systems. More...

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)
	Convert ecliptic longitude and latitude to right ascension and declination.
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.
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.
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.
int	equ2gal (double ra, double dec, double *restrict glon, double *restrict glat)
	Converts ICRS right ascension and declination to galactic longitude and latitude.
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)
	Converts galactic longitude and latitude to ICRS right ascension and declination.
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.
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.
int	novas_e2h_offset (double dra, double ddec, double pa, double *restrict daz, double *restrict del)
	Converts coordinate offsets, from the local equatorial system to local horizontal offsets.
double	novas_epa (double ha, double dec, double lat)
	Returns the Parallactic Angle (PA) calculated for an RA/Dec location of the sky at a given sidereal time.
int	novas_h2e_offset (double daz, double del, double pa, double *restrict dra, double *restrict ddec)
	Converts coordinate offsets, from the local horizontal system to local equatorial offsets.
double	novas_hpa (double az, double el, double lat)
	Returns the Parallactic Angle (PA) calculated for a horizontal Az/El location of the sky.
int	novas_los_to_xyz (const double *los, double lon, double lat, double *xyz)
	Converts a 3D line-of-sight vector (δφ, δθ δr) to a rectangular equatorial (δx, δy, δz) vector.
int	novas_uvw_to_xyz (const double *uvw, double ha, double dec, double *xyz)
	Converts equatorial u,v,w projected (absolute or relative) coordinates to rectangular telescope x,y,z coordinates (in ITRS) to for a specified line of sight.
int	novas_xyz_to_los (const double *xyz, double lon, double lat, double *los)
	Converts a 3D rectangular equatorial (δx, δy, δz) vector to a polar (δφ, δθ δr) vector along a line-of-sight.
int	novas_xyz_to_uvw (const double *xyz, double ha, double dec, double *uvw)
	Converts rectangular telescope x,y,z (absolute or relative) coordinates (in ITRS) to equatorial u,v,w projected coordinates for a specified line of sight.

Detailed Description

Various transformations between different coordinate systems used in astronomy, such as equatorial, ecliptic, Galactic, or local horizontal coordinate systems.

This module also provides functions otherwise relating to the observer locations.

For Earth-based geodetic locations, the module provides a set of functions to convert between various (local) coordinate systems. For example, calculating parallactic angles (a.k.a. vertical position angle or VPA), for converting between horizontal and equatorial offsets, and various functions for converting equatorial vectors to a line-of-sight, or u, v, w coordinate bases, and vice-versa.

Date

Created on Mar 5, 2025

Author

Attila Kovacs and G. Kaplan

See also

frames.c, transform.c

Function Documentation

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 )

Deprecated

You should use the frame-based novas_app_to_hor() instead, or else the more explicit (less ambiguous) tod_to_itrs() followed by itrs_to_hor(), and possibly following it with an atmospheric refraction correction if appropriate.

Transforms topocentric (TOD) apparent 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.

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:

1. 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, e.g. from IERS Bulletin A. If you have defined pole offsets to be incorporated into the TOD input coordinates (pre-IAU2000 method) via cel_pole(), then you should set this to 0.
	yp	[arcsec] Conventionally-defined y coordinate of celestial intermediate pole with respect to ITRS reference pole, e.g. from IERS Bulletin A. If you have defined pole offsets to be incorporated into the TOD input coordinates (pre-IAU2000 method) via cel_pole(), then you should set this to 0.
	location	Geodetic (ITRF / GRS80) observer location on Earth
	ra	[h] Topocentric apparent (TOD) right ascension of object of interest, referred to true equator and equinox of date.
	dec	[deg] Topocentric apparent (TOD) declination of object of interest, referred to true equator and equinox of date.
	ref_option	Refraction model to use. E.g., 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().