b612/astro
1
1
Fork 0
Code Issues Pull Requests Projects Releases 20 Wiki Activity

20 Releases 20 Tags

RSS Feed
  • v0.3.0 16c62a97d5
    Compare

    v0.3.0 Stable

    b612 released this 2026-09-23 21:34:18 +08:00 | 0 commits to master since this release

    中文

    v0.3.0

    v0.3.0 是一次包含破坏性 API 变更的版本。本版本重新整理 TT、UTC、UT1 与 ΔT 的语义，统一天文计算与输出时标，并扩展日月食、月掩、质心时标和地图导出能力。

    破坏性变更

    • 将实际表示民用时刻的 JDE API 统一改名为 JD：
      • Date2JDE → Date2JD
      • JDECalc → JDCalc
      • JDE2Date → JD2Date
      • JDE2DateByZone → JD2DateByZone
      • GetNowJDE → GetNowJD
      • calendar.NowJDE → calendar.NowJD
      • ApsisEvent.JDE、DeclinationEvent.JDE → JD
      • Time.JDE()、LunarTime.JDE() → JD()
    • 删除含义不明确的 basic.TD2UT：
      • UTC → TT 使用 UTC2TT
      • UT1 → TT 使用 UT12TT
      • TT → UTC 使用 TT2UTC
      • TT → UT1 使用 TT2UT1
      • UTC 与 UT1 之间使用 UTC2UT1 / UT12UTC
    • basic.DeltaT 的语义改为纯 TT−UT1。需要闰秒口径的 TT−UTC 请改用 TTMinusUTCSeconds，需要 UT1−UTC 请使用 DUT1Seconds 或根包的 DUT1。
    • 依赖地球自转的方位、升落、月掩和日食几何改按真实 UT1 计算，历史结果可能出现亚秒级到约 0.4 秒的变化。
    • SVG、GeoJSON 和 KML 默认输出 UTC 标签；需要 UT1 时必须显式选择 TimeScaleUT1 或调用对应的 ...InUT1 API。
    • 月食 GeoJSON 默认增加 visible-during-eclipse、visible-throughout-eclipse、penumbra-moonset 和 penumbra-moonrise 四类要素。需要兼容旧输出时，使用 LunarEclipseOptions.SkipRoles。
    • 月食 SVG 默认输出半影阶段；需要恢复旧的四类分区时，设置 DisablePenumbralPhase。
    • 仍保留 JDE 名称的字段和函数表示真正的 TT 儒略日，例如 SolarEclipsePathPoint.JDE、LunarEclipseDiagramPoint.JDE 和 CalcMoonSHByJDE，不应统一替换为 JD。

    主要变更

    • 新增根包与 basic 的时标转换接口，支持 UTC、UT1、TT、ΔT、DUT1 以及时标标签转换。
    • 新增 ΔT、TT−UTC 和未来时标政策注入，可通过 SetDeltaT、SetTTMinusUTC 和 SetTimeScaleFuturePolicy 对接外部数据或业务口径。
    • 新增 TCG、TCB、TDB 与 TT 之间的质心时标转换。
    • 新增日食贝塞尔要素、太阳半径模型和 WithOptions 入口。
    • 扩展月食可见性判断、正交投影月面图、半影状态和时间包络输出。
    • 扩展日食、月食和月掩的 SVG、GeoJSON 与 KML 2.2 导出，支持时间轴、UT1 标签、等经纬投影和极区投影。
    • 完善恒星三维自行、径向速度与动态距离传播，改进行星事件搜索、升落计算和极端历元稳定性。
    • 补充中英文手册、迁移说明、输出契约测试和历史回归测试。

    闰秒与未来时标

    即将召开的国际计量大会将讨论是否取消或调整闰秒制度。本次版本将未来时标政策显式做成可配置项。

    默认策略仍为 TimeScaleLeapSecond，即按现行闰秒规则对观测数据覆盖范围之外的未来日期进行外推。需要其他制度假设时，可选择：

    • TimeScaleAssumeUT1Tracking：让民用时标继续跟随 UT1；
    • TimeScaleFreezeUTCOffset：冻结当前 UTC 偏移；
    • TimeScaleLeapHour：采用闰时规则；
    • TimeScaleUT1Civil：令民用时标持续等同 UT1。

    观测数据覆盖范围内仍使用实测的 UTC、UT1 和 DUT1；这些未来政策只影响覆盖范围之外的预测和模拟。

    升级建议

    升级前请重点检查：

    1. 全部 JDE 民用时刻 API 是否已改为 JD。
    2. TD2UT 调用是否根据输入和目标时标改用明确的转换函数。
    3. 将 DeltaT 当作 TT−UTC 使用的代码是否改为 TTMinusUTCSeconds。
    4. GeoJSON 消费方是否能处理新增的月食角色。
    5. 需要输出 UT1 的接口是否显式设置了 TimeScaleUT1。

    English

    v0.3.0

    v0.3.0 introduces breaking API changes. It separates TT, UTC, UT1, and ΔT semantics, makes time-scale handling explicit, and expands eclipse, occultation, barycentric time, and map-export capabilities.

    Breaking Changes

    • Civil-time APIs previously named JDE are now named JD, including Date2JD, JDCalc, JD2Date, JD2DateByZone, GetNowJD, calendar.NowJD, event fields, and Time.JD() / LunarTime.JD().
    • basic.TD2UT has been removed:
      • use UTC2TT for UTC → TT;
      • UT12TT for UT1 → TT;
      • TT2UTC for TT → UTC;
      • TT2UT1 for TT → UT1;
      • and UTC2UT1 / UT12UTC for UTC ↔ UT1.
    • basic.DeltaT now consistently means TT−UT1. Use TTMinusUTCSeconds for TT−UTC, and DUT1Seconds or root-level DUT1 for UT1−UTC.
    • Azimuth, rise/set, lunar-occultation, and eclipse geometry now use UT1 instead of treating civil time as an approximation of Earth-rotation time. Historical results may change by sub-second amounts and by up to about 0.4 seconds for older dates.
    • SVG, GeoJSON, and KML labels use UTC by default. Select TimeScaleUT1 or use the corresponding ...InUT1 API for UT1 output.
    • Lunar-eclipse GeoJSON now includes four additional roles by default: visible-during-eclipse, visible-throughout-eclipse, penumbra-moonset, and penumbra-moonrise. Use LunarEclipseOptions.SkipRoles to retain the previous role set.
    • Lunar-eclipse SVGs show the penumbral phase by default. Set DisablePenumbralPhase to restore the previous four-region output.
    • Remaining JDE names represent genuine TT Julian dates, such as SolarEclipsePathPoint.JDE, LunarEclipseDiagramPoint.JDE, and CalcMoonSHByJDE; these should not be renamed to JD.

    Highlights

    • Added UTC, UT1, TT, ΔT, DUT1, and time-scale-label conversion APIs.
    • Added injectable ΔT, TT−UTC, and future time-scale policies through SetDeltaT, SetTTMinusUTC, and SetTimeScaleFuturePolicy.
    • Added TCG, TCB, and TDB conversions to and from TT.
    • Added solar-eclipse Besselian elements, solar-radius models, and WithOptions entry points.
    • Expanded lunar-eclipse visibility classification, orthographic lunar maps, penumbral output, and time-envelope GeoJSON.
    • Added SVG, GeoJSON, and KML 2.2 exports with time markers, UT1 labels, equirectangular projections, and polar projections.
    • Improved three-dimensional stellar proper motion with radial-velocity and dynamic-distance propagation, planetary-event searches, rise/set calculations, and extreme-epoch stability.
    • Added bilingual manuals, migration guidance, output-contract tests, and historical regression coverage.

    Leap Seconds and Future Time Scales

    The upcoming General Conference on Weights and Measures will discuss whether and how the leap-second system should change. future time-scale behavior is configurable in this version.

    The default policy is TimeScaleLeapSecond, which extrapolates the current leap-second convention beyond the observed data range. Applications may instead select:

    • TimeScaleAssumeUT1Tracking;
    • TimeScaleFreezeUTCOffset;
    • TimeScaleLeapHour;
    • TimeScaleUT1Civil.

    Observed UTC, UT1, and DUT1 data remain in effect within the covered range. These policies affect only future dates outside that range.

    Upgrade Checklist

    • Rename all civil-time JDE APIs to their JD equivalents.
    • Replace each TD2UT call with the conversion matching its actual source and target scales.
    • Replace uses of DeltaT as TT−UTC with TTMinusUTCSeconds.
    • Ensure GeoJSON consumers accept the additional lunar-eclipse roles.
    • Select UT1 explicitly wherever UT1 labels are required.
    Downloads