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

4.2 KiB
Raw Blame History

Cosmo - 深空探测器可视化系统 🚀

基于 NASA JPL Horizons 数据的深空探测器 3D 可视化系统。

快速开始

前置要求

  • Python 3.11+
  • Node.js 20+
  • Yarn

1. 启动后端 API

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

2. 启动前端应用

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 模型（未来）

行星纹理（未来）

开发进度

详见 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