# F-22 Cobra 机动研究记录 本文记录当前 JSBSim 眼镜蛇机动研究的现状、技术方案和已修改位置。范围覆盖 `service` 后端、`web-test` 前端、共享 schema，以及为 F-22 Cobra 研究复制出的本地飞机模型。 ## 目前现状 项目当前以 `web-test` 为前端、`service` 为后端，通过本地 HTTP API 调用 JSBSim 完成飞行动力学仿真。 当前默认研究对象是： - 前端 aircraftId: `f22cobra-jsbsim` - 后端 JSBSim model id: `f22cobra` - 模型文件: `service/aircraft/f22cobra/f22cobra.xml` - 后端服务: `http://127.0.0.1:4317` - 内部积分频率: `integrationRateHz = 120` - 输出采样频率: `sampleRateHz = 30` 当前 Cobra 默认参数是一个稳定的近似 Cobra 基线，而不是追求极限 120 度迎角的表演级参数： ```json { "aircraftId": "f22cobra-jsbsim", "durationSec": 5, "sampleRateHz": 30, "integrationRateHz": 120, "trim": false, "initialState": { "position": [0, 3000, 0], "velocityMps": 120, "headingDeg": 0 }, "maneuver": { "type": "cobra", "parameters": { "controlMode": "closed-loop", "entryDelaySec": 0.15, "pullDurationSec": 0.7, "holdDurationSec": 0, "recoveryDurationSec": 2.0, "targetAlphaDeg": 80, "recoveryAlphaDeg": 8, "pitchRateLimitDegS": 80, "holdPitchRateDegS": 0, "maxElevatorCmd": -0.45, "recoveryElevatorCmd": 0.65, "throttleCmd": 1, "pullTvcCmd": -0.05, "recoveryTvcCmd": 0.85, "speedbrakeCmd": 0 } } } ``` 在当前 F-22 模型和上述参数下，直接 JSBSim 验证的典型指标约为： - 峰值迎角 `maxAlpha`: 约 `71.9 deg` - 峰值俯仰角速度 `maxPitchRate`: 约 `122.9 deg/s` - 最低速度 `minSpeed`: 约 `106.4 m/s` - 5 秒末迎角 `endAlpha`: 约 `9.7 deg` - 5 秒末俯仰角 `endPitch`: 约 `31.0 deg` 这个状态的意义是：先获得可重复、能恢复、不会突然翻转的基线，再继续向更高 alpha 推进。 ## 技术方案 ### 1. 后端用 JSBSim 做 6DoF 积分 后端 `service/scripts/jsbsim_runner.py` 是 JSBSim 的 Python runner。Node 后端通过 `service/src/backends/jsbsimBackend.js` 调用该 runner。 关键点： - `sampleRateHz` 只控制返回给前端的采样密度。 - `integrationRateHz` 控制 JSBSim 内部积分步长，当前默认 120 Hz。 - 仿真过程中内部积分按 `integrationRateHz` 推进，输出样本按 `sampleRateHz` 抽样。 - F-22 研究默认 `trim: false`，因为 bundled F-22 在部分速度点纵向 trim 会失败，但直接 initial condition 可以运行。 ### 2. 用本地 F-22 研究模型打开 TVC 控制 原始 bundled F-22 的 TVC 链路不适合直接外部命令控制。当前复制出本地模型： ```text service/aircraft/f22cobra/f22cobra.xml ``` 并加入/改造： - `fcs/tvc-cmd-norm` - TVC actuator 输入改为外部命令。 - 输出仍写到 `fcs/tvc-pos-norm` / `fcs/tvc-pos-rad`，供 JSBSim 气动和遥测读取。 这样后端可以通过 `fcs/tvc-cmd-norm` 直接施加 TVC 指令。 ### 3. Cobra 从开环时间线升级为闭环控制器 早期 Cobra 使用固定时间线： ```text 某时刻 elevator = X, tvc = Y, throttle = Z ``` 这种开环方式容易出现： - 抬头过猛 - 俯仰角速度尖峰 - 高迎角后恢复不下来 - 轨迹出现不自然的旋转或深失速 现在 `cobra` 默认使用： ```json { "controlMode": "closed-loop" } ``` 闭环控制器每个积分步读取当前状态： - `aero/alpha-rad` - `attitude/theta-rad` - `velocities/q-rad_sec` - `velocities/vtrue-fps` 然后计算： - elevator command - TVC command - throttle command - speedbrake command 控制目标不是“固定时间点打多少杆”，而是： - 拉起阶段限制 pitch rate - 接近目标 alpha 时自动减小拉起 - 恢复阶段用 elevator + TVC 把 alpha 拉回低迎角 - 避免过快掉速和深失速 旧的开环 Cobra 仍保留： ```json { "controlMode": "open-loop" } ``` 这方便后续对比开环和闭环表现。 ### 4. 姿态输出改用四元数 前端之前使用 Euler/HPR 处理姿态，在接近 90 度俯仰时容易出现视觉上的突然翻转。 现在后端输出 body-to-local ENU 四元数： ```json "rotation": [x, y, z, w] ``` 前端播放时用 quaternion slerp 插值，Cesium 渲染也直接使用四元数路径。这避免了高俯仰角附近的 Euler 奇异跳变。 ### 5. 轨迹积分使用 JSBSim 地速分量 位置轨迹不再用 heading/pitch 自己推算水平位移，而是使用 JSBSim 输出的地球坐标速度： - `velocities/v-east-fps` - `velocities/v-north-fps` 这避免了姿态大幅变化时轨迹方向和机体方向互相污染。 ### 6. 前端加入 Cobra 参数面板和遥测面板 前端现在默认选中 `f22cobra-jsbsim` 和 `Cobra`。 Cobra 参数面板可以直接调： - `Target alpha` - `Pitch-rate cap` - `Pull time` - `Recovery time` - `Pull elevator` - `Recovery elevator` - `Pull TVC` - `Recovery TVC` 右侧遥测面板显示关键曲线和 summary，便于判断问题来源： - alpha - pitch - pitch rate - velocity - altitude delta - elevator command - TVC command - speedbrake command ## 修改的地方 ### service 后端 #### `service/scripts/jsbsim_runner.py` 主要改动： - 新增 `integrationRateHz` 支持，默认 120 Hz。 - 内部积分频率与输出采样频率解耦。 - 新增/扩展 `cobra` maneuver。 - 新增 `controlMode = closed-loop` 的 Cobra 控制器。 - 保留 `controlMode = open-loop` 的时间线控制。 - 控制输入支持： - elevator - aileron - rudder - throttle - tvc - speedbrake - 输出样本增加： - `alphaDeg` - `betaDeg` - `qbar` - `verticalSpeedMps` - `pitchRateDegS` - `rollRateDegS` - `yawRateDegS` - `controlInputs` - `controlSurfaces` - `fcs` - 姿态输出改为 ENU body quaternion。 - 本地位置积分改用 JSBSim east/north velocity。 #### `service/aircraft/f22cobra/f22cobra.xml` 主要改动： - 从 bundled JSBSim F-22 复制出项目本地研究模型。 - 模型名称改为 F-22 Cobra Research。 - 新增 `fcs/tvc-cmd-norm` property。 - TVC actuator 改为读取 `fcs/tvc-cmd-norm`。 - 保证外部控制能驱动 `fcs/tvc-pos-norm`。 #### `service/src/backends/jsbsimBackend.js` 主要改动： - 新增 `f22cobra-jsbsim` aircraft。 - 将 `integrationRateHz` 透传给 Python runner。 - `cobra` / `control-script` 加入 JSBSim 后端支持列表。 - F-22 研究机型标记为 high-alpha / TVC / no-trim experimental。 #### `service/src/backends/mockBackend.js` 主要改动： - mock backend 同步支持 `integrationRateHz`。 - mock 输出结构补齐部分 JSBSim 遥测字段。 - 支持 `control-script` / `cobra` 的视觉测试路径。 #### `service/src/simulator.test.js` 主要改动： - 增加对 `integrationRateHz = 120` 的断言。 - 增加 `control-script` / `cobra` 基础测试。 #### `service/scripts/sweep_f22_cobra.py` 主要作用： - 批量扫描 Cobra 参数组合。 - 计算 max alpha、max pitch、min speed、end alpha、end pitch、forward delta 等指标。 - 用 score 排序，辅助后续自动调参。 ### shared schema #### `shared/schemas/flight-sim-api.schema.json` 主要改动： - 新增 `integrationRateHz`。 - 新增 `trim`。 - maneuver enum 增加： - `control-script` - `cobra` - sample schema 增加遥测字段： - `qbar` - `verticalSpeedMps` - `pitchRateDegS` - `rollRateDegS` - `yawRateDegS` - `controlInputs` - `controlSurfaces` - `fcs` - Cobra 参数说明中记录 `controlMode=open-loop|closed-loop`。 ### web-test 前端 #### `web-test/src/api/simulationService.js` 主要改动： - 默认 aircraft 使用 F-22 Cobra research。 - 默认 `sampleRateHz = 30`。 - 默认 `integrationRateHz = 120`。 - F-22 research 默认 `trim = false`。 - Cobra 默认参数改为稳定闭环基线。 - 支持从前端 Cobra 参数面板覆盖默认参数。 - 参数进入请求前做范围 clamp。 #### `web-test/index.html` 主要改动： - 默认 maneuver 改为 Cobra。 - 默认 duration 改为 5 秒。 - 默认 speed 改为 120 m/s。 - 新增 Cobra Controller 参数面板。 - 新增遥测 canvas 面板。 #### `web-test/src/ui/controls.js` 主要改动： - 读取 Cobra 参数面板输入。 - `getValues()` 返回 `cobraParameters`。 - 非 Cobra 机动时隐藏 Cobra 参数区。 #### `web-test/src/ui/researchPanel.js` 主要作用： - 绘制 Cobra 遥测曲线。 - 输出 summary： - max alpha - max pitch - max pitch rate - min speed - end alpha - speedbrake 状态 #### `web-test/src/playback/trajectoryPlayer.js` 主要改动： - 使用四元数 slerp 插值姿态。 - 减少高俯仰角播放时的姿态跳变。 #### `web-test/src/renderer/cesiumScene.js` 主要改动： - 支持后端 quaternion rotation。 - Cesium aircraft orientation 从本地 ENU body quaternion 转换到世界坐标。 - 保留 HPR fallback。 #### `web-test/src/styles.css` 主要改动： - 增加 Cobra 参数面板样式。 - 增加遥测面板样式。 - 调整移动端布局。 ## 当前限制 1. 当前 F-22 XML 的高迎角 / 失速后气动可信度有限。 2. 目前稳定基线只能做到约 70-72 度 alpha，继续推高 alpha 容易进入深失速或恢复困难。 3. `speedbrakeCmd` 在该 F-22 模型中更像离散开关，部分小数指令不会有效展开。 4. 目前闭环控制器是工程研究用，不是完整真实 FCS。 5. 参数 sweep 还没有接入前端，只能通过脚本跑。 ## 下一步建议 1. 把 `sweep_f22_cobra.py` 接到 service API，支持前端一键 sweep。 2. 增加 Cobra 参数 preset： - stable baseline - high-alpha attempt - aggressive TVC recovery - open-loop comparison 3. 为机动研究抽象统一 controller 接口，后续复用到： - Herbst maneuver - Kulbit - J-turn - tailslide 4. 进一步寻找或构建更可信的高迎角/失速后 F-22、Su-27、F-16 MATV 等 JSBSim 模型。 5. 增加自动评分指标，把“像不像 Cobra”量化，而不是只靠视觉判断。