trey-copeland/uavsim

# quadrotor-sim (`uavsim`) **软件在环 (SIL) 四旋翼 GNC** — 配置飞行器与任务，使用 **LQR**、级联 **PID** 或级联 **NDI** 实现闭环，运行 Monte Carlo，通过可选的 KF/MEKF 进行状态估计，并比较运行结果。具备作品集级别的分析报告（GitHub Pages 展示页）。非飞行关键软件。

_{Live portfolio showcase — controller × sensor matrix, Flight 3D, MC, envelope}

_{Live intercept dashboard — online G-6 pursue, MEKF, battery, plant MC · tutorial}

| | | |--|--| | **在线作品集展示** | **[trey-copeland.github.io/uavsim](https://trey-copeland.github.io/uavsim/)** | | **在线拦截仪表盘** | **[…/uavsim/intercept/](https://trey-copeland.github.io/uavsim/intercept/)** | | **安装** | Python 3.11+ · [uv](https://docs.astral.sh/uv/) · `uv sync --extra dev` | | **历史传承** | 对 **[quad_uav](https://github.com/trey-copeland/quad_uav)** (ME590 MATLAB) 的重新设计 — 并非逐行移植 | | **开源许可** | [MIT](LICENSE) | ## 功能 ### 模型与飞行器 - 非线性 **6-DoF** 刚体动力学（NED，body wrench） - **Euler**（默认）或 **unit-quaternion** 模型（`sim.attitude: quat`），通过可插拔的 [`DynamicsModel`](docs/developer/dynamics.md) 实现 - 可选的 **mixer + 一阶电机**（`sim.plant: motors`）— 控制分配使用臂长 / \(c_T,c_Q\) - 可选的 **aero**：机身阻力、螺旋桨 H-force、地面效应（`vehicle.aero`，默认关闭） - YAML 飞行器配置：质量、惯量、臂长、限制、推进系统、aero — [飞行器指南](docs/developer/vehicles.md) ### 制导 - **Hold** 和 **waypoint** 任务（interp / min-snap / auto） - 针对预设目标轨迹的 **在线拦截**（`intercept_pursue`，G-6 重规划）— [教程](docs/tutorials/01_online_intercept.md) - 可行性检查（偏航角速率、轨迹极限工况） - 由配置驱动的任务位于 `configs/missions/` 下 — [制导指南](docs/developer/guidance.md) ### 控制 - 基于线性化的 **LQR hover** 设计（传承的 Q/R 风格） - **LQG 路径**：在来自部分传感器的 KF 估计值上应用相同的 LQR - **PID 级联**与级联 **NDI**（非线性动态逆；真空刚体逆模型） - 控制/指标中的 **SO(3) 姿态误差**（非简单的 Euler 相减） - **跟踪包络**：跨 controller × sensor 组合的时间尺度扫描（包含理想的 NDI） - 运行时会写入 **SIL** `nominal/controller_artifact.yaml`（增益 / 配平，用于溯源和双向转换） - **TODO:** HIL / 可供目标平台使用的 **controller export**（固件交接、固定速率打包）— 尚未作为交接产品发布 — [控制指南](docs/developer/control.md) · [EXTENSIBILITY_TODO](docs/developer/EXTENSIBILITY_TODO.md) ### 估计（可选） - 回路中的观测器：plant → 含噪测量 → filter → controller - **`partial_raw`**：对测量通道的简单打包（其余置零）— 教学基线 - **`linear_kf`**（悬停 \(A,B\)）和 **`mekf`**（误差状态 / 乘法姿态） - 通道：`pos` / `att` / `vel` / `omega`，加上无 GPS 环境下的 **`body_vel`（光流代理）**、**`alt`**、`vel_xy` - 传感器方案：GPS+IMU、AHRS、**flow+altitude**、纯 IMU — 在 **LQR / PID / NDI** 中使用相同的矩阵 - 估计值记录为 `x_hat` — [估计指南](docs/developer/estimation.md) ### 研究、鲁棒性与系统工程 - 基于配置的 **`simulate` / `study`** pipeline，具有种子稳定的 Monte Carlo - 质量 / 惯量 / 机臂的 **参数散布**；分片 MC + Docker — [容器](docs/containers.md) - 版本化的 **运行目录**（指标、时间序列、清单、报告） ### 可视化与比较 - 交互式 **3D 飞行** 进度条、条形图、MC hist/CDF/sensitivity 网格 — [可视化](docs/viz.md) - **`compare`** 两个 SIL 运行目录（指标差异 + 路径叠加） - **React 作品集展示**（GitHub Pages）— 多任务设计审查平台 — [展示页](docs/showcase/README.md) ### 可扩展性（未来发展方向） - 多机型 / flexible / motors 待办事项 — [飞行器机型](docs/developer/airframes.md) · [EXTENSIBILITY_TODO](docs/developer/EXTENSIBILITY_TODO.md) - 架构与 HIL 接口预留 — [ARCHITECTURE](docs/ARCHITECTURE.md) ## CLI 概览 | 命令 | 用途 | |---------|---------| | `uavsim simulate` | 标称闭环 SIL 研究 | | `uavsim study` | 标称研究 + 可选的 Monte Carlo | | `uavsim report` | Markdown 报告 + 图表（可选的交互式 3D） | | `uavsim compare` | 对比两个 SIL 运行目录 | | `uavsim gallery` | 构建 React 结果展示页 | | `uavsim mc-shard` / `mc-merge` | 分片 MC worker | | `uavsim export-controller` | **仅限 SIL:** 从某次运行中重新导出 `controller_artifact.yaml`（非 HIL 交接） | | `uavsim hil` | HIL 会话存根（**TODO** / 核心 cycle 之后） | ``` uv run uavsim --help ``` ## 文档 ### 从这里开始 | 文档 | 作用 | |-----|------| | **[开发者中心](docs/developer/README.md)** | 如何扩展飞行器、控制、制导、动力学、估计模块 | | **[SPEC.md](SPEC.md)** | 产品范围、需求、验收标准 | | **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** | 包、数据流、SIL/HIL 接口 | | **[ROADMAP.md](ROADMAP.md)** | 阶段、里程碑、当前 / 下一步 / 远期规划 | | **[LIMITATIONS.md](docs/LIMITATIONS.md)** | 客观坦诚的说明（LQG 命名、传感器、NDI 真空逆模型） | ### 操作指南 | 文档 | 作用 | |-----|------| | [飞行器](docs/developer/vehicles.md) | YAML 飞行器参数与限制 | | [动力学](docs/developer/dynamics.md) | Euler/quat 模型、SO(3) 误差、`DynamicsModel` | | [控制](docs/developer/control.md) | LQR、PID、**NDI**、SIL artifacts；HIL 导出 TODO | | [制导](docs/developer/guidance.md) | 任务、waypoint、后端 | | [估计](docs/developer/estimation.md) | KF/MEKF、通道、`sim.observer` | | [机型](docs/developer/airframes.md) | 多机型愿景 + HIL 台架笔记 | | [扩展性待办](docs/developer/EXTENSIBILITY_TODO.md) | 当前可用功能与 TODO | | [可视化](docs/viz.md) | 报告图表包 (§11A) | | [展示页 / Pages](docs/showcase/README.md) | React demo 托管 + 研究矩阵 | | [教程](docs/tutorials/README.md) | 在线拦截 + 电池指南 | | [拦截演示](docs/demos/intercept/README.md) | 针对于 `/intercept/` 的 SPA + 导出包 | | [容器](docs/containers.md) | Docker + 分片 MC | ### 流程 | 文档 | 作用 | |-----|------| | [GROK.md](GROK.md) | 工作协议、测试、传承规则 | | [AGENTS.md](AGENTS.md) | Agent 入口 → `GROK.md` | ## 在线展示与 Demo **→ [打开在线展示页](https://trey-copeland.github.io/uavsim/)** · **[打开拦截仪表盘](https://trey-copeland.github.io/uavsim/intercept/)** | | 作品集展示 | 拦截仪表盘 | |--|--------------------|---------------------| | **预览** | [`docs/uavsim.gif`](docs/uavsim.gif)（见上方链接） | [`docs/demo-intercept.gif`](docs/demo-intercept.gif)（见上方链接） | | **在线访问** | [trey-copeland.github.io/uavsim](https://trey-copeland.github.io/uavsim/) | […/uavsim/intercept/](https://trey-copeland.github.io/uavsim/intercept/) | | **本地运行** | `python -m http.server 8765 --directory docs/showcase` | `python -m http.server 8765 --directory docs/demos/intercept` | | **源码** | [`docs/showcase/`](docs/showcase/) | [`docs/demos/intercept/`](docs/demos/intercept/) | | **操作指南** | [展示页 README](docs/showcase/README.md) | [教程](docs/tutorials/README.md) · [demo README](docs/demos/intercept/README.md) | | **Pages CI** | [`.github/workflows/pages-site.yml`](.github/workflows/pages-site.yml) 会同时发布 **两者** | 同左 | **展示页：** controller × sensor 矩阵、多任务极限压力测试、模型保真度、**LQR / PID / NDI**、包络线、Monte Carlo — 飞行 3D · 系统 · 指标 · 包络线 · 对比。 **拦截：** 垫子爬升 + GE、**在线** `intercept_pursue`、MEKF、电池 SOC、模型 Monte Carlo 云图 — [T-GUIDE-ONLINE](docs/tutorials/01_online_intercept.md)。 ## 快速开始 要求安装 [uv](https://docs.astral.sh/uv/) 和 Python 3.11+。 ``` uv sync --extra dev uv run pre-commit install # once per clone: ruff lint+format on commit uv run uavsim --help uv run pytest uv run ruff check src tests ``` ### 代表性研究 ``` # 理想 full-state 定律 uv run uavsim simulate configs/studies/figure_eight.yaml # LQR uv run uavsim simulate configs/studies/figure_eight_pid.yaml # PID uv run uavsim simulate configs/studies/figure_eight_ndi.yaml # NDI # 估计 (LQG = KF + LQR) uv run uavsim simulate configs/studies/figure_eight_gps_imu_lqg.yaml uv run uavsim simulate configs/studies/figure_eight_gps_imu_naive.yaml uv run uavsim simulate configs/studies/figure_eight_flow_alt_lqg.yaml # Hi-fi plant / 激进的三定律比较 uv run uavsim simulate configs/studies/figure_eight_motors.yaml uv run uavsim simulate configs/studies/law_compare_hifi_ndi.yaml # Monte Carlo (小 N 用于快速循环) uv run uavsim study configs/studies/hover_mc_smoke.yaml uv run uavsim study configs/studies/figure_eight_mc.yaml --n-trials 20 uv run uavsim report runs/_/ --interactive # 比较两次 SIL 运行 uv run uavsim compare runs/ runs/ --figures # 作品集展示 (MC 默认 N≈200 — 较慢；使用 --n-mc-trials 8 进行 smoke) uv run uavsim gallery --base-case python -m http.server 8765 --directory docs/showcase ``` 更多 study YAML 位于 [`configs/studies/`](configs/studies/) 目录下。Artifacts 会生成在 `runs/_/` 中（已被 gitignore）：包含指标、时间序列、可选的 MC 表格、报告。可视化扩展依赖：`uv sync --extra viz` (matplotlib + plotly)。容器相关信息：[docs/containers.md](docs/containers.md)。 ## 历史传承 先前的实现与领域参考：**[quad_uav](https://github.com/trey-copeland/quad_uav)** (ME590 四旋翼 GNC，MATLAB)。本项目是对其的 **全面重新设计**（包括架构、Python 打包、研究 pipeline、可视化、估计、多定律作品集）。运行时**不**依赖于 MATLAB，也不依赖该历史代码库。 ## 开源许可 [MIT](LICENSE)

标签：导航制导与控制, 控制系统, 无人机仿真, 蒙特卡洛模拟, 请求拦截, 软件在环, 逆向工具, 飞行动力学