Angles

class coord.Angle(theta, unit=None)[source]

A class representing an Angle. Angles are a value with an AngleUnit.

Initialization:

You typically create an Angle by multiplying a number by a coord.AngleUnit, for example:

>>> pixel = 0.27 * arcsec
>>> ra = 13.4 * hours
>>> dec = -32 * degrees
>>> from math import pi
>>> theta = pi/2. * radians

You can also initialize explicitly, taking a value and a unit:

coord.Angle.__init__()

>>> unit = AngleUnit(math.pi / 100)  # gradians
>>> phi = Angle(90, unit)

Built-in units:

There are five built-in AngleUnits which are always available for use:

coord.radians

coord.AngleUnit(1.)

coord.degrees

coord.AngleUnit(pi / 180.)

coord.hours

coord.AngleUnit(pi / 12.)

coord.arcmin

coord.AngleUnit(pi / 180. / 60.)

coord.arcsec

coord.AngleUnit(pi / 180. / 3600.)

Attribute:

Since extracting the value in radians is extremely common, we have a read-only attribute to do this quickly:

rad

The measure of the unit in radians.

For example:

>>> theta = 90 * degrees
>>> print(theta.rad)
1.5707963267948966

It is equivalent to the more verbose:

>>> x = theta / radians
>>> print(x)
1.5707963267948966

but without actually requiring the floating point operation of dividing by 1.

Arithmetic:

Allowed arithmetic with Angles include the following. In the list below,

  • x is an arbitrary float value

  • unit1 and unit2 are arbitrary AngleUnit instances

  • theta1 and theta2 are arbitrary Angle instances

>>> x = 37.8
>>> unit1 = arcmin
>>> unit2 = degrees

>>> theta1 = x * unit1
>>> theta2 = x * unit2
>>> x2 = theta1 / unit2
>>> theta = theta1 + theta2
>>> theta = theta1 - theta2
>>> theta = theta1 * x
>>> theta = x * theta1
>>> theta = theta1 / x
>>> theta = -theta1
>>> theta += theta1
>>> theta -= theta1
>>> theta *= x
>>> theta /= x
>>> x = unit1 / unit2   # equivalent to x = (1 * unit1) / unit2

The above operations on NumPy arrays containing Angles are permitted as well.

Trigonometry:

There are convenience function for getting the sin, cos, and tan of an angle, along with one for getting sin and cos together, which should be more efficient than doing sin and cos separately:

coord.Angle.sin()
coord.Angle.cos()
coord.Angle.tan()
coord.Angle.sincos()
>>> sint = theta.sin()  # equivalent to sint = math.sin(theta.rad)
>>> cost = theta.cos()  # equivalent to cost = math.cos(theta.rad)
>>> tant = theta.tan()  # equivalent to tant = math.tan(theta.rad)
>>> sint, cost = theta.sincos()

These functions mean that numpy trig functions will work on Angles or arrays of Angles:

>>> sint = np.sin(theta)
>>> cost = np.cos(theta)
>>> tant = np.tan(theta)

Wrapping:

Depending on the context, theta = 2pi radians and theta = 0 radians may mean the same thing. If you want your angles to be wrapped to [-pi,pi) radians, you can do this by calling

coord.Angle.wrap()

>>> theta = theta.wrap()

This could be appropriate before testing for the equality of two angles for example, or calculating the difference between them.

There is also an option to wrap into a different 2 pi range if so desired by specifying the center of the range.

__init__(theta, unit=None)[source]
Parameters

  • theta – The numerical value of the angle.

  • unit – The units theta is measured in.

property rad

Return the Angle in radians.

Equivalent to angle / coord.radians

property deg

Return the Angle in degrees.

Equivalent to angle / coord.degrees

wrap(center=None)[source]

Wrap Angle to lie in the range [-pi, pi) radians (or other range of 2pi radians)

Depending on the context, theta = 2pi radians and theta = 0 radians are the same thing. If you want your angles to be wrapped to [-pi, pi) radians, you can do this as follows:

>>> theta = Angle(700 * degrees)
>>> theta = theta.wrap()
>>> print(theta.deg)
-19.99999999999998

This could be appropriate before testing for the equality of two angles for example, or calculating the difference between them.

If you want to wrap to a different range than [-pi, pi), you can set the center argument to be the desired center of the the range. e.g. for return values to fall in [0, 2pi), you could call

>>> theta = theta.wrap(center=180. * degrees)
>>> print(theta / degrees)
340.0
Parameters

center – The center point of the wrapped range. [default: 0 radians]

Returns

the equivalent angle within the range [center-pi, center+pi)

sin()[source]

Return the sin of an Angle.

cos()[source]

Return the cos of an Angle.

tan()[source]

Return the tan of an Angle.

sincos()[source]

Return both the sin and cos of an Angle as a numpy array [sint, cost].

hms(sep=':', prec=None, pad=True, plus_sign=False)[source]

Return an HMS representation of the angle as a string: +-hh:mm:ss.decimal.

An optional sep parameter can change the : to something else (e.g. a space or nothing at all).

Note: the reverse process is effected by Angle.from_hms():

>>> angle = -5.357 * hours
>>> hms = angle.hms()
>>> print(hms)
-05:21:25.2
>>> angle2 = Angle.from_hms(hms)
>>> print(angle2 / hours)
-5.356999999999999
Parameters

  • sep – The token to put between the hh and mm and beteen mm and ss. This may also be a string of 2 or 3 items, e.g. ‘hm’ or ‘hms’. Or even a tuple of strings such as (‘hours ‘, ‘minutes ‘, ‘seconds’). [default: ‘:’]

  • prec – The number of digits of precision after the decimal point. [default: None]

  • pad – Whether to pad with a leading 0 if necessary to make h,m,s 2 digits. [default: True]

  • plus_sign – Whether to use a plus sign for positive angles. [default: False]

Returns

a string of the HMS representation of the angle.

dms(sep=':', prec=None, pad=True, plus_sign=False)[source]

Return a DMS representation of the angle as a string: +-dd:mm:ss.decimal An optional sep parameter can change the : to something else (e.g. a space or nothing at all).

Note: the reverse process is effected by Angle.from_dms():

>>> angle = -(5 * degrees + 21 * arcmin + 25.2 * arcsec)
>>> dms = angle.dms()
>>> print(dms)
-05:21:25.2
>>> angle2 = Angle.from_dms(dms)
>>> print(angle2 / degrees)
-5.356999999999999
Parameters

  • sep – The token to put between the hh and mm and beteen mm and ss. This may also be a string of 2 or 3 items, e.g. ‘dm’ or ‘dms’. Or even a tuple of strings such as (‘degrees ‘, ‘minutes ‘, ‘seconds’). [default: ‘:’]

  • prec – The number of digits of precision after the decimal point. [default: None]

  • pad – Whether to pad with a leading 0 if necessary to make h 2 digits. [default: True]

  • plus_sign – Whether to use a plus sign for positive angles. [default: False]

Returns

a string of the DMS representation of the angle.

static from_hms(str)[source]

Convert a string of the form hh:mm:ss.decimal into an Angle.

There may be an initial + or - (or neither), then two digits for the hours, two for the minutes, and two for the seconds. Then there may be a decimal point followed by more digits. There may be a colon separating hh, mm, and ss, or whitespace, or nothing at all. In fact, the code will ignore any non-digits between the hours, minutes, and seconds.

Note: the reverse process is effected by Angle.hms():

>>> angle = -5.357 * hours
>>> hms = angle.hms()
>>> print(hms)
-05:21:25.2
>>> angle2 = Angle.from_hms(hms)
>>> print(angle2 / hours)
-5.356999999999999
Parameters

str – The string to parse.

Returns

the corresponding Angle instance

static from_dms(str)[source]

Convert a string of the form dd:mm:ss.decimal into an Angle.

There may be an initial + or - (or neither), then two digits for the degrees, two for the minutes, and two for the seconds. Then there may be a decimal point followed by more digits. There may be a colon separating dd, mm, and ss, or whitespace, or nothing at all. In fact, the code will ignore any non-digits between the degrees, minutes, and seconds.

Note: the reverse process is effected by Angle.dms():

>>> angle = -(5 * degrees + 21 * arcmin + 25.2 * arcsec)
>>> dms = angle.dms()
>>> print(dms)
-05:21:25.2
>>> angle2 = Angle.from_dms(dms)
>>> print(angle2 / degrees)
-5.356999999999999
Parameters

str – The string to parse.

Returns

the corresponding Angle instance

coord._Angle(theta)[source]

Equivalent to Angle(theta, coord.radians), but without the normal overhead (which isn’t much to be honest, but this is nonetheless slightly quicker).

Parameters

theta – The numerical value of the angle in radians.