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
+68 -148
View File
@@ -1,11 +1,11 @@
package jupiter
import (
"b612.me/astro/basic"
"b612.me/astro/calendar"
"b612.me/astro/planet"
"errors"
"time"
"b612.me/astro/basic"
"b612.me/astro/calendar"
)
var (
@@ -31,136 +31,94 @@ func riseSetResult(date time.Time, jd float64, err error) (time.Time, error) {
}
// ApparentLo 视黄经 / apparent ecliptic longitude.
//
// 返回木星在 date 对应绝对时刻的瞬时视黄经,单位度。
// Returns the apparent ecliptic longitude of Jupiter at the instant represented by date, in degrees.
func ApparentLo(date time.Time) float64 {
func (module *Jupiter) ApparentLo(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterApparentLo(basic.UTC2TT(jd))
return basic.JupiterApparentLoWithInstance(basic.UTC2TT(jd), module.inst)
}
// ApparentBo 视黄纬 / apparent ecliptic latitude.
//
// 返回木星在 date 对应绝对时刻的瞬时视黄纬,单位度。
// Returns the apparent ecliptic latitude of Jupiter at the instant represented by date, in degrees.
func ApparentBo(date time.Time) float64 {
func (module *Jupiter) ApparentBo(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterApparentBo(basic.UTC2TT(jd))
return basic.JupiterApparentBoWithInstance(basic.UTC2TT(jd), module.inst)
}
// ApparentRa 视赤经 / apparent right ascension.
//
// 返回木星在 date 对应绝对时刻的瞬时视赤经,单位度。
// Returns the apparent right ascension of Jupiter at the instant represented by date, in degrees.
func ApparentRa(date time.Time) float64 {
func (module *Jupiter) ApparentRa(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterApparentRa(basic.UTC2TT(jd))
return basic.JupiterApparentRaWithInstance(basic.UTC2TT(jd), module.inst)
}
// ApparentDec 视赤纬 / apparent declination.
//
// 返回木星在 date 对应绝对时刻的瞬时视赤纬,单位度。
// Returns the apparent declination of Jupiter at the instant represented by date, in degrees.
func ApparentDec(date time.Time) float64 {
func (module *Jupiter) ApparentDec(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterApparentDec(basic.UTC2TT(jd))
return basic.JupiterApparentDecWithInstance(basic.UTC2TT(jd), module.inst)
}
// ApparentRaDec 视赤经、视赤纬 / apparent right ascension and declination.
//
// 返回木星在 date 对应绝对时刻的瞬时视赤经与视赤纬,单位度。
// Returns the apparent right ascension and declination of Jupiter at the instant represented by date, in degrees.
func ApparentRaDec(date time.Time) (float64, float64) {
func (module *Jupiter) ApparentRaDec(date time.Time) (float64, float64) {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterApparentRaDec(basic.UTC2TT(jd))
return basic.JupiterApparentRaDecWithInstance(basic.UTC2TT(jd), module.inst)
}
// ApparentMagnitude 视星等 / apparent magnitude.
//
// 返回木星在 date 对应绝对时刻的视星等。
// Returns the apparent visual magnitude of Jupiter at the instant represented by date.
func ApparentMagnitude(date time.Time) float64 {
func (module *Jupiter) ApparentMagnitude(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterMag(basic.UTC2TT(jd))
return basic.JupiterMagWithInstance(basic.UTC2TT(jd), module.inst)
}
// EarthDistance 地心距离 / Earth distance.
//
// 返回木星在 date 对应绝对时刻到地球的距离,单位 AU。
// Returns the distance from Jupiter to Earth at the instant represented by date, in astronomical units.
func EarthDistance(date time.Time) float64 {
func (module *Jupiter) EarthDistance(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.EarthJupiterAway(basic.UTC2TT(jd))
return basic.EarthJupiterAwayWithInstance(basic.UTC2TT(jd), module.inst)
}
// SunDistance 日心距离 / Sun distance.
//
// 返回木星在 date 对应绝对时刻到太阳的距离,单位 AU。
// Returns the distance from Jupiter to the Sun at the instant represented by date, in astronomical units.
func SunDistance(date time.Time) float64 {
func (module *Jupiter) SunDistance(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return planet.WherePlanet(4, 2, basic.UTC2TT(jd))
return basic.PlanetCoordinateWithInstance(4, 2, basic.UTC2TT(jd), module.inst)
}
// Altitude 高度角 / altitude.
//
// date 表示观测时刻,会读取其时区参与地方时计算;lon 为观测者经度,东正西负;lat 为观测者纬度,北正南负。返回值单位度。
// date is the observing instant and its zone offset participates in local-time calculations. lon is east-positive longitude, lat is north-positive latitude, and the result is in degrees.
func Altitude(date time.Time, lon, lat float64) float64 {
// Altitude 站心视高度角,不含大气折射 / topocentric apparent altitude without refraction.
func (module *Jupiter) Altitude(date time.Time, lon, lat float64) float64 {
localJD := basic.Date2JD(date)
_, loc := date.Zone()
timezone := float64(loc) / 3600.0
return basic.JupiterHeight(localJD, lon, lat, timezone)
return basic.JupiterHeightWithInstance(localJD, lon, lat, timezone, module.inst)
}
// Zenith 天顶距 / zenith distance.
//
// 参数与 Altitude 相同,返回值为对应时刻的天顶距,单位度。
// Uses the same inputs as Altitude and returns the zenith distance in degrees.
func Zenith(date time.Time, lon, lat float64) float64 {
return 90 - Altitude(date, lon, lat)
func (module *Jupiter) Zenith(date time.Time, lon, lat float64) float64 {
return 90 - module.Altitude(date, lon, lat)
}
// Azimuth 方位角 / azimuth.
//
// date 表示观测时刻,会读取其时区参与地方时计算;lon 为观测者经度,东正西负;lat 为观测者纬度,北正南负。返回值按正北为 0°、向东增加。
// date is the observing instant and its zone offset participates in local-time calculations. lon is east-positive longitude, lat is north-positive latitude, and azimuth is measured from north toward east.
func Azimuth(date time.Time, lon, lat float64) float64 {
// Azimuth 站心方位角 / topocentric azimuth.
func (module *Jupiter) Azimuth(date time.Time, lon, lat float64) float64 {
localJD := basic.Date2JD(date)
_, loc := date.Zone()
timezone := float64(loc) / 3600.0
return basic.JupiterAzimuth(localJD, lon, lat, timezone)
return basic.JupiterAzimuthWithInstance(localJD, lon, lat, timezone, module.inst)
}
// HourAngle 时角 / hour angle.
//
// date 表示观测时刻,会读取其时区参与地方时计算;lon 为观测者经度,东正西负。返回值单位度。
// date is the observing instant and its zone offset participates in local-time calculations. lon is east-positive longitude and the returned hour angle is in degrees.
func HourAngle(date time.Time, lon float64) float64 {
// HourAngle 地心视时角,不含站心视差 / geocentric apparent hour angle without topocentric parallax.
func (module *Jupiter) HourAngle(date time.Time, lon float64) float64 {
localJD := basic.Date2JD(date)
_, loc := date.Zone()
timezone := float64(loc) / 3600.0
return basic.JupiterHourAngle(localJD, lon, timezone)
return basic.JupiterHourAngleWithInstance(localJD, lon, timezone, module.inst)
}
// CulminationTime 中天时刻 / culmination time.
//
// date 取其所在时区的当地日期,返回值保持相同时区;lon 为观测者经度,东正西负。
// date is interpreted on its local civil day and the result keeps the same time zone. lon is east-positive longitude.
func CulminationTime(date time.Time, lon float64) time.Time {
func (module *Jupiter) CulminationTime(date time.Time, lon float64) time.Time {
date = time.Date(date.Year(), date.Month(), date.Day(), 0, 0, 0, 0, date.Location())
localJD := basic.Date2JD(date)
_, loc := date.Zone()
timezone := float64(loc) / 3600.0
calcJD := basic.JupiterCulminationTime(localJD, lon, timezone) - timezone/24.00
calcJD := basic.JupiterCulminationTimeWithInstance(localJD, lon, timezone, module.inst) - timezone/24.00
return basic.JD2DateByZone(calcJD, date.Location(), false)
}
// RiseTime 升起时间 / rise time.
//
// date 取其所在时区的当地日期,返回值保持相同时区;lon 为东正西负经度,lat 为北正南负纬度;height 为观测点椭球高(大地高,米);aero 为 true 时加入标准大气折射。
// date is interpreted on its local civil day and the result keeps the same time zone. lon is east-positive longitude, lat is north-positive latitude, height is observer elevation in meters, and aero enables standard atmospheric refraction.
func RiseTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
func (module *Jupiter) RiseTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
var aeroFloat float64
if aero {
aeroFloat = 1
@@ -169,25 +127,17 @@ func RiseTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, e
localJD := basic.Date2JD(date)
_, loc := date.Zone()
timezone := float64(loc) / 3600.0
riseJD, err := basic.JupiterRiseTime(localJD, lon, lat, timezone, aeroFloat, height)
riseJD, err := basic.JupiterRiseTimeWithInstance(localJD, lon, lat, timezone, aeroFloat, height, module.inst)
return riseSetResult(date, riseJD, err)
}
// DownTime 落下时间别名 / deprecated set-time alias.
//
// Deprecated: use SetTime instead.
//
// 参数与 SetTime 相同,仅为兼容旧接口保留。
// Same as SetTime and kept only for backward compatibility.
func DownTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
return SetTime(date, lon, lat, height, aero)
func (module *Jupiter) DownTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
return module.SetTime(date, lon, lat, height, aero)
}
// SetTime 落下时间 / set time.
//
// 参数与 RiseTime 相同,返回给定当地日期内的落下时刻。
// Uses the same inputs as RiseTime and returns the set time on the corresponding local civil day.
func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
func (module *Jupiter) SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
var aeroFloat float64
if aero {
aeroFloat = 1
@@ -196,114 +146,84 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
localJD := basic.Date2JD(date)
_, loc := date.Zone()
timezone := float64(loc) / 3600.0
riseJD, err := basic.JupiterSetTime(localJD, lon, lat, timezone, aeroFloat, height)
riseJD, err := basic.JupiterSetTimeWithInstance(localJD, lon, lat, timezone, aeroFloat, height, module.inst)
return riseSetResult(date, riseJD, err)
}
// LastConjunction 上一次合日 / previous conjunction with the Sun.
//
// 返回 date 当前或之前最近一次与太阳的合日时刻,结果保持 date 的时区。
// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
func LastConjunction(date time.Time) time.Time {
func (module *Jupiter) LastConjunction(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.LastJupiterConjunction(jde), date.Location(), false)
return basic.JD2DateByZone(basic.LastJupiterConjunctionWithInstance(jde, module.inst), date.Location(), false)
}
// NextConjunction 下一次合日 / next conjunction with the Sun.
//
// 返回 date 当前或之后最近一次与太阳的合日时刻,结果保持 date 的时区。
// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
func NextConjunction(date time.Time) time.Time {
func (module *Jupiter) NextConjunction(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.NextJupiterConjunction(jde), date.Location(), false)
return basic.JD2DateByZone(basic.NextJupiterConjunctionWithInstance(jde, module.inst), date.Location(), false)
}
// LastOpposition 上一次冲日 / previous opposition.
//
// 返回 date 当前或之前最近一次冲日时刻,结果保持 date 的时区。
// Returns the nearest opposition at or before date, keeping date's time zone.
func LastOpposition(date time.Time) time.Time {
func (module *Jupiter) LastOpposition(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.LastJupiterOpposition(jde), date.Location(), false)
return basic.JD2DateByZone(basic.LastJupiterOppositionWithInstance(jde, module.inst), date.Location(), false)
}
// NextOpposition 下一次冲日 / next opposition.
//
// 返回 date 当前或之后最近一次冲日时刻,结果保持 date 的时区。
// Returns the nearest opposition at or after date, keeping date's time zone.
func NextOpposition(date time.Time) time.Time {
func (module *Jupiter) NextOpposition(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.NextJupiterOpposition(jde), date.Location(), false)
return basic.JD2DateByZone(basic.NextJupiterOppositionWithInstance(jde, module.inst), date.Location(), false)
}
// LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
//
// 返回 date 当前或之前最近一次由顺行转为逆行的留时刻,结果保持 date 的时区。
// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
func LastProgradeToRetrograde(date time.Time) time.Time {
func (module *Jupiter) LastProgradeToRetrograde(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.LastJupiterProgradeToRetrograde(jde), date.Location(), false)
return basic.JD2DateByZone(basic.LastJupiterProgradeToRetrogradeWithInstance(jde, module.inst), date.Location(), false)
}
// NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
//
// 返回 date 当前或之后最近一次由顺行转为逆行的留时刻,结果保持 date 的时区。
// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
func NextProgradeToRetrograde(date time.Time) time.Time {
func (module *Jupiter) NextProgradeToRetrograde(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.NextJupiterProgradeToRetrograde(jde), date.Location(), false)
return basic.JD2DateByZone(basic.NextJupiterProgradeToRetrogradeWithInstance(jde, module.inst), date.Location(), false)
}
// LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
//
// 返回 date 当前或之前最近一次由逆行转为顺行的留时刻,结果保持 date 的时区。
// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
func LastRetrogradeToPrograde(date time.Time) time.Time {
func (module *Jupiter) LastRetrogradeToPrograde(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.LastJupiterRetrogradeToPrograde(jde), date.Location(), false)
return basic.JD2DateByZone(basic.LastJupiterRetrogradeToProgradeWithInstance(jde, module.inst), date.Location(), false)
}
// NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
//
// 返回 date 当前或之后最近一次由逆行转为顺行的留时刻,结果保持 date 的时区。
// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
func NextRetrogradeToPrograde(date time.Time) time.Time {
func (module *Jupiter) NextRetrogradeToPrograde(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.NextJupiterRetrogradeToPrograde(jde), date.Location(), false)
return basic.JD2DateByZone(basic.NextJupiterRetrogradeToProgradeWithInstance(jde, module.inst), date.Location(), false)
}
// LastEasternQuadrature 上一次东方照 / previous eastern quadrature.
//
// 返回 date 当前或之前最近一次东方照时刻,结果保持 date 的时区。
// Returns the nearest eastern quadrature at or before date, keeping date's time zone.
func LastEasternQuadrature(date time.Time) time.Time {
func (module *Jupiter) LastEasternQuadrature(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.LastJupiterEasternQuadrature(jde), date.Location(), false)
return basic.JD2DateByZone(basic.LastJupiterEasternQuadratureWithInstance(jde, module.inst), date.Location(), false)
}
// NextEasternQuadrature 下一次东方照 / next eastern quadrature.
//
// 返回 date 当前或之后最近一次东方照时刻,结果保持 date 的时区。
// Returns the nearest eastern quadrature at or after date, keeping date's time zone.
func NextEasternQuadrature(date time.Time) time.Time {
func (module *Jupiter) NextEasternQuadrature(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.NextJupiterEasternQuadrature(jde), date.Location(), false)
return basic.JD2DateByZone(basic.NextJupiterEasternQuadratureWithInstance(jde, module.inst), date.Location(), false)
}
// LastWesternQuadrature 上一次西方照 / previous western quadrature.
//
// 返回 date 当前或之前最近一次西方照时刻,结果保持 date 的时区。
// Returns the nearest western quadrature at or before date, keeping date's time zone.
func LastWesternQuadrature(date time.Time) time.Time {
func (module *Jupiter) LastWesternQuadrature(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.LastJupiterWesternQuadrature(jde), date.Location(), false)
return basic.JD2DateByZone(basic.LastJupiterWesternQuadratureWithInstance(jde, module.inst), date.Location(), false)
}
// NextWesternQuadrature 下一次西方照 / next western quadrature.
//
// 返回 date 当前或之后最近一次西方照时刻,结果保持 date 的时区。
// Returns the nearest western quadrature at or after date, keeping date's time zone.
func NextWesternQuadrature(date time.Time) time.Time {
func (module *Jupiter) NextWesternQuadrature(date time.Time) time.Time {
jde := basic.UTC2TT(basic.Date2JD(date.UTC()))
return basic.JD2DateByZone(basic.NextJupiterWesternQuadrature(jde), date.Location(), false)
return basic.JD2DateByZone(basic.NextJupiterWesternQuadratureWithInstance(jde, module.inst), date.Location(), false)
}
// ApparentMagnitude2018 视星等(Mallama & Hilton 2018 模型)/ apparent magnitude, Mallama & Hilton 2018 model.
func (module *Jupiter) ApparentMagnitude2018(date time.Time) float64 {
jd := calendar.Date2JD(date.UTC())
return basic.JupiterMag2018WithInstance(basic.UTC2TT(jd), module.inst)
}