cysgp4: a wrapper around the SGP4 package, for sat TLE calculations
Project description
Version: 0.3.6
Lead author/package maintainer: Benjamin Winkel
Contributor(s): Gyula I.G. Józsa
Repository: on GitHub
Bug tracker: on GitHub
Project 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.8 or later
numpy 1.20 or later
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for cysgp4-0.3.6-cp312-cp312-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 729daf9f411beb6dd18f1c4fcb20091e195a2806e430083a563ae651d2b4fe63 |
|
MD5 | 171d906ccd650de8c0b0c71dac114bab |
|
BLAKE2b-256 | 505ec1bd193813b551c51dc513ef80c7c8850d02ed679e1e6f3520cb3611333c |
Hashes for cysgp4-0.3.6-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 31e4d420327e5d27724fb296db4f3d7242247f346dc8cd51d990a3efea60fb47 |
|
MD5 | 21501149292111892f5485d5ba841bb5 |
|
BLAKE2b-256 | 07bec47e9ddd9030dba880fe071b4206164a71a6027a73bbb5fd4ef992ab001f |
Hashes for cysgp4-0.3.6-cp312-cp312-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74a7327fc1e8b95ec3e83de53cfc520e18439b01bd6789fb3c4bd601878d707f |
|
MD5 | 76d9378e6fd4b28d2cf2212e36adfc21 |
|
BLAKE2b-256 | 373fed63e053a31ff5bb807094cfbc398df31535e32aa129d667db9aee46a06e |
Hashes for cysgp4-0.3.6-cp311-cp311-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 296b53e4ff4df84a7c4415cf3bdfbcc39e6b5a5e5008d2b2598b42a5cefa194d |
|
MD5 | 6b8b1e7feec238161e1ec8f93a001bb5 |
|
BLAKE2b-256 | 1983fec13d2a4cb36511872f61cc6a62836f14a0d68bf0f07b794a762005edb7 |
Hashes for cysgp4-0.3.6-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5172b0914c2dec5f30b16ae76f69d16353604808e7501807e8d79ba343d58b1d |
|
MD5 | 8f9ec0ab7b8f6fcae7b0e1b1a04aa78a |
|
BLAKE2b-256 | 989d72c25cb265640b65eb91bcf17c7aab286a9ed4380f539901458bf743aa99 |
Hashes for cysgp4-0.3.6-cp311-cp311-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6c2293d8f700f22f49468ad257095bf32fdd5d63690d7e406be35669ffab4d50 |
|
MD5 | 0fe48851e09d1423455598efc808b9ba |
|
BLAKE2b-256 | 43ec142c6f4c2baf8cdcb21ba288ab1f2d00f08ff70a303727ba87ac8712ed5a |
Hashes for cysgp4-0.3.6-cp310-cp310-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | eb574bf6d844248adf963dda66b9bd1dea3b5c492c387a99dab3c2f785f29c66 |
|
MD5 | 0e180a3eaf8b12b4324ca98bd2ba8658 |
|
BLAKE2b-256 | 475f6c25c0041021e2e94ea47e72c644f8690c73cc6abeb944cceb9ba213e6db |
Hashes for cysgp4-0.3.6-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d1cb30342315bd2141681ee6ef07252d0212c7e24fbff66d856097c15731bee2 |
|
MD5 | 80086cd3e6835829f7d50562450cf54c |
|
BLAKE2b-256 | 40100f175871112b5949ba93af73b94e88e7011ab5c99b74b5d16a8fb764d2eb |
Hashes for cysgp4-0.3.6-cp310-cp310-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0c8584f606b0d9363f1797f55d1cc8b1a038476329f3faef8efacffd85b979c |
|
MD5 | 310b1f520393ce5061eec65dbf7af87b |
|
BLAKE2b-256 | 364ed4d93e8e207eb43bd0df31066cbccf3386b467756d9181ad8d17a8af4535 |
Hashes for cysgp4-0.3.6-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6dc4f76cbeff5e499f95040cf868ac476ae706b525a1d1b4c9de018a45853a6b |
|
MD5 | 8bf91b92e95c241696c8f586c693d009 |
|
BLAKE2b-256 | ce7b7637ae86db6a12768e63eb30e0fcdb09f047988d2f9177b6dcdb02313959 |
Hashes for cysgp4-0.3.6-cp39-cp39-manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 47345564368dfcb8a9d148236e12d9d4f21763aa9669ca166e9a9e4b08ae951d |
|
MD5 | d369b087f295781f5f156009efd2e2ae |
|
BLAKE2b-256 | f095691f709a104de39fe0ef8e15d2e486337aa470253eae1d268db535a2b1a2 |
Hashes for cysgp4-0.3.6-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9ae7a1d07fd28dcc6d05d7900e689aacbc3107efc14a0a10c7241d5a676993fb |
|
MD5 | 55154dbad0b02739b2736d3a2dc5161b |
|
BLAKE2b-256 | 46ca26fc2f474c5d2bad47bb7d4423a99869d99e42dd1f46e7174ee7d0377ddd |
Hashes for cysgp4-0.3.6-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2fcae85f2e92113c373f825dcde211672a79b71ac2721342899a262a9b911ff2 |
|
MD5 | 13c5c56da2b3d3829eac748011f5823e |
|
BLAKE2b-256 | 1845c14e703aa6923e34860e4d6f59b85607bae5338705f4bb0c042a35bc75c1 |
Hashes for cysgp4-0.3.6-cp38-cp38-manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c9137bcb082b8573ccedaf8ca2642434e8d20331488e881fee6a910b2f98222 |
|
MD5 | 4f41990c671aae98f5cf8aca09acfe73 |
|
BLAKE2b-256 | 4baf3d8957560f1d13451d8cabd35cccead35b8bff8f2a06c33f56f1ae73b96e |
Hashes for cysgp4-0.3.6-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2b0449e69b9d85ebb1582cdba3a0dfc6f32a6b01c430c091745fcf37390a1564 |
|
MD5 | 06121cdac8d19f9495f2941aa2db6b3f |
|
BLAKE2b-256 | f0444ccf1b00e082134d1644ccdde913a3d603d287644fde1facc52a91d05811 |