ephem.Angle
===========

PyEphem measures all angles in radians.
But rather than simply returning angles as bare Python floats,
it returns each of them as an ``ephem.Angle``
which can print itself out in a more attractive format
than do raw floating-point numbers.

The vast majority of angles print as degrees.
For example,
the declination of Jupiter will print itself attractively
as degrees, minutes of arc, and seconds of arc:

    >>> import ephem
    >>> j = ephem.Jupiter('1994/7/16 20:13:16')
    >>> print(j.dec)
    -12:09:28.2

But the real value is always in radians,
which you can view by using ``repr()``::

    print repr(j.dec)  # => -0.21219402907256785

Since its numeric value is in radians,
printing the angle as degrees requires an extra step to convert the units.

    >>> from math import pi
    >>> print('Degrees: {:.4f}'.format(j.dec / pi * 180.0))
    Degrees: -12.1578

The only kind of angle which does not use degrees for display
is right ascension,
which instead traditionally breaks the celestial equator
into twenty-four “hours” which are each fifteen degress wide.

    >>> print(j.ra)
    14:12:45.77

As with PyEphem dates,
doing math with a PyEphem angle
results in an unadorned float in radians being returned.

    >>> type(j.dec).__name__
    'Angle'
    >>> a = j.dec + 3.14
    >>> type(a).__name__
    'float'

Setting angles follows the same rules:
a float is interpreted as radians
while a string is parsed as degrees or hours, as appropriate.

    >>> print(ephem.degrees('45.0'))
    45:00:00.0
    >>> print(ephem.degrees(3.141593))
    180:00:00.1

If you want to display the result of a computation
as an attractively formatted angle,
you can convert the float back to a PyEphem angle type
using either the ``degrees()`` function
or, for right ascension, the ``hours()`` function.
For example,
here are the results of adding fifteen degrees
to both Jupiter's declination and right ascension;
whereas the declination simply moves north by fifteen degrees
(passing north across the celestial equator into positive numbers),
the right ascension calls fifteen additional degrees “one hour” of motion:

    >>> import math
    >>> fifteen_degrees = ephem.degrees(math.pi / 12.)
    >>> print('%s %s' % (j.dec, ephem.degrees(j.dec + fifteen_degrees)))
    -12:09:28.2 2:50:31.8
    >>> print('%s %s' % (j.ra, ephem.hours(j.ra + fifteen_degrees)))
    14:12:45.77 15:12:45.77

Often when adding or subtracting with angles,
you will get a very large or small result
that you will want to normalize back to a respectable angle.
PyEphem angles offer two ways to make this convenient:
a ``norm`` attribute that returns the angle
normalized to the interval [0, 2π)
and a ``znorm`` attribute that returns the angle
normalized to the interval (-π, π] centered on zero.

    >>> circle = 2 * math.pi

::

    >>> a = + fifteen_degrees
    >>> print('%s %s %s' % (a, a.norm, a.znorm))
    15:00:00.0 15:00:00.0 15:00:00.0

::

    >>> a = - fifteen_degrees
    >>> print('%s %s %s' % (a, a.norm, a.znorm))
    -15:00:00.0 345:00:00.0 -15:00:00.0

::

    >>> a = ephem.degrees(circle - fifteen_degrees)
    >>> print('%s %s %s' % (a, a.norm, a.znorm))
    345:00:00.0 345:00:00.0 -15:00:00.0

::

    >>> a = ephem.degrees(circle + fifteen_degrees)
    >>> print('%s %s %s' % (a, a.norm, a.znorm))
    375:00:00.0 15:00:00.0 15:00:00.0

::

    >>> a = ephem.degrees(- circle + fifteen_degrees)
    >>> print('%s %s %s' % (a, a.norm, a.znorm))
    -345:00:00.0 15:00:00.0 15:00:00.0

::

    >>> a = ephem.degrees(- circle - fifteen_degrees)
    >>> print('%s %s %s' % (a, a.norm, a.znorm))
    -375:00:00.0 345:00:00.0 -15:00:00.0

Note that you cannot instantiate a raw ``Angle``:

    >>> ephem.Angle()
    Traceback (most recent call last):
     ...
    TypeError: you can only create an ephem.Angle through ephem.degrees() or ephem.hours()