# gnc-sim-enhanced

**Repository Path**: zd_g/gnc-sim-enhanced

## Basic Information

- **Project Name**: gnc-sim-enhanced
- **Description**: 基于 **Vite + TypeScript + Three.js + ECharts** 的卫星姿态确定与控制系统（GNC/ADCS）仿真平台。采用**完整 6 维误差状态扩展卡尔曼滤波（EKF）**融合星敏感器与陀螺仪测量，实时估计卫星三轴姿态与陀螺零偏，并提供三维可视化、实时曲线监控与 CSV 数据导出。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 12
- **Forks**: 6
- **Created**: 2026-08-05
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 姿态仿真, Threejs, ADCS, gnc

## README

# GNC 姿态仿真平台

基于 **Vite + TypeScript + Three.js + ECharts** 的卫星姿态确定与控制系统（GNC/ADCS）仿真平台。采用**完整 6 维误差状态扩展卡尔曼滤波（EKF）**融合星敏感器、陀螺仪、太阳敏感器与磁强计测量，实时估计卫星三轴姿态与陀螺零偏，并内置 PD 姿态控制闭环、轨道动力学、故障注入告警与蒙特卡洛统计分析。

界面采用**航天任务控制中心**设计语言：三栏任务控制台布局（顶栏全局状态 + 左侧 Tab 控制面板 + 中央 3D 可视化 + 右侧遥测告警 + 底部图表矩阵），Modern Dark 玻璃拟态主题，支持 1920×1080 单屏无滚动监控。

![姿态仿真](img/gnc.png)

![使用手册](img/books.png)

## ✨ 功能特性

### 姿态确定（EKF 滤波）

- **姿态运动学仿真**：Z-Y-X 欧拉角 → 四元数，RK4 四元数积分，支持任意初始姿态与三轴恒定角速度
- **星敏感器测量仿真**：在真实姿态四元数上叠加高斯小角度噪声，噪声强度可配置
- **陀螺仪测量仿真**：真实角速度 + 固定零偏 + 高斯噪声，零偏可在滤波中被在线估计
- **6 维误差状态 EKF**：状态量 = 3 姿态误差 + 3 陀螺零偏
  - 预测步：完整状态转移矩阵 F（含姿态误差动力学与零偏耦合），协方差传播 `P = F·P·Fᵀ + Q`
  - 更新步：星敏四元观测误差角作为量测，标准卡尔曼增益与 Joseph 稳定形式 `P = (I−KH)P(I−KH)ᵀ + KRKᵀ` 修正，保持协方差对称与非负方差

### 多传感器融合与故障注入

- **太阳敏感器模型**：由 UTC 历元计算低精度 ECI 日向矢量，本体系方向量测含半视场角（FOV）限制与可配置噪声
- **磁强计模型**：三轴磁强计，场强随轨道半径变化且偶极轴随地球自转的倾斜偶极子模型，量测单位为 T
- **多传感器融合 EKF**：在星敏 + 陀螺基础上扩展太阳敏/磁强计矢量观测，支持任意传感器组合参与滤波
- **传感器故障注入**：
  - 星敏：失效 / 卡死（指定姿态角）/ 跳变（指定幅度）
  - 陀螺：漂移增大（指定倍数）/ 失效
  - 太阳敏 / 磁强计：失效
- **执行器故障注入**：反作用轮停转 / 力矩偏差（输出 = `(1−e)·τ`，e 可配）
- **故障告警系统**：基于量测新息模值超阈值的新息检测，实时状态灯（正常/警告/严重）与滚动告警列表

### 姿态控制闭环

- **PD 姿态控制器**：基于四元数误差的 PD 控制律 `τ = −Kp·q_vec − Kd·ω_err`，Kp / Kd 可配置
- **三种控制模式**：
  - **三轴稳定**：将卫星稳定到指定目标 Roll / Pitch / Yaw
  - **机动模式**：支持目标姿态动态跟踪的大角度机动
  - **对日定向**：使本体系 +X 轴指向太阳方向
- **反作用轮模型**：三轴反作用轮，含力矩饱和、转速饱和与转速积分（动量管理），支持轮最大力矩/转速配置
- **磁力矩器模型**：简化地磁场偶极子模型与磁控制律 `m = (b×τ)/|b|²`，支持磁卸载
- **刚体姿态动力学**：主惯量模型 `I·ω̇ + ω×(I·ω) = τ`，RK4 角速度积分，并可叠加重力梯度力矩
- **执行器分配**：反作用轮 / 磁力矩器 / 理想执行器选择与力矩矢量叠加

### 轨道动力学与高级分析（阶段4）

- **轨道传播**：开普勒轨道根数初始化，RK4 传播二体引力，并可选 J2、分段指数大气阻力、太阳光压与圆柱地影
- **轨道可视化**：独立 3D 轨道视图（地球 + 轨道面 + 卫星运动），顶栏一键切换姿态/轨道视图
- **蒙特卡洛分析**：批量随机种子运行（1~500 次），统计**收敛概率**与**平均 RMSE Roll**，结果自动下载 CSV
- **敏感性分析**：对星敏噪声 / 陀螺噪声 / 陀螺零偏 / 太阳敏噪声 / 磁强计噪声做 0.5×~2× 因子扫描
- **数据回放**：加载 CSV / JSON 历史数据，0.05s 步进逐点回放时序曲线，无需重新仿真
- **多场景对比**：基准 / 低噪声(0.5×) / 高噪声(2×) 三场景并行运行，RMSE 汇总对比

### 可视化与数据

- **实时 3D 姿态可视化**：Three.js 卫星模型（本体 + 太阳能板 + 星敏 + 本体系坐标轴）+ 深空星空粒子背景，支持鼠标拖拽旋转、滚轮缩放
- **7 路实时曲线**：ECharts 深色主题时序图（数据窗口长度可配置，默认 1000 点）
  - RPY 姿态时序：实线真实 / 虚线星敏 / 橙色 EKF 滤波
  - 滤波误差曲线（真实 − EKF，°）
  - 角速度时序（rad/s）：真实 / 陀螺测量 / EKF 估计
  - EKF 协方差 P 对角元（log 坐标，方差）
  - 控制力矩时序（N·m）：PD 控制器三轴输出
  - 反作用轮转速（rad/s）
  - 姿态控制误差角（°）
- **18 项实时统计指标**：姿态误差 RMSE、陀螺零偏估计误差、EKF 收敛状态与收敛时间、P 对角元、控制误差角、控制力矩幅值、轮饱和状态与转速利用率等（蓝/琥珀/绿三组配色区分）
- **场景保存/加载**：完整仿真状态（参数 + 全部历史数据 + 告警）序列化为 JSON（v4，兼容 v3），一键保存/恢复复现实验
- **CSV 数据导出**：46 字段完整数据（姿态、误差、角速度、协方差、控制力矩、轮转速、误差角、目标姿态、轨道状态），可直接用于 MATLAB/Python 离线分析
- **中英文界面切换**：顶栏一键切换，全部界面文本与状态实时翻译
- **键盘快捷键**：`Space` 启停、`R` 重置、`E` 导出 CSV、`O` 切换姿态/轨道视图

## 🚀 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建（多页：主控制台 + 使用手册）
npm run build

# 预览生产构建
npm run preview
```

浏览器访问 Vite 输出的本地地址（默认 `http://localhost:5173`）即可打开平台；**系统使用手册**位于 `/manual.html`，也可点击顶栏"使用手册"按钮在新窗口打开。

## 🎮 使用说明

界面为三栏任务控制台布局，自上而下分为六个区域：


| 区域       | 位置     | 职责                                                                                    |
| ---------- | -------- | --------------------------------------------------------------------------------------- |
| 顶栏       | 顶部     | 视图切换（姿态/轨道）、开始/停止/重置、系统状态灯、告警指示灯、中英文切换、使用手册入口 |
| 控制面板   | 左栏     | 四个 Tab：仿真参数 / 控制闭环 / 传感器故障 / 轨道分析；底部为 CSV 导出与场景保存/加载   |
| 可视化区   | 中栏上部 | 3D 姿态/轨道视图，右上角 HUD 显示当前视图类型                                           |
| 统计面板   | 中栏下部 | 18 项实时统计指标                                                                       |
| 遥测与告警 | 右栏     | 真实姿态 / 星敏量测 / EKF 估计遥测值、轨道高度与速度、告警列表与计数                    |
| 图表矩阵   | 底部     | 7 张实时曲线图                                                                          |

### 仿真参数（Tab 1）

- 初始 Roll / Pitch / Yaw（°）：卫星初始姿态角（默认 15°/10°/20°）
- 角速度 ωx / ωy / ωz（°/s）：三轴真实角速度（默认 0/0/2）
- 星敏噪声 σ（°）、陀螺噪声 σ（°/s）、陀螺零偏 bx/by/bz（°/s）
- 仿真步长（s）：数值积分步长（默认 0.01）
- 数据窗口长度：图表保留点数（100~10000，默认 1000）

> 参数在**重置后生效**：修改参数 → 点击顶栏"重置"（或按 `R`）。

### 控制闭环（Tab 2）

- **启用姿态控制**：PD 闭环总开关（默认关闭）
- **反作用轮 / 磁力矩器**：执行机构使能
- **控制模式**：三轴稳定 / 机动模式 / 对日定向
- **PD 增益**：Kp=0.5、Kd=1.5（振荡时减小 Kp / 增大 Kd）
- **目标姿态**（°）、**惯量矩阵** Ix/Iy/Iz（kg·m²）、**轮最大力矩**（N·m）、**轮最大转速**（rad/s）

### 传感器与故障注入（Tab 3）

- **传感器配置**：太阳敏/磁强计使能、入 EKF 开关、噪声与视场角、告警阈值（新息，默认 0.05）
- **故障注入**：星敏（失效/卡死/跳变）、陀螺（漂移增大/失效）、太阳敏/磁强计（失效）、反作用轮（停转/力矩偏差）

### 轨道与分析（Tab 4）

- **轨道动力学**：启用轨道传播 + 六根数配置（默认 500 km 近地轨道）
- **环境与扰动**：UTC 历元、J2、大气阻力、太阳光压、重力梯度开关，以及质量、迎风/受光面积、Cd、Cr 参数
- **高级分析**：运行蒙特卡洛 / 敏感性分析 / 加载回放数据 / 多场景对比，结果自动下载 CSV

### 默认仿真条件


| 项目         | 默认值                                                  |
| ------------ | ------------------------------------------------------- |
| 仿真步长     | 0.01 s                                                  |
| 初始姿态     | Roll 15° / Pitch 10° / Yaw 20°                       |
| 角速度       | ωx=0 / ωy=0 / ωz=2 °/s（偏航可见）                  |
| 星敏噪声 σ  | 0.05°                                                  |
| 陀螺噪声 σ  | 0.008 °/s                                              |
| 陀螺真零偏   | 0.01 °/s（三轴）                                       |
| 数据窗口     | 1000 点                                                 |
| EKF 初值     | 姿态=真实姿态，零偏=0，P=0.001，Q 姿态 1e-7 / 零偏 1e-9 |
| 姿态控制     | 默认关闭                                                |
| 控制模式     | 三轴稳定                                                |
| PD 增益      | Kp=0.5，Kd=1.5                                          |
| 目标姿态     | 0° / 0° / 0°                                         |
| 惯量矩阵     | Ix=5 / Iy=4 / Iz=3 kg·m²                              |
| 反作用轮     | 最大力矩 0.1 N·m，最大转速 300 rad/s，默认启用         |
| 磁力矩器     | 默认关闭（最大磁矩 10 A·m²，磁卸载开启）              |
| 太阳敏感器   | 默认启用，噪声 0.5°，半视场角 60°                     |
| 磁强计       | 默认启用，噪声 1e-7 T                                   |
| 传感器入 EKF | 太阳敏 / 磁强计均默认启用                               |
| 故障注入     | 全部默认关闭                                            |
| 告警阈值     | 新息 0.05                                               |
| 轨道         | 默认关闭传播，a=6878 km / e=0.001 / i=97.5°            |
| 环境扰动     | J2 / 大气阻力 / 太阳光压 / 重力梯度默认开启；质量 100 kg，面积 1 m² |
| 蒙特卡洛     | 50 次 / 30s                                             |

## 📊 CSV 导出字段


| 分组               | 字段                                    |
| ------------------ | --------------------------------------- |
| 时间               | `time(s)`                               |
| 真实姿态 (°)      | `trueRoll, truePitch, trueYaw`          |
| 星敏测量 (°)      | `starRoll, starPitch, starYaw`          |
| EKF 估计 (°)      | `ekfRoll, ekfPitch, ekfYaw`             |
| 滤波误差 (°)      | `errRoll, errPitch, errYaw`             |
| 角速度 (rad/s)     | `omegaTrue/Gyro/Efk` × `X/Y/Z`         |
| 协方差 (rad²)     | `P_dthetaX/Y/Z`（姿态误差方差）         |
| 协方差 (rad²/s²) | `P_bx/by/bz`（陀螺零偏方差）            |
| 控制力矩 (N·m)    | `tauX, tauY, tauZ`（PD 控制器三轴输出） |
| 反作用轮 (rad/s)   | `wheelSpeedX/Y/Z`（三轴轮转速）         |
| 控制误差角 (rad)   | `errorAngle`（姿态误差角）              |
| 目标姿态 (°)      | `targetRoll, targetPitch, targetYaw`    |
| 轨道位置 (m)       | `orbitX, orbitY, orbitZ`                |
| 轨道速度 (m/s)     | `orbitVx, orbitVy, orbitVz`             |
| 轨道状态           | `orbitAlt(m), orbitSpeed(m/s)`          |

## 🏗️ 项目结构

```
├── index.html          # 主控制台页面（三栏任务控制台布局）
├── manual.html         # 系统使用手册页面（独立文档页）
├── vite.config.ts      # Vite 多页构建配置（index + manual）
├── src/
│   ├── main.ts         # 入口装配：仿真循环、事件绑定、快捷键、Tab 切换、i18n
│   ├── core/
│   │   ├── types.ts    # 共享类型定义（SimConfig / SimState / SimStats / SceneData）
│   │   ├── math.ts     # 四元数 / 欧拉角 / 矩阵 / RK4 积分工具
│   │   ├── noise.ts    # Box-Muller 高斯噪声生成
│   │   ├── orbit.ts    # 轨道动力学（开普勒根数 / 数值积分）
│   │   ├── environment.ts # 日向矢量 / 倾斜偶极地磁 / 重力梯度
│   │   └── sim.ts      # 仿真核心：状态创建 / 重置 / 步进 / CSV 导出
│   ├── sensors/
│   │   ├── starTracker.ts  # 星敏感器模型
│   │   ├── gyro.ts         # 陀螺仪模型
│   │   ├── sunSensor.ts    # 太阳敏感器模型（矢量量测 + FOV）
│   │   ├── magnetometer.ts # 磁强计模型（位置相关偶极场 + 矢量量测）
│   │   └── fault.ts        # 传感器/执行器故障注入
│   ├── ekf/
│   │   └── attitudeEKF.ts  # 6 维误差状态 EKF（预测 / 更新 / 多传感器融合）
│   ├── control/
│   │   ├── pdController.ts  # PD 姿态控制器（三种控制模式）
│   │   ├── reactionWheel.ts # 反作用轮模型（饱和 / 动量管理）
│   │   ├── magnetorquer.ts  # 磁力矩器模型（磁控 / 磁卸载）
│   │   ├── dynamics.ts      # 刚体姿态动力学（RK4 积分）
│   │   └── controlManager.ts# 控制管理器（模式切换 / 执行器分配）
│   ├── analysis/          # 阶段4：高级分析
│   │   ├── monteCarlo.ts  # 蒙特卡洛（收敛概率 / 平均 RMSE）
│   │   ├── sensitivity.ts # 参数敏感性扫描
│   │   ├── comparison.ts  # 多场景对比
│   │   └── replay.ts      # CSV / JSON 数据回放
│   ├── visual/
│   │   ├── threeView.ts    # Three.js 3D 姿态可视化（星空粒子）
│   │   ├── orbitView.ts    # 3D 轨道视图
│   │   └── charts.ts       # ECharts 实时曲线（7 图）
│   ├── i18n/
│   │   └── index.ts        # 中英文界面切换
│   ├── ui/
│   │   ├── panel.ts        # 控制面板 DOM 绑定与参数读写
│   │   ├── stats.ts        # 实时统计指标（18 项）
│   │   ├── scene.ts        # 场景保存 / 加载（JSON v4，兼容 v3）
│   │   └── alerts.ts       # 故障告警系统（新息检测 + 状态灯 + 列表）
│   └── css/
│       ├── style.css   # 设计令牌与组件基础样式（玻璃拟态）
│       ├── main.css    # 主控制台布局（三栏 + 图表矩阵）
│       └── manual.css  # 使用手册页样式
├── public/             # 静态资源（favicon 等）
└── package.json
```

## 🛠️ 技术栈


| 技术                                     | 用途                                         |
| ---------------------------------------- | -------------------------------------------- |
| [Vite](https://vitejs.dev/) + TypeScript | 工程化与类型安全（多页构建）                 |
| [Three.js](https://threejs.org/)         | 三维姿态/轨道可视化（WebGL + OrbitControls） |
| [ECharts](https://echarts.apache.org/)   | 实时时序曲线与协方差监控                     |
| [gl-matrix](https://glmatrix.net/)       | 四元数运算与矩阵数学                         |

## 🎨 设计主题

采用 **Modern Dark（星空白 + 发射蓝）** 航天任务控制中心风格，玻璃拟态面板 + 霓虹辉光 + JetBrains Mono 等宽数字仪表，深色固定主题与 3D 视图背景统一：


| 令牌 | 值                    | 用途                                   |
| ---- | --------------------- | -------------------------------------- |
| 背景 | `#0B0B10`             | 页面底色（深空黑）                     |
| 玻璃 | `rgba(20,22,31,0.72)` | 面板玻璃拟态背景（12px 圆角 + 内高光） |
| 主色 | `#3B82F6`             | 按钮、焦点、分段控制器、辉光           |
| 强调 | `#F59E0B`             | EKF 曲线、告警、导出按钮               |
| 弱化 | `#94A3B8`             | 标签、次级文字                         |
| 等宽 | JetBrains Mono        | 遥测数值、统计指标、kbd                |

## 📖 使用手册

系统内置完整使用手册（`/manual.html`，顶栏按钮新窗口打开），覆盖快速上手、界面导览、全部参数说明、故障注入模式、高级分析工具、告警系统解读与常见问题。

## ⚠️ 说明

- 本项目为教学/演示用途的姿态确定与控制仿真，阶段1（架构模块化）、阶段2（姿态控制闭环）、阶段3（多传感器融合 + 故障注入 + 告警）、阶段4（轨道动力学 + 蒙特卡洛 + 敏感性 + 回放 + 对比）均已完成
- 日向矢量使用低精度太阳平黄经近似；太阳敏仍假设安装在 +Z 轴，未建模星体/帆板自遮挡，不能替代任务星历
- 地磁场是位置相关的倾斜偶极子近似，不是 IGRF/WMM；大气密度、太阳光压和地影同样是教学级模型
- 惯量仅支持三个主轴分量，反作用轮默认采用三轴正交安装；尚未建模完整惯量积、任意轮系安装矩阵、柔性附件和液体晃动
- 传感器当前按统一仿真步长同步采样，尚未建模各设备独立采样率、时间戳抖动、链路时延和乱序
- 本项目不包含串口/CAN/SpaceWire/UDP 等星上硬件接口；接入真实遥测需单独的数据网关、时钟同步与坐标系适配层
- 故障检测基于量测新息模值超阈值（阈值可配置），属简化方案；真实系统常用残差平方加权（CUSUM / χ² 检验）
- 图表保留点数由「数据窗口长度」参数控制（默认 1000 点），CSV 导出包含全部历史数据
- 蒙特卡洛 / 敏感性分析为计算密集型任务，期间界面可能短暂卡顿，属正常现象
- 新场景文件版本为 v4，并向后兼容 v3；旧场景缺少的环境参数会使用当前默认值补齐
- 建议在 1920×1080 及以上分辨率全屏使用，以获得最佳单屏监控体验（窗口小于 1100px 或高度小于 860px 时自动降级为滚动布局）