



  

pyorbital 1.8.0+0.gaa3a216.dirty documentation

 [pyorbital](index.html#document-index) 

 stable

 

[pyorbital](index.html#document-index)

* [Docs](index.html#document-index) »

* pyorbital 1.8.0+0.gaa3a216.dirty documentation

* [Edit on GitHub](https://github.com/pytroll/pyorbital/blob/aa3a2169cb695068fd57cb257a5070736cc50098/doc/source/index.rst)

---

Pyorbital[¶](#pyorbital "Permalink to this headline")

=====================================================

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.

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

Pyorbital is available from the Python Package Index (PyPI) via pip or from

the conda-forge conda channel. To install from PyPI in an existing environment:

```

pip install pyorbital

```

Or in an existing conda-based environment:

```

conda install -c conda-forge pyorbital

```

### From Source[¶](#from-source "Permalink to this headline")

Pyorbital can also be installed from source. If you want to install pyorbital

from the latest in-development version on GitHub you can run:

```

pip install git+https://github.com/pytroll/pyorbital.git

```

However, if you instead want to edit the source code and see the changes reflected

when you run the code you can clone the git repository and install it in

“editable” mode:

```

git clone git://github.com/pytroll/pyorbital.git

cd pyorbital

pip install -e .

```

Add platform missing information[¶](#add-platform-missing-information "Permalink to this headline")

---------------------------------------------------------------------------------------------------

Pyorbital comes with a file *platforms.txt* that maps a satellite name to the NORAD identifier.

This file already contain many low earth orbiting environmental or

meteorological satellites and thus likely be sufficient for your purpose.

But should it not contain your satellites of interest make a copy of the

[platforms.txt](https://github.com/pytroll/pyorbital/blob/main/pyorbital/etc/platforms.txt)

file and add the missing satellites and their NORAD identifiers and place

the file in the directory pointed to by [`PYORBITAL\_CONFIG\_PATH`](#envvar-PYORBITAL_CONFIG_PATH).

The NORAD identifier can be found as the first number of each line in the

Two-Line Elements files (eg. from [`celestrak`\_](#id2)).

Pyorbital comes with a small script `check\_platform.py` to check whether a

satellite is already supported.

```

python -m pyorbital.check\_platform -s NOAA-21

[INFO: 2023-01-22 21:20:25 : pyorbital.tlefile] Satellite NOAA-21 is supported. NORAD number: 54234

[INFO: 2023-01-22 21:20:25 : pyorbital.tlefile] Satellite names and NORAD numbers are defined in /path/to/pyorbital/etc/directory/platforms.txt

```

TLE files[¶](#tle-files "Permalink to this headline")

-----------------------------------------------------

Pyorbital has a module for parsing NORAD TLE-files

```

>>> from pyorbital import tlefile

>>> tle = tlefile.read('noaa 18', '/path/to/my/tle\_file.txt')

>>> tle.inclination

99.043499999999995

```

If no path is provided pyorbital first tries to read any local TLE files in the

directory given by the environment variable [`TLES`](#envvar-TLES). If this variable is not

set Pyorbital will try get the earth observation TLE files over the internet

from [`celestrak`\_](#id4). Note this downloading only happens if no

specific TLE file is provided or if the [`TLES`](#envvar-TLES) environment variable is not set.

The historical TLE files can be requested from

[celestrak](https://celestrak.com/NORAD/archives/request.php).

There is also a script, `fetch\_tles.py`, that can be used to collect

TLE data from several locations. The currently supported locations

are:

* generic network locations without login

* Space-Track (login credentials needed)

* local files

The data are saved in a SQLite3 database, and can be written to a file

after each run. To see configuration options, see the example

configuration in `examples/tle.yaml`.

Computing satellite position[¶](#computing-satellite-position "Permalink to this headline")

-------------------------------------------------------------------------------------------

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[¶](#use-actual-tles-to-increase-accuracy "Permalink to this headline")

-----------------------------------------------------------------------------------------------------------

```

>>> 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='/path/to/tle/files/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='/path/to/tle/files/tle-20150131.txt')

>>> snpp.get\_lonlatalt(dtobj)

(104.1539184988462, 79.328272480878141, 838.81555967963391)

```

Computing astronomical parameters[¶](#computing-astronomical-parameters "Permalink to this headline")

-----------------------------------------------------------------------------------------------------

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)

62.685986438071602

```

`PYORBITAL_CONFIG_PATH`[¶](#envvar-PYORBITAL_CONFIG_PATH "Permalink to this definition")

It is possible (but not mandatory) to define this environment variable to

have full control of certain static data used by Pyorbital:

Pyorbital comes with a file *platforms.txt* that maps a satellite name to the

NORAD identifier. This internal file is accessed by Pyorbital without the

user having to do anything. But if you need to change or update this file

you can make your own copy and place in the directory pointed to by this

environment variable.

`TLES`[¶](#envvar-TLES "Permalink to this definition")

Two Line Element (TLE) files are accessed automatically over the internet

without the user having to do anything. When doing that Pyorbital will fetch

the most recent TLE data which may not be the most optimal for historic data

for instance. Also, it may not be sustainable in a production environment.

However, it is possible to let Pyorbital look for the necessary and more

optimal TLE data locally, by specifying the directory where such local TLE

files are located. If the TLES environment variable is set to point at an

existing local directory Pyorbital will first search for the needed TLEs

there. This can both be useful in an operational setup where access to the

internet is restricted, and when processing old/historic satellite data.

It is possible (but not mandatory) to define this environment variable.

API[¶](#api "Permalink to this headline")

-----------------------------------------

Module for computing the orbital parameters of satellites.

*class* `pyorbital.orbital.``OrbitElements`(*tle*)[¶](#pyorbital.orbital.OrbitElements "Permalink to this definition")

Class holding the orbital elements.

*class* `pyorbital.orbital.``Orbital`(*satellite*, *tle\_file=None*, *line1=None*, *line2=None*)[¶](#pyorbital.orbital.Orbital "Permalink to this definition")

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*)[¶](#pyorbital.orbital.Orbital.find_aol "Permalink to this definition")

`find_aos`(*utc\_time*, *lon*, *lat*)[¶](#pyorbital.orbital.Orbital.find_aos "Permalink to this definition")

`get_equatorial_crossing_time`(*tstart*, *tend*, *node='ascending'*, *local\_time=False*, *rtol=1e-09*)[¶](#pyorbital.orbital.Orbital.get_equatorial_crossing_time "Permalink to this definition")

Estimate the equatorial crossing time of an orbit.

The crossing time is determined via the orbit number, which increases by one if the

spacecraft passes the ascending node at the equator. A bisection algorithm is used to find

the time of that passage.

Args:

tstart: Start time of the orbit

tend: End time of the orbit. Orbit number at the end must be at least one greater than

> 

> at the start. If there are multiple revolutions in the given time interval, the

> crossing time of the last revolution in that interval will be computed.

node: Specifies whether to compute the crossing time at the ascending or descending

node. Choices: (‘ascending’, ‘descending’).

local\_time: By default the UTC crossing time is returned. Use this flag to convert UTC

to local time.

rtol: Tolerance of the bisection algorithm. The smaller the tolerance, the more accurate

the result.

`get_last_an_time`(*utc\_time*)[¶](#pyorbital.orbital.Orbital.get_last_an_time "Permalink to this definition")

Calculate time of last ascending node relative to the

specified time

`get_lonlatalt`(*utc\_time*)[¶](#pyorbital.orbital.Orbital.get_lonlatalt "Permalink to this definition")

Calculate sublon, sublat and altitude of satellite.

<http://celestrak.com/columns/v02n03/>

`get_next_passes`(*utc\_time*, *length*, *lon*, *lat*, *alt*, *tol=0.001*, *horizon=0*)[¶](#pyorbital.orbital.Orbital.get_next_passes "Permalink to this definition")

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. |

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

`get_observer_look`(*utc\_time*, *lon*, *lat*, *alt*)[¶](#pyorbital.orbital.Orbital.get_observer_look "Permalink to this definition")

Calculate observers look angle to a satellite.

<http://celestrak.com/columns/v02n02/>

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*, *as\_float=False*)[¶](#pyorbital.orbital.Orbital.get_orbit_number "Permalink to this definition")

Calculate orbit number at specified time.

Args:

tbus\_style: If True, use TBUS-style orbit numbering (TLE orbit number + 1)

as\_float: Return a continuous orbit number as float.

`get_position`(*utc\_time*, *normalize=True*)[¶](#pyorbital.orbital.Orbital.get_position "Permalink to this definition")

Get the cartesian position and velocity from the satellite.

`utc2local`(*utc\_time*)[¶](#pyorbital.orbital.Orbital.utc2local "Permalink to this definition")

Convert UTC to local time.

*exception* `pyorbital.orbital.``OrbitalError`[¶](#pyorbital.orbital.OrbitalError "Permalink to this definition")

`pyorbital.orbital.``get_observer_look`(*sat\_lon*, *sat\_lat*, *sat\_alt*, *utc\_time*, *lon*, *lat*, *alt*)[¶](#pyorbital.orbital.get_observer_look "Permalink to this definition")

Calculate observers look angle to a satellite.

<http://celestrak.com/columns/v02n02/>

| 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 |

| Returns: | (Azimuth, Elevation) |

`pyorbital.orbital.``kep2xyz`(*kep*)[¶](#pyorbital.orbital.kep2xyz "Permalink to this definition")

Classes and functions for handling TLE files.

*exception* `pyorbital.tlefile.``ChecksumError`[¶](#pyorbital.tlefile.ChecksumError "Permalink to this definition")

ChecksumError.

*class* `pyorbital.tlefile.``Downloader`(*config*)[¶](#pyorbital.tlefile.Downloader "Permalink to this definition")

Class for downloading TLE data.

`fetch_plain_tle`()[¶](#pyorbital.tlefile.Downloader.fetch_plain_tle "Permalink to this definition")

Fetch plain text-formated TLE data.

`fetch_spacetrack`()[¶](#pyorbital.tlefile.Downloader.fetch_spacetrack "Permalink to this definition")

Fetch TLE data from Space-Track.

`read_tle_files`()[¶](#pyorbital.tlefile.Downloader.read_tle_files "Permalink to this definition")

Read TLE data from files.

`read_xml_admin_messages`()[¶](#pyorbital.tlefile.Downloader.read_xml_admin_messages "Permalink to this definition")

Read Eumetsat admin messages in XML format.

`pyorbital.tlefile.``SATELLITES` *= {'ALOS-2': '39766', 'CALIPSO': '29108', '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-10': '38552', 'METEOSAT-11': '40732', 'METEOSAT-7': '24932', 'METEOSAT-8': '27509', 'METEOSAT-9': '28912', 'METOP-A': '29499', 'METOP-B': '38771', 'METOP-C': '43689', 'NOAA-10': '16969', 'NOAA-11': '19531', 'NOAA-12': '21263', 'NOAA-14': '23455', 'NOAA-15': '25338', 'NOAA-16': '26536', 'NOAA-17': '27453', 'NOAA-18': '28654', 'NOAA-19': '33591', 'NOAA-20': '43013', 'NOAA-21': '54234', 'NOAA-6': '11416', 'NOAA-7': '12553', 'NOAA-8': '13923', 'NOAA-9': '15427', 'RADARSAT-2': '32382', 'SENTINEL-1A': '39634', 'SENTINEL-3A': '41335', 'SENTINEL-3B': '43437', 'SENTINEL-5P': '42969', 'SMOS': '36036', 'SPOT-5': '27421', 'SPOT-6': '38755', 'SPOT-7': '40053', 'SUOMI-NPP': '37849', 'TANDEM-X': '36605', 'TERRASAR-X': '31698', 'TIROS-N': '11060'}*[¶](#pyorbital.tlefile.SATELLITES "Permalink to this definition")

The platform numbers are given in a file $PYORBITAL\_CONFIG\_PATH/platforms.txt

in the following format:

```

# Mappings between satellite catalogue numbers and corresponding

# platform names from OSCAR.

ALOS-2 39766

CloudSat 29107

CALIPSO 29108

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

Metop-C 43689

TIROS-N 11060

NOAA-6 11416

NOAA-7 12553

NOAA-8 13923

NOAA-9 15427

NOAA-10 16969

NOAA-11 19531

NOAA-12 21263

NOAA-14 23455

NOAA-15 25338

NOAA-16 26536

NOAA-17 27453

NOAA-18 28654

NOAA-19 33591

NOAA-20 43013

NOAA-21 54234

RadarSat-2 32382

Sentinel-1A 39634

Sentinel-3A 41335

Sentinel-3B 43437

Sentinel-5P 42969

SMOS 36036

SPOT-5 27421

SPOT-6 38755

SPOT-7 40053

Suomi-NPP 37849

TanDEM-X 36605

TerraSAR-X 31698

```

*class* `pyorbital.tlefile.``SQLiteTLE`(*db\_location*, *platforms*, *writer\_config*)[¶](#pyorbital.tlefile.SQLiteTLE "Permalink to this definition")

Store TLE data in a sqlite3 database.

`close`()[¶](#pyorbital.tlefile.SQLiteTLE.close "Permalink to this definition")

Close the database.

`update_db`(*tle*, *source*)[¶](#pyorbital.tlefile.SQLiteTLE.update_db "Permalink to this definition")

Update the collected data.

Only data with newer epoch than the existing one is used.

`write_tle_txt`()[¶](#pyorbital.tlefile.SQLiteTLE.write_tle_txt "Permalink to this definition")

Write TLE data to a text file.

*class* `pyorbital.tlefile.``Tle`(*platform*, *tle\_file=None*, *line1=None*, *line2=None*)[¶](#pyorbital.tlefile.Tle "Permalink to this definition")

Class holding TLE objects.

`line1`[¶](#pyorbital.tlefile.Tle.line1 "Permalink to this definition")

Return first TLE line.

`line2`[¶](#pyorbital.tlefile.Tle.line2 "Permalink to this definition")

Return second TLE line.

`platform`[¶](#pyorbital.tlefile.Tle.platform "Permalink to this definition")

Return satellite platform name.

`pyorbital.tlefile.``check_is_platform_supported`(*satname*)[¶](#pyorbital.tlefile.check_is_platform_supported "Permalink to this definition")

Check if satellite is supported and print info.

`pyorbital.tlefile.``collect_filenames`(*paths*)[¶](#pyorbital.tlefile.collect_filenames "Permalink to this definition")

Collect all filenames from *paths*.

`pyorbital.tlefile.``fetch`(*destination*)[¶](#pyorbital.tlefile.fetch "Permalink to this definition")

Fetch TLE from internet and save it to destination.

`pyorbital.tlefile.``get_platforms_filepath`()[¶](#pyorbital.tlefile.get_platforms_filepath "Permalink to this definition")

Get the platforms.txt file path.

Check that the file exists or raise an error.

`pyorbital.tlefile.``main`()[¶](#pyorbital.tlefile.main "Permalink to this definition")

Run a test TLE reading.

`pyorbital.tlefile.``read`(*platform*, *tle\_file=None*, *line1=None*, *line2=None*)[¶](#pyorbital.tlefile.read "Permalink to this definition")

Read TLE for *platform*.

The data are read 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`(*filename*, *in\_upper=False*, *num\_as\_int=False*)[¶](#pyorbital.tlefile.read_platform_numbers "Permalink to this definition")

Read platform numbers from $PYORBITAL\_CONFIG\_PATH/platforms.txt.

`pyorbital.tlefile.``read_tle_from_mmam_xml_file`(*fname*)[¶](#pyorbital.tlefile.read_tle_from_mmam_xml_file "Permalink to this definition")

Read TLEs from a EUMETSAT MMAM XML file.

`pyorbital.tlefile.``read_tles_from_mmam_xml_files`(*paths*)[¶](#pyorbital.tlefile.read_tles_from_mmam_xml_files "Permalink to this definition")

Read TLEs from EUMETSAT MMAM XML files.

`pyorbital.tlefile.``table_exists`(*db*, *name*)[¶](#pyorbital.tlefile.table_exists "Permalink to this definition")

Check if the table ‘name’ exists in the database.

Astronomy module.

Parts taken from <http://www.geoastro.de/elevaz/basics/index.htm>

`pyorbital.astronomy.``cos_zen`(*utc\_time*, *lon*, *lat*)[¶](#pyorbital.astronomy.cos_zen "Permalink to this definition")

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*)[¶](#pyorbital.astronomy.get_alt_az "Permalink to this definition")

Return sun altitude and azimuth from *utc\_time*, *lon*, and *lat*.

lon,lat in degrees

The returned angles are given in radians.

`pyorbital.astronomy.``gmst`(*utc\_time*)[¶](#pyorbital.astronomy.gmst "Permalink to this definition")

Greenwich mean sidereal utc\_time, in radians.

As defined in the AIAA 2006 implementation:

<http://www.celestrak.com/publications/AIAA/2006-6753/>

`pyorbital.astronomy.``jdays`(*utc\_time*)[¶](#pyorbital.astronomy.jdays "Permalink to this definition")

Get the julian day of *utc\_time*.

`pyorbital.astronomy.``jdays2000`(*utc\_time*)[¶](#pyorbital.astronomy.jdays2000 "Permalink to this definition")

Get the days since year 2000.

`pyorbital.astronomy.``observer_position`(*time*, *lon*, *lat*, *alt*)[¶](#pyorbital.astronomy.observer_position "Permalink to this definition")

Calculate observer ECI position.

<http://celestrak.com/columns/v02n03/>

`pyorbital.astronomy.``sun_earth_distance_correction`(*utc\_time*)[¶](#pyorbital.astronomy.sun_earth_distance_correction "Permalink to this definition")

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

`pyorbital.astronomy.``sun_ecliptic_longitude`(*utc\_time*)[¶](#pyorbital.astronomy.sun_ecliptic_longitude "Permalink to this definition")

Ecliptic longitude of the sun at *utc\_time*.

`pyorbital.astronomy.``sun_ra_dec`(*utc\_time*)[¶](#pyorbital.astronomy.sun_ra_dec "Permalink to this definition")

Right ascension and declination of the sun at *utc\_time*.

`pyorbital.astronomy.``sun_zenith_angle`(*utc\_time*, *lon*, *lat*)[¶](#pyorbital.astronomy.sun_zenith_angle "Permalink to this definition")

Sun-zenith angle for *lon*, *lat* at *utc\_time*.

lon,lat in degrees.

The angle returned is given in degrees

