317 lines
8.0 KiB
Markdown
317 lines
8.0 KiB
Markdown
# 天体轨道自动生成功能使用说明
|
||
|
||
**版本**: 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` 表中：
|
||
|
||
```sql
|
||
SELECT * FROM orbits WHERE body_id = '999'; -- 查看冥王星的轨道
|
||
```
|
||
|
||
返回字段：
|
||
- `body_id`: 天体ID
|
||
- `points`: 轨道点数组（JSONB）
|
||
- `num_points`: 点数量
|
||
- `period_days`: 轨道周期
|
||
- `color`: 轨道颜色
|
||
- `updated_at`: 最后更新时间
|
||
|
||
### 前端渲染
|
||
|
||
前端通过API获取轨道数据后，使用Three.js的Line对象渲染：
|
||
|
||
```typescript
|
||
GET /celestial/orbits?body_type=planet
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"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获取轨道周期
|
||
- [ ] 异步后台生成，不阻塞用户操作
|
||
- [ ] 轨道预览功能
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [天体轨道生成系统技术文档](./ORBIT_GENERATION_SYSTEM.md)
|
||
- [NASA JPL Horizons API文档](https://ssd.jpl.nasa.gov/horizons/)
|
||
|
||
---
|
||
|
||
**文档作者**: Claude Code AI
|
||
**反馈渠道**: 项目Issues
|