Skip to main content
`Ctrl`+`K`

# Angle

class astropy.coordinates.Angle(angle, unit=None, dtype=<class 'numpy.inexact'>, copy=True, **kwargs)

  Bases: `SpecificTypeQuantity`

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

  An angle can be specified either as an array, scalar, tuple (see below), string, `Quantity` or another `Angle`.

  The input parser is flexible and supports a variety of formats. The examples below illustrate common ways of initializing an `Angle` object. First some imports:

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

  The angle values can now be provided:

      >>> Angle('10.2345d')
      <Angle 10.2345 deg>
      >>> Angle(['10.2345d', '-20d'])
      <Angle [ 10.2345, -20.    ] deg>
      >>> Angle('1:2:30.43 degrees')
      <Angle 1.04178611 deg>
      >>> Angle('1 2 0 hours')
      <Angle 1.03333333 hourangle>
      >>> Angle(np.arange(1, 8), unit=u.deg)
      <Angle [1., 2., 3., 4., 5., 6., 7.] deg>
      >>> Angle('1°2′3″')
      <Angle 1.03416667 deg>
      >>> Angle('1°2′3″N')
      <Angle 1.03416667 deg>
      >>> Angle('1d2m3.4s')
      <Angle 1.03427778 deg>
      >>> Angle('1d2m3.4sS')
      <Angle -1.03427778 deg>
      >>> Angle('-1h2m3s')
      <Angle -1.03416667 hourangle>
      >>> Angle('-1h2m3sE')
      <Angle -1.03416667 hourangle>
      >>> Angle('-1h2.5m')
      <Angle -1.04166667 hourangle>
      >>> Angle('-1h2.5mW')
      <Angle 1.04166667 hourangle>
      >>> Angle('-1:2.5', unit=u.deg)
      <Angle -1.04166667 deg>
      >>> Angle(10.2345 * u.deg)
      <Angle 10.2345 deg>
      >>> Angle(Angle(10.2345 * u.deg))
      <Angle 10.2345 deg>

  Parameters:
    angle `array`, scalar, `Quantity`, `Angle`

      The angle value. If a tuple, will be interpreted as `(h, m, s)` or `(d, m, s)` depending on `unit`. If a string, it will be interpreted following the rules described above.

      If `angle` is a sequence or array of strings, the resulting values will be in the given `unit`, or if `None` is provided, the unit will be taken from the first given value.

    unit astropy:unit-like, optional

      The unit of the value specified for the angle. This may be any string that `Unit` understands, but it is better to give an actual unit object. Must be an angular unit.

    dtype `dtype`, optional

      See `Quantity`.

    copy bool, optional

      See `Quantity`.

  Raises:
    `UnitsError`

      If a unit is not provided or it is not an angular unit.

  Attributes Summary

  `dms` | The angle's value in degrees, as a `(d, m, s)` named tuple.
  `hms` | The angle's value in hours, as a named tuple with `(h, m, s)` members.
  `hour` | The angle's value in hours (read-only property).
  `signed_dms` | The angle's value in degrees, as a `(sign, d, m, s)` named tuple.

  Methods Summary

  `is_within_bounds`([lower, upper]) | Check if all angle(s) satisfy `lower <= angle < upper`.
  `to_string`([unit, decimal, sep, precision, ...]) | A string representation of the angle.
  `wrap_at`(wrap_angle[, inplace]) | Wrap the `Angle` object at the given `wrap_angle`.

  Attributes Documentation

  dms

    The angle’s value in degrees, as a `(d, m, s)` named tuple.

  hms

    The angle’s value in hours, as a named tuple with `(h, m, s)` members.

  hour

    The angle’s value in hours (read-only property).

  signed_dms

    The angle’s value in degrees, as a `(sign, d, m, s)` named tuple.

    The `d`, `m`, `s` are thus always positive, and the sign of the angle is given by `sign`.

    This is primarily intended for use with `dms` to generate string representations of coordinates that are correct for negative angles.

  Methods Documentation

  is_within_bounds(lower=None, upper=None)

    Check if all angle(s) satisfy `lower <= angle < upper`.

    If `lower` is not specified (or `None`) then no lower bounds check is performed. Likewise `upper` can be left unspecified. For example:

        >>> from astropy.coordinates import Angle
        >>> import astropy.units as u
        >>> a = Angle([-20, 150, 350] * u.deg)
        >>> a.is_within_bounds('0d', '360d')
        False
        >>> a.is_within_bounds(None, '360d')
        True
        >>> a.is_within_bounds(-30 * u.deg, None)
        True

    Parameters:
      lower astropy:angle-like or `python:None`

        Specifies lower bound for checking. This can be any object that can initialize an `Angle` object, e.g. `'180d'`, `180 * u.deg`, or `Angle(180, unit=u.deg)`.

      upper astropy:angle-like or `python:None`

        Specifies upper bound for checking. This can be any object that can initialize an `Angle` object, e.g. `'180d'`, `180 * u.deg`, or `Angle(180, unit=u.deg)`.

    Returns:
      is_within_bounds bool

        `True` if all angles satisfy `lower <= angle < upper`

  to_string(unit=None, decimal=False, sep='fromunit', precision=None, alwayssign=False, pad=False, fields=3, format=None)

    A string representation of the angle.

    Parameters:
      unit `UnitBase`, optional

        Specifies the unit. Must be an angular unit. If not provided, the unit used to initialize the angle will be used.

      decimal bool, optional

        If `False`, the returned string will be in sexagesimal form if possible (for units of degrees or hourangle). If `True`, a decimal representation will be used. In that case, no unit will be appended if `format` is not explicitly given.

      sep `python:str`, optional

        The separator between numbers in a sexagesimal representation. E.g., if it is ‘:’, the result is `'12:41:11.1241'`. Also accepts 2 or 3 separators. E.g., `sep='hms'` would give the result `'12h41m11.1241s'`, or sep=’-:’ would yield `'11-21:17.124'`. Alternatively, the special string ‘fromunit’ means ‘dms’ if the unit is degrees, or ‘hms’ if the unit is hours.

      precision `python:int`, optional

        The level of decimal precision. If `decimal` is `True`, this is the raw precision, otherwise it gives the precision of the last place of the sexagesimal representation (seconds). If `None`, or not provided, the number of decimal places is determined by the value, and will be between 0-8 decimal places as required.

      alwayssign bool, optional

        If `True`, include the sign no matter what. If `False`, only include the sign if it is negative.

      pad bool, optional

        If `True`, include leading zeros when needed to ensure a fixed number of characters for sexagesimal representation.

      fields `python:int`, optional

        Specifies the number of fields to display when outputting sexagesimal notation. For example:

        > - fields == 1: `'5d'`

        > - fields == 2: `'5d45m'`

        > - fields == 3: `'5d45m32.5s'`

        By default, all fields are displayed.

      format `python:str`, optional

        The format of the result. If not provided, an unadorned string is returned. Supported values are:

        - ‘latex’: Return a LaTeX-formatted string

        - ‘latex_inline’: Return a LaTeX-formatted string which is the same as with `format='latex'` for |Angle| instances

        - ‘unicode’: Return a string containing non-ASCII unicode characters, such as the degree symbol

    Returns:
      strrepr `python:str` or `array`

        A string representation of the angle. If the angle is an array, this will be an array with a unicode dtype.

  wrap_at(wrap_angle, inplace=False)

    Wrap the `Angle` object at the given `wrap_angle`.

    This method forces all the angle values to be within a contiguous 360 degree range so that `wrap_angle - 360d <= angle < wrap_angle`. By default a new Angle object is returned, but if the `inplace` argument is `True` then the `Angle` object is wrapped in place and nothing is returned.

    For instance:

        >>> from astropy.coordinates import Angle
        >>> import astropy.units as u
        >>> a = Angle([-20.0, 150.0, 350.0] * u.deg)

        >>> a.wrap_at(360 * u.deg).degree  # Wrap into range 0 to 360 degrees
        array([340., 150., 350.])

        >>> a.wrap_at('180d', inplace=True)  # Wrap into range -180 to 180 degrees
        >>> a.degree
        array([-20., 150., -10.])

    Parameters:
      wrap_angle astropy:angle-like

        Specifies a single value for the wrap angle. This can be any object that can initialize an `Angle` object, e.g. `'180d'`, `180 * u.deg`, or `Angle(180, unit=u.deg)`.

      inplace bool

        If `True` then wrap the object in place instead of returning a new `Angle`

    Returns:
      out `Angle` or `python:None`

        If `inplace is False` (default), return new `Angle` object with angles wrapped accordingly. Otherwise wrap in place and return `None`.