Skyfield: HomeTable of ContentsAPI Reference

API Reference — Astronomical Positions

See Positions and Coordinates for a detailed guide to these various kinds of position that Skyfield can compute, and to the selection of coordinate systems that can be used to express them.

Generic ICRF position

class skyfield.positionlib.ICRF(position_au, velocity_au_per_d=None, t=None, center=None, target=None, observer_data=None)

An (x, y, z) position and velocity oriented to the ICRF axes.

The ICRF is a permanent coordinate system that has superseded the old series of equinox-based systems like B1900 and B1950. Its axes are aligned with the axes of J2000 to within 0.02 arcseconds, which is tighter than the accuracy of J2000 itself.

t

The Time coordinate of this position.

position

The Distance coordinate as an (x, y, z) array.

velocity

The Velocity coordinate as an (x, y, z) array.

This attribute will have the value None if no velocity was specified for this position.

distance()

Compute the distance from the origin to this position.

>>> v = ICRF([1, 1, 0])
>>> print(v.distance())
1.41421 au
speed()

Compute the magnitude of the velocity vector.

>>> v = ICRF([0, 0, 0], [1, 2, 3])
>>> print(v.speed())
3.74166 au/day
radec(epoch=None)

Compute equatorial (RA, declination, distance)

When called without a parameter, this returns standard ICRF right ascension and declination:

>>> ra, dec, distance = ICRF([1, 2, 3]).radec()
>>> print(ra, dec, distance, sep='\n')
04h 13m 44.39s
+53deg 18' 02.8"
3.74166 au

If you instead want the coordinates referenced to the dynamical system defined by the Earth’s mean equator and equinox, provide an epoch time. To get J2000.0 coordinates, for example:

>>> ra, dec, distance = ICRF([1, 2, 3]).radec(ts.J2000)
>>> print(ra, dec, sep='\n')
04h 13m 43.32s
+53deg 17' 55.1"
separation_from(another_icrf)

Return the angle between this position and another.

>>> print(ICRF([1,0,0]).separation_from(ICRF([1,1,0])))
45deg 00' 00.0"

You can also compute separations across an array of positions.

>>> directions = ICRF([[1,0,-1,0], [0,1,0,-1], [0,0,0,0]])
>>> directions.separation_from(ICRF([0,1,0])).degrees
array([ 90.,   0.,  90., 180.])
ecliptic_position()

Compute J2000 ecliptic coordinates (x, y, z)

ecliptic_latlon()

Compute J2000 ecliptic coordinates (lat, lon, distance)

galactic_position()

Compute galactic coordinates (x, y, z)

galactic_latlon()

Compute galactic coordinates (lat, lon, distance)

to_skycoord(unit=None)

Convert this distance to an AstroPy SkyCoord object.

from_altaz(alt=None, az=None, alt_degrees=None, az_degrees=None, distance=<Distance 0.1 au>)

Generate an Apparent position from an altitude and azimuth.

The altitude and azimuth can each be provided as an Angle object, or else as a number of degrees provided as either a float or a tuple of degrees, arcminutes, and arcseconds:

alt=Angle(...), az=Angle(...)
alt_degrees=23.2289, az_degrees=142.1161
alt_degrees=(23, 13, 44.1), az_degrees=(142, 6, 58.1)

The distance should be a Distance object, if provided; otherwise a default of 0.1 au is used.

Position measured from the Solar System barycenter

class skyfield.positionlib.Barycentric(position_au, velocity_au_per_d=None, t=None, center=None, target=None, observer_data=None)

An (x, y, z) position measured from the Solar System barycenter.

Each barycentric position is an ICRS position vector, meaning that the coordinate axes are defined by the high-precision ICRF that has replaced the old J2000.0 reference frame, and the coordinate origin is the BCRS gravitational center of the Solar System.

Skyfield generates a Barycentric position whenever you ask a Solar System body for its location at a particular time:

>>> t = ts.utc(2003, 8, 29)
>>> mars.at(t)
<Barycentric position and velocity at date t center=0 target=499>
observe(body)

Compute the Astrometric position of a body from this location.

To compute the body’s astrometric position, it is first asked for its position at the time t of this position itself. The distance to the body is then divided by the speed of light to find how long it takes its light to arrive. Finally, the light travel time is subtracted from t and the body is asked for a series of increasingly exact positions to learn where it was when it emitted the light that is now reaching this position.

>>> earth.at(t).observe(mars)
<Astrometric position and velocity at date t>

Astrometric position relative to an observer

class skyfield.positionlib.Astrometric(position_au, velocity_au_per_d=None, t=None, center=None, target=None, observer_data=None)

An astrometric (x, y, z) position relative to a particular observer.

The astrometric position of a body is its position relative to an observer, adjusted for light-time delay: the position of the body back when it emitted (or reflected) the light that is now reaching the observer’s eyes or telescope.

Astrometric positions are usually generated in Skyfield by calling the Barycentric method observe() to determine where a body will appear in the sky relative to a specific observer.

apparent()

Compute an Apparent position for this body.

This applies two effects to the position that arise from relativity and shift slightly where the other body will appear in the sky: the deflection that the image will experience if its light passes close to large masses in the Solar System, and the aberration of light caused by the observer’s own velocity.

>>> earth.at(t).observe(mars).apparent()
<Apparent position at date t>

These transforms convert the position from the BCRS reference frame of the Solar System barycenter and to the reference frame of the observer. In the specific case of an Earth observer, the output reference frame is the GCRS.

Apparent position relative to an observer

class skyfield.positionlib.Apparent(position_au, velocity_au_per_d=None, t=None, center=None, target=None, observer_data=None)

An apparent (x, y, z) position relative to a particular observer.

The apparent position of a body is its position relative to an observer adjusted for light-time delay, deflection (light rays bending as they pass large masses like the Sun or Jupiter), and aberration (light slanting because of the observer’s motion through space).

Included in aberration is the relativistic transformation that takes the position out of the BCRS centered on the solar system barycenter and into the reference frame of the observer. In the case of an Earth observer, the transform takes the coordinate into the GCRS.

altaz(temperature_C=None, pressure_mbar='standard')

Compute (alt, az, distance) relative to the observer’s horizon

The altitude returned is an Angle in degrees above the horizon, while the azimuth is the compass direction in degrees with north being 0 degrees and east being 90 degrees.

Geocentric position relative to the Earth

class skyfield.positionlib.Geocentric(position_au, velocity_au_per_d=None, t=None, center=None, target=None, observer_data=None)

An (x,y,z) position measured from the geocenter.

subpoint()

Return the latitude and longitude directly beneath this position.

Returns a Topos whose longitude and latitude are those of the point on the Earth’s surface directly beneath this position, and whose elevation is the height of this position above the Earth’s surface.

Geometric instantaneous position between two objects

class skyfield.positionlib.Geometric(position_au, velocity_au_per_d=None, t=None, center=None, target=None, observer_data=None)

An (x,y,z) vector between two instantaneous position.

A geometric position is the difference between the Solar System positions of two bodies at exactly the same instant. It is not corrected for the fact that, in real physics, it will take time for light to travel from one position to the other.

altaz(temperature_C=None, pressure_mbar='standard')

Compute (alt, az, distance) relative to the observer’s horizon

The altitude returned is an Angle in degrees above the horizon, while the azimuth is the compass direction in degrees with north being 0 degrees and east being 90 degrees.