# 日晷与真太阳时 [English](en/sundial.md) | [返回 README](../../README.md) > 本手册的完整示例以仓库根目录为工作目录执行。 `sundial` 把 `sun` 包的真太阳时、太阳时角与日晷绘制所需的几何量集中在一起，不引入另一套算法。日晷部分按经典平面日晷模型工作：一根指向天极的极轴晷针，其影子投在任意平面上；坐标约定由构造器给定，水平日晷是 **x 轴向东、y 轴向北**。 ## 目录 - [计算水平日晷的影子位置](#计算水平日晷的影子位置) - [API 参考](#api-参考) - [真太阳时、平太阳时与均时差](#真太阳时平太阳时与均时差) - [时角](#时角) - [水平日晷时线角](#水平日晷时线角) - [平面日晷核心](#平面日晷核心) - [盘面受光区间](#盘面受光区间) - [时间线与赤纬曲线](#时间线与赤纬曲线) - [赤道、水平与垂直日晷特例](#赤道水平与垂直日晷特例) - [返回结构](#返回结构) - [完整示例](#完整示例) - [综合示例：一天的可用时角与等时线](#综合示例一天的可用时角与等时线) - [常见坑](#常见坑) - [常用场景](#常用场景) - [真太阳时与钟表时间的差](#真太阳时与钟表时间的差) - [水平日晷的时线角与落影](#水平日晷的时线角与落影) - [盘面受光区间与等时线](#盘面受光区间与等时线) - [退化情形与各面日晷口径](#退化情形与各面日晷口径) - [参数与返回值约定](#参数与返回值约定) - [相关手册](#相关手册) ## 计算水平日晷的影子位置 ```go package main import ( "fmt" "time" "b612.me/astro/sundial" ) func main() { cst := time.FixedZone("CST", 8*3600) date := time.Date(2026, 6, 21, 9, 30, 0, 0, cst) lon, lat := 121.4737, 31.2304 fmt.Println(sundial.TrueSolarTime(date, lon)) fmt.Println(sundial.HourAngle(date, lon)) dial := sundial.HorizontalDial(lat, 10) shadow := dial.ShadowPointAt(date, lon) if !shadow.Illuminated { fmt.Println("no illuminated shadow") return } fmt.Printf("x=%.6f y=%.6f\n", shadow.X, shadow.Y) } ``` `HorizontalDial` 的长度参数与返回坐标使用同一单位；例如晷针长度填厘米，影子坐标也是厘米。x 轴向东、y 轴向北，`Illuminated` 为真时才有可用的受光落影。 ## API 参考 | 分组 | 入口 | 用途 | 单位与口径 | | --- | --- | --- | --- | | 真/平太阳时 | `TrueSolarTime` / `MeanSolarTime` | 该绝对时刻在指定经度上的地方真/平太阳时 | 返回地方太阳时读数；经度东正西负（度） | | 太阳时角 | `HourAngle` | 真太阳时角 | 度，上午为负、下午为正 | | 时角换算 | `MeanSolarHourAngle` / `ZoneTimeHourAngle` | 把地方平太阳时或区时钟面读数换成视太阳时角 | 小时数与经度（度） | | 水平时线角 | `HorizontalHourLineAngle` / `HorizontalHourLineAngleAt` | 水平日晷时线相对午线的角度 | 度 | | 平面日晷核心 | `PlanarDial`（字段）+ `Geometry` / `ShadowPointByHourAngleDeclination` / `ShadowPointAt` | 任意平面的几何量与落影点 | 坐标与晷针长度为同一长度单位 | | 盘面受光 | `PlaneIlluminatedHourAngleIntervals` / `IlluminatedHourAngleIntervals` | 盘面受光时角区间与最终可用时角区间 | 度，`[-180, 180]` | | 时间线 | `MeanSolarTimePoint` / `ZoneTimePoint` / `MeanSolarTimeLine` / `ZoneTimeLine` | 把平太阳时线或区时线直接接到日晷几何 | 返回 `PlanarShadowPoint` / `TimeLineSample` | | 赤纬曲线 | `DeclinationCurve` / `DeclinationCurveAt` | 按赤纬或日期生成分段采样点列 | 时角步长单位为度 | | 特例构造 | `EquatorialNorthDial` / `EquatorialSouthDial` / `HorizontalDial` / `VerticalDial` | 赤道（南北面）、水平、垂直日晷 | 纬度与法线方位角单位为度 | 以下片段省略公共前置变量：`date`（时刻，民用时标）、`lon`（经度，东正西负，度）、`lat`（纬度，度）。 ### 真太阳时、平太阳时与均时差 ```go fmt.Println(sundial.TrueSolarTime(date, lon)) fmt.Println(sundial.MeanSolarTime(date, lon)) fmt.Println(sundial.TrueSolarTime(date, lon).Sub(sundial.MeanSolarTime(date, lon))) // 均时差 ``` 三者共用 `sun` 包的口径：`TrueSolarTime` 是视太阳时，`MeanSolarTime` 是地方平太阳时，两者之差即均时差（真 − 平）。 ### 时角 ```go fmt.Println(sundial.HourAngle(date, lon)) // 真太阳时角，上午为负 fmt.Println(sundial.MeanSolarHourAngle(date, 9.5)) // 地方平太阳时 9:30 对应的时角 fmt.Println(sundial.ZoneTimeHourAngle(date, lon, 9.5)) // 区时钟面 9:30 对应的时角 ``` `HourAngle` 直接用绝对时刻求时角；后两者用于"给定钟面读数求落影方向"，区别在于一个按地方平太阳时、一个按区时。 ### 水平日晷时线角 ```go fmt.Println(sundial.HorizontalHourLineAngle(31.2304, -45)) fmt.Println(sundial.HorizontalHourLineAngleAt(date, lon, 31.2304)) ``` 前者给定纬度与带符号时角，后者直接用时刻与经纬度求当前时线角；返回值是时线相对午线的夹角。 ### 平面日晷核心 ```go dial := sundial.PlanarDial{ Latitude: 31.2304, PlaneNormalAzimuth: 180, PlaneNormalZenithDistance: 90, StylusLength: 10, } g := dial.Geometry() fmt.Println(g.HasFiniteCenter, g.PolarStylusLength, g.PolarStylusPlaneAngle) p := dial.ShadowPointByHourAngleDeclination(-45, 23.44) fmt.Println(p.X, p.Y, p.Illuminated) ``` `PlanarDial` 的四个字段分别是纬度、盘面法线方位角、法线天顶距与晷针长度。`Geometry` 给出日晷中心（极轴晷针固定点）、极轴晷针长度以及它与盘面的夹角；`ShadowPointByHourAngleDeclination` 给定带符号时角与太阳赤纬求落影点，`ShadowPointAt` 则直接用时刻与经度。 ### 盘面受光区间 ```go for _, iv := range dial.PlaneIlluminatedHourAngleIntervals(23.44) { fmt.Println(iv.Start, iv.End) } for _, iv := range dial.IlluminatedHourAngleIntervals(23.44) { fmt.Println(iv.Start, iv.End) } ``` 前者只回答"盘面是否朝向太阳"（几何受光），后者叠加太阳在地平线以上与盘面朝向两个条件，给出**最终可用**的时角区间；区间约定在 `[-180, 180]` 且 `Start <= End`。 ### 时间线与赤纬曲线 ```go dates := []time.Time{date, date.Add(30 * time.Minute), date.Add(time.Hour)} fmt.Println(len(dial.MeanSolarTimeLine(dates, 9.5))) segs := dial.DeclinationCurve(23.44, 1.0) segsAt := dial.DeclinationCurveAt(date, 1.0) fmt.Println(len(segs), len(segsAt)) ``` 时间线把"地方平太阳时线上的等时刻点"直接投影成 `TimeLineSample`；赤纬曲线按固定赤纬或当日赤纬分段采样，段内 `Interval` 就是上面那条可用时角区间。 ### 赤道、水平与垂直日晷特例 ```go h := sundial.HorizontalDial(31.2304, 10) n := sundial.EquatorialNorthDial(31.2304, 10) s := sundial.EquatorialSouthDial(31.2304, 10) v := sundial.VerticalDial(31.2304, 180, 10) fmt.Println(h.PlaneNormalZenithDistance, n.PlaneNormalAzimuth, s.PlaneNormalAzimuth) fmt.Println(v.PlaneNormalAzimuth, v.PlaneNormalZenithDistance) ``` 四个构造器给出的盘面法线口径不同，画图时按 `PlanarDial` 字段判断即可： | 构造器 | `PlaneNormalAzimuth` | `PlaneNormalZenithDistance` | | --- | --- | --- | | `HorizontalDial` | `180°` | `0°`（法线指向天顶；x 轴向东、y 轴向北） | | `EquatorialNorthDial` | `0°` | `90° - 纬度` | | `EquatorialSouthDial` | `180°` | `90° + 纬度` | | `VerticalDial` | 入参归一化到 `[0°, 360°)` | `90°` | 北赤道日晷在北半球用于春夏半年（太阳赤纬为正），南赤道日晷用于秋冬半年；垂直日晷的 `planeNormalAzimuth` 按正北 `0°`、向东增加，朝南墙面取 `180°`、朝东墙面取 `90°`。 ### 返回结构 | 类型 | 字段 | 含义 | | --- | --- | --- | | `PlanarShadowPoint` | `X` / `Y` | 落影点坐标，与 `StylusLength` 同单位 | | | `DenominatorQ` | 投影分母，趋近 0 表示影子趋于无穷远 | | | `SunAboveHorizon` / `PlaneIlluminated` / `Illuminated` | 太阳在地平线上、盘面受光、两者同时成立的最终判据 | | `PlanarGeometry` | `CenterX` / `CenterY` | 日晷中心（极轴晷针固定点）坐标 | | | `PolarStylusLength` / `PolarStylusPlaneAngle` | 极轴晷针长度、它与盘面的夹角 | | | `HasFiniteCenter` | 为 false 时中心退化到无穷远，相关量为 `NaN` | | `HourAngleInterval` | `Start` / `End` | 有符号时角区间（度），保证 `Start <= End` | | `TimeLineSample` | `Date` / `Declination` / `HourAngle` / `Point` | 时刻、太阳赤纬、真太阳时角与对应落影点 | | `DeclinationCurveSegment` | `Declination` / `Interval` / `Samples` | 该段的赤纬、可用时角区间与采样点列 | ### 完整示例 ```go package main import ( "fmt" "time" "b612.me/astro/sundial" ) func main() { date := time.Date(2026, 6, 21, 9, 30, 0, 0, time.FixedZone("CST", 8*3600)) lon, lat := 121.4737, 31.2304 trueSolar := sundial.TrueSolarTime(date, lon) hourAngle := sundial.HourAngle(date, lon) lineAngle := sundial.HorizontalHourLineAngle(lat, -45) lineAngleNow := sundial.HorizontalHourLineAngleAt(date, lon, lat) fmt.Println(trueSolar) fmt.Printf("hour angle=%.6f line@9am=%.6f line@now=%.6f\n", hourAngle, lineAngle, lineAngleNow) } ``` 输出结果： ```text 2026-06-21 09:34:10.438158222 +0805 LTZ hour angle=-36.456508 line@9am=-27.405871 line@now=-20.959182 ``` 第一行的时区是合成的当地真太阳时区（经度 `121.4737°` 对应 `+08:05` 的 `LTZ`），所以打印值本身就体现了地方真太阳时与钟表时间的差。 ### 综合示例：一天的可用时角与等时线 ```go dial := sundial.HorizontalDial(31.2304, 10) for _, seg := range dial.DeclinationCurveAt(date, 1.0) { fmt.Printf("decl=%.2f usable=%.2f..%.2f samples=%d\n", seg.Declination, seg.Interval.Start, seg.Interval.End, len(seg.Samples)) } mean := sundial.MeanSolarTime(date, 121.4737) samples := dial.MeanSolarTimeLine([]time.Time{mean, mean.Add(30 * time.Minute)}, 9.5) fmt.Println(len(samples), samples[0].HourAngle) ``` 实测（`date = 2026-06-21 09:30 CST`、`121.4737°E, 31.2304°N`、晷针长 10）： ```text decl=23.44 usable=-105.24..105.24 samples=211 2 -37.92998436772365 ``` 第一行说明当天在纬度 `31.2304°` 的水平日晷上，太阳赤纬 `23.44°` 时盘面能用的时角区间是 `[-105.24°, +105.24°]`（约 14 小时），采样 211 点；第二行是"地方平太阳时 9:30 这条时线"的两个采样点与其时角。这两个量配合就能直接画出一张带可用范围的水平日晷。 ### 常见坑 - 把 `ZoneTimePoint` 的 `date` 当成目标地点的地方真太阳时 → 它只用年月日与时区，钟面时间来自 `zoneTimeHours`。 - 用 `PlaneIlluminated` 判断"这张日晷一天里能不能用" → 应该看 `Illuminated`，它才叠加了太阳在地平线以上这个条件。 - 垂直日晷传"墙面朝向" → `planeNormalAzimuth` 是**法线**方位角，朝南墙是 `180°`。 - 时角符号写反 → `HourAngle` 上午为负、下午为正，`HorizontalHourLineAngle` 也沿用同一符号。 - 以为时角区间一定是一段 → 跨零点的一天会被拆成多段，必须遍历返回的切片。 ## 常用场景 ### 真太阳时与钟表时间的差 ```go trueSolar := sundial.TrueSolarTime(date, lon) mean := sundial.MeanSolarTime(date, lon) fmt.Println(trueSolar, mean) fmt.Println(trueSolar.Sub(mean)) // 均时差 ``` ```text 2026-06-21 09:34:10.438158222 +0805 LTZ 2026-06-21 09:35:53.532790863 +0805 LTZ -1m43.094632641s ``` - `TrueSolarTime` 返回的是带合成时区的时刻，直接与自己钟表时间相减就得到"真太阳时快/慢多少"。 - 要把**钟面读数**换成时角（例如按区时排影子刻度），用 `MeanSolarHourAngle` / `ZoneTimeHourAngle`，不要手工加减均时差。 ### 水平日晷的时线角与落影 ```go dial := sundial.HorizontalDial(lat, 10) fmt.Println(sundial.HorizontalHourLineAngle(lat, -45)) // 时角 -45° 的时线角 fmt.Println(sundial.HorizontalHourLineAngleAt(date, lon, lat)) // 当前时刻的时线角 p := dial.ShadowPointAt(date, lon) fmt.Println(p.X, p.Y, p.Illuminated) ``` ```text -27.40587112370779 -20.95918157094186 -6.511723246549 0.507600045956 true ``` - 水平日晷的坐标约定是 `x` 轴向东、`y` 轴向北；`Illuminated` 是"太阳在地平线上且盘面朝向太阳"的最终判据，只画有效影子时看它。 - 只有时角、没有具体时刻时用 `ShadowPointByHourAngleDeclination`，同一几何给 `-6.511402572556 0.506762879485 true`。 ### 盘面受光区间与等时线 ```go dial := sundial.HorizontalDial(31.2304, 10) for _, seg := range dial.DeclinationCurveAt(date, 1.0) { fmt.Printf("decl=%.2f usable=%.2f..%.2f samples=%d\n", seg.Declination, seg.Interval.Start, seg.Interval.End, len(seg.Samples)) } mean := sundial.MeanSolarTime(date, 121.4737) samples := dial.MeanSolarTimeLine([]time.Time{mean, mean.Add(30 * time.Minute)}, 9.5) fmt.Println(len(samples), samples[0].HourAngle) ``` ```text decl=23.44 usable=-105.24..105.24 samples=211 2 -37.92998436772365 ``` - `PlaneIlluminatedHourAngleIntervals` 只判断"盘面是否朝向太阳"，`IlluminatedHourAngleIntervals` 再叠加太阳在地平线以上，回答"这盘一天能用多久"要用后者。 - 区间约定是 `[-180, 180]` 且 `Start <= End`，跨零点会拆成多段；赤纬曲线与时间线的完整接口见 [API 参考](#时间线与赤纬曲线)。 ### 退化情形与各面日晷口径 ```go h := sundial.HorizontalDial(31.2304, 10) n := sundial.EquatorialNorthDial(31.2304, 10) s := sundial.EquatorialSouthDial(31.2304, 10) v := sundial.VerticalDial(31.2304, 180, 10) fmt.Println(h.PlaneNormalZenithDistance, n.PlaneNormalAzimuth, s.PlaneNormalAzimuth) fmt.Println(v.PlaneNormalAzimuth, v.PlaneNormalZenithDistance) ``` ```text 0 0 180 180 90 ``` - **退化条件**：盘面法线与极轴垂直（等价于极轴晷针与盘面平行）时，`Geometry().HasFiniteCenter` 为 `false`，`CenterX`/`CenterY`/`PolarStylusLength` 为 `NaN`、`PolarStylusPlaneAngle` 为 0——纬度 `45°`、法线方位 `180°`、法线天顶距 `45°` 正落在这个点上，此时以中心为基准的绘制不可用。 - **各面口径**：水平盘法线指向天顶（天顶距 `0°`）；垂直盘法线天顶距 `90°`，其 `planeNormalAzimuth` 是**法线**方向（朝南墙 `180°`、朝东墙 `90°`）；赤道南北面分别用 `90-纬度` 与 `90+纬度`。四个构造器的完整表见[赤道、水平与垂直日晷特例](#赤道水平与垂直日晷特例)。 ## 参数与返回值约定 - **单位**：时角、时线角、赤纬、纬度、法线方位角与法线天顶距都是**度**；`PlanarDial` 的 `StylusLength` 与返回点 `X`/`Y` 共用同一长度单位，可以是任意自洽单位（毫米、米或画布坐标）。 - **时标**：观测输入为民用时刻；`TrueSolarTime` / `MeanSolarTime` 的返回字段表示地方太阳时读数，不应直接作为新的观测时刻传入星历接口。换算约定见[时标手册](timescale.md)。 - **时角符号**：`HourAngle` 上午为负、下午为正；`HourAngleInterval` 的取值范围是 `[-180, 180]` 且保证 `Start <= End`。跨零点的一天会被拆成多段。 - **`date` 的时区语义（易错）**：`MeanSolarTimePoint` / `MeanSolarTimeLine` 的 `date` 表示**目标地点的地方平太阳时**（通常是 `MeanSolarTime(...)` 的返回值）；`ZoneTimePoint` / `ZoneTimeLine` 会忽略传入 `date` 的时分秒，只用它的年月日与时区，再用参数 `zoneTimeHours` 替换钟面时间。传错会把整条时线平移。 - **落影有效性的三个布尔量**：`SunAboveHorizon` 表示太阳在地平线以上，`PlaneIlluminated` 表示盘面朝向太阳，`Illuminated` 是两者同时成立后的最终判据；只画影子时必须看 `Illuminated`。 - **退化情形**：当盘面法线与极轴垂直（等价于极轴晷针与盘面平行）时，`PlanarGeometry.HasFiniteCenter` 为 `false`，`CenterX`/`CenterY`/`PolarStylusLength` 返回 `NaN`、`PolarStylusPlaneAngle` 为 `0`——此时中心在无穷远，所有以中心为基准的绘制都不可用。例如纬度 `45°`、法线方位 `180°`、法线天顶距 `45°` 就落在这个退化点上。 - **`PlaneIlluminated` 与 `Illuminated` 的区别**：前者只做几何受光判断，后者还要求太阳在地平线以上；做"这张日晷一天里能用多久"的结论时用后者。 ## 相关手册 - 真太阳时、均时差与太阳位置：[太阳与月亮](sun-moon.md) - 时角、恒星时与地平转换：[坐标工具](coord.md) - 出图时标：[时标声明](map-geojson.md#时标声明)