feat: 引入可切换星历模型并扩展天象观测链路

- 新增半解析、旧模型、自定义与多源堆叠星历实例,提供 Context、Instance、SPK 读取及状态与视位置计算
- 统一太阳、月球和行星实例接口,扩展黄经穿越、留、相位、最近角距、偕日可见、任意高度升落、轨道节点及凌日等天象查询
- 完善日月食、月掩与凌日的月缘剖面、有限盘面接触、站心修正、局地可见性、全球路径和地图输出
- 新增 SVG、GeoJSON、KML 天象输出及凌日、月掩和月缘地形相关缓存与几何求解
- 新增恒星星表导入与查询,支持 CSV、Hipparcos、BSC5、Stellarium 等格式及名称、交叉标识、锥面检索和星等过滤
- 补充 IAU 2006、地球定向、折射消光、大气观测、轨道传播及半解析行星/月球数据支持
- 将默认未来民用时标切换为 TimeScaleLeapHour,更新 2027–2400 农历速查表、中文日期解析和时区边界处理
- 增加事件基线、跨模型回归、几何边界、月缘地形和输出契约测试,完善中英文手册、示例资源、NOTICE 与忽略规则
This commit is contained in:
2026-10-15 23:54:15 +08:00
parent 16c62a97d5
commit 044f2f4381
674 changed files with 62983 additions and 8396 deletions
+43
View File
@@ -0,0 +1,43 @@
package phenomena
import (
"time"
"b612.me/astro/basic"
)
// AltitudeLimb 日月取高度的位置 / limb used for Sun and Moon altitude.
type AltitudeLimb = basic.AltitudeLimb
const (
LimbUpper = basic.AltitudeLimbUpper
LimbCenter = basic.AltitudeLimbCenter
LimbLower = basic.AltitudeLimbLower
)
// AltitudeOptions 任意高度升落选项;零值为上缘、标准气象、计入折射 / altitude crossing options.
type AltitudeOptions = basic.AltitudeCrossingOptions
// AltitudeState 一个民用日内的穿越状态 / crossing state over one civil day.
type AltitudeState = basic.AltitudeCrossingState
const (
AltitudeCrosses = basic.AltitudeCrosses
AltitudeAlwaysAbove = basic.AltitudeAlwaysAbove
AltitudeAlwaysBelow = basic.AltitudeAlwaysBelow
AltitudeTangent = basic.AltitudeTangent
)
// AltitudeCrossingResult date 所在民用日内首次升、落(无则为零值,对应 HasRise/HasSet 为 false)与残差范围(度)/ first rise and set on the civil day.
type AltitudeCrossingResult = basic.AltitudeCrossingResult
// AltitudeCrossing 日、月或行星在 date 所在民用日内穿过视高度 altitude(度,相对天文地平)的时刻;height 只影响月球视差 /
// Sun, Moon or planet crossings of an apparent altitude.
func (module *Phenomena) AltitudeCrossing(body Body, date time.Time, lon, lat, height, altitude float64, options AltitudeOptions) (AltitudeCrossingResult, error) {
return basic.SkyAltitudeCrossingOnDate(body, date, lon, lat, height, altitude, options, module.inst)
}
// StarAltitudeCrossing 恒星(视赤经、视赤纬,度)穿过视高度 altitude 的时刻 / star crossings of an apparent altitude.
func StarAltitudeCrossing(date time.Time, ra, dec, lon, lat, altitude float64, options AltitudeOptions) (AltitudeCrossingResult, error) {
return basic.StarAltitudeCrossingOnDate(date, ra, dec, lon, lat, altitude, options)
}
+53
View File
@@ -0,0 +1,53 @@
package phenomena
import "time"
// LongitudeCrossings 视黄经经过 longitude 的全部时刻 / times when the apparent longitude equals longitude.
func LongitudeCrossings(body Body, longitude float64, start, end time.Time) []Event {
return defaultModule.LongitudeCrossings(body, longitude, start, end)
}
// Stations 视黄经留 / longitude stations.
func Stations(body Body, start, end time.Time) []Event {
return defaultModule.Stations(body, start, end)
}
// AspectCrossings a 与 b 视黄经差(a − b)等于 angle 的时刻 / times when lon(a) − lon(b) equals angle.
func AspectCrossings(a, b Body, angle float64, start, end time.Time) []Event {
return defaultModule.AspectCrossings(a, b, angle, start, end)
}
// ClosestApproaches 两天体最近角距 / closest approaches of two bodies.
func ClosestApproaches(a, b Body, maxSeparation float64, start, end time.Time) []Event {
return defaultModule.ClosestApproaches(a, b, maxSeparation, start, end)
}
// StarApproaches 天体与恒星最近角距 / closest approaches of a body to a star.
func StarApproaches(body Body, star StarCoordinate, maxSeparation float64, start, end time.Time) []Event {
return defaultModule.StarApproaches(body, star, maxSeparation, start, end)
}
// PlanetHeliacalEvents 行星偕日事件 / planet heliacal events.
func PlanetHeliacalEvents(body Body, start, end time.Time, lon, lat float64, options HeliacalOptions) []HeliacalEvent {
return defaultModule.PlanetHeliacalEvents(body, start, end, lon, lat, options)
}
// StarHeliacalEvents 恒星偕日事件 / star heliacal events.
func StarHeliacalEvents(star StarCoordinate, magnitude float64, start, end time.Time, lon, lat float64, options HeliacalOptions) []HeliacalEvent {
return defaultModule.StarHeliacalEvents(star, magnitude, start, end, lon, lat, options)
}
// Apsides 行星或地球的近日点与远日点 / perihelia and aphelia.
func Apsides(body Body, start, end time.Time) []OrbitalEvent {
return defaultModule.Apsides(body, start, end)
}
// Nodes 行星的升交点与降交点 / node passages.
func Nodes(body Body, start, end time.Time) []OrbitalEvent {
return defaultModule.Nodes(body, start, end)
}
// AltitudeCrossing 日、月或行星穿过任意视高度的时刻 / altitude crossings with the default ephemeris.
func AltitudeCrossing(body Body, date time.Time, lon, lat, height, altitude float64, options AltitudeOptions) (AltitudeCrossingResult, error) {
return defaultModule.AltitudeCrossing(body, date, lon, lat, height, altitude, options)
}
+30
View File
@@ -0,0 +1,30 @@
package phenomena
import (
"testing"
"time"
)
func TestApsidesIndependentOfHostZone(t *testing.T) {
start := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
end := time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC)
saved := time.Local
defer func() { time.Local = saved }()
time.Local = time.UTC
want := Apsides(Earth, start, end)
newYork, err := time.LoadLocation("America/New_York")
if err != nil {
newYork = time.FixedZone("EST", -5*3600)
}
time.Local = newYork
got := Apsides(Earth, start, end)
if len(got) != len(want) || len(got) == 0 {
t.Fatalf("len got %d, want %d", len(got), len(want))
}
for i := range got {
if !got[i].Time.Equal(want[i].Time) || got[i].Time.Location() != time.UTC {
t.Fatalf("event %d: got %v, want %v", i, got[i].Time, want[i].Time)
}
}
}
+176
View File
@@ -0,0 +1,176 @@
// Package phenomena 提供任意两天体的黄经穿越、留、相位、最近角距与偕日可见搜索 / generic sky event and heliacal visibility searches.
package phenomena
import (
"time"
"b612.me/astro/basic"
"b612.me/astro/internal/ephem"
)
// Body 可搜索的天体 / searchable body.
type Body = basic.SkyBody
// Earth 地球,只用于 Apsides / Earth, valid only for Apsides.
const Earth = basic.SkyEarth
const (
// Sun 太阳 / the Sun.
Sun = basic.SkySun
// Moon 月球 / the Moon.
Moon = basic.SkyMoon
// Mercury 水星 / Mercury.
Mercury = basic.SkyMercury
// Venus 金星 / Venus.
Venus = basic.SkyVenus
// Mars 火星 / Mars.
Mars = basic.SkyMars
// Jupiter 木星 / Jupiter.
Jupiter = basic.SkyJupiter
// Saturn 土星 / Saturn.
Saturn = basic.SkySaturn
// Uranus 天王星 / Uranus.
Uranus = basic.SkyUranus
// Neptune 海王星 / Neptune.
Neptune = basic.SkyNeptune
)
// StarCoordinate 恒星星表坐标 / catalog star coordinate.
type StarCoordinate = basic.StarCoordinate
// HeliacalOptions 偕日可见参数 / heliacal visibility options.
type HeliacalOptions = basic.HeliacalOptions
// HeliacalEventKind 偕日事件类型 / heliacal event kind.
type HeliacalEventKind = basic.HeliacalEventKind
const (
// HeliacalMorningFirst 晨始见(偕日升) / morning first visibility.
HeliacalMorningFirst = basic.HeliacalMorningFirst
// HeliacalMorningLast 晨末见 / morning last visibility.
HeliacalMorningLast = basic.HeliacalMorningLast
// HeliacalEveningFirst 昏始见 / evening first visibility.
HeliacalEveningFirst = basic.HeliacalEveningFirst
// HeliacalEveningLast 昏末见(偕日落) / evening last visibility.
HeliacalEveningLast = basic.HeliacalEveningLast
)
// Event 天象事件;Value 为事件对应的角量(度)/ sky event; Value is the event angle in degrees.
type Event struct {
Time time.Time
Value float64
}
// HeliacalEvent 偕日事件,Time 为当次晨昏最佳可见时刻 / heliacal event at the best moment of that twilight.
type HeliacalEvent struct {
Kind HeliacalEventKind
Time time.Time
Margin float64
TargetAltitude float64
SunAltitude float64
}
// Phenomena 指定星历实例的计算模块 / computation module bound to an ephemeris instance.
type Phenomena struct{ inst *ephem.Instance }
// NewWithInstance 创建指定星历实例的模块,nil 使用全局模型 / create a module; nil uses the global model.
func NewWithInstance(inst *ephem.Instance) *Phenomena { return &Phenomena{inst: inst} }
var defaultModule Phenomena
func toTT(date time.Time) float64 { return basic.UTC2TT(basic.Date2JD(date.UTC())) }
func events(list []basic.SkyEvent, loc *time.Location) []Event {
out := make([]Event, 0, len(list))
for _, e := range list {
out = append(out, Event{Time: basic.JD2DateByZone(basic.TT2UTC(e.JDE), loc, false), Value: e.Value})
}
return out
}
// LongitudeCrossings 视黄经经过 longitude 的全部时刻 / times when the apparent longitude equals longitude.
func (module *Phenomena) LongitudeCrossings(body Body, longitude float64, start, end time.Time) []Event {
return events(basic.SkyLongitudeCrossingsWithInstance(body, longitude, toTT(start), toTT(end), module.inst), start.Location())
}
// Stations 视黄经留,Value 为留时视黄经 / longitude stations; Value is the longitude.
func (module *Phenomena) Stations(body Body, start, end time.Time) []Event {
return events(basic.SkyStationsWithInstance(body, toTT(start), toTT(end), module.inst), start.Location())
}
// AspectCrossings a 与 b 视黄经差(a − b)等于 angle 的时刻 / times when lon(a) − lon(b) equals angle.
func (module *Phenomena) AspectCrossings(a, b Body, angle float64, start, end time.Time) []Event {
return events(basic.SkyAspectCrossingsWithInstance(a, b, angle, toTT(start), toTT(end), module.inst), start.Location())
}
// ClosestApproaches 两天体地心视角距的局部极小,Value 为角距(度)/ closest approaches within maxSeparation degrees.
func (module *Phenomena) ClosestApproaches(a, b Body, maxSeparation float64, start, end time.Time) []Event {
return events(basic.SkySeparationMinimaWithInstance(a, b, maxSeparation, toTT(start), toTT(end), module.inst), start.Location())
}
// StarApproaches 天体与恒星地心视角距的局部极小 / closest approaches of a body to a star.
func (module *Phenomena) StarApproaches(body Body, star StarCoordinate, maxSeparation float64, start, end time.Time) []Event {
return events(basic.SkyStarSeparationMinimaWithInstance(body, star, maxSeparation, toTT(start), toTT(end), module.inst), start.Location())
}
func heliacal(list []basic.HeliacalEvent, loc *time.Location) []HeliacalEvent {
out := make([]HeliacalEvent, 0, len(list))
for _, e := range list {
out = append(out, HeliacalEvent{e.Kind, basic.JD2DateByZone(e.JD, loc, false), e.Margin, e.TargetAltitude, e.SunAltitude})
}
return out
}
// PlanetHeliacalEvents 行星晨昏始见、末见(经度东正)/ planet heliacal events; longitude east positive.
func (module *Phenomena) PlanetHeliacalEvents(body Body, start, end time.Time, lon, lat float64, options HeliacalOptions) []HeliacalEvent {
return heliacal(basic.FindPlanetHeliacalEventsWithInstance(body, basic.Date2JD(start.UTC()), basic.Date2JD(end.UTC()), lon, lat, options, module.inst), start.Location())
}
// StarHeliacalEvents 恒星晨昏始见、末见;magnitude 为 V 星等 / star heliacal events with V magnitude.
func (module *Phenomena) StarHeliacalEvents(star StarCoordinate, magnitude float64, start, end time.Time, lon, lat float64, options HeliacalOptions) []HeliacalEvent {
return heliacal(basic.FindStarHeliacalEventsWithInstance(star, magnitude, basic.Date2JD(start.UTC()), basic.Date2JD(end.UTC()), lon, lat, options, module.inst), start.Location())
}
// LimitingMagnitude 无月夜肉眼极限星等(Schaefer 模型),消光系数非正时为 NaN / naked-eye limiting magnitude without moonlight.
func LimitingMagnitude(targetAltitude, sunAltitude, separation, extinction float64) float64 {
return basic.LimitingMagnitude(targetAltitude, sunAltitude, separation, extinction)
}
// OrbitalEventKind 轨道事件类型 / orbital event kind.
type OrbitalEventKind = basic.OrbitalEventKind
const (
// Perihelion 近日点 / perihelion.
Perihelion = basic.OrbitalPerihelion
// Aphelion 远日点 / aphelion.
Aphelion = basic.OrbitalAphelion
// AscendingNode 升交点 / ascending node.
AscendingNode = basic.OrbitalAscendingNode
// DescendingNode 降交点 / descending node.
DescendingNode = basic.OrbitalDescendingNode
)
// OrbitalEvent 轨道事件,DistanceAU 为日心距 / orbital event with heliocentric distance in AU.
type OrbitalEvent struct {
Time time.Time
Kind OrbitalEventKind
DistanceAU float64
}
func orbital(list []basic.OrbitalEvent, loc *time.Location) []OrbitalEvent {
out := make([]OrbitalEvent, 0, len(list))
for _, e := range list {
out = append(out, OrbitalEvent{Time: basic.JD2DateByZone(basic.TT2UTC(e.JDE), loc, false), Kind: e.Kind, DistanceAU: e.DistanceAU})
}
return out
}
// Apsides 行星或地球在 [start, end] 内的近日点与远日点 / perihelia and aphelia in the window.
func (module *Phenomena) Apsides(body Body, start, end time.Time) []OrbitalEvent {
return orbital(basic.PlanetApsidesWithInstance(body, toTT(start), toTT(end), module.inst), start.Location())
}
// Nodes 行星在 [start, end] 内穿过历元平黄道的升交点与降交点 / ascending and descending node passages.
func (module *Phenomena) Nodes(body Body, start, end time.Time) []OrbitalEvent {
return orbital(basic.PlanetNodesWithInstance(body, toTT(start), toTT(end), module.inst), start.Location())
}
+41
View File
@@ -0,0 +1,41 @@
// 被测契约:公开包装与 basic 一致,并保留输入时区。
package phenomena
import (
"testing"
"time"
)
func TestGreatConjunctionPublic(t *testing.T) {
loc := time.FixedZone("CST", 8*3600)
got := ClosestApproaches(Jupiter, Saturn, 1, time.Date(2020, 10, 1, 0, 0, 0, 0, loc), time.Date(2021, 3, 1, 0, 0, 0, 0, loc))
if len(got) != 1 || got[0].Time.Location() != loc || got[0].Time.Month() != time.December || got[0].Value > 0.11 {
t.Fatalf("%+v", got)
}
}
func TestVenusHeliacalPublic(t *testing.T) {
got := PlanetHeliacalEvents(Venus, time.Date(2025, 2, 15, 0, 0, 0, 0, time.UTC), time.Date(2025, 4, 30, 0, 0, 0, 0, time.UTC), 116.4, 39.9, HeliacalOptions{})
if len(got) < 2 {
t.Fatalf("%+v", got)
}
}
func TestAltitudeCrossingPublic(t *testing.T) {
date := time.Date(2025, 3, 20, 0, 0, 0, 0, time.FixedZone("CST", 8*3600))
got, err := AltitudeCrossing(Sun, date, 116.4, 39.9, 0, -18, AltitudeOptions{Limb: LimbCenter, NoRefraction: true})
if err != nil || !got.HasRise || !got.HasSet || got.State != AltitudeCrosses {
t.Fatalf("astronomical twilight: %+v %v", got, err)
}
if got.Rise.Hour() != 4 || got.Set.Hour() != 19 {
t.Errorf("unexpected twilight times %v %v", got.Rise, got.Set)
}
star, err := StarAltitudeCrossing(date, 101.287, -16.716, 116.4, 39.9, 0, AltitudeOptions{})
if err != nil || !star.HasRise {
t.Fatalf("star: %+v %v", star, err)
}
ev := Apsides(Earth, time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC))
if len(ev) != 2 || ev[0].Kind != Perihelion || ev[0].Time.Month() != time.January {
t.Errorf("earth apsides 2026: %+v", ev)
}
}
+29
View File
@@ -0,0 +1,29 @@
package phenomena
import "b612.me/astro/basic"
// StarData 内嵌 9100 星表中的一条记录 / one entry from the embedded 9100-star catalog.
type StarData = basic.StarData
// StarCoordinateFromStarData 将星表记录转换为恒星坐标 / converts a catalog entry to a star coordinate.
func StarCoordinateFromStarData(star StarData) (StarCoordinate, error) {
return basic.StarCoordinateFromStarData(star)
}
// StarCoordinateByHR 按 HR 编号从内嵌星表得到恒星坐标 / returns a star coordinate by HR number.
func StarCoordinateByHR(hr int) (StarCoordinate, error) {
star, err := basic.StarDataByHR(hr)
if err != nil {
return StarCoordinate{}, err
}
return StarCoordinateFromStarData(star)
}
// StarCoordinateByName 按内嵌星表中文名得到恒星坐标 / returns a star coordinate by Chinese catalog name.
func StarCoordinateByName(name string) (StarCoordinate, error) {
star, err := basic.StarDataByChinese(name)
if err != nil {
return StarCoordinate{}, err
}
return StarCoordinateFromStarData(star)
}
+45
View File
@@ -0,0 +1,45 @@
package phenomena
import (
"testing"
"b612.me/astro/basic"
)
func TestStarCoordinateLookup(t *testing.T) {
byHR, err := StarCoordinateByHR(2491)
if err != nil {
t.Fatalf("StarCoordinateByHR() error = %v", err)
}
byName, err := StarCoordinateByName("天狼")
if err != nil {
t.Fatalf("StarCoordinateByName() error = %v", err)
}
if byHR != byName {
t.Fatalf("lookup mismatch: HR=%+v name=%+v", byHR, byName)
}
data, err := basic.StarDataByHR(2491)
if err != nil {
t.Fatalf("basic star lookup error = %v", err)
}
converted, err := StarCoordinateFromStarData(data)
if err != nil {
t.Fatalf("StarCoordinateFromStarData() error = %v", err)
}
if byHR != converted {
t.Fatalf("wrapper mismatch: lookup=%+v converted=%+v", byHR, converted)
}
}
func TestStarCoordinateLookupInvalid(t *testing.T) {
if _, err := StarCoordinateByHR(0); err == nil {
t.Fatal("StarCoordinateByHR(0) expected an error")
}
if _, err := StarCoordinateByName("不存在的恒星"); err == nil {
t.Fatal("StarCoordinateByName() expected an error")
}
if _, err := StarCoordinateFromStarData(StarData{}); err == nil {
t.Fatal("StarCoordinateFromStarData() expected an error")
}
}