Non-equatorial coordinates

Expressing coordinates in non-equatorial systems, such as ecliptic, galactic, or local horizontal (for geodetic observer) coordinate systems. More...

Classes
class	supernovas::Ecliptic
	Ecliptic coordinates (l, b or λ, β), representing the direction on the sky, for a particular type of equatorial coordinate reference system, relative to the ecliptic and equinox of that system. More...
class	supernovas::Galactic
	Galactic coordinates (l, b), representing the direction on the sky, relative to the Galactic plane and the nominal Galactic center location. More...
class	supernovas::Horizontal
	Horizontal (azimuth, elevation = Az/El) sky coordinates at a geodetic observing location, such as an observatory site, an aircraft, or a balloon. More...

Functions
Ecliptic	supernovas::Apparent::ecliptic () const
	Returns the apparent ecliptic coordinates on the sky, with respect to the true equinox of date.
Ecliptic	supernovas::Geometric::ecliptic () const
	Returns the geometric ecliptic coordinates, in the system in which the geometric positions and velocities were defined.
Galactic	supernovas::Apparent::galactic () const
	Returns the apparent galactic coordinates on the sky.
Galactic	supernovas::Geometric::galactic () const
	Returns the geometric galactic coordinates, in the system in which the geometric positions and velocities were defined.
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.
Ecliptic	supernovas::Equatorial::to_ecliptic () const
	Returns the equivalent ecliptic coordinates corresponding to these equatorial coordinates.
Ecliptic	supernovas::Galactic::to_ecliptic () const
	Converts these galactic coordinates to equivalent ICRS ecliptic coordinates.
Galactic	supernovas::Ecliptic::to_galactic () const
	Converts these ecliptic coordinates to equivalent Galactic coordinates.
Galactic	supernovas::Equatorial::to_galactic () const
	Returns the equivalent galactic coordinates corresponding to these equatorial coordinates.
Horizontal	supernovas::Apparent::to_horizontal () const
	Returns the apparent unrefracted horizontal coordinates for this position for a geodetic observer located on or near Earth's surface, or as an invalid set of coordinates if the observer location is not Earth bound.

Detailed Description

Expressing coordinates in non-equatorial systems, such as ecliptic, galactic, or local horizontal (for geodetic observer) coordinate systems.

Function Documentation

ecliptic() [1/2]

Ecliptic supernovas::Apparent::ecliptic

(

)

const

Returns the apparent ecliptic coordinates on the sky, with respect to the true equinox of date.

Returns

the apparent ecliptic coordinates with respect to the true equinox of date.

See also

equatorial(), galactic(), to_horizontal()

Equatorial::to_ecliptic()

References ecliptic(), equatorial(), and supernovas::Validating::is_valid().

Referenced by ecliptic().

ecliptic() [2/2]

Ecliptic supernovas::Geometric::ecliptic

(

)

const

Returns the geometric ecliptic coordinates, in the system in which the geometric positions and velocities were defined.

Note, that these coordinates are physical, and not what an observer would perceive at the time of observation, because:

• they are not corrected for aberration for a moving observer.
• they do not account for gravitational bending around massive Solar-system bodies, as light travels to the observer.

If you are interested in observable ecliptic coordinates, see Apparent::ecliptic() instead.

Returns

geometric ecliptic coordinates.

See also

Apparent::ecliptic(), equatorial(), galactic()

References equatorial(), supernovas::Validating::is_valid(), and supernovas::Equatorial::to_ecliptic().

galactic() [1/2]

Galactic supernovas::Apparent::galactic

(

)

const

Returns the apparent galactic coordinates on the sky.

Returns

the apparent galactic coordinates for this position.

See also

equatorial(), ecliptic(), to_horizontal()

Equatorial::to_galactic()

References equatorial(), galactic(), and supernovas::Validating::is_valid().

Referenced by galactic().

galactic() [2/2]

Galactic supernovas::Geometric::galactic

(

)

const

Returns the geometric galactic coordinates, in the system in which the geometric positions and velocities were defined.

Note, that these coordinates are physical, and not what an observer would perceive at the time of observation, because:

• they are not corrected for aberration for a moving observer.
• they do not account for gravitational bending around massive Solar-system bodies, as light travels to the observer.

If you are interested in observable galactic coordinates, see Apparent::galactic() instead.

Returns

geometric galactic coordinates.

See also

Apparent::galactic(), equatorial(), ecliptic()

References equatorial(), supernovas::Validating::is_valid(), and supernovas::Equatorial::to_galactic().

novas_e2h_offset()

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.

Converting between local flat projections and spherical coordinates usually requires a WCS projection.

REFERENCES:

1. Calabretta, M.R., & Greisen, E.W., (2002), Astronomy & Astrophysics, 395, 1077-1122.

Parameters

	dra	[arcsec] Projected ffset position in the apparent true-of-date R.A. direction. E.g. The projected offset between two RA coordinates at a same reference declination, is δRA = (RA2 - RA1) * cos(Dec0).
	ddec	[arcsec] Projected offset position in the apparent true-of-date declination direction.
	pa	[deg] Parallactic Angle
[out]	daz	[arcsec] Output offset position in the local azimuth direction. It can be a pointer to one of the input coordinates, or NULL if not required.
[out]	del	[arcsec] Output offset position in the local elevation direction. It can be a pointer to one of the input coordinates, or NULL if not required.

Returns

0

Since

1.3

Author

Attila Kovacs

See also

novas_h2e_offset(), novas_epa()

References novas_h2e_offset().

novas_epa()

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.

The PA is the angle between the local horizontal coordinate directions and the local true-of-date equatorial coordinate directions, at the given location and time. The polar wobble is not included in the calculation.

The Parallactic Angle is sometimes referrred to as the Vertical Position Angle (VPA). Both define the same quantity.

Parameters

ha	[h] Hour angle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source.
dec	[deg] Apparent (true-of-date) declination of observed source
lat	[deg] Geodetic latitude of observer

Returns

[deg] Parallactic Angle (PA). I.e., the clockwise position angle of the elevation direction w.r.t. the declination axis in the equatorial system. Same as the clockwise position angle of the declination direction w.r.t. the elevation axis, in the horizontal system.

Since

1.3

Author

Attila Kovacs

See also

novas_hpa(), novas_e2h_offset()

novas_h2e_offset()

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.

Converting between local flat projections and spherical coordinates usually requires a WCS projection.

REFERENCES:

1. Calabretta, M.R., & Greisen, E.W., (2002), Astronomy & Astrophysics, 395, 1077-1122.

Parameters

	daz	[arcsec] Projected offset position in the azimuth direction. The projected offset between two azimuth positions at the same reference elevation is δAz = (Az2 - Az1) * cos(El0).
	del	[arcsec] projected offset position in the elevation direction
	pa	[deg] Parallactic Angle
[out]	dra	[arcsec] Output offset position in the local true-of-date R.A. direction. It can be a pointer to one of the input coordinates, or NULL if not required.
[out]	ddec	[arcsec] Output offset position in the local true-of-date declination direction. It can be a pointer to one of the input coordinates, or NULL if not required.

Returns

0

Since

1.3

Author

Attila Kovacs

See also

novas_e2h_offset(), novas_hpa()

Referenced by novas_e2h_offset().

novas_hpa()

double novas_hpa	(	double	az,
		double	el,
		double	lat )

Returns the Parallactic Angle (PA) calculated for a horizontal Az/El location of the sky.

The PA is the angle between the local horizontal coordinate directions and the local true-of-date equatorial coordinate directions at the given location. The polar wobble is not included in the calculation.

The Parallactic Angle is sometimes referrred to as the Vertical Position Angle (VPA). Both define the same quantity.

Parameters

az	[deg] Azimuth angle
el	[deg] Elevation angle
lat	[deg] Geodetic latitude of observer

Returns

[deg] Parallactic Angle (PA). I.e., the clockwise position angle of the declination direction w.r.t. the elevation axis in the horizontal system. Same as the the clockwise position angle of the elevation direction w.r.t. the declination axis in the equatorial system.

Since

1.3

Author

Attila Kovacs

See also

novas_epa(), novas_h2e_offset()

novas_los_to_xyz()

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.

Parameters

	los	[arb.u.] Line-of-sight 3-vector (δφ, δθ, δr).
	lon	[deg] Line-of-sight longitude.
	lat	[deg] Line-of-sight latitude.
[out]	xyz	[arb.u.] Output rectangular equatorial 3-vector (δx, δy, δz), in the same units as the input. It may be the same vector as the input.

Returns

0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL).

Since

1.3

Author

Attila Kovacs

See also

novas_xyz_to_los(), novas_uvw_to_xyz()

Referenced by novas_uvw_to_xyz(), starvectors(), and transform_cat().

novas_uvw_to_xyz()

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.

u,v,w are Cartesian coordinates (u,v) along the local equatorial R.A. and declination directions as seen from a direction on the sky (w). As such, they are effectively ITRS-based line-of-sight (LOS) coordinates.

x,y,z are Cartesian coordinates w.r.t the Greenwich meridian in the ITRS frame. The directions are x: long=0, lat=0; y: long=90, lat=0; z: lat=90.

Parameters

	xyz	[arb.u.] Absolute or relative u,v,w coordinates (double[3]).
	ha	[h] Hourangle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source.
	dec	[deg] Apparent (true-of-date) declination of source
[out]	uvw	[arb.u.] Converted x,y,z coordinates (double[3]) in the same unit as uvw. It may be the same vector as the input.

Returns

0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL)

Since

1.3

Author

Attila Kovacs

See also

novas_xyz_to_uvw()

References novas_los_to_xyz().

novas_xyz_to_los()

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.

Parameters

	xyz	[arb.u.] Rectangular equatorial 3-vector (δx, δy, δz).
	lon	[deg] Line-of-sight longitude.
	lat	[deg] Line-of-sight latitude.
[out]	los	[arb.u.] Output line-of-sight 3-vector (δφ, δθ, δr), in the same units as the input. It may be the same vector as the input.

Returns

0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL).

Since

1.3

Author

Attila Kovacs

See also

novas_los_to_xyz(), novas_xyz_to_uvw()

Referenced by novas_xyz_to_uvw(), and transform_cat().

novas_xyz_to_uvw()

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.

x,y,z are Cartesian coordinates w.r.t the Greenwich meridian, in the ITRS frame. The directions are x: long=0, lat=0; y: long=90, lat=0; z: lat=90.

u,v,w are Cartesian coordinates (u,v) along the local equatorial R.A. and declination directions as seen from a direction on the sky (w). As such, they are effectively ITRS-based line-of-sight (LOS) coordinates.

Parameters

	xyz	[arb.u.] Absolute or relative x,y,z coordinates (double[3]).
	ha	[h] Hourangle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source.
	dec	[deg] Apparent (true-of-date) declination of source
[out]	uvw	[arb.u.] Converted u,v,w coordinates (double[3]) in same units as xyz. It may be the same vector as the input.

Returns

0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL)

Since

1.3

Author

Attila Kovacs

See also

novas_uvw_to_xyz()

References novas_xyz_to_los().

to_ecliptic() [1/2]

Ecliptic supernovas::Equatorial::to_ecliptic

(

)

const

Returns the equivalent ecliptic coordinates corresponding to these equatorial coordinates.

Returns

the ecliptic coordinates that represent the same position on sky as these equariorial coordinates.

See also

Ecliptic::to_equatorial(), to_galactic()

References dec(), supernovas::Angle::deg(), supernovas::Unit::deg, equ2ecl(), supernovas::TimeAngle::hours(), ira_equinox(), supernovas::Validating::is_valid(), NOVAS_CIRS, NOVAS_FULL_ACCURACY, NOVAS_TRUE_EQUINOX, ra(), and supernovas::Ecliptic::undefined().

Referenced by supernovas::Geometric::ecliptic(), supernovas::Galactic::to_ecliptic(), supernovas::Ecliptic::to_icrs(), supernovas::Ecliptic::to_j2000(), supernovas::Ecliptic::to_mod(), supernovas::Ecliptic::to_system(), and supernovas::Ecliptic::to_tod().

to_ecliptic() [2/2]

Ecliptic supernovas::Galactic::to_ecliptic

(

)

const

Converts these galactic coordinates to equivalent ICRS ecliptic coordinates.

Returns

the equivalent ICRS ecliptic coordinates.

See also

Ecliptic::to_galactic(), to_equatorial()

References supernovas::Validating::is_valid(), supernovas::Equatorial::to_ecliptic(), and to_equatorial().

to_galactic() [1/2]

Galactic supernovas::Ecliptic::to_galactic

(

)

const

Converts these ecliptic coordinates to equivalent Galactic coordinates.

Returns

the equivalent Galactic coordinates for the same place on sky.

See also

Galactic::to_ecliptic(), to_equatorial()

References supernovas::Validating::is_valid(), to_equatorial(), and supernovas::Equatorial::to_galactic().

to_galactic() [2/2]

Galactic supernovas::Equatorial::to_galactic

(

)

const

Returns the equivalent galactic coordinates corresponding to these equatorial coordinates.

Returns

the galactic coordinates that represent the same position on sky as these equariorial coordinates.

See also

Galactic::to_equatorial(), to_ecliptic()

References dec(), supernovas::Angle::deg(), supernovas::Unit::deg, equ2gal(), supernovas::TimeAngle::hours(), supernovas::Validating::is_valid(), supernovas::Spherical::latitude(), supernovas::Spherical::longitude(), ra(), to_icrs(), and supernovas::Galactic::undefined().

Referenced by supernovas::Geometric::galactic(), and supernovas::Ecliptic::to_galactic().

to_horizontal()

Horizontal supernovas::Apparent::to_horizontal

(

)

const

Returns the apparent unrefracted horizontal coordinates for this position for a geodetic observer located on or near Earth's surface, or as an invalid set of coordinates if the observer location is not Earth bound.

It's best practice to check if the returned coordinates are valid, e.g. as:

Apparent app = ...;
Horizontal h = app.to_horizontal();
if(!h) {
  // Oops, could not provide valid horizontal coordinates...
  return;
}

Returns

the unrefracted (astrometric) horizontal position on the Earth-bound observer's sky, or else Horizontal::undefined() if the observer is not on or near Earth's surface.

See also

equatorial(), ecliptic(), galactic()

Horizontal::to_apparent(), GeodeticObserver

References supernovas::Unit::deg, supernovas::Validating::is_valid(), novas_app_to_hor(), NOVAS_TOD, to_horizontal(), supernovas::Horizontal::undefined(), and vector2radec().

Referenced by to_horizontal().