Skyfield: Home • Table of Contents • Changelog • API Reference
When you ask positions to return distances, velocities, or angles, they return instances of the following classes.
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.
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.
skyfield.units.
Angle
(angle=None, radians=None, degrees=None, hours=None, preference=None, signed=False)¶radians
()¶Radians (𝜏 = 2𝜋 in a circle).
hours
¶Hours (24^{h} 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.
skyfield.units.
AngleRate
¶The rate at which an angle is changing.
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.
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:
'-'
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.”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.)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.