-
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 的语义，统一天文计算与输出时标，并扩展日月食、月掩、质心时标和地图导出能力。
破坏性变更
- 将实际表示民用时刻的
JDEAPI 统一改名为JD：Date2JDE→Date2JDJDECalc→JDCalcJDE2Date→JD2DateJDE2DateByZone→JD2DateByZoneGetNowJDE→GetNowJDcalendar.NowJDE→calendar.NowJDApsisEvent.JDE、DeclinationEvent.JDE→JDTime.JDE()、LunarTime.JDE()→JD()
- 删除含义不明确的
basic.TD2UT：- UTC → TT 使用
UTC2TT - UT1 → TT 使用
UT12TT - TT → UTC 使用
TT2UTC - TT → UT1 使用
TT2UT1 - UTC 与 UT1 之间使用
UTC2UT1/UT12UTC
- UTC → TT 使用
basic.DeltaT的语义改为纯TT−UT1。需要闰秒口径的TT−UTC请改用TTMinusUTCSeconds，需要UT1−UTC请使用DUT1Seconds或根包的DUT1。- 依赖地球自转的方位、升落、月掩和日食几何改按真实 UT1 计算，历史结果可能出现亚秒级到约 0.4 秒的变化。
- SVG、GeoJSON 和 KML 默认输出 UTC 标签；需要 UT1 时必须显式选择
TimeScaleUT1或调用对应的...InUT1API。 - 月食 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；这些未来政策只影响覆盖范围之外的预测和模拟。
升级建议
升级前请重点检查：
- 全部
JDE民用时刻 API 是否已改为JD。 TD2UT调用是否根据输入和目标时标改用明确的转换函数。- 将
DeltaT当作TT−UTC使用的代码是否改为TTMinusUTCSeconds。 - GeoJSON 消费方是否能处理新增的月食角色。
- 需要输出 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
JDEare now namedJD, includingDate2JD,JDCalc,JD2Date,JD2DateByZone,GetNowJD,calendar.NowJD, event fields, andTime.JD()/LunarTime.JD(). basic.TD2UThas been removed:- use
UTC2TTfor UTC → TT; UT12TTfor UT1 → TT;TT2UTCfor TT → UTC;TT2UT1for TT → UT1;- and
UTC2UT1/UT12UTCfor UTC ↔ UT1.
- use
basic.DeltaTnow consistently meansTT−UT1. UseTTMinusUTCSecondsforTT−UTC, andDUT1Secondsor root-levelDUT1forUT1−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
TimeScaleUT1or use the corresponding...InUT1API for UT1 output. - Lunar-eclipse GeoJSON now includes four additional roles by default:
visible-during-eclipse,visible-throughout-eclipse,penumbra-moonset, andpenumbra-moonrise. UseLunarEclipseOptions.SkipRolesto retain the previous role set. - Lunar-eclipse SVGs show the penumbral phase by default. Set
DisablePenumbralPhaseto restore the previous four-region output. - Remaining
JDEnames represent genuine TT Julian dates, such asSolarEclipsePathPoint.JDE,LunarEclipseDiagramPoint.JDE, andCalcMoonSHByJDE; these should not be renamed toJD.
Highlights
- Added UTC, UT1, TT, ΔT, DUT1, and time-scale-label conversion APIs.
- Added injectable ΔT,
TT−UTC, and future time-scale policies throughSetDeltaT,SetTTMinusUTC, andSetTimeScaleFuturePolicy. - Added TCG, TCB, and TDB conversions to and from TT.
- Added solar-eclipse Besselian elements, solar-radius models, and
WithOptionsentry 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
JDEAPIs to theirJDequivalents. - Replace each
TD2UTcall with the conversion matching its actual source and target scales. - Replace uses of
DeltaTasTT−UTCwithTTMinusUTCSeconds. - Ensure GeoJSON consumers accept the additional lunar-eclipse roles.
- Select UT1 explicitly wherever UT1 labels are required.
Downloads
- 将实际表示民用时刻的
-
v0.3.0-rc1 Pre-Release
2026-09-17 12:29:08 +08:00 | 2 commits to master since this releasefeat: 完善日月食与月掩几何链路并扩展历法接口
- 新增日月食中心带、偏食带、阴影足迹、等时线、食分线及升落边界计算，支持极区与混合食拓扑
- 新增日食单时刻阴影求解器、站心状态查询、批量采样和 ΔT 覆盖接口
- 重构恒星与行星月掩路径，补充有限盘面接触、站心修正、掩带宽度、极区投影及升落边界
- 扩展 SVG 与 GeoJSON 输出，支持详细面板、全球/极区/地球投影、边界闭合、时间标记和拓扑签名
- 扩展日月食候选搜索、局地搜索、沙罗序列预计算与范围外推，补充系列锚点和成员一致性校验
- 补齐古历纪年、儒略历独有闰日、多公历候选、历法改革跨日及精确日期运算接口
- 优化 ΔT、章动、恒星时、月球地平线、事件根搜索和本地星历缓存，降低重复计算开销并提升边界稳定
Downloads
-
v0.2.0 Stable
2026-08-06 12:41:42 +08:00 | 3 commits to master since this release中文
主要变更
- 新增恒星/月掩完整能力：支持固定地点接触、全球掩带、几何掩甚点、局地与全球 SVG，以及星表坐标转换。
- 新增日食、月食和月掩的全球投影图与 GeoJSON 输出，支持时间标记、等经纬/极区投影和无行政边界底图。
- 扩展日食中心线与偏食足迹，补齐 P1-P4、U1-U4 接触信息和可选中心影采样。
- 修正站心时角、月出月落和太阳升落口径，改为按动态标准折射与实时太阳/月球视半径计算上缘过地平线。
- 收紧行星合冲、留、大距与驻留事件搜索的收敛和边界控制，增加非有限输入保护，提升极端时刻与古代样本稳定性。
English
Highlights
- Added full stellar and planetary lunar-occultation support: fixed-site contacts, global footprints, geometric greatest points, local/global SVGs, and catalog-coordinate conversion.
- Added global projection maps and GeoJSON exports for solar eclipses, lunar eclipses, and lunar occultations, with time markers plus equirectangular and polar projections.
- Expanded solar-eclipse central-path and partial-footprint outputs with P1-P4 / U1-U4 contact data and optional central-shadow sampling.
- Corrected topocentric hour-angle handling and Sun/Moon rise-set semantics by using dynamic standard refraction and instantaneous semidiameters for upper-limb crossings.
- Hardened conjunction, station, elongation, and related event searches with bounded convergence and non-finite input guards.
Downloads
-
v0.1.5-rc2 Pre-Release
2026-06-11 09:34:57 +08:00 | 4 commits to master since this releasecalendar: 补齐前104古历纪年解析与回归测试
- 为先秦与秦汉古历结果填充周、鲁、秦、西汉早期纪年信息
- 支持默认与显式古历下的年号日期解析
Downloads
-
v0.1.5-rc1 Pre-Release
2026-06-09 19:37:52 +08:00 | 5 commits to master since this release• feat(calendar): 扩展先秦至秦汉古历支持
- 新增显式古历 API，支持先秦古历与秦汉颛顼历选择
- 将默认公农历转换范围扩展至 -721..3000
- 支持后九月解析、负年份干支日和古历法相符节气
- 补充秦汉、先秦、交接边界和节气回归测试
- 同步 README 古历与节气 API 说明
Downloads
-
v0.1.4 Stable
2026-05-30 21:59:40 +08:00 | 6 commits to master since this release中文
主要变更
- 修复 moon.TrueRa / moon.TrueDec / moon.TrueRaDec 的月球地心真赤经、真赤纬口径，使其与公开 API 注释语义一致。
- 新增月球地心视赤经、视赤纬接口：moon.GeocentricApparentRa、moon.GeocentricApparentDec、moon.GeocentricApparentRaDec。
- 新增行星合月（赤经合）查询接口，支持水星、金星、火星、木星、土星、天王星、海王星：
moon.LastConjunctionWithPlanet、moon.NextConjunctionWithPlanet、moon.ClosestConjunctionWithPlanet。 - 修复合月、合日、冲日、留、大距、方照等天象事件 API 在事件边界附近可能重复返回同一事件的问题。
- 优化行星合月搜索在跨世纪、分支跳变和邻近事件场景下的稳定性。
- 统一公开 API 的中英双语注释结构，补齐 calendar、coord、formula、orbit、moon、sun、sundial、star 及各行星包的英文说明。
测试与基线
- 增加月球地心视赤经、视赤纬外部基线测试。
- 增加行星合月外部基线与跨世纪回归测试。
- 增加公开事件 API 的边界单调性测试，覆盖合月、内行星合日/大距/留、外行星合日/冲日/留/方照等场景。
English
Highlights
- Fixed the semantics of moon.TrueRa, moon.TrueDec, and moon.TrueRaDec so they now match the documented geocentric true right ascension and declination contract.
- Added Moon apparent geocentric equatorial APIs: moon.GeocentricApparentRa, moon.GeocentricApparentDec, and moon.GeocentricApparentRaDec.
- Added Moon-planet conjunction APIs for Mercury, Venus, Mars, Jupiter, Saturn, Uranus, and Neptune:
moon.LastConjunctionWithPlanet, moon.NextConjunctionWithPlanet, and moon.ClosestConjunctionWithPlanet. - Fixed event-boundary behavior for conjunctions, oppositions, stations, greatest elongations, quadratures, and Moon-planet conjunctions so Next APIs advance correctly near exact event times.
- Improved Moon-planet conjunction search stability across long time ranges, branch jumps, and near-event queries.
- Standardized bilingual public API comments across calendar, coord, formula, orbit, moon, sun, sundial, star, and planet packages.
Tests and Baselines
- Added external baseline tests for Moon apparent geocentric right ascension and declination.
- Added external Moon-planet conjunction baselines and cross-century regression coverage.
- Added public event-boundary monotonicity tests covering Moon-planet conjunctions, inner-planet conjunctions/elongations/stations, and outer-planet conjunctions/oppositions/stations/quadratures.
Downloads
-
v0.1.4-rc.2 Pre-Release
2026-05-23 23:10:06 +08:00 | 7 commits to master since this releasefix: 修复天象事件 API 在事件边界附近的重复返回问题
- 修正合月、合日、留等Last/Next/Closest接口在精确命中和事件后秒级查询时仍返回当前事件的问题，避免应用侧枚举卡死
- 收紧事件边界判定，并补强水星、金星、火星近事件路径的稳定化，保证公开API的单调前进语义
- 补充公开wrapper、跨世纪样本和外部基线回归，覆盖合月邻近事件与边界场景
Downloads
-
v0.1.3 Stable
2026-05-22 12:34:41 +08:00 | 9 commits to master since this release中文
- 修复七大行星事件计算中的边界与漏检问题，重点覆盖合日、冲日、留、东西方照、内行星大距等场景。
- 统一公开 API 在“精确事件时刻”的 Last/Next 语义，修复 UT/TT 比较口径不一致导致的边界跳轮问题。
- 内行星事件基线改为以 JPL Horizons 为准，NAOJ 作为辅助覆盖参考；外行星留点保留 JPL 参考数据，当前测试仍按既有口径约束。
- 重构行星视位置公共计算路径，补充光行时与视黄经/黄纬修正，并新增校验。
English
- Fixed boundary and missed-cycle issues in planetary event calculations, covering conjunctions, oppositions, stations, quadratures, and inner-planet greatest elongations.
- Normalized public Last/Next API behavior at exact event boundaries, fixing UT/TT comparison mismatches that could skip the current event cycle.
- Switched inner-planet event baselines to JPL Horizons as the authority, with NAOJ used as auxiliary coverage hints; outer-planet station JPL rows are retained as reference data while current tests keep the
existing station semantics. - Refactored the shared apparent-position path, including light-time and apparent ecliptic corrections, and added a small seven-planet Horizons apparent-coordinate fixture.
Downloads
-
v0.1.2 Stable
2026-05-17 21:24:16 +08:00 | 10 commits to master since this release中文
Fixed
- 修复 TinyGo 编译到 wasm 时可能在
planet包初始化阶段报interp: unsupported fcmp的问题。 - 将
planetViews从包级初始化改为sync.Once懒加载，避免 TinyGo 在编译期解释大型float64星历表切片索引。 planet内部视图构建改为返回error，再由兼容层统一panic，避免懒加载初始化失败后留下未初始化缓存。- 补充无效行星数据切片边界测试。
English
Fixed
- Fixed a TinyGo wasm build failure that could report
interp: unsupported fcmpduringplanetpackage initialization. - Changed
planetViewsfrom package-level eager initialization tosync.Oncelazy initialization, avoiding TinyGo compile-time interpretation of largefloat64ephemeris table slicing. - Changed internal planet-view construction to return
error, with the compatibility layer still panicking on corrupted built-in data, avoiding an uninitialized cache after lazy initialization failure. - Added a test for invalid planet-data slice boundaries.
Downloads
- 修复 TinyGo 编译到 wasm 时可能在