From 7bb313822988f2359010d578314d06948d9bf207 Mon Sep 17 00:00:00 2001 From: ApsisRS contributors Date: Fri, 2 Oct 2026 01:47:49 +0800 Subject: [PATCH] docs: bilingual module docs for the orbit layer --- crates/orbit/apsis-ephemeris/src/ephemeris.rs | 2 ++ crates/orbit/apsis-ephemeris/src/error.rs | 2 ++ crates/orbit/apsis-ephemeris/src/lib.rs | 22 ++++++++++++++++ crates/orbit/apsis-ephemeris/src/sampler.rs | 2 ++ crates/orbit/apsis-kepler/src/anomaly.rs | 16 ++++++++++++ crates/orbit/apsis-kepler/src/elements.rs | 2 ++ crates/orbit/apsis-kepler/src/lib.rs | 13 ++++++++++ crates/orbit/apsis-kepler/src/parameter.rs | 2 ++ crates/orbit/apsis-maneuver/src/burn.rs | 2 ++ crates/orbit/apsis-maneuver/src/error.rs | 2 ++ crates/orbit/apsis-maneuver/src/hohmann.rs | 2 ++ crates/orbit/apsis-maneuver/src/impulse.rs | 2 ++ crates/orbit/apsis-maneuver/src/lib.rs | 26 +++++++++++++++++++ crates/orbit/apsis-orbit/src/lib.rs | 23 ++++++++++++++++ crates/orbit/apsis-orbit/src/orbit.rs | 2 ++ crates/orbit/apsis-sgp4/src/batch.rs | 9 +++++++ crates/orbit/apsis-sgp4/src/deep_space.rs | 17 ++++++++++++ crates/orbit/apsis-sgp4/src/error.rs | 2 ++ crates/orbit/apsis-sgp4/src/init.rs | 12 +++++++++ crates/orbit/apsis-sgp4/src/lib.rs | 22 ++++++++++++++++ crates/orbit/apsis-sgp4/src/model.rs | 17 ++++++++++++ crates/orbit/apsis-sgp4/src/propagate.rs | 12 +++++++++ crates/orbit/apsis-sgp4/src/satellite.rs | 2 ++ crates/orbit/apsis-sgp4/src/state.rs | 2 ++ crates/orbit/apsis-tle/src/checksum.rs | 7 +++++ crates/orbit/apsis-tle/src/element.rs | 2 ++ crates/orbit/apsis-tle/src/field.rs | 2 ++ crates/orbit/apsis-tle/src/lib.rs | 21 +++++++++++++++ 28 files changed, 247 insertions(+) diff --git a/crates/orbit/apsis-ephemeris/src/ephemeris.rs b/crates/orbit/apsis-ephemeris/src/ephemeris.rs index b8a6180..044c3d5 100644 --- a/crates/orbit/apsis-ephemeris/src/ephemeris.rs +++ b/crates/orbit/apsis-ephemeris/src/ephemeris.rs @@ -1,4 +1,6 @@ //! The ephemeris table and its Hermite interpolation. +//! +//! 星历表及其 Hermite 插值。 use crate::error::{EphemerisError, EphemerisErrorKind}; use apsis_math::Vec3; diff --git a/crates/orbit/apsis-ephemeris/src/error.rs b/crates/orbit/apsis-ephemeris/src/error.rs index 72cd908..116afc1 100644 --- a/crates/orbit/apsis-ephemeris/src/error.rs +++ b/crates/orbit/apsis-ephemeris/src/error.rs @@ -1,4 +1,6 @@ //! Errors reported while building or querying an ephemeris. +//! +//! 构建或查询星历时报告的错误。 use core::fmt; diff --git a/crates/orbit/apsis-ephemeris/src/lib.rs b/crates/orbit/apsis-ephemeris/src/lib.rs index e2df21a..0d94013 100644 --- a/crates/orbit/apsis-ephemeris/src/lib.rs +++ b/crates/orbit/apsis-ephemeris/src/lib.rs @@ -60,6 +60,28 @@ //! let state = ephemeris.state_at(30.0).expect("the time is covered"); //! assert!(state.position.norm() > 6_900.0); //! ``` +//! +//! 星历采样与插值。 +//! +//! 传播器给出卫星在任意瞬时的状态，但当结果只用于绘制轨迹或搜索穿越时，调用 +//! 它数百万次是浪费的。本 crate 在一组时刻网格上记录状态（称为样本），并用 +//! 插值回答其间的查询。 +//! +//! 两半是有意独立的： +//! +//! - [`Ephemeris`] 是时刻与状态的表。它对状态来自何处一无所知，故由 SGP4 +//! 传播、由二体理论计算，或从文件读取的表都以相同方式工作。 +//! - [`Sampler`] 通过调用一个由时刻产生状态的函数来填充表。在本工作区中该 +//! 函数通常是 `apsis_sgp4::Satellite::propagate_at`，但采样器只需要一个 +//! 闭包，故测试可用解析函数。 +//! +//! 插值是 Hermite 三次插值，它同时使用区间两端的位与速度。使用速度正是它 +//! 准确的原因：只过两个位置的三次式没有卫星移动多快的信息，而 Hermite 重构 +//! 匹配两端的斜率，故在相同采样间距下能好得多地复现光滑轨道。在圆轨道上误差 +//! 是步长的四阶量，故步长减半使误差约减为十六分之一。 +//! +//! 时间以距调用方所选原点的秒数计，与 orbit 层其余部分一致。位置以千米计， +//! 速度以千米每秒计。 #![forbid(unsafe_code)] #![deny(missing_docs)] diff --git a/crates/orbit/apsis-ephemeris/src/sampler.rs b/crates/orbit/apsis-ephemeris/src/sampler.rs index f69d09f..110b9e6 100644 --- a/crates/orbit/apsis-ephemeris/src/sampler.rs +++ b/crates/orbit/apsis-ephemeris/src/sampler.rs @@ -1,4 +1,6 @@ //! Filling an ephemeris by calling a state function on a grid. +//! +//! 通过在网格上调用状态函数来填充星历。 use crate::ephemeris::{Ephemeris, Sample}; use crate::error::{EphemerisError, EphemerisErrorKind}; diff --git a/crates/orbit/apsis-kepler/src/anomaly.rs b/crates/orbit/apsis-kepler/src/anomaly.rs index 04d37d7..a7c60b2 100644 --- a/crates/orbit/apsis-kepler/src/anomaly.rs +++ b/crates/orbit/apsis-kepler/src/anomaly.rs @@ -20,6 +20,22 @@ //! //! All angles are in radians. The functions reduce their results into //! `[-pi, pi)` so that a value is comparable without further wrapping. +//! +//! 三种近点角之间的换算。 +//! +//! 近点角是度量卫星绕其轨道走了多远的角。此处所用的三种形式是： +//! +//! - 真近点角，自近地点到卫星的角，从中心天体所在的焦点看。它是唯一具有 +//! 直接几何意义者。 +//! - 偏近点角，自近地点到卫星在椭圆辅助圆上的投影的角，从椭圆中心看。 +//! - 平近点角，时间的线性函数，与自近地点起扫过的面积成正比。它没有直接的 +//! 几何意义，但它是轨道随时间传播所采用的形式。 +//! +//! 开普勒方程联系平近点角与偏近点角，且没有闭式解。此处用牛顿法求解，其 +//! 初值足够准确，对小于一的每个偏心率都能在几次迭代内收敛。 +//! +//! 所有角度都以弧度计。各函数把结果归约到 `[-pi, pi)`，使值无需再作环绕即可 +//! 比较。 use core::f64::consts::PI; diff --git a/crates/orbit/apsis-kepler/src/elements.rs b/crates/orbit/apsis-kepler/src/elements.rs index 55a74c6..0caba4d 100644 --- a/crates/orbit/apsis-kepler/src/elements.rs +++ b/crates/orbit/apsis-kepler/src/elements.rs @@ -1,4 +1,6 @@ //! Keplerian elements and their conversion to a Cartesian state. +//! +//! 开普勒根数及其到直角坐标状态的换算。 use crate::anomaly::{eccentric_from_mean, mean_from_eccentric, true_from_eccentric, wrap_to_pi}; use crate::parameter::GravityParameter; diff --git a/crates/orbit/apsis-kepler/src/lib.rs b/crates/orbit/apsis-kepler/src/lib.rs index 6657db5..f385334 100644 --- a/crates/orbit/apsis-kepler/src/lib.rs +++ b/crates/orbit/apsis-kepler/src/lib.rs @@ -33,6 +33,19 @@ //! let state = elements.to_state(GravityParameter::WGS84).expect("valid elements"); //! assert!((state.velocity.norm() - 7.909).abs() < 0.01); //! ``` +//! +//! 开普勒轨道根数与二体传播。 +//! +//! 开普勒根数集把轨道描述为空间中具有固定取向的椭圆、抛物线或双曲线。由 +//! 六个根数与引力参数，本 crate 在二体假定下计算任意时刻的位置与速度，并 +//! 作反方向换算。 +//! +//! 二体模型只包含中心天体的质点引力。它略去地球扁率、阻力与第三体摄动，故 +//! 随时间偏离现实。对分析已知根数的轨道（例如求真近点角处的半径），它是恰当 +//! 的模型；对传播两行根数集，它是错误的模型，后者是 `apsis-sgp4` 的事。 +//! +//! 角度以弧度计。长度以千米计，引力参数以立方千米每平方秒计，与 orbit 层 +//! 其余部分一致。 #![forbid(unsafe_code)] #![deny(missing_docs)] diff --git a/crates/orbit/apsis-kepler/src/parameter.rs b/crates/orbit/apsis-kepler/src/parameter.rs index 2474824..cea09e1 100644 --- a/crates/orbit/apsis-kepler/src/parameter.rs +++ b/crates/orbit/apsis-kepler/src/parameter.rs @@ -1,4 +1,6 @@ //! The Earth gravitational parameter. +//! +//! 地球引力参数。 /// The gravitational parameter of the central body, in cubic kilometers per /// second squared. diff --git a/crates/orbit/apsis-maneuver/src/burn.rs b/crates/orbit/apsis-maneuver/src/burn.rs index de32d8d..f218915 100644 --- a/crates/orbit/apsis-maneuver/src/burn.rs +++ b/crates/orbit/apsis-maneuver/src/burn.rs @@ -1,4 +1,6 @@ //! The finite burn. +//! +//! 有限点火。 use crate::error::{ManeuverError, ManeuverErrorKind}; use apsis_kepler::{GravityParameter, KeplerianElements, State}; diff --git a/crates/orbit/apsis-maneuver/src/error.rs b/crates/orbit/apsis-maneuver/src/error.rs index 67f183f..be22222 100644 --- a/crates/orbit/apsis-maneuver/src/error.rs +++ b/crates/orbit/apsis-maneuver/src/error.rs @@ -1,4 +1,6 @@ //! Errors reported while building or applying a maneuver. +//! +//! 构建或施加机动时报告的错误。 use core::fmt; diff --git a/crates/orbit/apsis-maneuver/src/hohmann.rs b/crates/orbit/apsis-maneuver/src/hohmann.rs index f21fdb7..b5222c9 100644 --- a/crates/orbit/apsis-maneuver/src/hohmann.rs +++ b/crates/orbit/apsis-maneuver/src/hohmann.rs @@ -1,4 +1,6 @@ //! The two impulse Hohmann transfer between coplanar circular orbits. +//! +//! 共面圆轨道之间的双脉冲 Hohmann 转移。 use crate::error::{ManeuverError, ManeuverErrorKind}; use apsis_kepler::GravityParameter; diff --git a/crates/orbit/apsis-maneuver/src/impulse.rs b/crates/orbit/apsis-maneuver/src/impulse.rs index 7855078..5fd512b 100644 --- a/crates/orbit/apsis-maneuver/src/impulse.rs +++ b/crates/orbit/apsis-maneuver/src/impulse.rs @@ -1,4 +1,6 @@ //! The impulsive maneuver. +//! +//! 脉冲机动。 use crate::error::{ManeuverError, ManeuverErrorKind}; use apsis_math::Vec3; diff --git a/crates/orbit/apsis-maneuver/src/lib.rs b/crates/orbit/apsis-maneuver/src/lib.rs index b08a464..8d6a3fd 100644 --- a/crates/orbit/apsis-maneuver/src/lib.rs +++ b/crates/orbit/apsis-maneuver/src/lib.rs @@ -48,6 +48,32 @@ //! assert!(transfer.first_burn > 0.0); //! assert!(transfer.total_delta_v() > 0.0); //! ``` +//! +//! 脉冲式与有限式轨道机动模型。 +//! +//! 机动通过施加推力改变轨道。此处的两个模型是谱系的两端。 +//! +//! 脉冲机动 [`Impulse`] 瞬时施加速度变化，故位置不变、只有速度跃变。这是 +//! 化学推进点火所用的模型，其持续时间相对轨道周期很短，也是每本教科书 +//! delta-v 预算所写的模型。它在点火时间为零的极限下精确，也是两轨道之间 +//! 转移各闭式结果的来源。 +//! +//! 有限机动 [`FiniteBurn`] 在一段时长上施加恒定加速度，故位置在点火期间 +//! 漂移，且当推力须对抗引力时，所达到的速度变化小于推力在自由空间中会给出 +//! 的。这是电推进器所用的模型，其点火可能持续轨道的很大一部分，也适用于 +//! 任何短时近似不够好的点火。 +//! +//! 二者在极限下一致：加速度为 `a`、时长为 `t` 的有限点火给出冲量 `a t`， +//! 故时长趋于零的 [`FiniteBurn`] 收敛到相应的 [`Impulse`]。测试检查该极限， +//! 正是它把两个模型联系起来。 +//! +//! 脉冲模型还提供两个共面圆轨道之间经典的双脉冲转移 +//! [`hohmann_transfer`]，它是每个低推力结果所比较的参照。它给出给定半径的 +//! 两个圆轨道之间转移的两次点火与总 delta-v，以及转移时间，即转移椭圆的 +//! 半个周期。 +//! +//! 约定与 orbit 层其余部分一致：长度以千米计，速度以千米每秒计，角度以 +//! 弧度计。 #![forbid(unsafe_code)] #![deny(missing_docs)] diff --git a/crates/orbit/apsis-orbit/src/lib.rs b/crates/orbit/apsis-orbit/src/lib.rs index 6ebdb8e..819d721 100644 --- a/crates/orbit/apsis-orbit/src/lib.rs +++ b/crates/orbit/apsis-orbit/src/lib.rs @@ -49,6 +49,29 @@ //! let osculating = orbit.osculating_elements(60.0).expect("state exists"); //! assert!(osculating.eccentricity < 0.01); //! ``` +//! +//! 整合 orbit 层的轨道状态门面。 +//! +//! 本 crate 是 orbit 层的单一入口。它重导出根数解析、解析传播器与二体模型， +//! 并加入一个把它们联系起来的类型。 +//! +//! [`Orbit`] 保存为传播准备好的卫星，连同其初始化所用的引力模型，并提供该层 +//! 所支持的两种轨道描述之间的换算： +//! +//! - 由 SGP4 传播的平根数，这是两行根数集所针对的模型，也是复现已编目卫星 +//! 已发布位置的唯一方式。 +//! - 瞬时开普勒根数，它描述某一瞬时的密切二体轨道，对检视与规划机动有用。 +//! +//! 两种描述不可互换。用二体模型传播平根数，或用 SGP4 传播密切根数，会给出 +//! 不同且错误的答案；此处的换算明确说明它们朝哪个方向进行。 +//! +//! 另有两项操作建立在传播之上并在此公开，因为它们需要同一引力参数以保持 +//! 一致： +//! +//! - [`Orbit::sample_ephemeris`] 在时间网格上记录轨迹，使其可经插值而非 +//! 传播查询，这正是覆盖或可见性搜索所需的。 +//! - [`Orbit::apply_burn`] 对密切状态施加有限机动并返回所得根数，这正是 +//! 机动规划所产生的。 #![forbid(unsafe_code)] #![deny(missing_docs)] diff --git a/crates/orbit/apsis-orbit/src/orbit.rs b/crates/orbit/apsis-orbit/src/orbit.rs index 21cdf54..23749f9 100644 --- a/crates/orbit/apsis-orbit/src/orbit.rs +++ b/crates/orbit/apsis-orbit/src/orbit.rs @@ -1,4 +1,6 @@ //! The combined orbit type. +//! +//! 合并后的轨道类型。 use apsis_ephemeris::EphemerisError; use apsis_kepler::{GravityParameter, KeplerianElements}; diff --git a/crates/orbit/apsis-sgp4/src/batch.rs b/crates/orbit/apsis-sgp4/src/batch.rs index 39bcfe6..e404f62 100644 --- a/crates/orbit/apsis-sgp4/src/batch.rs +++ b/crates/orbit/apsis-sgp4/src/batch.rs @@ -8,6 +8,15 @@ //! //! The parallel entry point produces the same values as the sequential one, //! in the same order. It differs only in how the work is distributed. +//! +//! 在许多瞬时上的批量传播，可选跨多个线程。 +//! +//! 单颗卫星的轨迹是覆盖运行或可见性搜索的常见情形：调用方想要某一天每一 +//! 分钟、某一壳层每颗卫星的状态。每个状态与其他独立，故该循环是多核的 +//! 候选，且工作量大到启动线程本身就值回代价。 +//! +//! 并行入口产生与顺序入口相同的值，次序也相同。它只在工作的分配方式上 +//! 不同。 use crate::{Satellite, State}; use apsis_math::parallel::map_index; diff --git a/crates/orbit/apsis-sgp4/src/deep_space.rs b/crates/orbit/apsis-sgp4/src/deep_space.rs index 1111fd6..2ff55bb 100644 --- a/crates/orbit/apsis-sgp4/src/deep_space.rs +++ b/crates/orbit/apsis-sgp4/src/deep_space.rs @@ -20,6 +20,23 @@ //! and `znl`, the tesseral coefficients such as `q22`, and the resonance //! coefficients are quoted to the precision the reference uses, because //! reproducing its output requires the same rounding. +//! +//! 传播器的深空分支。 +//! +//! 轨道周期为 225 分钟及以上的卫星用 SDP4 理论传播，它以日月摄动及与地球 +//! 引力场的共振扩展 SGP4。 +//! +//! 各摄动分为三组。长期项随时间线性增长，累积在各速率字段中。长周期项随 +//! 太阳与月球的位置变化，由 [`dpper`] 施加。当轨道周期与地球自转成简单 +//! 整数比（每天一圈或两圈）时出现共振项，由于没有闭式，由 [`dspace`] 数值 +//! 积分。 +//! +//! 各系数在初始化时计算一次，因为它们只依赖于历元根数与历元时间。 +//! +//! 出处：每个表达式都遵循 Vallado 等，*Revisiting Spacetrack Report #3*， +//! AIAA 2006-6753，2006，以及随该论文分发的参考实现。诸如 `zes` 与 `znl` +//! 的摄动幅度、诸如 `q22` 的田谐系数，以及共振系数都取参考实现所用的精度， +//! 因为复现其输出需要相同的舍入。 use crate::satellite::{Satellite, TWO_PI}; use core::f64::consts::PI; diff --git a/crates/orbit/apsis-sgp4/src/error.rs b/crates/orbit/apsis-sgp4/src/error.rs index a4cb93e..2609961 100644 --- a/crates/orbit/apsis-sgp4/src/error.rs +++ b/crates/orbit/apsis-sgp4/src/error.rs @@ -1,4 +1,6 @@ //! Errors reported by the propagator. +//! +//! 传播器报告的错误。 use core::fmt; diff --git a/crates/orbit/apsis-sgp4/src/init.rs b/crates/orbit/apsis-sgp4/src/init.rs index 1293aab..7d6ca23 100644 --- a/crates/orbit/apsis-sgp4/src/init.rs +++ b/crates/orbit/apsis-sgp4/src/init.rs @@ -13,6 +13,18 @@ //! //! Source: the correction and the coefficient definitions follow Vallado et //! al., *Revisiting Spacetrack Report #3*, AIAA 2006-6753, 2006. +//! +//! 由两行根数集初始化传播器。 +//! +//! 根数集给出以度、每天圈数计的平根数与一个阻力项。传播器以弧度、每分钟 +//! 弧度与地球半径工作，故初始化换算各输入并预计算只依赖于根数的每个系数。 +//! +//! 量 `no_unkozai` 是去掉根数集所用 Kozai 平运动约定影响后的修正平运动。 +//! 该修正由二阶带谐项得出，并用不动点迭代求解，因为修正后的值出现在关系的 +//! 两侧。 +//! +//! 出处：该修正与各系数定义遵循 Vallado 等，*Revisiting Spacetrack +//! Report #3*，AIAA 2006-6753，2006。 use crate::error::{PropagationError, PropagationErrorKind}; use crate::model::GravityModel; diff --git a/crates/orbit/apsis-sgp4/src/lib.rs b/crates/orbit/apsis-sgp4/src/lib.rs index 3387aee..0717a74 100644 --- a/crates/orbit/apsis-sgp4/src/lib.rs +++ b/crates/orbit/apsis-sgp4/src/lib.rs @@ -49,6 +49,28 @@ //! assert!(state.position.norm() > 6_600.0); //! assert!(state.position.norm() < 7_200.0); //! ``` +//! +//! SGP4 与 SDP4 解析轨道传播器。 +//! +//! 该传播器接收两行根数集的平轨道根数，返回卫星在所请求瞬时的位置与速度。 +//! 它是各根数集所拟合的模型，故是使用它们的正确方式；给同一个根数集一个 +//! 通用数值积分器会偏离已发布的位置。 +//! +//! 有两条分支，传播器按轨道周期在二者之间选择。周期低于 225 分钟的卫星用 +//! SGP4 传播，它建模地球扁率的长期效应与一个阻力项。周期不低于该值的卫星 +//! 用 SDP4 传播，它加入在该高度占主导的共振与日月摄动。 +//! +//! 输入与输出： +//! +//! - 根数是来自 [`apsis_tle::TwoLineElement`] 的平根数。根数集中的角度以度 +//! 计，平运动以每天圈数计；本 crate 内部换算为弧度与每分钟弧度。 +//! - 输出表达在真赤道平春分点（TEME）坐标系中，位置以千米计、速度以千米 +//! 每秒计。TEME 是该模型所定义的坐标系；把它换算到地固系需要地球自转与 +//! 分点方程式，不属于本 crate。 +//! - 时间自根数集历元起以分钟计。 +//! +//! 出处：该算法遵循 Vallado 等，*Revisiting Spacetrack Report #3*， +//! AIAA 2006-6753，2006，以及随该论文分发的修订实现。 #![forbid(unsafe_code)] #![deny(missing_docs)] diff --git a/crates/orbit/apsis-sgp4/src/model.rs b/crates/orbit/apsis-sgp4/src/model.rs index ad5b091..94e8e1b 100644 --- a/crates/orbit/apsis-sgp4/src/model.rs +++ b/crates/orbit/apsis-sgp4/src/model.rs @@ -20,6 +20,23 @@ //! Vallado et al., *Revisiting Spacetrack Report #3*, AIAA 2006-6753, //! appendix. The values match the WGS 72 gravity field. //! - WGS 84 values: NIMA TR8350.2, third edition, 2000. +//! +//! 传播器所用的引力模型。 +//! +//! 传播器需要描述地球的四个数：引力参数、赤道半径，以及二阶与三阶带谐项。 +//! SGP4 模型是 fitted 到 WGS 72 值的，而 Space-Track 分发的标准根数集意在 +//! 与它们一起使用，故 WGS 72 是缺省。 +//! +//! 提供 WGS 84 是因为也有 fitted 到它的根数。把模型与 fitted 到另一模型的 +//! 根数集混用会使位置偏移数千米，故该选择应与根数的来源相匹配。 +//! +//! 导出值 `xke`、`tumin` 与 `j3oj2` 由这四个定义数得出，在构造时计算一次。 +//! +//! 出处： +//! +//! - WGS 72 值，即 Vallado 等，*Revisiting Spacetrack Report #3*， +//! AIAA 2006-6753 附录中 SGP4 参考实现所用者。各值与 WGS 72 引力场一致。 +//! - WGS 84 值：NIMA TR8350.2，第三版，2000。 /// A gravity model: the Earth constants used by the propagator. /// diff --git a/crates/orbit/apsis-sgp4/src/propagate.rs b/crates/orbit/apsis-sgp4/src/propagate.rs index ecfcac1..73f3052 100644 --- a/crates/orbit/apsis-sgp4/src/propagate.rs +++ b/crates/orbit/apsis-sgp4/src/propagate.rs @@ -14,6 +14,18 @@ //! Source: the sequence follows Vallado et al., *Revisiting Spacetrack //! Report #3*, AIAA 2006-6753, 2006, and the reference implementation //! distributed with that paper. +//! +//! 近地传播步。 +//! +//! 给定一条卫星记录与一个距历元的时间，本模块求 SGP4 理论的长期项与周期 +//! 项，并返回真赤道平春分点坐标系中的状态。 +//! +//! 平根数随时间以多项式推进：平近点角、近地点幅角与赤经是线性的，赤经另有 +//! 一个二次项，而对高于简化阈值的轨道，半长轴、偏心率与平近点角还会获得 +//! 更多阻力项。随后用牛顿法解轨道求偏近点角，并施加短周期项。 +//! +//! 出处：该序列遵循 Vallado 等，*Revisiting Spacetrack Report #3*， +//! AIAA 2006-6753，2006，以及随该论文分发的参考实现。 use crate::error::{PropagationError, PropagationErrorKind}; use crate::satellite::{Method, Satellite, TWO_PI}; diff --git a/crates/orbit/apsis-sgp4/src/satellite.rs b/crates/orbit/apsis-sgp4/src/satellite.rs index a2dacee..93aa179 100644 --- a/crates/orbit/apsis-sgp4/src/satellite.rs +++ b/crates/orbit/apsis-sgp4/src/satellite.rs @@ -1,4 +1,6 @@ //! The satellite record and its initialisation from mean elements. +//! +//! 卫星记录及其由平根数的初始化。 use crate::error::{PropagationError, PropagationErrorKind}; use crate::init::{self, Elements}; diff --git a/crates/orbit/apsis-sgp4/src/state.rs b/crates/orbit/apsis-sgp4/src/state.rs index 9eb1ec4..15e489b 100644 --- a/crates/orbit/apsis-sgp4/src/state.rs +++ b/crates/orbit/apsis-sgp4/src/state.rs @@ -1,4 +1,6 @@ //! The propagated state of a satellite. +//! +//! 卫星被传播后的状态。 use apsis_math::Vec3; diff --git a/crates/orbit/apsis-tle/src/checksum.rs b/crates/orbit/apsis-tle/src/checksum.rs index 2ae5eb6..5330081 100644 --- a/crates/orbit/apsis-tle/src/checksum.rs +++ b/crates/orbit/apsis-tle/src/checksum.rs @@ -7,6 +7,13 @@ //! //! The checksum digit itself is the last character of the line and is not //! part of the sum. +//! +//! 两行根数格式的行校验和。 +//! +//! 每行以一个数字结尾，它是前面各列的校验和。该校验和是该行十进制数字之和 +//! 模十，其中负号贡献一，其余每个字符贡献零。 +//! +//! 校验和数字本身是该行的最后一个字符，不属于该和。 use crate::field::{ElementError, ElementErrorKind, Result}; diff --git a/crates/orbit/apsis-tle/src/element.rs b/crates/orbit/apsis-tle/src/element.rs index d713ebe..b8af1e6 100644 --- a/crates/orbit/apsis-tle/src/element.rs +++ b/crates/orbit/apsis-tle/src/element.rs @@ -1,4 +1,6 @@ //! Structured fields of a two-line element set. +//! +//! 两行根数集的结构化字段。 use crate::checksum::verify_line_checksum; use crate::field::{ElementError, ElementErrorKind, Result}; diff --git a/crates/orbit/apsis-tle/src/field.rs b/crates/orbit/apsis-tle/src/field.rs index 415958d..f56e487 100644 --- a/crates/orbit/apsis-tle/src/field.rs +++ b/crates/orbit/apsis-tle/src/field.rs @@ -1,4 +1,6 @@ //! The error type and result alias for element parsing. +//! +//! 根数解析的错误类型与结果别名。 use core::fmt; diff --git a/crates/orbit/apsis-tle/src/lib.rs b/crates/orbit/apsis-tle/src/lib.rs index 60b12d7..f8617c1 100644 --- a/crates/orbit/apsis-tle/src/lib.rs +++ b/crates/orbit/apsis-tle/src/lib.rs @@ -37,6 +37,27 @@ //! assert_eq!(element.satellite_number, 25544); //! assert!((element.eccentricity - 0.0006703).abs() < 1e-12); //! ``` +//! +//! 两行根数集的解析。 +//! +//! 两行根数集（TLE）以北美防空司令部所用、由 Space-Track 分发的形式描述 +//! 卫星轨道。卫星名称携带在可选的第一行，其后两行携带轨道数据。 +//! +//! 该格式是定宽的。每个字段占据固定的列范围，每行的校验和是其各位数字之和 +//! 模十，其中负号计为一。本 crate 把 TLE 解析为结构化字段，并校验各行校验和 +//! 与相匹配的根数集编号。它不解释各字段；平根数及其单位是 `apsis-sgp4` 的 +//! 事。 +//! +//! 列位置以 1 为基，与该格式的文档一致。该格式有两条约定值得明确写出，因为 +//! 它们容易误读： +//! +//! - 指数字段写为一个带符号的单数字后接幅度。例如 ` 12345-3` 意为 +//! `0.12345e-3`，而非 `12345e-3`。 +//! - 隐含小数点不写小数点。例如偏心率字段 `0006703` 意为 `0.0006703`。 +//! +//! 出处：字段布局遵循 CelesTrak 发布的格式说明，*FAQs: Two-Line Element Set +//! Format*，它记录了原 NORAD 规范所定义的各列。校验和规则即其中所述、 +//! Space-Track 所用者。 #![forbid(unsafe_code)] #![deny(missing_docs)]