Skip to main content

cysgp4: a wrapper around the SGP4 package, for sat TLE calculations

Project description

License-GPL3 License-Apache License-BSD3

PyPI tag PyPI - Downloads

conda-forge platforms: Version on conda-forge conda-forge platforms: linux-64, osx-64, win-64 conda-forge downloads

  • Version: 0.4.0

  • Lead author/package maintainer: Benjamin Winkel

  • Contributor(s): Gyula I.G. Józsa, Boris Sorokin

  • Repository: on GitHub

  • Bug tracker: on GitHub

  • User manual: stable | developer

Project Status

cysgp4's Azure Pipelines Status

Purpose

The cysgp4 package is a Cython-powered wrapper of the sgp4lib library (by Daniel Warner) to compute satellite positions from two-line elements (TLE).

It provides similar functionality as the well-known sgp4 Python package (by Brandon Rhodes), which uses Numba internally to speed-up the calculations. In contrast to sgp4, cysgp4 can work well with arrays of TLEs and/or times and make use of multi-core platforms (via OpenMP) to boost processing times a lot.

Installation

We highly recommend to use cysgp4 with the Anaconda Python distribution, in which case installiation is as easy as

conda install -c conda-forge cysgp4

Otherwise, you should install cysgp4 via pip:

python -m pip install cysgp4

The installation is also possible from source. Detailed installation instructions can be found in the user manual.

Dependencies

We kept the dependencies as minimal as possible. The following packages are required:

  • Python 3.10 or later

  • numpy 2.0 or later (older numpy version may work)

If you want to run the notebooks yourself, you will also need the Jupyter server and install matplotlib. To run the tests, you’ll need sgp4.

Note, for compiling the C-extension, OpenMP is used for parallelization. If you use gcc, for example, you should have at least version 4.8 otherwise the setup-script may fail. Again, see Detailed installation instructions for more information.

Usage

Using cysgp4 is possible via an object-oriented interface or with a fast numpy-array functional approach. The former works like this:

import cysgp4

# Define a date/time and an observer
pydt = cysgp4.PyDateTime.from_mjd(58805.57)
lon_deg, lat_deg = 6.88375, 50.525
alt_km = 0.366
obs = cysgp4.PyObserver(lon_deg, lat_deg, alt_km)

# Define satellite properties/orbit via two-line element string (TLE)
hst_tle = cysgp4.PyTle(
    'HST',
    '1 20580U 90037B   19321.38711875  .00000471  00000-0  17700-4 0  9991',
    '2 20580  28.4699 288.8102 0002495 321.7771 171.5855 15.09299865423838',
    )

# Create a satellite object for querying coordinates
sat = cysgp4.Satellite(hst_tle, obs, pydt)
sat.eci_pos().loc  # ECI cartesian position, km
(5879.5931344459295, 1545.7455647032068, 3287.4155452595)
sat.eci_pos().vel  # ECI cartesian velocity, km/s
(-1.8205895517672226, 7.374044252723081, -0.20697960810978586)
sat.geo_pos()  # geographic (geodetic) position, lon/lat/alt
<PyCoordGeodetic: 112.2146d, 28.5509d, 538.0186km>
sat.topo_pos()  # topocentric position, az/el/dist/dist_rate
<PyCoordTopocentric: 60.2453d, -35.6844d, 8314.5683km, 3.5087km/s>

# One can change time to determine positions at another moment
sat.mjd += 1 / 720.  # one minute later
sat.topo_pos()
<PyCoordTopocentric: 54.8446d, -38.2749d, 8734.9195km, 3.4885km/s>

In many cases, however, one probably wants to calculate coordinates for a (large) number of satellites, observer locations, and/or observing times. For this, the function ~cysgp4.propagate_many is useful. This is an array interface to the sgp4 calculations, which allows to perform calculations for different satellite TLEs, observers and times in a parallelized manner. ~numpy broadcasting rules apply:

import requests
import numpy as np
from cysgp4 import PyTle, PyObserver, propagate_many

# Download many TLEs from a website
url = 'http://celestrak.com/NORAD/elements/science.txt'
ctrak_science = requests.get(url)
all_lines = ctrak_science.text.split('\\r\\n')

# Need to convert them to a list of tuples (each tuple consisting
# of the three TLE strings)
tle_list = list(zip(*tuple(
    all_lines[idx::3] for idx in range(3)
    )))
# Create an array of PyTle and PyObserver objects, and MJDs
tles = np.array([
    PyTle(*tle) for tle in tle_list
    ])[np.newaxis, np.newaxis, :20]  # use first 20 TLEs
observers = np.array([
    PyObserver(6.88375, 50.525, 0.366),
    PyObserver(16.88375, 50.525, 0.366),
    ])[np.newaxis, :, np.newaxis]
mjds = np.linspace(
    58805.5, 58806.5, 1000  # 1000 time steps
    )[:, np.newaxis, np.newaxis]

# The result is a dictionary
result = propagate_many(mjds, tles, observers)
print(result.keys())
dict_keys(['eci_pos', 'eci_vel', 'geo', 'topo'])

# Returned array shapes are as follows; last array dimension
# contains the coordinate pairs.
print(np.broadcast(mjds, tles, observers).shape)
(1000, 2, 20)
print(result['eci_pos'].shape, result['topo'].shape)
(1000, 2, 20, 3) (1000, 2, 20, 4)

# One can also skip over coordinate frames.
result = propagate_many(
    mjds, tles, observers,
    do_eci_pos=False, do_eci_vel=False, do_geo=False, do_topo=True
    )
print(result.keys())
dict_keys(['topo'])

More use-cases and tutorials

Check out the user manual or the Jupyter tutorial notebooks in the repository for further examples of how to use cysgp4. Note that you can only view the notebooks on GitHub, if you want to edit something it is necessary to clone the repository or download a notebook to run it on your machine.

Who do I talk to?

If you encounter any problems or have questions, do not hesitate to raise an issue or make a pull request. Moreover, you can contact the devs directly:

Licenses

cysgp4 itself is published under GPL v3, an open-source license. The package is a Cython-powered wrapper of the sgp4lib library (by Daniel Warner) to compute satellite positions from two-line elements (TLE). The sgp4lib source code is licensed under Apache-2.0 license

The package is partly based on the Astropy-affiliated package template, which is under BSD 3-clause license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cysgp4-0.4.0.tar.gz (955.9 kB view details)

Uploaded Source

Built Distributions

cysgp4-0.4.0-cp312-cp312-win_amd64.whl (689.3 kB view details)

Uploaded CPython 3.12Windows x86-64

cysgp4-0.4.0-cp312-cp312-manylinux_2_28_x86_64.whl (2.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

cysgp4-0.4.0-cp312-cp312-macosx_10_13_x86_64.whl (741.8 kB view details)

Uploaded CPython 3.12macOS 10.13+ x86-64

cysgp4-0.4.0-cp311-cp311-win_amd64.whl (691.3 kB view details)

Uploaded CPython 3.11Windows x86-64

cysgp4-0.4.0-cp311-cp311-manylinux_2_28_x86_64.whl (2.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

cysgp4-0.4.0-cp311-cp311-macosx_10_13_x86_64.whl (738.9 kB view details)

Uploaded CPython 3.11macOS 10.13+ x86-64

cysgp4-0.4.0-cp310-cp310-win_amd64.whl (691.2 kB view details)

Uploaded CPython 3.10Windows x86-64

cysgp4-0.4.0-cp310-cp310-manylinux_2_28_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

cysgp4-0.4.0-cp310-cp310-macosx_10_13_x86_64.whl (743.8 kB view details)

Uploaded CPython 3.10macOS 10.13+ x86-64

File details

Details for the file cysgp4-0.4.0.tar.gz.

File metadata

  • Download URL: cysgp4-0.4.0.tar.gz
  • Upload date:
  • Size: 955.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.11

File hashes

Hashes for cysgp4-0.4.0.tar.gz
Algorithm Hash digest
SHA256 bb38659db575bddd8aae30c8e1cb8060a278ac06f867b2bd18e1b4ce483d8182
MD5 815d860a555ac33ab3041cd29e9441cb
BLAKE2b-256 6f333baf022b61f80f24995c74effff0f711c34707a6447f3f4538548cd18e26

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: cysgp4-0.4.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 689.3 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.13

File hashes

Hashes for cysgp4-0.4.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 d132e073821691ddbc1f38a926f9ba7ff2e025b2a058c42850cb3a6019a97a73
MD5 ee8480a4842126a2522df094ac100691
BLAKE2b-256 21a693f11894350520a10c5f90ffad1de4402c296dd1e1f314a4e2dcecf0437c

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for cysgp4-0.4.0-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 fb0fcc4ed822c6577a331f9a7411aee218cd244e36cd9717ff46f559754e7941
MD5 241b4d6be5a8a40627d9f16398492e4b
BLAKE2b-256 bb23f97162e0f38b4ee48e1ad278f4370e87eb7fd42f5e142200e9ae57b2e2b6

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp312-cp312-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for cysgp4-0.4.0-cp312-cp312-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 f0726c30321e266e70329c65ca38ecc66c812af511a1d96ae2b4243e021b5975
MD5 ef4fdae1825a8f7c7db0327ae404e6ad
BLAKE2b-256 f43034a1f0bbc43386e14167bcd85ae7c9ecb86dc0f91e4e910b1d61e6ac5fbf

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: cysgp4-0.4.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 691.3 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.13

File hashes

Hashes for cysgp4-0.4.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 9e7170f87b1c169d60d839fb16e0d8e29319657574d0b928c4bfffe8e6753393
MD5 5f6efac8348d4bb7238006d998e8307f
BLAKE2b-256 a291feea64494b17f0880e7adaaf0a25b263e29f71257bcb032e7748ebefdab1

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for cysgp4-0.4.0-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a2f18f125726d25297df9579b8a7716b27c4489e0828e16a5a6097133b94695a
MD5 a097086d9d79d5e5a8f8ab8ca313553c
BLAKE2b-256 638a640de6c8e9f1e16ef46686c4ce7e2ce809582955c345be4df7ec17a4296d

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp311-cp311-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for cysgp4-0.4.0-cp311-cp311-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 b1498e474be500dddb2f9c439fe954f6ea579eea506ea34bfbc88230993eb9b4
MD5 7d0b6288cff5ef463adab8906e65ceaa
BLAKE2b-256 31bbb64df373622967849e0d3a6f8664a7f45054c7c9cae870a61e9396be5fbc

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: cysgp4-0.4.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 691.2 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.13

File hashes

Hashes for cysgp4-0.4.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 d91c847ea779bb235125866c6569255a7215fdd5da5f7920a83537748e6593b2
MD5 0c2b2437fba42c98a96658189d067dd3
BLAKE2b-256 8e549b63ba4f6231680e918892128a49f914eb76790df6d50c5c605412ea0e7d

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for cysgp4-0.4.0-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 85ce63de2e8556ccb2f97c669bd4c8aea02ebaa7f5ab5e8b4eeba46e1f3d3241
MD5 9e6644ef871428a8482929c797eac756
BLAKE2b-256 ac69cb2a024ab55dcb61b837734f16cf1f272abca52e9abb3704ad26761e7cc3

See more details on using hashes here.

File details

Details for the file cysgp4-0.4.0-cp310-cp310-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for cysgp4-0.4.0-cp310-cp310-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 007ba2d07ceb6e371e3ecfbe7c5ab84524497011f7f27de1740e8cbea47f87c9
MD5 e1c91d0863c83af4b27e6037dcfc9f83
BLAKE2b-256 39163bff5611da06502e847438191b7cfded15d8bf86d324d2a5402213960dc0

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page