sgp4 2.23

使用方法

您可能首先想检查您的机器是否已成功安装了快速的SGP4 C++代码，或者是否使用的是较慢的Python版本（在这种情况下，此值将为false）

>>> from sgp4.api import accelerated
>>> print(accelerated)
True

此库使用与官方C++代码相同的函数名，以帮助那些已经熟悉其他语言中的SGP4的用户。以下是如何计算2019年12月9日20:42:00的国际空间站的x,y,z位置和速度的示例

>>> from sgp4.api import Satrec
>>>
>>> s = '1 25544U 98067A   19343.69339541  .00001764  00000-0  38792-4 0  9991'
>>> t = '2 25544  51.6439 211.2001 0007417  17.6667  85.6398 15.50103472202482'
>>> satellite = Satrec.twoline2rv(s, t)
>>>
>>> jd, fr = 2458826.5, 0.8625
>>> e, r, v = satellite.sgp4(jd, fr)
>>> e
0
>>> print(r)  # True Equator Mean Equinox position (km)
(-6088.92..., -936.13..., -2866.44...)
>>> print(v)  # True Equator Mean Equinox velocity (km/s)
(-1.525..., -5.538..., 5.068...)

作为输入，您可以提供以下内容：

• 对于 jd，提供一个简单的浮点数儒略日，对于 fr，提供一个值0.0，如果您对64位浮点数的精度满意。请注意，现代儒略日大于2,450,000，这意味着64位浮点数的几乎一半的精度将被用于指定日期的整数部分。剩余的数字将提供大约20.1µs的分数精度。这应该不会对结果的精度造成问题——卫星位置通常偏离几公里，远小于卫星在20.1µs内移动的距离——但如果您运行一个求解器，该求解器在搜索上升或下降时间时深入到微秒级别，那么求解器可能会对卫星位置之间的20.1µs平台感到困扰。

• 或者，您可以为 jd 提供一个粗略的日期以及一个非常精确的分数 fr，该分数提供了其余值。计算卫星位置的儒略日是这两个值的总和。一种常见的做法是将整数作为 jd 提供的，将分数作为 fr 提供；另一种做法是让 jd 带有分数0.5，因为UTC午夜发生在每个儒略日的中点。无论哪种方式，分割值允许求解器运行到纳秒级别，同时仍然可以看到SGP4对微小日期调整的微小变化在结果卫星位置中的平稳响应。

以下是如何解释结果：

• e 将是一个非零的错误代码，如果对于给定的日期无法计算卫星位置。您可以通过 from sgp4.api import SGP4_ERRORS 访问将错误代码映射到解释每个代码含义的错误消息的字典。

• r 衡量的是卫星在SGP4使用的独特的真赤道平赤经坐标框架中相对于地球中心的距离，单位为 公里。

• v 速度是位置变化的速率，以 公里/秒 表示。

如果您的应用程序无法原生处理儒略日，您可以使用 jday() 函数从日历日期计算 jd 和 fr。

>>> from sgp4.api import jday
>>> jd, fr = jday(2019, 12, 9, 20, 42, 0)
>>> jd
2458826.5
>>> fr
0.8625

检查您的TLE行

由于TLE是一个旧的固定宽度打孔卡格式，它对是否在正确的列中恰好放置了正确的空格数非常敏感。如果您怀疑您的卫星元素没有被正确加载，请尝试调用较慢的纯Python版本 twoline2rv()，它执行了快速C++版本中没有的额外检查。

>>> from sgp4.earth_gravity import wgs72
>>> from sgp4.io import twoline2rv
>>> assert twoline2rv(s, t, wgs72)

任何TLE格式错误都会引发一个 ValueError。

使用OMM元素代替TLE

由于卫星编号即将用尽，整个行业正在远离原始的TLE格式。

• 一些TLE文件现在使用新的“Alpha-5”约定，通过使用初始字母来扩展卫星编号的范围；例如，“E8493”表示卫星148493。这个库支持Alpha-5约定，并且应该返回Python中的正确整数。

• 一些机构现在以“OMM”轨道平均元素信息格式分发卫星元素，该格式取代了TLE格式。您可以在CelesTrak网站的Dr. T.S. Kelso的 “一种新的获取GP数据的方法” 中了解OMM。

您已经可以尝试实验性地支持OMM

>>> from sgp4 import omm

读取OMM数据需要两步，因为OMM支持几种不同的文本格式。首先，解析输入文本以恢复它存储的字段名称和值；其次，从这些字段值构建一个Python卫星对象。例如，要从XML加载OMM

>>> with open('sample_omm.xml') as f:
...     fields = next(omm.parse_xml(f))
>>> sat = Satrec()
>>> omm.initialize(sat, fields)

或者，从CSV加载OMM

>>> with open('sample_omm.csv') as f:
...     fields = next(omm.parse_csv(f))
>>> sat = Satrec()
>>> omm.initialize(sat, fields)

无论哪种方式，卫星对象都应该被正确初始化并准备好开始产生位置。

如果您有兴趣使用新的OMM格式保存卫星参数，请参阅下面的“导出”部分。

历元

在给定卫星的生命周期中，随着其轨道的发展，会产生数十或数百个不同的TLE记录。每个TLE记录指定了其最准确的“历元日期”。通常，TLE仅在历元日期两侧的两周内有用，超出这个范围其预测变得不可靠。

卫星对象以两位数的年份和年份中的小数天数原生化地提供其历元。

>>> satellite.epochyr
19
>>> satellite.epochdays
343.69339541

由于Sputnik是在1957年发射的，因此卫星元素集永远不会提到更早的年份，所以57到99年意味着1957-1999年，而0到56年意味着2000-2056年。预计TLE格式将在2057年过时，并需要升级到四位数的年份。

要使用 days2mdhms() 函数将天数及其分数转换为日历日期和时间。

>>> from sgp4.api import days2mdhms
>>> month, day, hour, minute, second = days2mdhms(19, 343.69339541)
>>> month
12
>>> day
9
>>> hour
16
>>> minute
38
>>> second
29.363424

SGP4库还提供了将这些两个数字转换为儒略日和分数儒略日的便利函数，因为儒略日在天文学中更常用。

>>> satellite.jdsatepoch
2458826.5
>>> satellite.jdsatepochF
0.69339541

最后，如果您需要儒略日和时间的Python datetime，库中提供了一个便利函数。

>>> from sgp4.conveniences import sat_epoch_datetime
>>> sat_epoch_datetime(satellite)
datetime.datetime(2019, 12, 9, 16, 38, 29, 363423, tzinfo=UTC)

数组加速

为了避免在需要许多日期和时间以获得位置时要运行Python循环的开销，您可以传递您的儒略日数组。只有当您的机器成功安装或编译了SGP4 C++代码时，数组例程才会更快，因此您可能需要先进行检查。

>>> from sgp4.api import accelerated
>>> print(accelerated)
True

要调用数组例程，为 jd 和 fr 创建相同长度的NumPy数组。

>>> import numpy as np
>>> np.set_printoptions(precision=2)

>>> jd = np.array((2458826, 2458826, 2458826, 2458826))
>>> fr = np.array((0.0001, 0.0002, 0.0003, 0.0004))

>>> e, r, v = satellite.sgp4_array(jd, fr)

>>> print(e)
[0 0 0 0]
>>> print(r)
[[-3431.31  2620.15 -5252.97]
 [-3478.86  2575.14 -5243.87]
 [-3526.09  2529.89 -5234.28]
 [-3572.98  2484.41 -5224.19]]
>>> print(v)
[[-5.52 -5.19  1.02]
 [-5.49 -5.22  1.08]
 [-5.45 -5.25  1.14]
 [-5.41 -5.28  1.2 ]]

为了避免在拥有许多卫星和日期时使用Python循环带来的开销，可以从几个单个卫星构建一个SatrecArray。其sgp4()方法将期望jd和fr都是NumPy数组，所以如果您只有一个日期，请确保提供长度为一的NumPy数组。以下是对2个卫星和4个日期的示例计算：

>>> u = '1 20580U 90037B   19342.88042116  .00000361  00000-0  11007-4 0  9996'
>>> w = '2 20580  28.4682 146.6676 0002639 185.9222 322.7238 15.09309432427086'
>>> satellite2 = Satrec.twoline2rv(u, w)

>>> from sgp4.api import SatrecArray
>>> a = SatrecArray([satellite, satellite2])
>>> e, r, v = a.sgp4(jd, fr)

>>> np.set_printoptions(precision=2)
>>> print(e)
[[0 0 0 0]
 [0 0 0 0]]
>>> print(r)
[[[-3431.31  2620.15 -5252.97]
  [-3478.86  2575.14 -5243.87]
  [-3526.09  2529.89 -5234.28]
  [-3572.98  2484.41 -5224.19]]
<BLANKLINE>
 [[ 5781.85  2564.   -2798.22]
  [ 5749.36  2618.59 -2814.63]
  [ 5716.35  2672.94 -2830.78]
  [ 5682.83  2727.05 -2846.68]]]
>>> print(v)
[[[-5.52 -5.19  1.02]
  [-5.49 -5.22  1.08]
  [-5.45 -5.25  1.14]
  [-5.41 -5.28  1.2 ]]
<BLANKLINE>
 [[-3.73  6.33 -1.91]
  [-3.79  6.3  -1.88]
  [-3.85  6.28 -1.85]
  [-3.91  6.25 -1.83]]]

导出

如果您想与朋友分享一个Satrec或者将其持久化到文件，有一个导出例程可以将它转换回TLE。

>>> from sgp4 import exporter
>>> line1, line2 = exporter.export_tle(satellite)
>>> line1
'1 25544U 98067A   19343.69339541  .00001764  00000-0  38792-4 0  9991'
>>> line2
'2 25544  51.6439 211.2001 0007417  17.6667  85.6398 15.50103472202482'

幸运的是，这正是我们创建卫星对象所使用的两个TLE行。

>>> (s == line1) and (t == line2)
True

还有一个导出例程，它生成由新OMM格式定义的字段（见上文的“OMM”部分）。

>>> from pprint import pprint
>>> fields = exporter.export_omm(satellite, 'ISS (ZARYA)')
>>> pprint(fields)
{'ARG_OF_PERICENTER': 17.6667,
 'BSTAR': 3.8792e-05,
 'CENTER_NAME': 'EARTH',
 'CLASSIFICATION_TYPE': 'U',
 'ECCENTRICITY': 0.0007417,
 'ELEMENT_SET_NO': 999,
 'EPHEMERIS_TYPE': 0,
 'EPOCH': '2019-12-09T16:38:29.363423',
 'INCLINATION': 51.6439,
 'MEAN_ANOMALY': 85.6398,
 'MEAN_ELEMENT_THEORY': 'SGP4',
 'MEAN_MOTION': 15.501034720000002,
 'MEAN_MOTION_DDOT': 0.0,
 'MEAN_MOTION_DOT': 1.764e-05,
 'NORAD_CAT_ID': 25544,
 'OBJECT_ID': '1998-067A',
 'OBJECT_NAME': 'ISS (ZARYA)',
 'RA_OF_ASC_NODE': 211.2001,
 'REF_FRAME': 'TEME',
 'REV_AT_EPOCH': 20248,
 'TIME_SYSTEM': 'UTC'}

重力

SGP4算法在一系列常数的顶部运行，这些常数指定了地球引力的强度。最新的SGP4官方论文（见下文）规定：“我们使用WGS-72作为默认值”，因此这个Python模块使用相同的默认值。但是，如果您想使用旧版WGS-72常量或非标准的更现代的WGS-84常量，twoline2rv()构造函数可以接受一个可选参数。

>>> from sgp4.api import WGS72OLD, WGS72, WGS84
>>> satellite3 = Satrec.twoline2rv(s, t, WGS84)

如果您选择WGS-84，您通常会得到更不准确的结果。尽管它反映了更准确和最新的地球测量数据，但整个行业中卫星TLE的生成最有可能以WGS-72为基础。如果您使用生成TLE时所用的相同基本重力常数，您生成的位置将更好地与每个卫星的实际位置相吻合。

提供自己的元素

如果您不想解析TLE而想直接指定轨道元素，可以将它们作为浮点数传递给卫星对象的sgp4init()方法。例如，以下是如何构建与上面第一个代码示例中从TLE加载的相同国际空间站轨道的方法：

>>> satellite2 = Satrec()
>>> satellite2.sgp4init(
...     WGS72,                # gravity model
...     'i',                  # 'a' = old AFSPC mode, 'i' = improved mode
...     25544,                # satnum: Satellite number
...     25545.69339541,       # epoch: days since 1949 December 31 00:00 UT
...     3.8792e-05,           # bstar: drag coefficient (1/earth radii)
...     0.0,                  # ndot: ballistic coefficient (radians/minute^2)
...     0.0,                  # nddot: mean motion 2nd derivative (radians/minute^3)
...     0.0007417,            # ecco: eccentricity
...     0.3083420829620822,   # argpo: argument of perigee (radians)
...     0.9013560935706996,   # inclo: inclination (radians)
...     1.4946964807494398,   # mo: mean anomaly (radians)
...     0.06763602333248933,  # no_kozai: mean motion (radians/minute)
...     3.686137125541276,    # nodeo: R.A. of ascending node (radians)
... )

这些数字看起来与TLE中的数字不同，因为底层的sgp4init()例程使用不同的单位：弧度而不是度。但这仍然是相同的轨道，并将产生相同的位置。

请注意，ndot和nddot被SGP4推进器忽略，因此您可以保持它们为0.0而不影响最终卫星位置。但它们至少会被保存到卫星对象中，并在将参数写入TLE或OMM文件时写入（见上文的“导出”部分）。

要计算“epoch”参数，将历元的儒略日期减去2433281.5天。

虽然底层的sgp4init()例程将属性epochyr、epochdays、jdsatepoch和jdsatepochF设置为未设置，但这个库仍然会为您设置它们，使用您提供的历元。

请参阅下一节，了解一旦初始化卫星记录后可用的完整属性列表。

属性

有几十个Satrec属性，它们公开了底层C++ SGP4记录中的数据。它们分为以下几类。

标识

这些直接从TLE记录复制而来，但不会被传播数学使用。

轨道元素

这些是轨道参数，直接从TLE记录的文本中复制而来。它们描述了TLE的历元时刻的轨道，因此即使卫星记录被反复用来传播不同时间的位置，这些参数也保持不变。

您还可以将历元作为儒略日访问

计算轨道属性

这些是在卫星首次加载时计算的，为可能对它们感兴趣的用户提供了便利。它们不被SGP4传播器本身使用。

传播模式

最近一次传播的结果

可能出现的错误代码有

0. 没有错误。

1. 平均偏心率超出范围 0 ≤ e < 1。

2. 平均轨道运动降至零以下。

3. 受扰偏心率超出范围 0 ≤ e ≤ 1。

4. 轨道半通径长度降至零以下。

5. （不再使用。）

6. 轨道衰减：计算出的位置在地表以下。（如果该向量有助于寻找再入时刻的软件，则仍返回该位置。）

最近一次传播的平均元素

在每次传播过程中，SGP4 例程保存一组“单次平均平均元素”，这些元素描述了正在计算位置的轨道形状。它们是按平均经度平均的，包括长期重力、大气阻力和——在深空模式下——太阳和月亮在整个公转周期内对 SGP4 的扰动。它们省略了 SGP4 在计算每个位置之前应用的太阳和月亮的短期和长期周期性扰动。

重力模型参数

当卫星记录初始化时，您选择的引力模型会导致以下八个常数被复制

打印卫星属性

如果您想打印卫星，这个库提供了一个方便的“属性转储”例程，它接受一个卫星并生成列出其属性的行

from sys import stdout
from sgp4.conveniences import dump_satrec

stdout.writelines(dump_satrec(satellite))

如果您想比较两个卫星，只需传递第二个参数；第二个卫星的属性将打印在第一个卫星的属性旁边，第二个列。

stdout.writelines(dump_satrec(satellite, satellite2))

与官方算法进行验证

此实现通过了 Vallado 等人在 2006 年首次发布 SGP4 修订版的参考实现（SGP4）的 2010 年 8 月发布的所有自动测试。

Vallado, David A., Paul Crawford, Richard Hujsak, and T.S. Kelso, “Revisiting Spacetrack Report #3,” presented at the AIAA/AAS Astrodynamics Specialist Conference, Keystone, CO, 2006 August 21–24.

如果您想查看该论文，它可在网上找到：https://www.celestrak.com/publications/AIAA/2006-6753/。您可以从 AIAA-2006-6753.zip 下载他们的最新版本代码，以便与此 Python 模块（或其他实现）进行比较。

对于开发者

开发者可以从 GitHub 检出此完整项目

https://github.com/brandon-rhodes/python-sgp4

要运行其单元测试，请安装 Python 2、Python 3 和 tox 测试工具。在 Python 2 中运行的测试将锻炼例程的纯 Python 版本，而在 Python 3 中运行的测试将锻炼快速新的 C++ 加速代码

cd python-sgp4
tox

遗留 API

在此库转向包装 Vallado 的官方 C++ 代码并在纯 Python 中运行之前，它有一个稍微古怪的 API，但仍然为与旧客户端兼容而提供支持。您可以通过阅读 1.4 版本或更早的文档来了解它。

https://pypi.ac.cn/project/sgp4/1.4/

更新日志

2023-10-01 — 2.23

• 调整测试，以解决由 Python 3.12 引入的破坏性问题。

2023-04-27 — 2.22

• 添加了 satnum_str 属性，暴露了 C++ 现在以字符串形式存储卫星编号的事实；并检查 satnum 从不大于 339999。

• 修复了从 OMM 记录加载值时 nddot 属性的单位。（由于 TLE 计算本身忽略了此属性，因此这不会影响任何卫星的位置。）

• 增强了 twoline2rv() 的回退 Python 版本，以验证 TLE 行是否为 ASCII，并添加了使用它的文档，以双重检查可能包含非 ASCII 字符的 TLE。

• 如果用户未设置卫星的 classification，现在默认为 'U'，表示“未分类”。

2022-04-06 — 2.21

• 将 dump_satrec() 添加到 sgp4.conveniences 模块。

• 修复了 Satrec 属性 .error，该属性先前从内存中的错误数据构建了一个无意义的整数。

• 从 Python Satrec 中移除了 .whichconst，以帮助用户避免编写在 C++ 扩展可用时会导致中断的代码。

2021-07-01 — 2.20

• 教 sgp4init() 将 epochdays 和 jdsatepochF 四舍五入到与 TLE 中的日期分数相同的 8 位小数，如果用户提供的 epoch 本身小数点后有 8 位或更少的数字。这应该使构建往返 TLE 格式并具有完美精确度的卫星更容易。

• 修复了 export_tle() 格式化 BSTAR 字段的方法，当其值以科学记数法写出时，指数为正。

• 修复了 sgp4init() 分配的 epochyr，因此 2000 年之前的年份现在是两位数字而不是三位（例如，使 1980 产生一个 epochyr 值为 80 而不是 980）。

2021-04-22 — 2.19

• 扩展了 Python 软件包索引和模块文档中的文档，列出此库公开的所有 Satrec 属性；甚至那些不太为人所知的属性也可能对分析卫星轨道的人员有用。

2021-03-08 — 2.18

• 如果 TLE 卫星编号缺少所需的 5 位数字，现在 twoline2rv() 会给底层的 C++ 库提供一点帮助，以便它仍然可以正确解析分类和国际设计符。

• 现在 Satrec 属性 jdsatepoch、jdsatepochF、epochyr 和 epochdays 是可写的，因此用户可以手动调整它们的值——这应该可以弥补 sgp4init() 方法无法使用完全浮点精度设置它们的事实。