mula
/
cosmo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
cosmo/ORBIT_GENERATION_USER_GUIDE.md

8.0 KiB
Raw Blame History

天体轨道自动生成功能使用说明

版本: 1.0 最后更新: 2025-12-10

功能概述

Cosmo项目现已支持为行星和矮行星自动生成公转轨道。该功能通过调用NASA JPL Horizons API获取真实的天体位置数据，预先计算并存储完整的轨道路径，供前端高效渲染。

适用天体类型

天体类型 是否支持轨道生成 说明
✅ 行星 (planet) 是 太阳系八大行星
✅ 矮行星 (dwarf_planet) 是 冥王星、谷神星、阋神星等
❌ 卫星 (satellite) 否 当前版本不支持
❌ 恒星 (star) 否 恒星无需轨道
❌ 探测器 (probe) 否 当前版本不支持
❌ 彗星 (comet) 否 当前版本不支持

使用方法

方法一：为新增天体生成轨道（推荐）

步骤1: 新增天体时填写轨道参数

  1. 进入 管理后台 > 天体数据管理

  2. 选择恒星系统（例如"太阳系"）

  3. 点击 "新增" 按钮

  4. 填写基本信息：

    • JPL Horizons ID
    • 英文名 / 中文名
    • 类型: 选择"行星"或"矮行星"
    • 描述

  5. 填写轨道参数（当类型为行星/矮行星时自动显示）：

    ![轨道参数示例]

    • 轨道周期（天）: 天体完整公转一周所需的天数

      • 例如：地球 = 365.25天
      • 例如：冥王星 = 90560天（约248年）

    • 轨道颜色: 轨道线的显示颜色（HEX格式）

      • 例如：地球 = #4A90E2（蓝色）
      • 例如：火星 = #CD5C5C（红色）
      • 点击颜色选择器可视化选择

  6. 保存天体

步骤2: 生成轨道

  1. 保存后返回天体列表
  2. 找到刚才新增的天体
  3. 点击该行右侧的 "生成轨道" 按钮
  4. 等待生成完成（通常需要5-30秒）
  5. 成功后会显示："轨道生成成功！共 XXX 个点"

方法二：为已有天体补充轨道参数并生成

步骤1: 编辑天体添加轨道参数

  1. 进入 管理后台 > 天体数据管理
  2. 选择对应的恒星系统
  3. 找到目标天体，点击 "编辑" 按钮
  4. 在"基础信息"Tab中找到"轨道参数"部分
  5. 填写：
    • 轨道周期（天）
    • 轨道颜色
  6. 保存

步骤2: 生成轨道

  1. 返回列表，点击 "生成轨道" 按钮
  2. 等待生成完成

方法三：批量生成（适合系统管理员）

如果您已经在代码中定义了轨道参数（通过硬编码的ORBITAL_PERIODS字典），可以使用批量生成：

  1. 进入 管理后台 > NASA数据下载
  2. 点击 "生成所有轨道" 按钮
  3. 系统会自动为所有已定义轨道周期的行星/矮行星生成轨道

轨道参数参考

太阳系行星轨道周期

天体 轨道周期（天） 建议颜色
水星 88.0 #8C7853
金星 224.7 #FFC649
地球 365.25 #4A90E2
火星 687.0 #CD5C5C
木星 4333.0 #DAA520
土星 10759.0 #F4A460
天王星 30687.0 #4FD1C5
海王星 60190.0 #4169E1

太阳系矮行星轨道周期

天体 轨道周期（天） 建议颜色
谷神星 (Ceres) 1680.0 #9E9E9E
冥王星 (Pluto) 90560.0 #8B7355
阋神星 (Eris) 203500.0 #E0E0E0
妊神星 (Haumea) 104000.0 #D4A574
鸟神星 (Makemake) 112897.0 #C49A6C

技术细节

轨道采样策略

系统会根据轨道周期智能决定采样点数量：

  • 短周期天体（<10年）：约每天1个点，最少100个点

    • 例如：地球（365天）→ 365个采样点

  • 长周期天体（≥10年）：约每月1个点，最多1000个点

    • 例如：冥王星（90560天）→ 1000个采样点

数据存储

生成的轨道数据存储在 orbits 表中：

SELECT * FROM orbits WHERE body_id = '999';  -- 查看冥王星的轨道

返回字段：

  • body_id: 天体ID
  • points: 轨道点数组（JSONB）
  • num_points: 点数量
  • period_days: 轨道周期
  • color: 轨道颜色
  • updated_at: 最后更新时间

前端渲染

前端通过API获取轨道数据后，使用Three.js的Line对象渲染：

GET /celestial/orbits?body_type=planet

响应示例：

{
  "orbits": [
    {
      "body_id": "399",
      "body_name": "地球",
      "points": [
        {"x": 1.0, "y": 0.0, "z": 0.0},
        {"x": 0.99, "y": 0.01, "z": 0.0},
        ...
      ],
      "num_points": 365,
      "period_days": 365.25,
      "color": "#4A90E2"
    }
  ]
}

常见问题

Q1: 为什么生成轨道需要这么长时间？

A: 轨道生成需要调用NASA JPL Horizons API获取天体在整个公转周期内的位置数据。对于长周期天体（如冥王星），需要查询数百年的数据，因此耗时较长（通常10-30秒）。

Q2: 我新增的矮行星没有"生成轨道"按钮？

A: 请检查以下几点：

  1. 确认天体类型是否为"行星"或"矮行星"
  2. 确认在列表中能看到该天体
  3. 刷新页面重试

Q3: 轨道生成失败，提示"No orbital period defined"？

A: 这表示系统无法获取该天体的轨道周期。解决方法：

  1. 方法一（推荐）：编辑天体，在"轨道参数"中手动填写轨道周期
  2. 方法二：联系管理员在代码的 ORBITAL_PERIODS 字典中添加该天体的周期

Q4: 如何修改已生成的轨道颜色？

A:

  1. 编辑天体，修改 extra_data.orbit_color 字段
  2. 重新点击"生成轨道"按钮
  3. 系统会覆盖旧轨道数据

Q5: 轨道数据需要多久更新一次？

A:

  • 行星: 轨道相对稳定，建议每年更新一次
  • 矮行星: 建议每5年更新一次
  • 特殊情况: 如果发现轨道显示不准确，可随时重新生成

Q6: 生成轨道时提示"NASA API超时"怎么办？

A:

  1. 检查网络连接
  2. 稍后重试（NASA API可能繁忙）
  3. 如果持续失败，联系管理员检查代理配置

数据优先级说明

轨道参数的读取优先级：

1. extra_data.orbit_period_days (用户填写的轨道周期)
   ↓ 如果没有
2. ORBITAL_PERIODS字典 (代码中硬编码的周期)
   ↓ 如果没有
3. 跳过该天体，不生成轨道

颜色优先级：

1. extra_data.orbit_color (用户选择的颜色)
   ↓ 如果没有
2. DEFAULT_COLORS字典 (代码中硬编码的颜色)
   ↓ 如果没有
3. 使用默认灰色 #CCCCCC

示例：新增一个矮行星并生成轨道

场景：新增塞德娜（Sedna）

  1. 基本信息：

    • JPL Horizons ID: 90377 (Sedna的JPL ID)
    • 英文名: Sedna
    • 中文名: 塞德娜
    • 类型: 矮行星
    • 所属系统: 太阳系
    • 描述: 极远距离的外海王星天体

  2. 轨道参数：

    • 轨道周期：4155150天 (约11,400年)
    • 轨道颜色：#B8860B (深金色)

  3. 保存后生成：

    • 点击"生成轨道"
    • 等待20-30秒
    • 成功后前端会显示塞德娜的椭圆轨道

最佳实践

✅ 推荐做法

  1. 使用标准周期数据: 从维基百科或NASA查询准确的轨道周期
  2. 颜色统一规范: 使用天文学上约定俗成的颜色（例如地球用蓝色）
  3. 批量生成: 对于太阳系已知天体，使用批量生成功能更高效

❌ 避免的做法

  1. 随意填写周期: 不准确的周期会导致轨道显示错误
  2. 频繁重复生成: 轨道生成消耗NASA API配额，避免无意义的重复
  3. 不填轨道参数: 忘记填写参数会导致无法生成轨道

未来改进方向

  • 支持卫星轨道生成
  • 支持彗星椭圆轨道
  • 自动从NASA API获取轨道周期
  • 异步后台生成，不阻塞用户操作
  • 轨道预览功能

相关文档

文档作者: Claude Code AI 反馈渠道: 项目Issues