astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- Astronomical Coordinate Systems (`astropy.coordinates`) »
- Working with Angles

# Working with Angles

The angular components of the various coordinate objects are represented by objects of the `Angle` class. While most likely to be encountered in the context of coordinate objects, `Angle` objects can also be used on their own wherever a representation of an angle is needed.

## Creation

The creation of an `Angle` object is quite flexible and supports a wide variety of input object types and formats. The type of the input angle(s) can an array, scalar, tuple, string, `Quantity` or another `Angle`. This is best illustrated with a number of examples of valid ways to create an `Angle`:

    >>> import numpy as np
    >>> from astropy import units as u
    >>> from astropy.coordinates import Angle

    >>> Angle('10.2345d')              # String with 'd' abbreviation for degrees
    <Angle 10.2345 deg>
    >>> Angle(['10.2345d', '-20d'])    # Array of strings
    <Angle [ 10.2345,-20.    ] deg>
    >>> Angle('1:2:30.43 degrees')     # Sexagesimal degrees
    <Angle 1.0417861111111113 deg>
    >>> Angle('1 2 0 hours')           # Sexagesimal hours
    <Angle 1.0333333333333334 hourangle>
    >>> Angle(np.arange(1., 8.), unit=u.deg)  # Numpy array from 1..7 in degrees
    <Angle [ 1., 2., 3., 4., 5., 6., 7.] deg>
    >>> Angle(u'1°2′3″')               # Unicode degree, arcmin and arcsec symbols
    <Angle 1.0341666666666667 deg>
    >>> Angle('1d2m3.4s')              # Degree, arcmin, arcsec.
    <Angle 1.0342777777777779 deg>
    >>> Angle('-1h2m3s')               # Hour, minute, second
    <Angle -1.0341666666666667 hourangle>
    >>> Angle((-1, 2, 3), unit=u.deg)  # (degree, arcmin, arcsec)
    <Angle -1.0341666666666667 deg>
    >>> Angle(10.2345 * u.deg)         # From a Quantity object in degrees
    <Angle 10.2345 deg>
    >>> Angle(Angle(10.2345 * u.deg))  # From another Angle object
    <Angle 10.2345 deg>

## Representation

The `Angle` object also supports a variety of ways of representing the value of the angle, both as a floating point number as a string:

    >>> a = Angle(1, u.radian)
    >>> a
    <Angle 1.0 rad>
    >>> a.radian
    1.0
    >>> a.degree
    57.29577951308232
    >>> a.hour
    3.8197186342054885
    >>> a.hms
    hms_tuple(h=3.0, m=49.0, s=10.987083139758766)
    >>> a.dms
    dms_tuple(d=57.0, m=17.0, s=44.806247096362313)
    >>> a.signed_dms
    signed_dms_tuple(sign=1.0, d=57.0, m=17.0, s=44.806247096362313)
    >>> (-a).dms
    dms_tuple(d=-57.0, m=-17.0, s=-44.806247096362313)
    >>> (-a).signed_dms
    signed_dms_tuple(sign=-1.0, d=57.0, m=17.0, s=44.806247096362313)
    >>> a.arcminute
    3437.7467707849396
    >>> a.to_string()
    u'1rad'
    >>> a.to_string(unit=u.degree)
    u'57d17m44.8062s'
    >>> a.to_string(unit=u.degree, sep=':')
    u'57:17:44.8062'
    >>> a.to_string(unit=u.degree, sep=('deg', 'm', 's'))
    u'57deg17m44.8062s'
    >>> a.to_string(unit=u.hour)
    u'3h49m10.9871s'
    >>> a.to_string(unit=u.hour, decimal=True)
    u'3.81972'

## Usage

Angles will also behave correctly for appropriate arithmetic operations:

    >>> a = Angle(1.0, u.radian)
    >>> a + 0.5 * u.radian + 2 * a
    <Angle 3.5 rad>
    >>> np.sin(a / 2)
    <Quantity 0.479425538604203>
    >>> a == a
    array(True, dtype=bool)
    >>> a == (a + a)
    array(False, dtype=bool)

`Angle` objects can also be used for creating coordinate objects:

    >>> from astropy.coordinates import ICRS
    >>> ICRS(Angle(1, u.radian), Angle(0.5, u.radian))
    <ICRS Coordinate: (ra, dec) in deg
        (57.2957795131, 28.6478897565)>

## Wrapping and bounds

There are two utility methods that simplify working with angles that should have bounds. The `wrap_at()` method allows taking an angle or angles and wrapping to be within a single 360 degree slice. The `is_within_bounds()` method returns a boolean indicating whether an angle or angles is within the specified bounds.

## Longitude and Latitude objects

`Longitude` and `Latitude` are two specialized subclasses of the `Angle` class that are used for all of the spherical coordinate classes. `Longitude` is used to represent values like right ascension, Galactic longitude, and azimuth (for Equatorial, Galactic, and Alt-Az coordinates, respectively). `Latitude` is used for declination, Galactic latitude, and elevation.

### Longitude

A `Longitude` object is distinguished from a pure `Angle` by virtue of a `wrap_angle` property. The `wrap_angle` specifies that all angle values represented by the object will be in the range:

    wrap_angle - 360 * u.deg <= angle(s) < wrap_angle

The default `wrap_angle` is 360 deg. Setting `'wrap_angle=180 * u.deg'` would instead result in values between -180 and +180 deg. Setting the `wrap_angle` attribute of an existing `Longitude` object will result in re-wrapping the angle values in-place. For example:

    >>> from astropy.coordinates import Longitude
    >>> a = Longitude([-20, 150, 350, 360] * u.deg)
    >>> a.degree
    array([ 340., 150., 350.,   0.])
    >>> a.wrap_angle = 180 * u.deg
    >>> a.degree
    array([ -20., 150., -10.,   0.])

### Latitude

A Latitude object is distinguished from a pure `Angle` by virtue of being bounded so that:

    -90.0 * u.deg <= angle(s) <= +90.0 * u.deg

Any attempt to set a value outside that range will result in a `ValueError`.