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 a
variety of celestial/spatial coordinates, as well as tools for
converting between common coordinate systems in a uniform way.

Note

If you have existing code that uses `coordinates` functionality from
Astropy version 0.3.x or earlier, please see the section on Migrating from
pre-v0.4 coordinates. The interface has changed in ways that are not
backward compatible in many circumstances.

The simplest way to use `coordinates` is to use the `SkyCoord`
class. `SkyCoord` objects are instantiated with a flexible and natural
approach that supports inputs provided in a number of convenient
formats. The following ways of initializing a coordinate are all
equivalent:

```
>>> from astropy import units as u
>>> from astropy.coordinates import SkyCoord
>>> c = SkyCoord(ra=10.625*u.degree, dec=41.2*u.degree, frame='icrs')
>>> c = SkyCoord(10.625, 41.2, frame='icrs', unit='deg')
>>> c = SkyCoord('00h42m30s', '+41d12m00s', frame='icrs')
>>> c = SkyCoord('00h42.5m', '+41d12m', frame='icrs')
>>> c = SkyCoord('00 42 30 +41 12 00', frame='icrs', unit=(u.hourangle, u.deg))
>>> c = SkyCoord('00:42.5 +41:12', frame='icrs', unit=(u.hourangle, u.deg))
>>> c
<SkyCoord (ICRS): (ra, dec) in deg
(10.625, 41.2)>
```

The examples above illustrate a few simple rules to follow when creating a coordinate object:

- Coordinate values can be provided either as unnamed positional arguments or
via keyword arguments like
`ra`,`dec`,`l`, or`b`(depending on the frame). - Coordinate frame value is optional and can be specified as a positional
argument or via the
`frame`keyword. - Angle units must be specified, either in the values themselves
(e.g.
`10.5*u.degree`or`'+41d12m00s'`) or via the`unit`keyword.

The individual components of equatorial coordinates are
`Longitude` or `Latitude`
objects, which are specialized versions of the general
`Angle` class. The component values are accessed
using aptly named attributes:

```
>>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree)
>>> c.ra
<Longitude 10.68458 deg>
>>> c.ra.hour
0.7123053333333335
>>> c.ra.hms
hms_tuple(h=0.0, m=42.0, s=44.299200000000525)
>>> c.dec
<Latitude 41.26917 deg>
>>> c.dec.degree
41.26917
>>> c.dec.radian
0.7202828960652683
```

Coordinates can easily be converted to strings using the
`to_string()` method:

```
>>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree)
>>> c.to_string('decimal')
'10.6846 41.2692'
>>> c.to_string('dms')
'10d41m04.488s 41d16m09.012s'
>>> c.to_string('hmsdms')
'00h42m44.2992s +41d16m09.012s'
```

For more control over the string formatting, use the
`to_string` method of the individual
components:

```
>>> c.ra.to_string(decimal=True)
'10.6846'
>>> c.dec.to_string(format='latex')
'$41^\\circ16{}^\\prime09.012{}^{\\prime\\prime}$'
>>> msg = 'My coordinates are: ra="{0}"" dec="{1}"'
>>> msg.format(c.ra.to_string(sep=':'), c.dec.to_string(sep=':'))
'My coordinates are: ra="10:41:04.488"" dec="41:16:09.012"'
```

Many of the above examples did not explicitly specify the coordinate frame.
This is fine if you do not need to transform to other frames or compare with
coordinates defined in a different frame. However, to use the full power of
`coordinates`, you should specify the reference frame your coordinates
are defined in:

```
>>> c_icrs = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree, frame='icrs')
```

Once you’ve defined the frame of your coordinates, you can transform from that
frame to another frame. You can do this a few different ways: For more control,
you can use the `transform_to` method, which
accepts a frame name, frame class, or frame instance:

```
>>> from astropy.coordinates import FK5
>>> c_icrs.galactic
<SkyCoord (Galactic): (l, b) in deg
(121.174241811, -21.5728855724)>
>>> c_fk5 = c_icrs.transform_to('fk5') # c_icrs.fk5 does the same thing
>>> c_fk5
<SkyCoord (FK5: equinox=J2000.000): (ra, dec) in deg
(10.6845915393, 41.2691714591)>
>>> c_fk5.transform_to(FK5(equinox='J1975')) # precess to a different equinox
<SkyCoord (FK5: equinox=J1975.000): (ra, dec) in deg
(10.3420913461, 41.1323211229)>
```

This form of `transform_to` also makes it
straightforward to convert from celestial coordinates to
`AltAz` coordinates, allowing the use of `SkyCoord`
as a tool for planning observations. For a more complete example of
this, see *Example: Observation Planning*.

`SkyCoord` and all other `coordinates` objects also support
array coordinates. These work the same as single-value coordinates, but
they store multiple coordinates in a single object. When you’re going
to apply the same operation to many different coordinates (say, from a
catalog), this is a better choice than a list of `SkyCoord` objects,
because it will be *much* faster than applying the operation to each
`SkyCoord` in a for loop.

```
>>> SkyCoord(ra=[10, 11]*u.degree, dec=[41, -5]*u.degree)
<SkyCoord (ICRS): (ra, dec) in deg
[(10.0, 41.0), (11.0, -5.0)]>
```

So far we have been using a spherical coordinate representation in the all the
examples, and this is the default for the built-in frames. Frequently it is
convenient to initialize or work with a coordinate using a different
representation such as cartesian or cylindrical. This can be done by setting
the `representation` for either `SkyCoord` objects or low-level frame
coordinate objects:

```
>>> c = SkyCoord(x=1, y=2, z=3, unit='kpc', frame='icrs', representation='cartesian')
>>> c
<SkyCoord (ICRS): (x, y, z) in kpc
(1.0, 2.0, 3.0)>
>>> c.x, c.y, c.z
(<Quantity 1.0 kpc>, <Quantity 2.0 kpc>, <Quantity 3.0 kpc>)
>>> c.representation = 'cylindrical'
>>> c
<SkyCoord (ICRS): (rho, phi, z) in (kpc, deg, kpc)
(2.2360679775, 63.4349488229, 3.0)>
>>> c.phi
<Angle 63.434948... deg>
>>> c.phi.to(u.radian)
<Angle 1.107148... rad>
>>> c.representation = 'spherical'
>>> c
<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, kpc)
(63.4349488229, 53.3007747995, 3.74165738677)>
>>> c.representation = 'unitspherical'
>>> c
<SkyCoord (ICRS): (ra, dec) in deg
(63.4349488229, 53.3007747995)>
```

`SkyCoord` defines a number of convenience methods as well, like on-sky
separation between two coordinates and catalog matching (detailed in
*Matching Catalogs*):

```
>>> c1 = SkyCoord(ra=10*u.degree, dec=9*u.degree, frame='icrs')
>>> c2 = SkyCoord(ra=11*u.degree, dec=10*u.degree, frame='fk5')
>>> c1.separation(c2) # Differing frames handled correctly
<Angle 1.4045335865905868 deg>
```

Distance from the origin (which is system-dependent, but often the Earth
center) can also be assigned to a `SkyCoord`. With two angles and a
distance, a unique point in 3D space is available, which also allows
conversion to the Cartesian representation of this location:

```
>>> from astropy.coordinates import Distance
>>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree, distance=770*u.kpc)
>>> c.cartesian.x
<Quantity 568.7128654235232 kpc>
>>> c.cartesian.y
<Quantity 107.3008974042025 kpc>
>>> c.cartesian.z
<Quantity 507.88994291875713 kpc>
```

With distances assigned, `SkyCoord` convenience methods are more powerful, as
they can make use of the 3D information. For example:

```
>>> c1 = SkyCoord(ra=10*u.degree, dec=9*u.degree, distance=10*u.pc, frame='icrs')
>>> c2 = SkyCoord(ra=11*u.degree, dec=10*u.degree, distance=11.5*u.pc, frame='icrs')
>>> c1.separation_3d(c2)
<Distance 1.5228602415117989 pc>
```

Finally, the `astropy.coordinates` subpackage also provides a quick way to get
coordinates for named objects assuming you have an active internet
connection. The `from_name` method of `SkyCoord`
uses Sesame to retrieve coordinates
for a particular named object:

```
>>> SkyCoord.from_name("M42")
<SkyCoord (ICRS): (ra, dec) in deg
(83.82208, -5.39111)>
```

Note

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

Note

The `coordinates` package from v0.4 onward builds from
previous versions of the package, and more detailed information and
justification of the design is available in APE (Astropy Proposal for Enhancement) 5.

Here we provide an overview of the package and associated framework.
This background information is not necessary for simply using
`coordinates`, particularly if you use the `SkyCoord` high-
level class, but it is helpful for more advanced usage, particularly
creating your own frame, transformations, or representations. Another
useful piece of background information are some
*Important Definitions* as they are used in
`coordinates`.

`coordinates` is built on a three-tiered system of objects:
representations, frames, and a high-level class. Representations
classes are a particular way of storing a three-dimensional data point
(or points), such as Cartesian coordinates or spherical polar
coordinates. Frames are particular reference frames like FK5 or ICRS,
which may store their data in different representations, but have well-
defined transformations between each other. These transformations are
all stored in the `astropy.coordinates.frame_transform_graph`, and new
transformations can be created by users. Finally, the high-level class
(`SkyCoord`) uses the frame classes, but provides a more accessible
interface to these objects as well as various convenience methods and
more string-parsing capabilities.

Separating these concepts makes it easier to extend the functionality of
`coordinates`. It allows representations, frames, and
transformations to be defined or extended separately, while still
preserving the high-level capabilities and simplicity of the `SkyCoord`
class.

More detailed information on using the package is provided on separate pages, listed below.

- Working with Angles
- Using the SkyCoord High-level Class
- Transforming Between Systems
- Example: Observation Planning
- Formatting Coordinate Strings
- Separations, Catalog Matching, and Related Functionality
- Using and Designing Coordinate Representations
- Using and Designing Coordinate Frames
- Example: Defining A Coordinate Frame for the Sgr Dwarf
- Important Definitions
- Transforming to Galactocentric coordinates

In addition, another resource for the capabilities of this package is the
`astropy.coordinates.tests.test_api_ape5` 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_ape5
In [2]: test_api_ape5??
```

For typical users, the major change is that the recommended way to use
coordinate functionality is via the `SkyCoord` class,
instead of classes like `ICRS` classes (now called
“frame classes”).

For most users of pre-v0.4 coordinates, this means that the best way to adapt old code to the new framework is to change code like:

```
>>> from astropy import units as u
>>> from astropy.coordinates import ICRS # or FK5, or Galactic, or similar
>>> coordinate = ICRS(123.4*u.deg, 56.7*u.deg)
```

to instead be:

```
>>> from astropy import units as u
>>> from astropy.coordinates import SkyCoord
>>> coordinate = SkyCoord(123.4*u.deg, 56.7*u.deg, frame='icrs')
```

Note that usage like:

```
>>> coordinate = ICRS(123.4, 56.7, unit=('deg', 'deg')) # NOT RECOMMENDED!
```

will continue to work in v0.4, but will yield a `SkyCoord`
instead of an `ICRS` object (the former behaves
more like the pre-v0.4 `ICRS`). This compatibility
feature will issue a deprecation warning, and will be removed in the next major
version, so you should update your code to use `SkyCoord`
directly by the next release.

Users should also be aware that if they continue to use the first form (directly
creating `ICRS` frame objects), old code may still
work if it uses basic coordinate functionality, but many of the
convenience functions like catalog matching or attribute-based
transforms like `coordinate.galactic` will no longer work. These
features are now all in `SkyCoord`.

For advanced users or developers who have defined their own coordinates,
take note that the extensive internal changes will require re-writing
user-defined coordinate frames. The *Example: Defining A Coordinate Frame for the Sgr Dwarf* document has
been updated for the new framework to provide a worked example of how
custom coordinates work.

More detailed information about the new framework and using it to define
custom coordinates is available at *Overview of astropy.coordinates concepts*,
*Important Definitions*, *Defining a New Frame*,
and *Creating your own representations*.

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

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

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

- IERS Conventions (2010)
An exhaustive reference covering the ITRS, the IAU2000 celestial coordinates framework, and other related details of modern coordinate conventions.

- 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 (useful 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 transformations
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 transformation paths have the same number
of steps. These priorities are defined such that the path with a
*smaller* total priority is favored.

cartesian_to_spherical(x, y, z) |
Converts 3D rectangular cartesian coordinates to spherical polar coordinates. |

concatenate(coords) |
Combine multiple coordinate objects into a single SkyCoord. |

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

get_sun(time) |
Determines the location of the sun at a given time, in geocentric coordinates. |

match_coordinates_3d(matchcoord, catalogcoord) |
Finds the nearest 3-dimensional matches of a coordinate or coordinates in a set of catalog coordinates. |

match_coordinates_sky(matchcoord, catalogcoord) |
Finds the nearest on-sky matches of a coordinate or coordinates in a set of catalog coordinates. |

search_around_3d(coords1, coords2, distlimit) |
Searches for pairs of points that are at least as close as a specified distance in 3D space. |

search_around_sky(coords1, coords2, seplimit) |
Searches for pairs of points that have an angular separation at least as close as a specified angle. |

spherical_to_cartesian(r, lat, lon) |
Converts spherical polar coordinates to rectangular cartesian coordinates. |

AltAz(*args, **kwargs) |
A coordinate or frame in the Altitude-Azimuth system (Horizontal coordinates). |

Angle |
One or more angular value(s) with units equivalent to radians or degrees. |

BaseCoordinateFrame(*args, **kwargs) |
The base class for coordinate frames. |

BaseRepresentation |
Base Representation object, for representing a point in a 3D coordinate system. |

BoundsError |
Raised when an angle is outside of its user-specified bounds. |

CIRS(*args, **kwargs) |
A coordinate or frame in the Celestial Intermediate Reference System (CIRS). |

CartesianRepresentation(x[, y, z, copy]) |
Representation of points in 3D cartesian coordinates. |

CompositeTransform(transforms, fromsys, tosys) |
A transformation constructed by combining together a series of single-step transformations. |

ConvertError |
Raised if a coordinate system cannot be converted to another |

CoordinateTransform(fromsys, tosys[, ...]) |
An object that transforms a coordinate from one system to another. |

CylindricalRepresentation(rho, phi, z[, copy]) |
Representation of points in 3D cylindrical coordinates. |

Distance |
A one-dimensional distance. |

DynamicMatrixTransform(matrix_func, fromsys, ...) |
A coordinate transformation specified as a function that yields a 3 x 3 cartesian transformation matrix. |

EarthLocation |
Location on the Earth. |

EarthLocationAttribute([default, ...]) |
A frame attribute that can act as a EarthLocation. |

FK4(*args, **kwargs) |
A coordinate or frame in the FK4 system. |

FK4NoETerms(*args, **kwargs) |
A coordinate or frame in the FK4 system, but with the E-terms of aberration removed. |

FK5(*args, **kwargs) |
A coordinate or frame in the FK5 system. |

FrameAttribute([default, secondary_attribute]) |
A non-mutable data descriptor to hold a frame attribute. |

FunctionTransform(func, fromsys, tosys[, ...]) |
A coordinate transformation defined by a function that accepts a coordinate object and returns the transformed coordinate object. |

GCRS(*args, **kwargs) |
A coordinate or frame in the Geocentric Celestial Reference System (GCRS). |

Galactic(*args, **kwargs) |
Galactic Coordinates. |

Galactocentric(*args, **kwargs) |
A coordinate or frame in the Galactocentric system. |

GenericFrame(frame_attrs) |
A frame object that can’t store data but can hold any arbitrary frame attributes. |

ICRS(*args, **kwargs) |
A coordinate or frame in the ICRS system. |

ITRS(*args, **kwargs) |
A coordinate or frame in the International Terrestrial Reference System (ITRS). |

IllegalHourError(hour) |
Raised when an hour value is not in the range [0,24). |

IllegalHourWarning(hour[, alternativeactionstr]) |
Raised when an hour value is 24. |

IllegalMinuteError(minute) |
Raised when an minute value is not in the range [0,60]. |

IllegalMinuteWarning(minute[, ...]) |
Raised when a minute value is 60. |

IllegalSecondError(second) |
Raised when an second value (time) is not in the range [0,60]. |

IllegalSecondWarning(second[, ...]) |
Raised when a second value is 60. |

Latitude |
Latitude-like angle(s) which must be in the range -90 to +90 deg. |

Longitude |
Longitude-like angle(s) which are wrapped within a contiguous 360 degree range. |

PhysicsSphericalRepresentation(phi, theta, r) |
Representation of points in 3D spherical coordinates (using the physics convention of using phi and theta for azimuth and inclination from the pole). |

QuantityFrameAttribute([default, ...]) |
A frame attribute that is a quantity with specified units and shape (optionally). |

RangeError |
Raised when some part of an angle is out of its valid range. |

RepresentationMapping |
This namedtuple is used with the frame_specific_representation_info attribute to tell frames what attribute names (and default units) to use for a particular representation. |

SkyCoord(*args, **kwargs) |
High-level object providing a flexible interface for celestial coordinate representation, manipulation, and transformation between systems. |

SphericalRepresentation(lon, lat, distance) |
Representation of points in 3D spherical coordinates. |

StaticMatrixTransform(matrix, fromsys, tosys) |
A coordinate transformation defined as a 3 x 3 cartesian transformation matrix. |

TimeFrameAttribute([default, ...]) |
Frame attribute descriptor for quantities that are Time objects. |

TransformGraph() |
A graph representing the paths between coordinate frames. |

UnitSphericalRepresentation(lon, lat[, copy]) |
Representation of points on a unit sphere. |