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)
|