feat: 完善日月食与月掩几何链路并扩展历法接口

- 新增日月食中心带、偏食带、阴影足迹、等时线、食分线及升落边界计算，支持极区与混合食拓扑 - 新增日食单时刻阴影求解器、站心状态查询、批量采样和 ΔT 覆盖接口 - 重构恒星与行星月掩路径，补充有限盘面接触、站心修正、掩带宽度、极区投影及升落边界 - 扩展 SVG 与 GeoJSON 输出，支持详细面板、全球/极区/地球投影、边界闭合、时间标记和拓扑签名 - 扩展日月食候选搜索、局地搜索、沙罗序列预计算与范围外推，补充系列锚点和成员一致性校验 - 补齐古历纪年、儒略历独有闰日、多公历候选、历法改革跨日及精确日期运算接口 - 优化 ΔT、章动、恒星时、月球地平线、事件根搜索和本地星历缓存，降低重复计算开销并提升边界稳定
2026-09-17 12:27:40 +08:00
parent 9ee2163cc7
commit 2bf8478639
428 changed files with 85981 additions and 7998 deletions
@@ -0,0 +1,150 @@
+package basic
+
+import (
+	"fmt"
+	"math"
+	"time"
+)
+
+// StarOccultationInstant 包含指定时刻的点源恒星月掩可见足迹；若接触锥在该时刻未到达可见地球，Footprint 为 nil。
+// StarOccultationInstant contains the visible point-source footprint at one requested instant; Footprint is nil when no part of the contact cone reaches the visible Earth.
+type StarOccultationInstant struct {
+	Time     time.Time
+	TargetID string
+	// DeltaTSeconds 本次实际使用的 ΔT / ΔT actually used.
+	DeltaTSeconds float64
+	// SublunarLongitude 与 SublunarLatitude 是该时刻月下点，用于声明地平闭合弧 / sublunar point for the horizon closure.
+	SublunarLongitude float64
+	SublunarLatitude  float64
+	Footprint         *OccultationFootprint
+}
+
+// PlanetOccultationInstant 包含指定时刻的行星外接触和内接触可见足迹；相应接触锥未到达可见地球时，Partial 或 Total 为 nil。
+// PlanetOccultationInstant contains the visible outer- and inner-contact footprints at one requested instant; Partial or Total is nil when that contact cone does not reach the visible Earth.
+type PlanetOccultationInstant struct {
+	Time     time.Time
+	Planet   OccultationPlanet
+	TargetID string
+	// DeltaTSeconds 本次实际使用的 ΔT / ΔT actually used.
+	DeltaTSeconds float64
+	// SublunarLongitude 与 SublunarLatitude 是该时刻月下点，用于声明地平闭合弧 / sublunar point for the horizon closure.
+	SublunarLongitude float64
+	SublunarLatitude  float64
+	Partial           *PlanetOccultationFootprint
+	Total             *PlanetOccultationFootprint
+}
+
+// StarOccultationFootprintAt 返回指定时刻的精确点源恒星月掩可见足迹；它采用与路径时间线相同的分辨率，并对完整接触弧执行站心校正。
+// StarOccultationFootprintAt returns the exact visible lunar-occultation footprint of a point-source star at one instant, using timeline resolution and station-centred correction of the complete contact arc.
+func StarOccultationFootprintAt(at time.Time, star StarCoordinate) (StarOccultationInstant, error) {
+	result := StarOccultationInstant{Time: at, TargetID: star.ID}
+	if at.IsZero() {
+		return result, fmt.Errorf("%w: time is required", ErrInvalidOccultationInput)
+	}
+	if err := star.Validate(); err != nil {
+		return result, err
+	}
+
+	cache := newStarOccultationEventCache(star)
+	tt := occultationTimeToTT(at)
+	result.DeltaTSeconds = DeltaT(tt, true)
+	result.SublunarLongitude, result.SublunarLatitude = occultationSublunarPoint(tt, cache.frameAt)
+	result.Footprint = occultationInstantFootprint(
+		at, cache.frameAt, cache.riseSetContextAt, false,
+	)
+	return result, nil
+}
+
+// PlanetOccultationFootprintsAt 返回指定时刻有限行星盘面的精确外接触和内接触月掩可见足迹；它采用路径时间线分辨率，并对每条完整接触弧执行站心校正。
+// PlanetOccultationFootprintsAt returns the exact visible outer- and inner-contact lunar-occultation footprints of a finite planetary disk at one instant, using timeline resolution and station-centred correction of each complete contact arc.
+func PlanetOccultationFootprintsAt(at time.Time, planet OccultationPlanet) (PlanetOccultationInstant, error) {
+	result := PlanetOccultationInstant{Time: at, Planet: planet, TargetID: planet.String()}
+	if at.IsZero() {
+		return result, fmt.Errorf("%w: time is required", ErrInvalidOccultationInput)
+	}
+	if err := planet.Validate(); err != nil {
+		return result, err
+	}
+
+	config, _ := planetOccultationConfigFor(planet)
+	cache := newPlanetOccultationEventCache(config)
+	tt := occultationTimeToTT(at)
+	result.DeltaTSeconds = DeltaT(tt, true)
+	result.SublunarLongitude, result.SublunarLatitude = occultationSublunarPoint(tt, cache.outerFrameAt)
+	result.Partial = occultationInstantFootprint(
+		at, cache.outerFrameAt, cache.riseSetContextAt, false,
+	)
+	result.Total = occultationInstantFootprint(
+		at, cache.totalFrameAt, cache.riseSetContextAt, true,
+	)
+	return result, nil
+}
+
+func occultationSublunarPoint(tt float64, frameAt occultationPathFrameFunc) (float64, float64) {
+	frame, ok := frameAt(tt)
+	if !ok {
+		return math.NaN(), math.NaN()
+	}
+	distance := math.Sqrt(frame.moon.x*frame.moon.x + frame.moon.y*frame.moon.y + frame.moon.z*frame.moon.z)
+	if distance == 0 {
+		return math.NaN(), math.NaN()
+	}
+	rightAscension := math.Atan2(frame.moon.y, frame.moon.x) * 180 / math.Pi
+	declination := math.Asin(math.Max(-1, math.Min(1, frame.moon.z/distance))) * 180 / math.Pi
+	longitude := rightAscension - ApparentSiderealTime(TD2UT(tt, false))*15
+	for longitude > 180 {
+		longitude -= 360
+	}
+	for longitude < -180 {
+		longitude += 360
+	}
+	return longitude, declination
+}
+
+func occultationInstantFootprint(
+	at time.Time,
+	frameAt occultationPathFrameFunc,
+	contextAt occultationRiseSetContextFunc,
+	total bool,
+) *OccultationFootprint {
+	tt := occultationTimeToTT(at)
+	footprint, ok := planetOccultationFootprintAtWithResolution(
+		tt, frameAt, at.Location(),
+		planetOccultationTimelineBoundaryPoints,
+		planetOccultationTimelineHorizonPoints,
+		planetOccultationTimelineTargetSpacingKM,
+	)
+	if !ok {
+		return nil
+	}
+
+	// A one-element correction deliberately treats this instant as both ends of
+	// the sequence, so every contact-arc sample receives the exact station solve.
+	corrected := occultationStationCorrectFootprintEdges(
+		[]PlanetOccultationFootprint{footprint}, frameAt, contextAt, total, at.Location(),
+	)
+	if len(corrected) != 1 {
+		return nil
+	}
+	footprint = corrected[0]
+	normalizeOccultationInstantTime(&footprint, at)
+	return &footprint
+}
+
+func normalizeOccultationInstantTime(footprint *OccultationFootprint, at time.Time) {
+	if footprint == nil {
+		return
+	}
+	footprint.Time = at
+	for _, polygons := range [][][]OccultationPathPoint{
+		footprint.Polygons,
+		footprint.InteriorPolygons,
+		footprint.Boundaries,
+	} {
+		for polygonIndex := range polygons {
+			for pointIndex := range polygons[polygonIndex] {
+				polygons[polygonIndex][pointIndex].Time = at
+			}
+		}
+	}
+}