201 lines
4.2 KiB
Markdown
201 lines
4.2 KiB
Markdown
|
# Cosmo - 深空探测器可视化系统 🚀
|
|||
|
|
|
|||
|
|
基于 NASA JPL Horizons 数据的深空探测器 3D 可视化系统。
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
### 前置要求
|
|||
|
|
|
|||
|
|
- Python 3.11+
|
|||
|
|
- Node.js 20+
|
|||
|
|
- Yarn
|
|||
|
|
|
|||
|
|
### 1. 启动后端 API
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd backend
|
|||
|
|
|
|||
|
|
# 创建虚拟环境并安装依赖
|
|||
|
|
python -m venv venv
|
|||
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
|
|||
|
|
# 启动服务器
|
|||
|
|
python -m app.main
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
后端将运行在 http://localhost:8000
|
|||
|
|
|
|||
|
|
- API 文档: http://localhost:8000/docs
|
|||
|
|
- 健康检查: http://localhost:8000/health
|
|||
|
|
|
|||
|
|
### 2. 启动前端应用
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd frontend
|
|||
|
|
|
|||
|
|
# 安装依赖
|
|||
|
|
yarn install --ignore-engines
|
|||
|
|
|
|||
|
|
# 启动开发服务器
|
|||
|
|
yarn dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
前端将运行在 http://localhost:5173
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
cosmo/
|
|||
|
|
├── backend/ # Python FastAPI 后端
|
|||
|
|
│ ├── app/
|
|||
|
|
│ │ ├── main.py # FastAPI 入口
|
|||
|
|
│ │ ├── api/ # API 路由
|
|||
|
|
│ │ ├── models/ # 数据模型
|
|||
|
|
│ │ └── services/ # 业务逻辑
|
|||
|
|
│ └── requirements.txt
|
|||
|
|
├── frontend/ # React + Three.js 前端
|
|||
|
|
│ ├── src/
|
|||
|
|
│ │ ├── components/ # React 组件
|
|||
|
|
│ │ ├── hooks/ # 自定义 hooks
|
|||
|
|
│ │ ├── types/ # TypeScript 类型
|
|||
|
|
│ │ └── utils/ # 工具函数
|
|||
|
|
│ └── package.json
|
|||
|
|
├── PROJECT.md # 详细技术方案
|
|||
|
|
├── IMPLEMENTATION_PLAN.md # 实施计划
|
|||
|
|
└── README.md # 本文件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 功能特性
|
|||
|
|
|
|||
|
|
### 已实现 ✅
|
|||
|
|
|
|||
|
|
- **后端 API**
|
|||
|
|
- 从 NASA JPL Horizons 获取实时天体数据
|
|||
|
|
- 支持时间范围查询
|
|||
|
|
- 数据缓存机制（每3天更新）
|
|||
|
|
- RESTful API 设计
|
|||
|
|
|
|||
|
|
- **前端 3D 可视化**
|
|||
|
|
- React + Three.js 3D 场景
|
|||
|
|
- 实时显示太阳系天体位置
|
|||
|
|
- 交互式相机控制（旋转、平移、缩放）
|
|||
|
|
- 星空背景
|
|||
|
|
- 响应式设计
|
|||
|
|
|
|||
|
|
- **支持的天体**
|
|||
|
|
- 探测器: Voyager 1 & 2, New Horizons, Parker Solar Probe, Juno, Cassini, Perseverance
|
|||
|
|
- 行星: 太阳系八大行星
|
|||
|
|
|
|||
|
|
### 规划中 🚧
|
|||
|
|
|
|||
|
|
- 轨道线绘制
|
|||
|
|
- 时间选择器
|
|||
|
|
- 点击聚焦功能
|
|||
|
|
- 信息面板
|
|||
|
|
- 真实纹理贴图
|
|||
|
|
- 3D 探测器模型
|
|||
|
|
- 动态缩放优化
|
|||
|
|
|
|||
|
|
## 技术栈
|
|||
|
|
|
|||
|
|
### 后端
|
|||
|
|
- FastAPI - 现代 Python Web 框架
|
|||
|
|
- astroquery - NASA JPL Horizons 数据查询
|
|||
|
|
- astropy - 天文计算
|
|||
|
|
- Pydantic - 数据验证
|
|||
|
|
|
|||
|
|
### 前端
|
|||
|
|
- React 18 + TypeScript
|
|||
|
|
- Vite - 快速构建工具
|
|||
|
|
- Three.js - 3D 渲染
|
|||
|
|
- @react-three/fiber - React Three.js 集成
|
|||
|
|
- @react-three/drei - Three.js 辅助工具
|
|||
|
|
- Tailwind CSS - 样式框架
|
|||
|
|
- Axios - HTTP 客户端
|
|||
|
|
|
|||
|
|
## API 端点
|
|||
|
|
|
|||
|
|
### 获取天体位置
|
|||
|
|
```
|
|||
|
|
GET /api/celestial/positions
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
查询参数:
|
|||
|
|
- `start_time`: 起始时间 (ISO 8601)
|
|||
|
|
- `end_time`: 结束时间 (ISO 8601)
|
|||
|
|
- `step`: 时间步长 (如 "1d", "12h")
|
|||
|
|
|
|||
|
|
### 获取天体信息
|
|||
|
|
```
|
|||
|
|
GET /api/celestial/info/{body_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 列出所有天体
|
|||
|
|
```
|
|||
|
|
GET /api/celestial/list
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 使用说明
|
|||
|
|
|
|||
|
|
### 控制方式
|
|||
|
|
|
|||
|
|
- **左键拖动**: 旋转视角
|
|||
|
|
- **右键拖动**: 平移视角
|
|||
|
|
- **滚轮**: 缩放
|
|||
|
|
|
|||
|
|
### 坐标系统
|
|||
|
|
|
|||
|
|
使用日心坐标系（Heliocentric），以太阳为原点，单位为 AU (天文单位)。
|
|||
|
|
|
|||
|
|
## 外部资源需求
|
|||
|
|
|
|||
|
|
### 3D 模型（未来）
|
|||
|
|
- 来源: https://nasa3d.arc.nasa.gov/models
|
|||
|
|
- 格式: GLB/GLTF
|
|||
|
|
- 存放: `frontend/public/models/`
|
|||
|
|
|
|||
|
|
### 行星纹理（未来）
|
|||
|
|
- 来源: https://www.solarsystemscope.com/textures/
|
|||
|
|
- 格式: JPG/PNG
|
|||
|
|
- 存放: `frontend/public/textures/`
|
|||
|
|
|
|||
|
|
## 开发进度
|
|||
|
|
|
|||
|
|
详见 [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)
|
|||
|
|
|
|||
|
|
- ✅ Stage 1: 后端基础框架和数据获取
|
|||
|
|
- ✅ Stage 2: 前端基础框架和简单 3D 场景
|
|||
|
|
- ✅ Stage 3: 集成真实数据（部分完成）
|
|||
|
|
- 🚧 Stage 4: 进阶交互和信息面板
|
|||
|
|
- 🚧 Stage 5: 视觉优化和模型加载
|
|||
|
|
|
|||
|
|
## 故障排除
|
|||
|
|
|
|||
|
|
### 后端无法启动
|
|||
|
|
- 确保 Python 3.11+ 已安装
|
|||
|
|
- 检查虚拟环境是否激活
|
|||
|
|
- 尝试升级 pip: `pip install --upgrade pip`
|
|||
|
|
|
|||
|
|
### 前端依赖安装失败
|
|||
|
|
- 使用 `yarn install --ignore-engines`
|
|||
|
|
- 确保 Node.js 版本 >= 20
|
|||
|
|
|
|||
|
|
### 数据加载缓慢
|
|||
|
|
- NASA JPL Horizons API 首次查询较慢（10-30秒）
|
|||
|
|
- 后续请求会使用缓存，速度更快
|
|||
|
|
|
|||
|
|
## 许可证
|
|||
|
|
|
|||
|
|
MIT
|
|||
|
|
|
|||
|
|
## 致谢
|
|||
|
|
|
|||
|
|
- NASA JPL Horizons System
|
|||
|
|
- React Three Fiber 社区
|
|||
|
|
- Astroquery 项目
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
更多技术细节请查看 [PROJECT.md](./PROJECT.md)
|