Note

This is an old version of the documentation. See http://docs.astropy.org/en/stable for the latest version.

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.

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
```

The `Coordinates` subpackage also provides a quick way to get coordinates
for named objects (with an internet connection). All subclasses of
`SphericalCoordinatesBase` have a special
class method, `from_name()`, that accepts a string and queries Sesame to retrieve coordinates for
that object:

```
>>> c = coord.ICRSCoordinates.from_name("M42")
>>> c.ra, c.dec
(<RA 83.82208 deg>, <Dec -5.39111 deg>)
```

This works for any subclass of `SphericalCoordinatesBase`:

```
>>> c = coord.GalacticCoordinates.from_name("M42")
>>> c.l, c.b
(<Angle -150.98622 deg>, <Angle -19.38162 deg>)
```

Note

This is intended to be a convenience, and is very simple. If you need precise coordinates for an object you should find the appropriate reference for that measurement and input the coordinates manually.

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

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??
```

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.

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.

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. |

get_icrs_coordinates(name) |
Retrieve an ICRSCoordinates object by using an online name resolving service to retrieve coordinates for the specified name. |

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. |

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. |