Skyfield: Home • Table of Contents • API Reference
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.
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.
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.])
cirs_xyz
(epoch)¶Compute cartesian CIRS coordinates at a given epoch (x, y, z).
Calculate coordinates in the Celestial Intermediate Reference System (CIRS), a dynamical coordinate system referenced to the Celestial Intermediate Origin (CIO). As this is a dynamical system it must be calculated at a specific epoch.
cirs_radec
(epoch)¶Get spherical CIRS coordinates at a given epoch (ra, dec, distance).
Calculate coordinates in the Celestial Intermediate Reference System (CIRS), a dynamical coordinate system referenced to the Celestial Intermediate Origin (CIO). As this is a dynamical system it must be calculated at a specific epoch.
ecliptic_xyz
(epoch=None)¶Compute J2000 ecliptic position vector (x, y, z).
If you instead want the coordinates referenced to the dynamical system defined by the Earth’s true equator and equinox, provide an epoch time.
ecliptic_velocity
()¶Compute J2000 ecliptic velocity vector (x_dot, y_dot, z_dot)
ecliptic_latlon
(epoch=None)¶Compute J2000 ecliptic coordinates (lat, lon, distance)
If you instead want the coordinates referenced to the dynamical system defined by the Earth’s true equator and equinox, provide an epoch time.
galactic_xyz
()¶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.
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>
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 and velocity 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.
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.
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.
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.