Orrery Vibe 项目

项目简介

Orrery 是一个用 NASA 真实空间几何数据驱动的浏览器端太阳系可视化项目。它的内核数据来自 NAIF（NASA 喷气推进实验室的导航与辅助信息中心）的 Generic Kernels——包括 Leap Second Kernel (naif0012.tls)、Planetary Constants Kernel (pck00011.tpc) 和 Planetary SPK (de432s.bsp)——并按 NAIF 的使用规则原样分发。前端用 Vite + React + TypeScript + Three.js 构建，把这些"航空级"坐标数据无损地搬到浏览器里渲染一个可交互的太阳系。点击进入 Live Demo 即可在线体验，无需安装任何环境。

核心功能

• 真实 NAIF 数据驱动：项目自带 NAIF Generic Kernels（LSK/PCK/SPK）作为静态资源，使用 SPICE 约定在 J2000 惯性参考系下计算所有天体的位置与速度。
• J2000 惯性系坐标：所有天体的位置用公里（km）表达、速度用公里每秒（km/s）表达、时间用 J2000 起的历元秒（ephemeris time, ET）表达，符合航天任务的坐标惯例。
• 基于 Three.js 的 3D 渲染：用 WebGL 在浏览器里渲染带光照的太阳系天体，天体半径同样来自 SPICE 数据。
• 坐标尺度自动处理：内置 kmToWorld = 1 / 1_000_000 把公里转换为 Three.js 单位（1 threeUnit = 1,000,000 km），并避免 32 位 float 在天文尺度下的精度塌陷。
• 可聚焦任意天体：默认聚焦地球，每帧重算天体到聚焦目标的位置差，再换算到渲染单位赋给 Three.js 对象，支持切换到任意 SPICE body。
• SPICE 框架变换矩阵：SpiceClient.getFrameTransform({ from, to, et }) 返回一个列主序的 number[9] 旋转矩阵（m00, m10, m20, m01, m11, m21, m02, m12, m22），与 Three.js Matrix3 直接对齐。
• 自动化测试覆盖：Playwright e2e 测试覆盖渲染路径，pnpm run test 跑单元测试、pnpm run e2e 跑端到端验证。

技术实现

Orrery 的核心数据流是"SPICE → J2000 → Three.js"。仓库自带一小组 NAIF Generic Kernels 作为静态资产（public/static/kernels/naif/ 下的 lsk/naif0012.tls、pck/pck00011.tpc、spk/planets/de432s.bsp），完全遵守 NAIF 的再分发条款。每个天体位置都以 J2000 惯性参考系为基准、相对 SUN 这个稳定观测者查询，对应 SPICE 库的 spkezr / pxform 调用语义。坐标尺度方面，SPICE 默认的公里级位置在天文尺度下会接近 1 AU（≈1.5×10^8 km），远超出 WebGL 32 位浮点的精度，所以项目强制以 1 threeUnit = 10^6 km 做一次预缩放；半径单独用公里级数据用于真实尺寸渲染。帧间变换通过 SpiceClient.getFrameTransform({ from, to, et }) 返回的 3×3 旋转矩阵表达，按列主序写成 number[9]，可直接赋值给 Matrix3.fromArray，矩阵乘法约定为 v_to = M(from→to) * v_from。整个前端用 Vite + React + TypeScript 构建，开发用 pnpm run dev，构建用 pnpm run build，测试用 pnpm run test，e2e 用 Playwright（pnpm run e2e）。GitHub Actions 还会跑 pnpm run format:check、pnpm run lint、pnpm run typecheck 三个质量门。

快速上手

1. 克隆仓库：git clone https://github.com/rybosome/orrery，确保本地 Node 与 pnpm 已安装。
2. 安装依赖：在仓库根目录运行 pnpm install。
3. 启动开发服务器：pnpm run dev，浏览器会自动打开本地预览，实时修改热重载。
4. 直接体验线上 Demo：访问 https://orrery.ryboso.me，免安装即可看到完整效果。
5. 运行 e2e 测试：pnpm run e2e 触发 Playwright 跑一遍渲染验证。
6. 构建生产包：pnpm run build 产出可部署到任何静态托管服务的资产。
7. 调整坐标尺度：编辑 kmToWorld 常量，根据相机远近裁切面和想要的效果做缩放。

适用人群

航空航天工程专业的学生与教师（教学演示真实星历表）；Three.js / WebGL 开发者（学习如何把"科学坐标系"映射到"游戏渲染坐标系"）；SPICE API 的初学者（用最少的代码就能跑通的浏览器参考实现）；天文科普内容创作者（制作轨道可视化素材）；以及对"科学软件如何优雅地跨入浏览器"感兴趣的工程师。

项目链接

https://github.com/rybosome/orrery

Live Demo https://orrery.ryboso.me