Skyfield: Home • Table of Contents • Changelog • API Reference

API Reference — Units

When you ask positions to return distances, velocities, or angles, they return instances of the following classes.

class skyfield.units.Distance(au=None, km=None, m=None)

A distance, stored internally as au and available in other units.

You can initialize a Distance by providing a single float or a float array as either an au=, km=, or m= parameter.

You can access the magnitude of the distance with its three attributes .au, .km, and .m. By default a distance prints itself in astronomical units (au), but you can take control of the formatting and choice of units yourself using standard Python numeric formatting:

>>> d = Distance(au=1)
>>> print(d)
1.0 au
>>> print('{:.2f} km'.format(d.km))
149597870.70 km
au()

Astronomical units.

km()

Kilometers (1,000 meters).

m()

Meters.

length()

Compute the length when this is an (x,y,z) vector.

The Euclidean vector length of this vector is returned as a new Distance object.

>>> from skyfield.api import Distance
>>> d = Distance(au=[1, 1, 0])
>>> d.length()
<Distance 1.41421 au>
light_seconds()

Return the length of this vector in light seconds.

to(unit)

Convert this distance to the given AstroPy unit.

class skyfield.units.Velocity(au_per_d=None, km_per_s=None)

A velocity, stored internally as au/day and available in other units.

You can initialize a Velocity by providing a float or float array to its au_per_d= parameter.

au_per_d()

Astronomical units per day.

km_per_s()

Kilometers per second.

m_per_s()

Meters per second.

to(unit)

Convert this velocity to the given AstroPy unit.

class skyfield.units.Angle(angle=None, radians=None, degrees=None, hours=None, preference=None, signed=False)
radians()

Radians (𝜏 = 2𝜋 in a circle).

hours

Hours (24h in a circle).

degrees

Degrees (360° in a circle).

arcminutes()

Return the angle in arcminutes.

arcseconds()

Return the angle in arcseconds.

mas()

Return the angle in milliarcseconds.

hms(warn=True)

Convert to a tuple (hours, minutes, seconds).

All three quantities will have the same sign as the angle itself.

signed_hms(warn=True)

Convert to a tuple (sign, hours, minutes, seconds).

The sign will be either +1 or -1, and the other quantities will all be positive.

hstr(places=2, warn=True, format='{0}{1:02}h {2:02}m {3:02}.{4:0{5}}s')

Return a string like 12h 07m 30.00s; see Formatting angles.

New in version 1.39: Added the format= parameter.

dms(warn=True)

Convert to a tuple (degrees, minutes, seconds).

All three quantities will have the same sign as the angle itself.

signed_dms(warn=True)

Convert to a tuple (sign, degrees, minutes, seconds).

The sign will be either +1 or -1, and the other quantities will all be positive.

dstr(places=1, warn=True, format=None)

Return a string like 181deg 52' 30.0"; see Formatting angles.

New in version 1.39: Added the format= parameter.

to(unit)

Convert this angle to the given AstroPy unit.

class skyfield.units.AngleRate

The rate at which an angle is changing.

radians

Rate of change in radians.

degrees

Rate of change in degrees.

arcminutes

Rate of change in arcminutes.

arcseconds

Rate of change in arcseconds.

mas

Rate of change in milliarcseconds.

class skyfield.units.Rate

Measurement whose denominator is time.

per_day

Units per day of Terrestrial Time.

per_hour

Units per hour of Terrestrial Time.

per_minute

Units per minute of Terrestrial Time.

per_second

Units per second of Terrestrial Time.

Formatting angles

To display an angle as decimal degrees or hours, ask the angle for its .hours or .degrees attribute and then use any normal Python mechanism for formatting a float. For example:

ra, dec = Angle(hours=5.5877286), Angle(degrees=-5.38731536)

print('RA {:.8f} hours'.format(ra.hours))
print('Dec {:+.8f} degrees'.format(dec.degrees))

RA 5.58772860 hours
Dec -5.38731536 degrees

If you let Skyfield do the formatting instead, then hours are split into 60 minutes of 60 seconds each, and degrees are split into 60 arcminutes of 60 arcseconds each:

print('RA', ra)
print('Dec', dec)

RA 05h 35m 15.82s
Dec -05deg 23' 14.3"

If you want more control over the display of minutes and seconds, you can call an angle’s “hours as a string” method hstr() or “degrees as a string” method dstr(). The simplest adjustment you can make is to specify the number of decimal places that will be shown in the seconds field.

print('RA', ra.hstr(places=4))
print('Dec', dec.dstr(places=4))

RA 05h 35m 15.8230s
Dec -05deg 23' 14.3353"

In each of these examples you can see that Skyfield marks arcminutes with the ASCII apostrophe ' and arcseconds with the ASCII quotation mark ". Using plain ASCII lets Skyfield support as many operating systems and output media as possible. But it would be more correct to denote arcseconds and arcminutes with the Unicode symbols PRIME and DOUBLE PRIME, and to use the Unicode DEGREE SIGN to mark the whole number:

−5°23′14.3″

If you want to override Skyfield’s default notation to create either the string above, or any other notation, then give hstr() or dstr() a format= string of your own. It should use the syntax of Python’s str.format() method. For example, here’s the exact string you would use to format an angle in degrees, arcminutes, and arcseconds using the traditional typographic symbols discussed above:

print(dec.dstr(format=u'{0}{1}°{2:02}′{3:02}.{4:0{5}}″'))

-5°23′14.3″

(Note that the leading u, for “Unicode”, is only mandatory in Python 2, not Python 3.)

Skyfield will call your string’s format method with these six arguments:

{0}
An ASCII hyphen '-' if the angle is negative, else the empty string. If you want positive angles to be decorated with a plus sign, try using {0:+>1} which tells Python, “display positional parameter 0, padding the field to one character wide if it’s less than one character already, and use the + character to do the padding.”
{1}
The number of whole hours or degrees.
{2}
The number of whole minutes.
{3}
The number of whole seconds.
{4}
The fractions of a second. Be sure to pad this field to the number of places= you’ve requested, or else a fraction like .0012 will format incorrectly as .12. If you have asked for places=3, for example, you’ll want to display this field as {4:03}. (See also the next item.)
{5}
The number of places= you requested, which you will probably use like {4:0{5}} when formatting field 4. You can use this in case you might not know the number of places ahead of time, for example if the number of places is configured by your user.

It would have been nice if the format= string were the first option to hstr() or dstr() so that its keyword name could be omitted but, alas, it was only added in Skyfield 1.39, by which point the other options had already grabbed the first spots.