Celestial Coordinates

class coord.CelestialCoord(ra, dec=None)

This class defines a position on the celestial sphere, normally given by two angles, ra and dec.

This class can be used to perform various calculations in spherical coordinates, such as finding the angular distance between two points in the sky, calculating the angles in spherical triangles, projecting from sky coordinates onto a Euclidean tangent plane, etc.

Initialization:

A CelestialCoord object is constructed from the right ascension and declination:

coord.CelestialCoord.__init__()

>>> c = CelestialCoord(ra=12*hours, dec=31*degrees)
>>> print(c)
coord.CelestialCoord(3.14159265359 radians, 0.541052068118 radians)

Attributes:

A CelestialCoord has the following (read-only) attributes:

ra:The right ascension (an Angle instance) dec:The declination (an Angle instance)

>>> print(c.ra / degrees, c.dec / degrees)
180.0 31.0

In addition there is a convenience access property that returns ra and dec in radians.

rad:A tuple (ra.rad, dec.rad)

>>> print(c.rad)
(3.141592653589793, 0.5410520681182421)

Spherical Geometry:

The basic spherical geometry operations are available to work with spherical triangles

For three coordinates cA, cB, cC making a spherical triangle, one can calculate the sides and angles via:

coord.CelestialCoord.distanceTo()

coord.CelestialCoord.angleBetween()

>>> cA = CelestialCoord(0 * degrees, 0 * degrees)
>>> cB = CelestialCoord(0 * degrees, 10 * degrees)
>>> cC = CelestialCoord(10 * degrees, 0 * degrees)
>>> a = cB.distanceTo(cC)
>>> b = cC.distanceTo(cA)
>>> c = cA.distanceTo(cB)
>>> print(a / degrees, b / degrees, c / degrees)
14.1060442606 10.0 10.0
>>> A = cA.angleBetween(cB, cC)
>>> B = cB.angleBetween(cC, cA)
>>> C = cC.angleBetween(cA, cB)
>>> print(A / degrees, B / degrees, C / degrees)
90.0 45.4385485867 45.4385485867

Projections:

Local tangent plane projections of an area of the sky can be performed using the project method:

coord.CelestialCoord.project()

>>> center = CelestialCoord(ra=10*hours, dec=30*degrees)
>>> sky_coord = CelestialCoord(ra=10.5*hours, dec=31*degrees)
>>> print(sky_coord)
coord.CelestialCoord(2.74889357189 radians, 0.541052068118 radians)
>>> u, v = center.project(sky_coord)
>>> print(u / degrees, v / degrees)
-6.45237127534 1.21794987289

and back:

coord.CelestialCoord.deproject()

>>> sky_coord = center.deproject(u,v)
>>> print(sky_coord)
coord.CelestialCoord(2.74889357189 radians, 0.541052068118 radians)

where u and v are Angles and center and sky_coord are CelestialCoords.

__init__(ra, dec=None)

Parameters:

• ra – The right ascension. Must be an Angle instance.
• dec – The declination. Must be an Angle instance.

ra

A read-only attribute, giving the Right Ascension as an Angle

dec

A read-only attribute, giving the Declination as an Angle

rad

A convenience property, giving a tuple (ra.rad, dec.rad)

get_xyz()

Get the (x,y,z) coordinates on the unit sphere corresponding to this (RA, Dec).

\[\begin{split}x &= \cos(dec) \cos(ra) \\ y &= \cos(dec) \sin(ra) \\ z &= \sin(dec)\end{split}\]

Returns:a tuple (x,y,z)

static from_xyz(x, y, z)

Construct a CelestialCoord from a given (x,y,z) position in three dimensions.

The 3D (x,y,z) position does not need to fall on the unit sphere. The RA, Dec will be inferred from the relations:

\[\begin{split}x &= r \cos(dec) \cos(ra) \\ y &= r \cos(dec) \sin(ra) \\ z &= r \sin(dec)\end{split}\]

where \(r\) is arbitrary.

Parameters:

• x – The x position in 3 dimensions. Corresponds to r cos(dec) cos(ra)
• y – The y position in 3 dimensions. Corresponds to r cos(dec) sin(ra)
• z – The z position in 3 dimensions. Corresponds to r sin(dec)

Returns:

a CelestialCoord instance

normal()

Return the coordinate in the “normal” convention of having 0 <= ra < 24 hours.

This convention is not enforced on construction, so this function exists to make it easy to convert if desired.

Functions such as from_galactic and from_xyz will return normal coordinates.

distanceTo(coord2)

Returns the great circle distance between this coord and another one. The return value is an Angle object

Parameters:coord2 – The CelestialCoordinate to calculate the distance to. Returns:the great circle distance to coord2.

angleBetween(coord2, coord3)

Find the open angle at the location of the current coord between coord2 and coord3.

The current coordinate along with the two other coordinates form a spherical triangle on the sky. This function calculates the angle between the two sides at the location of the current coordinate.

Note that this returns a signed angle. The angle is positive if the sweep direction from coord2 to coord3 is counter-clockwise (as observed from Earth). It is negative if the direction is clockwise.

Parameters:

• coord2 – A second CelestialCoord
• coord3 – A third CelestialCoord

Returns:

the angle between the great circles joining the other two coordinates to the current coordinate.

area(coord2, coord3)

Find the area of a spherical triangle in steradians.

The current coordinate along with the two other coordinates form a spherical triangle on the sky. This function calculates the area of that spherical triangle, which is measured in steradians (i.e. surface area of the triangle on the unit sphere).

Parameters:

• coord2 – A second CelestialCoord
• coord3 – A third CelestialCoord

Returns:

the area in steradians of the given spherical triangle.

project(coord2, projection=None)

Use the currect coord as the center point of a tangent plane projection to project the coord2 coordinate onto that plane.

This function return a tuple (u,v) in the Euclidean coordinate system defined by a tangent plane projection around the current coordinate, with +v pointing north and +u pointing west. (i.e. to the right on the sky if +v is up.)

There are currently four options for the projection, which you can specify with the optional projection keyword argument:

gnomonic:[default] uses a gnomonic projection (i.e. a projection from the center of the sphere, which has the property that all great circles become straight lines. For more information, see http://mathworld.wolfram.com/GnomonicProjection.html This is the usual TAN projection used by most FITS images. stereographic:uses a stereographic proejection, which preserves angles, but not area. For more information, see http://mathworld.wolfram.com/StereographicProjection.html lambert:uses a Lambert azimuthal projection, which preserves area, but not angles. For more information, see http://mathworld.wolfram.com/LambertAzimuthalEqual-AreaProjection.html postel:uses a Postel equidistant proejection, which preserves distances from the projection point, but not area or angles. For more information, see http://mathworld.wolfram.com/AzimuthalEquidistantProjection.html

The distance or angle errors increase with distance from the projection point of course.

Parameters:

• coord2 – The coordinate to project onto the tangent plane.
• projection – The name of the projection to be used. [default: gnomonic, see above for other options]

Returns:

(u,v) as Angle instances

project_rad(ra, dec, projection=None)

This is basically identical to the project() function except that the input ra, dec are given in radians rather than packaged as a CelestialCoord object and the returned u,v are given in radians.

The main advantage to this is that it will work if ra and dec are NumPy arrays, in which case the output u, v will also be NumPy arrays.

Parameters:

• ra – The right ascension in radians to project onto the tangent plane.
• dec – The declination in radians to project onto the tangent plane.
• projection – The name of the projection to be used. [default: gnomonic, see project docstring for other options]

Returns:

(u,v) in radians

deproject(u, v, projection=None)

Do the reverse process from the project() function.

i.e. This takes in a position (u,v) and returns the corresponding celestial coordinate, using the current coordinate as the center point of the tangent plane projection.

Parameters:

• u – The u position on the tangent plane to deproject (must be an Angle instance)
• v – The v position on the tangent plane to deproject (must be an Angle instance)
• projection – The name of the projection to be used. [default: gnomonic, see project docstring for other options]

Returns:

the corresponding CelestialCoord for that position.

deproject_rad(u, v, projection=None)

This is basically identical to the deproject() function except that the output ra, dec are returned as a tuple (ra, dec) in radians rather than packaged as a CelestialCoord object and u and v are in radians rather than Angle instances.

The main advantage to this is that it will work if u and v are NumPy arrays, in which case the output ra, dec will also be NumPy arrays.

Parameters:

• u – The u position in radians on the tangent plane to deproject
• v – The v position in radians on the tangent plane to deproject
• projection – The name of the projection to be used. [default: gnomonic, see project docstring for other options]

Returns:

the corresponding RA, Dec in radians

jac_deproject(u, v, projection=None)

Return the jacobian of the deprojection.

i.e. if the input position is (u,v) then the return matrix is

\[\begin{split}J \equiv \begin{bmatrix} J00 & J01 \\ J10 & J11 \end{bmatrix} = \begin{bmatrix} d\textrm{ra}/du \cos(\textrm{dec}) & d\textrm{ra}/dv \cos(\textrm{dec}) \\ d\textrm{dec}/du & d\textrm{dec}/dv \end{bmatrix}\end{split}\]

Parameters:

• u – The u position (as an Angle instance) on the tangent plane
• v – The v position (as an Angle instance) on the tangent plane
• projection – The name of the projection to be used. [default: gnomonic, see project docstring for other options]

Returns:

the Jacobian as a 2x2 numpy array [[J00, J01], [J10, J11]]

jac_deproject_rad(u, v, projection=None)

Equivalent to jac_deproject, but the inputs are in radians and may be numpy arrays.

Parameters:

• u – The u position (in radians) on the tangent plane
• v – The v position (in radians) on the tangent plane
• projection – The name of the projection to be used. [default: gnomonic, see project docstring for other options]

Returns:

the Jacobian as a 2x2 numpy array [[J00, J01], [J10, J11]]

precess(from_epoch, to_epoch)

This function precesses equatorial ra and dec from one epoch to another.

It is adapted from a set of fortran subroutines based on (a) pages 30-34 of the Explanatory Supplement to the AE, (b) Lieske, et al. (1977) A&A 58, 1-16, and (c) Lieske (1979) A&A 73, 282-284.

Parameters:

• from_epoch – The epoch of the current coordinate
• to_epoch – The epoch of the returned precessed coordinate

Returns:

a CelestialCoord object corresponding to the precessed position.

galactic(epoch=2000.0)

Get the longitude and latitude in galactic coordinates corresponding to this position.

Parameters:epoch – The epoch of the current coordinate. [default: 2000.] Returns:the longitude and latitude as a tuple (el, b), given as Angle instances.

static from_galactic(el, b, epoch=2000.0)

Create a CelestialCoord from the given galactic coordinates

Parameters:

• el – The longitude in galactic coordinates (an Angle instance)
• b – The latitude in galactic coordinates (an Angle instance)
• epoch – The epoch of the returned coordinate. [default: 2000.]

Returns:

the CelestialCoord corresponding to these galactic coordinates.

ecliptic(epoch=2000.0, date=None)

Get the longitude and latitude in ecliptic coordinates corresponding to this position.

The epoch parameter is used to get an accurate value for the (time-varying) obliquity of the ecliptic. The formulae for this are quite straightforward. It requires just a single parameter for the transformation, the obliquity of the ecliptic (the Earth’s axial tilt).

Parameters:

• epoch – The epoch to be used for estimating the obliquity of the ecliptic, if date is None. But if date is given, then use that to determine the epoch. [default: 2000.]
• date – If a date is given as a python datetime object, then return the position in ecliptic coordinates with respect to the sun position at that date. If None, then return the true ecliptic coordiantes. [default: None]

Returns:

the longitude and latitude as a tuple (lambda, beta), given as Angle instances.

static from_ecliptic(lam, beta, epoch=2000.0, date=None)

Create a CelestialCoord from the given ecliptic coordinates

Parameters:

• lam – The longitude in ecliptic coordinates (an Angle instance)
• beta – The latitude in ecliptic coordinates (an Angle instance)
• epoch – The epoch to be used for estimating the obliquity of the ecliptic, if date is None. But if date is given, then use that to determine the epoch. [default: 2000.]
• date – If a date is given as a python datetime object, then return the position in ecliptic coordinates with respect to the sun position at that date. If None, then return the true ecliptic coordiantes. [default: None]

Returns:

the CelestialCoord corresponding to these ecliptic coordinates.

coord._CelestialCoord(ra, dec)

Equivalent to CeletialCoord(ra,dec), but without the normal sanity checks.

Parameters:

• ra – The right ascension. Must be an Angle instance.
• dec – The declination. Must be an Angle instance.