jsbsim-service/service/F22_COBRA_RESEARCH.md

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 度迎角的表演级参数：

{
  "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 链路不适合直接外部命令控制。当前复制出本地模型：

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 使用固定时间线：

某时刻 elevator = X, tvc = Y, throttle = Z

这种开环方式容易出现：

• 抬头过猛
• 俯仰角速度尖峰
• 高迎角后恢复不下来
• 轨迹出现不自然的旋转或深失速

现在 cobra 默认使用：

{ "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 仍保留：

{ "controlMode": "open-loop" }

这方便后续对比开环和闭环表现。

4. 姿态输出改用四元数

前端之前使用 Euler/HPR 处理姿态，在接近 90 度俯仰时容易出现视觉上的突然翻转。

现在后端输出 body-to-local ENU 四元数：

"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”量化，而不是只靠视觉判断。