# Pyorbital

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

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 = tlefile.read('noaa 18', '/path/to/my/tle_file.txt')
    >>> tle.inclination
    99.043499999999995

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

### TLE download and database

The historical TLE files can be requested from celestrak.

There is also a script, `fetch_tles.py`, that can be used to collect TLE data from several locations. Then currently supported locaions 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

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

## API

### 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)
  get_equatorial_crossing_time(tstart, tend, node='ascending', local_time=False, rtol=1e-09)

    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)

    Calculate time of last ascending node relative to the specified time

  get_lonlatalt(utc_time)

    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)

    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)

    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)

    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)

    Get the cartesian position and velocity from the satellite.

  utc2local(utc_time)

    Convert UTC to local time.

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

### TLE handling

Classes and functions for handling TLE files.

exception pyorbital.tlefile.ChecksumError

  ChecksumError.

class pyorbital.tlefile.Downloader(config)

  Class for downloading TLE data.

  fetch_plain_tle()

    Fetch plain text-formated TLE data.

  fetch_spacetrack()

    Fetch TLE data from Space-Track.

  read_tle_files()

    Read TLE data from files.

  read_xml_admin_messages()

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

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

class pyorbital.tlefile.SQLiteTLE(db_location, platforms, writer_config)

  Store TLE data in a sqlite3 database.

  close()

    Close the database.

  update_db(tle, source)

    Update the collected data.

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

  write_tle_txt()

    Write TLE data to a text file.

class pyorbital.tlefile.Tle(platform, tle_file=None, line1=None, line2=None)

  Class holding TLE objects.

  property line1

    Return first TLE line.

  property line2

    Return second TLE line.

  property platform

    Return satellite platform name.

pyorbital.tlefile.collect_filenames(paths)

  Collect all filenames from paths.

pyorbital.tlefile.fetch(destination)

  Fetch TLE from internet and save it to destination.

pyorbital.tlefile.main()

  Run a test TLE reading.

pyorbital.tlefile.read(platform, tle_file=None, line1=None, line2=None)

  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(in_upper=False, num_as_int=False)

  Read platform numbers from $PPP_CONFIG_DIR/platforms.txt.

pyorbital.tlefile.read_tle_from_mmam_xml_file(fname)

pyorbital.tlefile.read_tles_from_mmam_xml_files(paths)

pyorbital.tlefile.table_exists(db, name)

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

### Astronomical computations

Astronomy module. Parts taken from http://www.geoastro.de/elevaz/basics/index.htm

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 The returned angles are given in radians.

pyorbital.astronomy.gmst(utc_time)

  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)

  Get the julian day of utc_time.

pyorbital.astronomy.jdays2000(utc_time)

  Get the days since year 2000.

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

  Calculate observer ECI position.

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

pyorbital.astronomy.sun_earth_distance_correction(utc_time)

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

pyorbital.astronomy.sun_ecliptic_longitude(utc_time)

  Ecliptic longitude of the sun at utc_time.

pyorbital.astronomy.sun_ra_dec(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