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

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

## Computing satellite postion

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

    >>> from pyorbital.orbital import Orbital
    >>> from datetime import datetime
    >>> orb = Orbital("noaa 18")
    >>> now = datetime.utcnow()
    >>> # Get normalized position and velocity of the satellite:
    >>> orb.get_position(now)
    ([0.57529384846822862, 0.77384005228105424, 0.59301408257897559],
    [0.031846489698768146, 0.021287993461926374, -0.05854106186659274])
    >>> # Get longitude, latitude and altitude of the satellite:
    >>> orb.get_lonlatalt(now)
    (-1.1625895579622014, 0.55402132517640568, 847.89381184656702)

## 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 retreive 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_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.

    Return: [(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 lat: Latitude of observer position on ground alt: Altitude above sea-level (geoid) of observer position on ground

    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.``kep2xyz`(kep)

### TLE handling

exception `pyorbital.tlefile.``ChecksumError`

  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 GOES-13 29155 GOES-14 35491 GOES-15 36411 Himawari-6 28622 Himawari-7 28937 Himawari-8 40267 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 Metop-A 29499 Metop-B 38771 NOAA-15 25338 NOAA-16 26536 NOAA-17 27453 NOAA-18 28654 NOAA-19 33591 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.

  `line1`

    Return first TLE line.

  `line2`

    Return second TLE line.

  `platform`

    Return satellite platform name.

`pyorbital.tlefile.``fetch`(destination)

  fetch TLE from internet and save it to destination.

`pyorbital.tlefile.``main`()

  Main for testing TLE reading.

`pyorbital.tlefile.``read`(platform, 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 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 What is the unit of the returned angles and heights!? FIXME!

`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