# orbit_visualizer

**Repository Path**: zd_g/orbit_visualizer

## Basic Information

- **Project Name**: orbit_visualizer
- **Description**: 多源轨道综合可视化系统、基于 FastAPI + Cesium 的多源轨道数据解析、生成与 3D 可视化平台。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Cesium, Python

## README

# 多源轨道综合可视化系统

基于 FastAPI + Cesium 的多源轨道数据解析、生成与 3D 可视化平台。
![多源轨道综合可视化系统](./image/orbit.png)
---


## 一、项目结构

```
orbit_visualizer/
├── main.py              # 后端：FastAPI + 轨道力学计算 + CZML 生成
├── static/
│   └── index.html       # 前端：Cesium 3D 可视化 + 控制面板
├── data/                # 测试数据目录
│   ├── example.sp3      # SP3 精密星历示例（2 颗 GPS 卫星，12h 弧段）
│   ├── example.rnx      # RINEX v2 广播星历示例（3 颗 GPS 卫星）
│   ├── example.tle      # 批量 TLE 示例（ISS / Hubble / NOAA-19）
│   └── example_iod.csv  # IOD 观测数据示例（5 点 LEO 位置）
├── run.bat              # 启动脚本（uvicorn --reload）             
└── README.md            # 项目介绍
```

## 二、技术栈

| 层级 | 技术 |
|------|------|
| Web 框架 | FastAPI + uvicorn |
| 3D 渲染 | Cesium.js (CZML 格式) |
| 轨道力学 | NumPy 数值计算 |
| TLE 传播 | sgp4 (Satrec) |
| 文件解析 | 正则表达式 + 位置索引 |
| 数据格式 | CZML (JSON) |

## 三、功能模块

### 3.1 数据源导入（📡）

#### SP3 精密星历

- **格式支持**：SP3-a / SP3-c
- **解析内容**：epoch 行 (`*` 开头) + 位置记录 (`P` 开头)
- **坐标转换**：km → m（×1000）
- **输出**：按卫星 ID 分组的时间-位置序列
- **API**：`POST /api/upload/sp3`

#### RINEX 广播星历

- **格式支持**：RINEX v2 导航文件
- **解析方式**：位置索引逐行读取，每颗卫星 8 行一组
- **D 指数处理**：`replace("D","e")` → `float()`
- **坐标反演**：按 ICD-GPS-200 标准计算 ECEF 坐标
  - Kepler 方程迭代求解
  - 摄动修正（Crs, Cuc, Cus, Cic, Cis, Crc）
  - 升交点经度 + 地球自转修正
- **API**：`POST /api/upload/rinex`

#### 批量 TLE

- **格式支持**：
  - 3 行格式：Name / Line1 / Line2
  - 2 行格式：Line1 / Line2（自动生成名称 TLE-N）
- **输入方式**：文件上传 + 文本框粘贴
- **传播模型**：SGP4 (sgp4 库)
- **容错**：单颗卫星解析失败不影响其余
- **API**：`POST /api/upload/tle`

---

### 3.2 自定义轨道生成（🛰️）

#### 状态向量（高度 + 倾角）

- **输入参数**：高度 (km)、倾角 (°)、升交点赤经 (°)
- **默认值**：400 km / 51.6° / 0°（ISS 典型轨道）
- **生成方式**：封装 `kepler_orbit(e≈0.0001)` 生成近圆轨道
- **API**：`GET /api/orbit/state_vector_custom`

#### 轨道六根数 (Keplerian Elements)

- **输入参数**：

| 参数 | 符号 | 单位 | 默认值 |
|------|------|------|--------|
| 半长轴 | a | m | 7,000,000 |
| 偏心率 | e | — | 0.001 |
| 倾角 | i | ° | 51.6 |
| 升交点赤经 | Ω | ° | 100 |
| 近地点幅角 | ω | ° | 0 |
| 平近点角 | M₀ | ° | 0 |

- **计算流程**：
  1. Newton-Raphson 求解 Kepler 方程：\( E - e\sin E = M \)
  2. 真近点角：\( \nu = \arctan2(\sqrt{1-e^2}\sin E,\; \cos E - e) \)
  3. 轨道半径：\( r = a(1 - e\cos E) \)
  4. 3-1-3 旋转矩阵：\( R_z(-\Omega) \cdot R_x(-i) \cdot R_z(-\omega) \)
- **API**：`GET /api/orbit/kepler`

---

### 3.3 观测反演轨道确定 (IOD)

#### Gibbs 三点法

- **输入**：≥3 个 ECI 位置矢量（时间, x, y, z）
- **算法流程**：
  1. 取首、中、尾三点的位置 \( \vec{r}_1, \vec{r}_2, \vec{r}_3 \)
  2. 计算 N/D/S 矢量：\( N = r_1|c_{23}| + r_2|c_{31}| + r_3|c_{12}| \)
  3. 中间点速度：\( \vec{v}_2 = \frac{L_g}{r_2}\vec{B} + L_g\vec{S} \)，其中 \( L_g = \sqrt{\frac{\mu}{N_m D_m}} \)
  4. 笛卡尔 (r₂, v₂) → Kepler 六根数反演

#### 笛卡尔 → Kepler 反演

- 半长轴：\( a = -\frac{\mu}{2\xi} \)，\( \xi = \frac{v^2}{2} - \frac{\mu}{r} \)
- 偏心率矢量：\( \vec{e} = \frac{\vec{v}\times\vec{h}}{\mu} - \frac{\vec{r}}{r} \)
- 倾角：\( i = \arccos(h_z / h) \)
- 升交点赤经：\( \Omega = \arccos(n_x/n) \)，象限修正
- 近地点幅角：\( \omega = \arccos(\vec{n}\cdot\vec{e} / ne) \)，象限修正
- 平近点角：由真近点角经 Kepler 方程反推

- **API**：`POST /api/orbit/determine`

---

### 3.4 模拟轨道（默认加载）

| 轨道 | 类型 | 参数 | 周期 |
|------|------|------|------|
| 状态向量(仿真) | LEO 近地 | a≈7000km | ~1.5h |
| ISS(TLE仿真) | TLE-SGP4 | ISS 标准 TLE | ~1.5h |
| 广播星历(仿真) | GPS MEO | a=26560km, i=55° | ~12h |
| 精密星历(仿真) | Galileo MEO | a=29600km, i=56° | ~14h |

---

## 四、API 端点总览

| 方法 | 路径 | 功能 |
|------|------|------|
| GET | `/` | 前端页面 |
| GET | `/api/all` | 4 条预置模拟轨道 |
| GET | `/api/orbit/state_vector` | 单条仿真状态向量 |
| GET | `/api/orbit/tle` | 单条仿真 ISS-TLE |
| GET | `/api/orbit/broadcast` | 单条仿真广播星历 |
| GET | `/api/orbit/precise` | 单条仿真精密星历 |
| GET | `/api/orbit/kepler` | 六根数 → 轨道 |
| GET | `/api/orbit/state_vector_custom` | 高度+倾角 → 圆轨道 |
| POST | `/api/orbit/determine` | Gibbs 三点法轨道确定 |
| POST | `/api/upload/sp3` | 上传 SP3 文件 |
| POST | `/api/upload/rinex` | 上传 RINEX 文件 |
| POST | `/api/upload/tle` | 上传/粘贴 TLE |

## 五、颜色体系

每种数据源分配独立的 3 色调色板，跨类型绝不重复：

| 数据源 | 色系 | Cesium 颜色 | 前端标识 |
|--------|------|-------------|----------|
| SP3 精密星历 | 红 | `[255, 82, 82]` | ● `#ff5252` |
| RINEX 广播星历 | 绿 | `[105, 240, 174]` | ● `#69f0ae` |
| TLE | 橙 | `[255, 171, 64]` | ● `#ffab40` |
| 状态向量 (SV) | 青 | `[64, 196, 255]` | ● `#40c4ff` |
| Kepler 六根数 | 粉 | `[255, 128, 171]` | ● `#ff80ab` |
| IOD 观测反演 | 紫 | `[234, 128, 252]` | ● `#ea80fc` |

同类型多颗卫星在各自色系内循环（如 3 个 SP3 卫星分别为深红/正红/浅红）。

## 六、CZML 渲染机制

- **实体属性**：`position.cartesian`（多时刻）+ `path.material.solidColor` + `point`
- **时间控制**：
  - 文档级 `clock.interval` + `clock.currentTime`
  - 实体级 `availability` 时间区间
  - 路径 `path.show` 时间区间数组格式（非静态布尔值）
- **时间倍速**：`clock.multiplier = 60`

## 七、启动方式

```bash
# 安装依赖
pip install fastapi uvicorn numpy sgp4 python-multipart

# 启动服务（生产模式）
cd orbit_visualizer
python -m uvicorn main:app --host 0.0.0.0 --port 8000

# 或双击 run.bat（开发模式，含 --reload 热重载）
```

浏览器访问 `http://localhost:8000`

## 八、快速体验

首次打开页面后，系统已自动加载 4 条预置仿真轨道。也可以通过以下步骤快速体验各项功能：

| 功能 | 操作 | 测试数据 |
|------|------|----------|
| SP3 精密星历 | 左侧面板 → 📡 数据源导入 → 选择 `data/example.sp3` | 2 颗 GPS 卫星，12 小时 15 分钟步长 |
| RINEX 广播星历 | 左侧面板 → 📡 数据源导入 → 选择 `data/example.rnx` | 3 颗 GPS 卫星，24 小时 5 分钟步长 |
| 批量 TLE | 左侧面板 → 📡 数据源导入 → 选择 `data/example.tle` | ISS、Hubble、NOAA-19 三颗卫星 |
| TLE 粘贴 | 打开 `data/example.tle` 复制内容 → 粘贴到 TLE 文本框 → 点击「解析粘贴的 TLE」 | — |
| 轨道六根数 | 🛰️ 自定义轨道生成 → Kepler 区 → 点击「生成轨道」 | 默认：a=7000km, e=0.001, i=51.6° |
| 状态向量 | 🛰️ 自定义轨道生成 → 状态向量区 → 点击「生成轨道」 | 默认：高度 400km, 倾角 51.6° |
| IOD 轨道确定 | 🛰️ 自定义轨道生成 → IOD 区 → 粘贴 `data/example_iod.csv` 内容 → 点击「确定轨道」 | 5 个 LEO 观测点，Gibbs 三点法反演 |

> **提示**：每次导入/生成的数据会叠加显示，点「清空全部」可重置场景。

## 九、界面特性

- 毛玻璃半透明面板（`backdrop-filter: blur(20px)`）
- 两大可折叠分组：📡 数据源导入 / 🛰️ 自定义轨道生成
- 文件上传虚线区域 + 选择后显示文件名
- 实时状态反馈（加载中/成功/失败）
- IOD 拟合结果卡片展示（六根数完整输出）
- 一键盘"清空全部"（移除所有 DataSource + 重置状态）