Astronomical Coordinate Systems (astropy.coordinates)

Introduction

The coordinates package provides classes for representing celestial coordinates, as well as tools for converting between standard systems in a uniform way.

Note

The current coordinates framework only accepts scalar coordinates, i.e. one coordinate per object. In the next release it will be expanded to accept arrays of coordinates.

Warning

coordinates is currently a work-in-progress, and thus it is possible there will be significant API changes in later versions of Astropy.

Getting Started

Coordinate objects are instantiated with a flexible and natural approach that supports both numeric angle values and (limited) string parsing:

>>> from astropy import coordinates as coord
>>> from astropy import units as u
>>> coord.ICRSCoordinates(ra=10.68458, dec=41.26917, unit=(u.degree, u.degree))
<ICRSCoordinates RA=10.68458 deg, Dec=41.26917 deg>
>>> coord.ICRSCoordinates('00h42m44.3s +41d16m9s')
<ICRSCoordinates RA=10.68458 deg, Dec=41.26917 deg>

The individual components of a coordinate are Angle objects, and their values are accessed using special attributes:

>>> c = coord.ICRSCoordinates(ra=10.68458, dec=41.26917, unit=(u.degree, u.degree))
>>> c.ra
<RA 10.68458 deg>
>>> c.ra.hours
0.7123053333333333
>>> c.ra.hms
(0.0, 42, 44.2992000000001)
>>> c.dec
<Dec 41.26917 deg>
>>> c.dec.radians
0.7202828960652683

To convert to some other coordinate system, the easiest method is to use attribute-style access with short names for the built-in systems, but explicit transformations via the transform_to method are also available:

>>> c.galactic
<GalacticCoordinates l=121.17422 deg, b=-21.57283 deg>
>>> c.transform_to(coord.GalacticCoordinates)
<GalacticCoordinates l=121.17422 deg, b=-21.57283 deg>

Distances from the origin (which is system-dependent, but often the Earth center) can also be assigned to a coordinate. This specifies a unique point in 3D space, which also allows conversion to cartesian coordinates:

>>> c = coord.ICRSCoordinates(ra=10.68458, dec=41.26917, unit=(u.degree, u.degree), distance=coord.Distance(770, u.kpc))
>>> c.x
568.7128654235232
>>> c.y
107.3008974042025
>>> c.z
507.88994291875713

Using astropy.coordinates

More details of using astropy.coordinates are provided in the following sections:

• Working with Angles
• Creating Coordinate Objects
• Separations
• Distances and Cartesian Representations
• Transforming Between Systems
• Designing Coordinate Systems

In addition, another resource for the capabilities of this package is the astropy.coordinates.tests.test_api testing file. It showcases most of the major capabilities of the package, and hence is a useful supplement to this document. You can see it by either looking at it directly if you downloaded a copy of the astropy source code, or typing the following in an IPython session:

In [1]: from astropy.coordinates.tests import test_api
In [2]: test_api??

See Also

Some references particularly useful in understanding subtleties of the coordinate systems implemented here include:

• Standards Of Fundamental Astronomy

  The definitive implementation of IAU-defined algorithms. The “SOFA Tools for Earth Attitude” document is particularly valuable for understanding the latest IAU standards in detail.

• USNO Circular 179

  A useful guide to the IAU 2000/2003 work surrounding ICRS/IERS/CIRS and related problems in precision coordinate system work.

• Meeus, J. “Astronomical Algorithms”

  A valuable text describing details of a wide range of coordinate-related problems and concepts.

Reference/API

astropy.coordinates Module

This subpackage contains classes and functions for celestial coordinates of astronomical objects. It also contains a framework for conversions between coordinate systems.

The diagram below shows all of the coordinate systems built into the coordinates package, their aliases (usable for converting other coordinates to them using attribute-style access) and the pre-defined transformations between them. The user is free to override any of these transformations by defining new trasnformation between these systems, but the pre-defined transformations should be sufficient for typical usage.

The graph also indicates the priority for each transformation as a number next to the arrow. These priorities are used to decide the preferred order when two trasnformation paths have the same number of steps. These priorities are defined such that path with a smaller total priority are favored over larger. E.g., the path from ICRSCoordinates to GalacticCoordinates goes through FK5Coordinates because the total path length is 2 instead of 2.03.

Functions

cartesian_to_spherical(x, y, z)	Converts 3D rectangular cartesian coordinates to spherical polar coordinates.
coordinate_alias(name[, coordcls])	Gives a short name to this coordinate system, allowing other coordinate objects to convert to this one using attribute-style access.
dynamic_transform_matrix(fromsys, tosys[, ...])	A function decorator for defining transformations between coordinate systems using a function that yields a matrix.
spherical_to_cartesian(r, lat, lon)	Converts spherical polar coordinates to rectangular cartesian coordinates.
static_transform_matrix(fromsys, tosys[, ...])	A function decorator for defining transformations between coordinate systems using a matrix.
transform_function(fromsys, tosys[, ...])	A function decorator for defining transformations between coordinate systems.

Classes

Angle(angle[, unit, bounds])	An angle.
AngularSeparation(lat1, lon1, lat2, lon2, units)	An on-sky separation between two directions.
BoundsError	Raised when an angle is outside of its user-specified bounds.
CartesianPoints(x, y, z[, unit])	A cartesian representation of a point in three-dimensional space.
CompositeStaticMatrixTransform(fromsys, ...)	A MatrixTransform constructed by combining a sequence of matricies together.
ConvertError	Raised if a coordinate system cannot be converted to another
Dec(angle[, unit])	Represents a declination value.
Distance(*args, **kwargs)	A one-dimensional distance.
DynamicMatrixTransform(fromsys, tosys, ...)	A coordinate transformation specified as a function that yields a 3 x 3 cartesian transformation matrix.
FK4Coordinates(*args, **kwargs)	A coordinate in the FK4 system.
FK4NoETermCoordinates(*args, **kwargs)	A coordinate in the FK4 system.
FK5Coordinates(*args, **kwargs)	A coordinate in the FK5 system.
FunctionTransform(fromsys, tosys, func[, ...])	A coordinate transformation defined by a function that simply accepts a coordinate object and returns the transformed coordinate object.
GalacticCoordinates(*args, **kwargs)	A coordinate in Galactic Coordinates.
HorizontalCoordinates(*args, **kwargs)	A coordinate in the Horizontal or “az/el” system.
ICRSCoordinates(*args, **kwargs)	A coordinate in the ICRS.
IllegalHourError(hour)	Raised when an hour value is not in the range [0,24).
IllegalMinuteError(minute)	Raised when an minute value is not in the range [0,60).
IllegalSecondError(second)	Raised when an second value (time) is not in the range [0,60).
RA(angle[, unit])	An object that represents a right ascension angle.
RangeError	Raised when some part of an angle is out of its valid range.
SphericalCoordinatesBase(*args, **kwargs)	Abstract superclass for all coordinate classes representing points in three dimensions.
StaticMatrixTransform(fromsys, tosys, matrix)	A coordinate transformation defined as a 3 x 3 cartesian transformation matrix.
UnitsError	Raised if units are missing or invalid.

Class Inheritance Diagram

[edit this page on github]