Pyorbital is a python package to compute orbital parameters for satellites from TLE files as well as astronomical parameters of interest for satellite remote sensing. Currently pyorbital only supports low earth orbit satellites.


Pyorbital comes with a file platforms.txt that maps satellite name to NORAD identifier. This file needs to be copied to the appropriate satpy etc directory ($PPP_CONFIG_DIR). It is wise to check it contains your satellites of interest. The NORAD identifier can be found as the first number of each line in the Two-Line Elements (eg. from celestrak).

TLE files

Pyorbital has a module for parsing NORAD TLE-files

>>> from pyorbital import tlefile
>>> tle ='noaa 18', '/path/to/my/tle_file.txt')
>>> tle.inclination

If no path is given pyorbital tries to read the earth observation TLE-files from

Computing satellite position

The orbital module enables computation of satellite position and velocity at a specific time:

>>> from pyorbital.orbital import Orbital
>>> from datetime import datetime
>>> # Use current TLEs from the internet:
>>> orb = Orbital("Suomi NPP")
>>> now = datetime.utcnow()
>>> # Get normalized position and velocity of the satellite:
>>> orb.get_position(now)
(array([-0.20015267,  0.09001458,  1.10686756]),
 array([ 0.06148495,  0.03234914,  0.00846805]))
>>> # Get longitude, latitude and altitude of the satellite:
>>> orb.get_lonlatalt(now)
(40.374855865574951, 78.849923885700363, 839.62504115338368)

Use actual TLEs to increase accuracy

>>> from pyorbital.orbital import Orbital
>>> from datetime import datetime
>>> orb = Orbital("Suomi NPP")
>>> dtobj = datetime(2015,2,7,3,0)
>>> orb.get_lonlatalt(dtobj)
(152.11564698762811, 20.475251739329622, 829.37355785502211)

But since we are interested in knowing the position of the Suomi-NPP more than two and half years from now (September 26, 2017) we can not rely on the current TLEs, but rather need a TLE closer to the time of interest:

>>> snpp = Orbital('Suomi NPP', tle_file='/data/lang/satellit/polar/orbital_elements/TLE/201502/tle-20150207.txt')
>>> snpp.get_lonlatalt(dtobj)
(105.37373804512762, 79.160752404540133, 838.94605490133154)

If we take a TLE from one week earlier we get a slightly different result:

>>> snpp = Orbital('Suomi NPP', tle_file='/data/lang/satellit/polar/orbital_elements/TLE/201501/tle-20150131.txt')
>>> snpp.get_lonlatalt(dtobj)
(104.1539184988462, 79.328272480878141, 838.81555967963391)

Computing astronomical parameters

The astronomy module enables computation of certain parameters of interest for satellite remote sensing for instance the Sun-zenith angle:

>>> from pyorbital import astronomy
>>> from datetime import datetime
>>> utc_time = datetime(2012, 5, 15, 15, 45)
>>> lon, lat = 12, 56
>>> astronomy.sun_zenith_angle(utc_time, lon, lat)


Orbital computations

Module for computing the orbital parameters of satellites.

class pyorbital.orbital.OrbitElements(tle)

Class holding the orbital elements.

class pyorbital.orbital.Orbital(satellite, tle_file=None, line1=None, line2=None)

Class for orbital computations.

The satellite parameter is the name of the satellite to work on and is used to retrieve the right TLE data for internet or from tle_file in case it is provided.

find_aol(utc_time, lon, lat)
find_aos(utc_time, lon, lat)

Calculate time of last ascending node relative to the specified time


Calculate sublon, sublat and altitude of satellite.

get_next_passes(utc_time, length, lon, lat, alt, tol=0.001, horizon=0)

Calculate passes for the next hours for a given start time and a given observer.

Original by Martin.

utc_time: Observation time (datetime object) length: Number of hours to find passes (int) lon: Longitude of observer position on ground (float) lat: Latitude of observer position on ground (float) alt: Altitude above sea-level (geoid) of observer position on ground (float) tol: precision of the result in seconds horizon: the elevation of horizon to compute risetime and falltime.

Return: [(rise-time, fall-time, max-elevation-time), …]

get_observer_look(utc_time, lon, lat, alt)

Calculate observers look angle to a satellite.

utc_time: Observation time (datetime object) lon: Longitude of observer position on ground in degrees east lat: Latitude of observer position on ground in degrees north alt: Altitude above sea-level (geoid) of observer position on ground in km

Return: (Azimuth, Elevation)

get_orbit_number(utc_time, tbus_style=False)

Calculate orbit number at specified time. Optionally use TBUS-style orbit numbering (TLE orbit number + 1)

get_position(utc_time, normalize=True)

Get the cartesian position and velocity from the satellite.

exception pyorbital.orbital.OrbitalError
pyorbital.orbital.get_observer_look(sat_lon, sat_lat, sat_alt, utc_time, lon, lat, alt)

Calculate observers look angle to a satellite.

utc_time: Observation time (datetime object) lon: Longitude of observer position on ground in degrees east lat: Latitude of observer position on ground in degrees north alt: Altitude above sea-level (geoid) of observer position on ground in km

Return: (Azimuth, Elevation)


TLE handling

exception pyorbital.tlefile.ChecksumError


pyorbital.tlefile.SATELLITES = {}

The platform numbers are given in a file $PPP_CONFIG/platforms.txt in the following format:

# Mappings between satellite catalogue numbers and corresponding
# platform names from OSCAR.
ALOS-2 39766
CloudSat 29107
CryoSat-2 36508
CSK-1 31598
CSK-2 32376
CSK-3 33412
CSK-4 37216
DMSP-F15 25991
DMSP-F16 28054
DMSP-F17 29522
DMSP-F18 35951
DMSP-F19 39630
EOS-Aqua 27424
EOS-Aura 28376
EOS-Terra 25994
FY-2D 29640
FY-2E 33463
FY-2F 38049
FY-2G 40367
FY-3A 32958
FY-3B 37214
FY-3C 39260
FY-3D 43010
GOES-13 29155
GOES-14 35491
GOES-15 36411
GOES-16 41866
Himawari-6 28622
Himawari-7 28937
Himawari-8 40267
Himawari-9 41836
INSAT-3A 27714
INSAT-3C 27298
INSAT-3D 39216
JASON-2 33105
Kalpana-1 27525
Landsat-7 25682
Landsat-8 39084
Meteosat-7 24932
Meteosat-8 27509
Meteosat-9 28912
Meteosat-10 38552
Meteosat-11 40732
Metop-A 29499
Metop-B 38771
NOAA-15 25338
NOAA-16 26536
NOAA-17 27453
NOAA-18 28654
NOAA-19 33591
NOAA-20 43013
RadarSat-2 32382
Sentinel-1A 39634
SMOS 36036
SPOT-5 27421
SPOT-6 38755
SPOT-7 40053
Suomi-NPP 37849
TanDEM-X 36605
TerraSAR-X 31698
class pyorbital.tlefile.Tle(platform, tle_file=None, line1=None, line2=None)

Class holding TLE objects.


Return first TLE line.


Return second TLE line.


Return satellite platform name.


fetch TLE from internet and save it to destination.


Main for testing TLE reading., tle_file=None, line1=None, line2=None)

Read TLE for satellite from tle_file, from line1 and line2, from the newest file provided in the TLES pattern, or from internet if none is provided.

pyorbital.tlefile.read_platform_numbers(in_upper=False, num_as_int=False)

Read platform numbers from $PPP_CONFIG_DIR/platforms.txt if available.

Astronomical computations

Astronomy module. Parts taken from

pyorbital.astronomy.cos_zen(utc_time, lon, lat)

Cosine of the sun-zenith angle for lon, lat at utc_time. utc_time: datetime.datetime instance of the UTC time lon and lat in degrees.

pyorbital.astronomy.get_alt_az(utc_time, lon, lat)

Return sun altitude and azimuth from utc_time, lon, and lat. lon,lat in degrees What is the unit of the returned angles and heights!? FIXME!


Greenwich mean sidereal utc_time, in radians.

As defined in the AIAA 2006 implementation:


Get the julian day of utc_time.


Get the days since year 2000.

pyorbital.astronomy.observer_position(time, lon, lat, alt)

Calculate observer ECI position.


Calculate the sun earth distance correction, relative to 1 AU.


Ecliptic longitude of the sun at utc_time.


Right ascension and declination of the sun at utc_time.

pyorbital.astronomy.sun_zenith_angle(utc_time, lon, lat)

Sun-zenith angle for lon, lat at utc_time. lon,lat in degrees. The angle returned is given in degrees