apsis-rs/docs/design/units.zh.md

单位与坐标约定

English | 简体中文

本文件记录跨层的单位与坐标约定。单个 crate 的内部约定见其模块文档；这里只 记录跨层边界必须一致的部分，因为边界处的单位不一致是本仓库最容易引入 也最难发现的错误。

长度的两种单位

仓库同时使用千米与米，边界在 orbit 层与 physics 层之间：

层 / crate	长度单位
apsis-kepler、apsis-sgp4、apsis-tle	千米
apsis-ephemeris	千米
apsis-maneuver	千米
apsis-constellation、apsis-coverage、apsis-access、apsis-isl	千米
apsis-topology、apsis-routing、apsis-mesh	长度仅在 apsis-isl 计算，边的 cost 是调用方定义的无量纲值
apsis-handover	不涉及长度；quality 为调用方定义，时间用秒
apsis-coord（Eci、Ecef）	米
apsis-geodesy（Geodetic 高度、椭球半轴、笛卡尔位置）	米
apsis-frames	无量纲（角度与旋转）
apsis-rf、apsis-antenna、apsis-atmosphere、apsis-noise、apsis-doppler、apsis-interference、apsis-link	米、赫兹

选择千米还是米并非任意：卫星轨道用千米表达更自然（apsis-sgp4 输出的量级 是几千），射频链路用米表达更自然（波长与距离用米，与 ITU-R 建议书一致）。 代价是边界处必须显式换算。

边界处的换算

从 orbit 层进入 physics 层时乘以 1000.0，返回时除以 1000.0：

// orbit 层的千米位置转 physics 层的米位置。
let position_km = satellite.propagate_minutes(0.0)?.position;  // 千米
let ecef = Ecef::new(position_km * 1_000.0);                    // 米

漏掉这一步会把卫星放到地球内部，而且数值仍然"看起来合理"，不会立刻报错。 integrate_network 示例对这一边界做了断言：换算后的半径必须与传播器报告 的半径一致，这是唯一能自动发现漏乘或漏除的检查。

角度

所有计算用角度一律为弧度。纬度、经度、倾角、升交点赤经、近地点幅角、 真近点角、仰角、方位角、天线方向图角都是弧度。

唯一的例外是两线元素集：apsis-tle::TwoLineElement 的原始字段按 TLE 格式 用度与每日圈数，因为那是文件的编码。apsis-sgp4 在初始化时换算为弧度与 弧度每分钟。

时间

时间统一用秒表示，原点由调用方选择：

• ops 与 sim 层：从场景原点（scenario epoch）起算的秒数。
• orbit 层：apsis-sgp4 用"距元素历元的分钟数"，apsis-ephemeris 与 其余 crate 用秒。
• 日历时间：apsis-time 的 Epoch 存 TAI 儒略日；UTC 换算经 apsis-leap 的闰秒表。

Orbit::sample_ephemeris 是两种时间表示的边界：入参是距元素历元的分钟， 返回的星历内部用秒，换算在方法内完成。

坐标框架

框架	类型	说明
TEME	apsis_sgp4::State	SGP4 定义的真赤道平春分点框架
ECI	apsis_coord::Eci	惯性笛卡尔坐标
ECEF	apsis_coord::Ecef	地固笛卡尔坐标
大地坐标	apsis_geodesy::Geodetic	纬度、经度、大地高
地面点	apsis_coverage::GroundPoint	大地坐标加仰角遮蔽

TEME 到 ECEF 需要地球自转角（apsis-frames::EarthRotationAngle）加上岁差 章动；apsis-coord 提供变换，apsis-frames 提供角。TEME 与 ECI 的差别是 分点方程，量级低于千分之一度；integrate_network 示例中直接把它当作惯性 系处理，并注明这是该示例的近似。

其它量

• 引力参数：apsis-kepler::GravityParameter，单位 km³/s²。WGS 72 对应 SGP4，WGS 84 对应其余用途；选错会使密切半长轴偏约百万分之一。门面 apsis-orbit::Orbit 把引力参数与传播器绑定，避免这一错误。
• 速度：与长度同层，km/s 或 m/s。
• 功率用瓦、频率用赫兹、温度用开尔文；分贝为功率比，dBi 相对各向同性、 dBd 相对半波偶极子（相差 2.15 dB）。
• 相对量一律无量纲：偏心率、填充率、利用率、信噪比的分贝值。

检查

单位边界没有类型系统保护，靠测试与文档：

• 各层测试覆盖层内换算。
• integrate_network 断言千米与米的边界换算保持半径。
• integrate_ops、integrate_sim 覆盖 ops 与 sim 层的时间轴约定。
• cargo run --release -p apsis-rs --features full --example bench 覆盖 各层热点路径，任一层的接口变更导致编译失败都会在此暴露。