# Planetary science

**Repository Path**: yangyiheng2005/planetary-science

## Basic Information

- **Project Name**: Planetary science
- **Description**: 行星科学课程N体问题可视化模拟
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌌 行星系统可视化与N体物理引擎

> Planetary System Visualizer & N-body Physics Engine

这是一个用于**行星科学课程**的教学项目，实现了一个完整的N体引力模拟系统和3D可视化界面。

![Project Preview](https://via.placeholder.com/800x400/1a1a2e/40c4ff?text=Planetary+System+Visualizer)

## ✨ 功能特性

### 物理引擎
- **牛顿万有引力**：所有天体之间的引力相互作用
- **多种积分方法**：
  - 半隐式欧拉法（快速，具有辛性质）
  - 四阶龙格-库塔法（高精度，推荐）
  - Velocity Verlet（能量守恒好）
- **天体类型**：恒星、行星、卫星、小行星、彗星、黑洞
- **单位系统**：使用天文单位（AU、太阳质量、天）确保数值稳定

### 可视化
- **3D渲染**：使用Three.js/React Three Fiber
- **轨道轨迹**：实时绘制天体运动路径
- **相机控制**：自由旋转、缩放、平移，可跟踪特定天体
- **恒星发光**、**黑洞吸积盘**等特殊效果

### 用户界面
- **现代暗色主题**：专业科学工具风格
- **预设场景**：太阳系、双星系统、黑洞飞掠、三体问题等
- **天体编辑器**：可视化修改天体属性
- **时间控制**：播放/暂停、单步、时间缩放

---

## 🚀 快速开始

### 环境要求
- Node.js 18+
- npm 或 yarn

### 安装和运行

```bash
# 进入项目目录
cd planetary-system

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

打开浏览器访问 `http://localhost:5173` 即可看到应用。

### 构建生产版本

```bash
npm run build
npm run preview
```

---

## 📚 物理原理简介

### 牛顿万有引力定律

任意两个质点之间存在引力，大小与它们质量的乘积成正比，与距离的平方成反比：

$$
\vec{F}_{12} = -G \frac{m_1 m_2}{r^2} \hat{r}_{12}
$$

其中：
- $G$ 是万有引力常数
- $m_1, m_2$ 是两个天体的质量
- $r$ 是两天体之间的距离
- $\hat{r}_{12}$ 是从天体1指向天体2的单位向量

### N体问题

当有N个天体相互作用时，每个天体受到其他所有天体的引力作用：

$$
\vec{a}_i = G \sum_{j \neq i} \frac{m_j}{|\vec{r}_j - \vec{r}_i|^3} (\vec{r}_j - \vec{r}_i)
$$

这是一个没有解析解的问题（N≥3时），必须使用数值方法求解。

### 单位系统

为了避免数值溢出，我们使用天文学常用单位：

| 物理量 | 单位 | 符号 |
|--------|------|------|
| 距离 | 天文单位 | AU |
| 质量 | 太阳质量 | M☉ |
| 时间 | 天 | day |

在这个单位系统中，$G \approx 2.959 \times 10^{-4}$ AU³/(M☉·day²)

---

## 🏗️ 项目结构

```
planetary-system/
├── src/
│   ├── physics/           # 物理引擎核心
│   │   ├── types.ts       # 类型定义
│   │   ├── constants.ts   # 物理常数和单位
│   │   ├── vector.ts      # 向量运算
│   │   ├── integrators.ts # 数值积分器
│   │   ├── engine.ts      # 主引擎逻辑
│   │   └── index.ts       # 模块导出
│   │
│   ├── presets/           # 预设场景
│   │   ├── solarSystem.ts # 太阳系
│   │   ├── binaryStars.ts # 双星系统
│   │   ├── planetMoon.ts  # 行星-卫星
│   │   ├── blackHole.ts   # 黑洞场景
│   │   └── index.ts       # 场景导出
│   │
│   ├── store/             # 状态管理
│   │   └── simulationStore.ts  # Zustand store
│   │
│   ├── viewer/            # 3D渲染
│   │   ├── Viewport.tsx   # 主视口
│   │   └── CelestialBodyMesh.tsx  # 天体渲染
│   │
│   ├── components/        # UI组件
│   │   ├── App.tsx        # 主应用
│   │   ├── Toolbar.tsx    # 工具栏
│   │   ├── Sidebar.tsx    # 侧边栏
│   │   ├── BodyEditor.tsx # 天体编辑器
│   │   └── SettingsModal.tsx  # 设置弹窗
│   │
│   ├── styles/            # 样式
│   │   └── global.css     # 全局样式
│   │
│   └── main.tsx           # 入口文件
│
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
```

---

## 🔧 核心模块详解

### 物理引擎 (`src/physics/`)

#### `types.ts` - 类型定义
定义了所有核心数据结构：
- `Vector3` - 三维向量
- `CelestialBody` - 天体对象
- `SimulationConfig` - 模拟配置
- `SimulationState` - 完整状态

#### `integrators.ts` - 数值积分器
实现了三种积分方法：

```typescript
// 半隐式欧拉法
function integrateEuler(bodies, config, dt)

// 四阶龙格-库塔法
function integrateRK4(bodies, config, dt)

// Velocity Verlet
function integrateVerlet(bodies, config, dt)
```

#### `engine.ts` - 主引擎
提供模拟控制接口：

```typescript
// 创建模拟
createSimulation(bodies, config)

// 执行一步
step(state)

// 添加/删除/更新天体
addBody(state, body)
removeBody(state, bodyId)
updateBody(state, bodyId, updates)
```

### 预设场景 (`src/presets/`)

每个场景文件导出一个 `Scenario` 对象：

```typescript
export const myScenario: Scenario = {
  id: 'my-scenario',
  name: '我的场景',
  description: '场景描述',
  bodies: [
    {
      name: '太阳',
      type: 'star',
      mass: 1.0,
      radius: 0.00465,
      position: { x: 0, y: 0, z: 0 },
      velocity: { x: 0, y: 0, z: 0 },
      color: '#FDB813',
    },
    // ... 更多天体
  ],
  configOverrides: {
    baseDt: 0.5,
    timeScale: 5,
  },
};
```

### 添加新场景

1. 在 `src/presets/` 创建新文件
2. 定义并导出 `Scenario` 对象
3. 在 `src/presets/index.ts` 中注册

---

## 🎮 使用指南

### 视口操作
- **旋转视角**：鼠标左键拖拽
- **平移**：鼠标右键拖拽
- **缩放**：滚轮

### 天体交互
- **选中**：点击天体
- **跟踪**：双击天体（相机跟随）
- **编辑**：在右侧面板修改属性

### 时间控制
- **播放/暂停**：点击播放按钮或按空格
- **单步**：点击前进按钮
- **调速**：拖动时间缩放滑块

---

## 📖 扩展阅读

### 推荐教材
- 《天体力学引论》
- 《数值方法》相关章节

### 相关概念
- 开普勒定律
- 二体问题解析解
- 限制性三体问题
- 辛积分器

---

## 📝 许可证

MIT License - 仅供教学使用

---

## 🙏 致谢

本项目作为行星科学课程设计作业，感谢课程老师的指导。

---

*Made with ❤️ for Planetary Science Course*