从寿星天文历到 3D 太阳系：一个老牌天文历算项目的现代化表达
最近整理 sxwnl 相关项目时，重新看了一遍寿星天文历的历史，以及它后来发展出来的 C++ 3D 版本。
这其实是一个很有意思的项目：一边是传统的农历、节气、朔望、日月食和行星星历计算，另一边则是 OpenGL、Dear ImGui 和 3D 太阳系可视化。
它没有把“万年历”停留在日期查询和表格展示上，而是试着回答一个更直观的问题：
我们能不能把这些天文历算结果真正“看见”？
项目地址：
- 原版来源: http://bbs.nongli.net/dispbbs_2_14995.html
- git仓库：https://github.com/sxwnl/sxwnl
- C++ 3D 版本：https://github.com/sxwnl/sxwnl-cpp-3d
- 在线参考页面：https://sxwnl.github.io
一、寿星天文历的来源
寿星天文历并不是一个普通的日历程序。
它的名称是：
寿星天文历（万年历）5.10
原作者为 许剑伟。
早期版本的相关资料曾发布于农历论坛：
http://bbs.nongli.net/dispbbs_2_14995.html
随着项目不断发展，相关内容也逐渐整理到了 sxwnl.github.io 以及后续的 GitHub 仓库中。现在常见的 sxwnl/sxwnl，可以看作寿星天文历原有历算体系的开源延续和整理版本。
这段历史很重要，因为 sxwnl 并不是为了做一个简单的“日期显示器”才开始开发的。它背后真正关注的是一整套天文历算问题：
- 农历如何计算
- 节气如何确定
- 月相和朔望如何推算
- 日食、月食在什么时候发生
- 行星在天空中的位置如何计算
- 真太阳时和地方时间有什么关系
- 日出、日落、月出、月落如何得到
从这个角度看，寿星天文历更像是一套长期积累的天文计算工具，而不是单纯意义上的万年历。
二、从万年历到天文历算
很多人第一次接触万年历，可能只是为了查询：
- 某一天对应的农历日期
- 今天是什么节气
- 某个节日是哪一天
- 某年的生肖和干支
但真正深入之后会发现，这些内容并不是互相独立的。
农历月份和月相有关，节气和太阳周年运动有关，日月食又和太阳、地球、月球之间的空间位置有关。八字、真太阳时、日出日落等功能，也都离不开时间系统和天体位置计算。
因此，寿星天文历的核心并不只是“查日期”，而是把这些内容放进了一个完整的天文历算框架里。
原版主要覆盖了以下内容：
- 农历万年历
- 公历、农历、回历等历法转换
- 二十四节气
- 月相与朔望
- 日月食
- 行星星历
- 八字与干支
- 真太阳时
- 日出日落
- 月出月落
- 天体升降
这些功能共同构成了寿星天文历的基础。
三、C++ 版本：把核心能力带到桌面端
在原有寿星天文历体系的基础上，后来出现了 sxwnl/sxwnl-cpp-3d。
顾名思义，这是一个 C++ 移植版本，并且加入了新的 3D 图形界面。
它的目标并不是重新发明一套历法，而是把原有的天文历算能力以更适合 C++ 和桌面程序的方式组织起来，同时增加可视化和交互功能。
C++ 版本包含：
- 农历万年历
- 节气计算
- 日月食搜索
- 行星星历
- 八字与真太阳时
- 日月升降
- 3D 太阳系
- 3D 日月食演示
原本只能通过文本、表格或网页结果查看的数据，现在可以进一步放进一个可操作的图形界面里。
这也是这个版本比较有意思的地方：
计算引擎负责把结果算出来，3D 界面负责让人理解这些结果。
四、3D 太阳系：把抽象的轨道变成可以观察的场景
天文计算中有很多数据对程序来说非常明确，但对普通人来说并不容易理解。
例如：
- 黄经是多少度
- 赤经是多少小时
- 天体距离是多少
- 某一时刻的方位角和高度角是多少
这些数据当然有用，但如果只看一串数字，很难形成空间概念。
3D 太阳系提供了另一种表达方式。
在这个场景中，可以查看太阳系中的行星轨道，并观察行星随时间变化的位置。项目还支持根据时间推进，让行星按照计算结果运行起来。
目前 3D 部分主要包括：
- 日心轨道展示
- 行星实时位置
- 光照球体
- 轨道和行星大小控制
- 线性或对数距离压缩
- 行星运行速度控制
- 行星详细星历参数
由于太阳系中各天体之间的真实距离差别很大，如果完全按照实际比例显示，内行星和外行星很容易挤在一起，或者部分天体看不清楚。因此，界面提供了距离压缩和大小调节功能。
这并不是为了追求严格的视觉比例，而是为了让用户能够在一个场景中同时观察整个太阳系。
五、3D 日月食：从结果查询到空间演示
日月食是寿星天文历的重要功能之一。
传统方式通常是查询一张表：
- 发生时间
- 食甚时间
- 食分
- 初亏
- 复圆
- 可见地区
- 食带范围
这些数据很精确，但对于没有天文学基础的人来说，还是比较抽象。
3D 版本增加了日月食可视化功能，可以从空间角度观察：
- 太阳、地球、月球三者的位置关系
- 月球经过地球阴影的过程
- 日食时月球阴影落在地球表面的情况
- 本影与半影的范围
- 地球上的食带变化
- 三体光锥的空间关系
其中比较有特色的是“三体光锥”演示。
日食和月食本质上都是光影关系：
- 日食时，月球挡住了太阳光，月球的影子投射到地球表面
- 月食时，月球进入地球的本影或半影区域
- 本影、半影和天体之间形成了具有空间方向的几何结构
通过 3D 场景，这些内容不再只是几个时间点和一张地图，而是可以旋转、缩放和播放的空间模型。
六、3D 版本适合哪些应用场景？
这个项目的 3D 部分并不只是为了增加视觉效果。它其实有不少实际应用场景。
1. 天文教育
这是最直接的用途。
在课堂上讲解太阳系、月相、日食、月食时，二维图片往往不够直观。3D 模型可以帮助学生建立空间关系，理解：
- 行星的公转
- 地球和月球的相对运动
- 月相为什么会变化
- 日食和月食为什么不会每个月都发生
- 本影和半影有什么区别
它可以用于：
- 中学地理课堂
- 中学物理课堂
- 天文兴趣课程
- 科学教育活动
- 青少年天文科普
2. 天文科普展示
天文馆、科技馆和博物馆经常需要把复杂知识解释给普通观众。
相比单纯展示数据，3D 模型更容易吸引注意，也更方便现场讲解。
例如，可以通过控制时间来演示：
- 某次日食的发生过程
- 月球穿过地影的全过程
- 行星在一段时间内的轨道运动
- 某个节气时太阳的位置变化
这种方式比直接告诉观众“某年某月某日发生月食”更容易留下印象。
3. 传统历法展示
寿星天文历本身和中国传统历法关系密切。
节气、月相、农历月份、干支和真太阳时，都是中国传统时间体系的重要组成部分。
如果只从文字角度介绍这些内容，容易让人觉得它们比较遥远。
但如果把它们和太阳、地球、月球的实际运动联系起来，就能更清楚地看到传统历法背后的天文基础。
这类 3D 应用可以用于：
- 传统文化数字化展示
- 农历和节气科普
- 古代历法介绍
- 汉文化相关展览
- 天文与传统文化结合的互动项目
4. 软件工程和图形学演示
对于开发者来说，这个项目还有另外一层价值。
它把几个通常分开出现的模块放到了一起：
- 天文算法
- C++ 工程
- CMake 构建
- OpenGL 渲染
- Dear ImGui 界面
- 时间控制
- 数据与图形同步
- 3D 相机交互
如果想学习如何把一个计算型项目扩展成桌面可视化工具，这类项目很适合作为参考。
尤其是下面这些问题，都可以从中找到实际案例：
- 如何把计算结果传给渲染场景
- 如何设计一个可播放的天文时间轴
- 如何在 3D 场景中表达不同比例的空间距离
- 如何让 ImGui 面板和 OpenGL 画面配合工作
- 如何组织天文数据、轨道数据和 UI 状态
七、项目使用的技术
3D 版本的图形界面主要基于以下技术：
- C++
- OpenGL
- Dear ImGui
- GLFW
- CMake
项目的 GUI 部分大致包括：
gui/
├── main.cpp GLFW、OpenGL 和 ImGui 主循环
├── scene.{h,cpp} 太阳系场景与天文引擎对接
├── renderer.{h,cpp} OpenGL 渲染、球体、轨道和着色器
├── panels.{h,cpp} 控制、历法、星历、日月食等面板
├── camera.h 轨道相机
└── mathx.h 向量和矩阵工具
天文引擎部分则主要分布在：
eph/ 天文历算、行星、章动、日月食等
lunar/ 农历、节气、气朔、八字
mylib/ 工具库和数学功能
test/ 控制台程序与回归测试
从结构上看，它采用了比较清晰的分层方式：
- 历算模块负责计算
- 场景模块负责组织天体和时间
- 渲染模块负责绘制
- 面板模块负责交互
- 测试模块负责验证结果
八、如何构建 3D 版本？
项目提供了脚本构建和 CMake 构建两种方式。
Windows
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
.\build_gui.ps1
也可以使用：
.\build_gui.ps1 -Clean
.\build_gui.ps1 -Debug
.\build_gui.ps1 -MinGW
.\build_gui.ps1 -NoGui
Linux、macOS、MSYS2
bash build_gui.sh
其他选项：
bash build_gui.sh --clean
bash build_gui.sh --debug
bash build_gui.sh --no-gui
手动使用 CMake
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j$(nproc)
如果只构建控制台版本，可以关闭 GUI：
cmake -B build -DSXWNL_BUILD_GUI=OFF
cmake --build build
第一次构建 GUI 时，CMake 会通过 FetchContent 获取相关依赖，通常包括 GLFW、Dear ImGui 等。
九、运行和操作方式
构建完成后，可以直接运行 GUI：
./build/sxwnl_gui
控制台版本：
./build/test1
GUI 中提供了比较常见的 3D 操作：
| 操作 | 功能 |
|---|---|
| 左键拖拽 | 旋转相机 |
| 右键拖拽 | 平移相机 |
| 滚轮 | 缩放 |
| 播放/暂停 | 控制天体运动 |
| 日期跳转 | 跳到指定时间 |
| 速度预设 | 按秒、小时或日期推进 |
| 负速度 | 反向播放 |
| 行星列表 | 查看详细星历 |
| 日月食面板 | 搜索和查看食象事件 |
| 3D 食影 | 观察地球食带和光锥 |
项目还支持固定 UTC 时区，默认可以按北京、上海等 UTC+8 时区显示时间。
中文字体方面，程序会尝试检测系统中的微软雅黑等字体。如果系统没有合适的中文字体，则会回退到默认字体，中文可能显示为方块。
十、一个老项目为什么还值得继续做？
寿星天文历的特别之处，在于它并不是一个追逐新框架的项目。
它的核心价值来自长期积累：
- 算法积累
- 历法资料积累
- 计算结果验证
- 用户使用反馈
- 不同平台上的持续维护
这类项目往往不会因为界面简单就失去价值。相反，真正稳定的天文历算核心，通常需要经过很长时间的验证。
而 3D 版本做的事情，是在不放弃原有计算能力的前提下，给这个老项目增加了一种新的表达方式。
以前我们看到的是：
日期 → 计算结果
现在还可以看到：
日期 → 天体位置 → 空间运动 → 可视化结果
这让很多原本只能通过数字理解的内容，变得更容易观察和解释。
十一、总结
如果说 sxwnl/sxwnl 代表的是寿星天文历的计算基础，那么 sxwnl/sxwnl-cpp-3d 更像是这个基础上的一次现代化延伸。
它保留了原有的：
- 农历万年历
- 节气
- 月相
- 日月食
- 行星星历
- 八字
- 真太阳时
- 日月升降
同时又增加了：
- 3D 太阳系
- 行星轨道
- 实时运行参数
- 3D 日月食
- 地球食带
- 本影和半影
- 太阳—地球—月球三体光锥
从寿星天文历最初的历算工具，到现在的 C++ 3D 可视化程序，这条发展路线其实很有代表性：
先把复杂的东西算准确，再想办法把它讲清楚。
这也是这个项目最值得记录的地方。
它既可以是一个实用的天文历算工具，也可以是一个天文教育和科普演示程序；既能服务传统历法相关应用，也能作为 C++、OpenGL 和 ImGui 结合使用的工程案例。
如果你对天文历法、传统文化数字化、3D 可视化，或者 C++ 图形界面开发感兴趣，都可以从这个项目开始了解。
项目地址：
sxwnl/sxwnl：https://github.com/sxwnl/sxwnlsxwnl/sxwnl-cpp-3d：https://github.com/sxwnl/sxwnl-cpp-3dsxwnl.github.io：https://sxwnl.github.io
参考资料
- 寿星天文历（万年历）5.10
- 原作者：许剑伟
- 早期相关资料：http://bbs.nongli.net/dispbbs_2_14995.html
- 寿星天文历项目主页：https://sxwnl.github.io
sxwnl/sxwnlGitHub 仓库：https://github.com/sxwnl/sxwnlsxwnl/sxwnl-cpp-3dGitHub 仓库：https://github.com/sxwnl/sxwnl-cpp-3d
–本篇文章由AI辅助编写–
评论区