drone-camera 0.0.0-stage → 0.1.2

package/lib/drone-sim.d.ts

@@ -0,0 +1,883 @@
+/**
+ * DJI Mini 4 Pro 飞行仿真内核。
+ *
+ * 这里只做"飞控 + 电池 + 定位"的确定性逻辑,不引用 three,方便单独调参与验证:
+ * - 状态机对齐真机流程:上电自检 → 传感器预热 → 地面待机(搜星) → 电机启动 → 自动起飞 →
+ *   手动飞行 → 智能返航 / 自动降落 → 停桨;另含遥控失联失效保护、低电量返航。
+ *   ⚠️ 紧急停桨只在飞行器**落地后**可用(空中停桨会坠机,按需求禁用;空中调用会被拒绝并写警告日志);
+ *   空中"动力丧失"状态仅由电池耗尽等真实故障触发。
+ * - 摇杆在 GPS / 视觉定位下是"速度指令":松杆由飞控刹停并定点悬停;姿态模式下不保持位置,随风漂移。
+ * - 电池按 18.96 Wh 真实容量与分项功耗积分(悬停 33 W → 约 34 分钟,与官方标称一致),
+ *   低电量返航 / 严重低电量强制降落按百分比触发。
+ * - 风按"空气速度 = 指令 − 风"建模:逆风顶得住就顶,顶不住(超过该档最大空速)才被吹跑。
+ *
+ * 坐标约定:+X 东、-Z 北、+Y 上(与模型一致,机头朝 -Z),航向 0° = 正北。
+ */
+/** 机型公开规格(Mini 4 Pro) */
+export declare const DRONE_SPEC: {
+    readonly name: "DJI Mini 4 Pro";
+    readonly weightKg: 0.249;
+    readonly batteryWh: 18.96;
+    readonly batteryNominalVoltage: 7.32;
+    readonly batteryFullVoltage: 8.4;
+    readonly batteryEmptyVoltage: 6.9;
+    readonly batteryInternalResistance: 0.09;
+    readonly maxWindResistance: 10.7;
+    readonly hoverPowerWatts: 33;
+    readonly idlePowerWatts: 1.6;
+    readonly climbWattsPerMps: 3.6;
+    readonly levelSpeedPowerGain: 0.55;
+    readonly maxFlightTimeMin: 34;
+    readonly takeoffAltitude: 1.2;
+    readonly rthAltitudeDefault: 20;
+    readonly landingSlowAltitude: 2;
+    readonly gimbalPitchMin: -90;
+    readonly gimbalPitchMax: 60;
+    readonly gimbalYawRange: 5;
+};
+/** 飞行挡位:平稳 C / 普通 N / 运动 S */
+export type FlightMode = 'cine' | 'normal' | 'sport';
+/** 单个挡位的性能参数:限速(水平/升降)、姿态倾角与加减速、偏航角速度 */
+export interface ModeSpec {
+    label: string;
+    horizontalSpeed: number;
+    climbSpeed: number;
+    descendSpeed: number;
+    maxTiltDeg: number;
+    accel: number;
+    brakeAccel: number;
+    yawRateDeg: number;
+}
+/** N / S / C 三档飞行模式(对齐 DJI 飞行挡位参数) */
+export declare const FLIGHT_MODES: Record<FlightMode, ModeSpec>;
+/** 挡位列表(供下拉框渲染的稳定顺序) */
+export declare const FLIGHT_MODE_LIST: Array<{
+    key: FlightMode;
+    label: string;
+}>;
+/** 飞行速度倍率的取值区间(与面板滑杆一致):数值**本身**就是倍数,0 = 冻结、1 = 真机原速 */
+export declare const SPEED_SCALE_MIN = 0;
+export declare const SPEED_SCALE_MAX = 1000;
+/** 速度倍率缺省值:1 = 真机原速 */
+export declare const DEFAULT_SPEED_SCALE = 1;
+/**
+ * 机身**原地自转**的默认角速度(度/秒)。
+ *
+ * 这是给"机体自己转"用的独立通道(见 `DroneSim.spinTo`):全景扫描的水平覆盖
+ * 必须靠它,靠不了云台 —— Mini 4 Pro 云台 Pan 机械行程只有 ±30°
+ * (`DRONE_SPEC.gimbalYawRange`),转不出 180°。90°/s 对齐真机全景的转速手感。
+ */
+export declare const BODY_SPIN_RATE_DEG = 90;
+/** 判定"机身自转已对准目标航向"的容差(度):1 帧的转角远大于它,但航向是连续量 */
+export declare const BODY_SPIN_TOLERANCE_DEG = 0.5;
+/** 飞行阶段:上电自检 → 预热 → 待机 → 起飞 → 飞行/航线 → 返航/降落 → 停桨/失效 */
+export type FlightPhase = 'powerOff' | 'selfCheck' | 'warmingUp' | 'standby' | 'motorsOn' | 'takingOff' | 'flying' | 'waypoint' | 'rth' | 'landing' | 'emergency' | 'stopped';
+/** 阶段的中文标签(界面显示用) */
+export declare const PHASE_LABELS: Record<FlightPhase, string>;
+/** 定位来源:GNSS / 视觉 / 姿态模式(无定位) */
+export type PositionSource = 'gps' | 'vision' | 'atti';
+/** 定位来源的中文标签 */
+export declare const POSITION_SOURCE_LABELS: Record<PositionSource, string>;
+/** 四通道摇杆量,每通道取值 -1~1(松杆为 0) */
+export interface StickState {
+    /** 左杆上下:升降 -1~1(正 = 上升) */
+    throttle: number;
+    /** 左杆左右:偏航 -1~1(正 = 右转) */
+    yaw: number;
+    /** 右杆上下:俯仰 -1~1(正 = 前进) */
+    pitch: number;
+    /** 右杆左右:横滚 -1~1(正 = 右移) */
+    roll: number;
+}
+/** 摇杆回中(全零) */
+export declare const NEUTRAL_STICK: StickState;
+/** 四个电机对应的机臂位置(与 DroneRig 的 ArmPosition 一致,模型节点名同款后缀) */
+export type MotorPosition = 'FrontLeft' | 'FrontRight' | 'RearLeft' | 'RearRight';
+/** 四机臂的固定遍历顺序 */
+export declare const MOTOR_POSITIONS: MotorPosition[];
+/** 故障注入:测试沙盒里用来复现各种真机异常 */
+export interface FaultFlags {
+    /** GNSS 卫星丢失(强制进入视觉/姿态模式) */
+    gnssLost: boolean;
+    /** 指南针受扰(需要校准,否则姿态模式) */
+    compassError: boolean;
+    /** IMU 异常(禁止起飞) */
+    imuError: boolean;
+    /** 电机异常:1 个电机动力衰减,导致偏航漂移 */
+    motorFailure: boolean;
+    /** 遥控器失联(3 秒后触发失效返航) */
+    rcLost: boolean;
+    /** 下视视觉失效(低空无法视觉定位) */
+    visionLost: boolean;
+    /** 避障传感器关闭 */
+    obstacleAvoidanceOff: boolean;
+}
+/** 全部故障关闭(正常飞行) */
+export declare const NO_FAULTS: FaultFlags;
+/** 沙盒可调参数(限高限距、风、电量阈值、失效动作、时间倍速) */
+export interface SimConfig {
+    /** 限高(AGL,米) */
+    maxAltitude: number;
+    /** 限距(米) */
+    maxDistance: number;
+    /**
+     * 取消高度与距离限制(演示 / 取景用),默认 `false`。
+     *
+     * `true` 时 `maxAltitude` / `maxDistance` 不再参与任何夹紧:
+     * 摇杆升降与水平位移不被截断、航点不被夹回限高面/限距圆、航线校验不再拦超限航点,
+     * 面板通过 `getLimits()` 拿到的高度/距离上限变成 `Infinity`。
+     *
+     * 改回 `false` 时若机体已在限制之外,下一帧就会被夹回边界(高度落到 `maxAltitude`,
+     * 位置沿返航点方向缩到 `maxDistance` 圆上),所以这不是"一次性开关"。
+     *
+     * ⚠️ 只放开**限高 / 限距**这两条人为上限:电池、姿态、避障、GNSS 等物理与失效约束照旧生效。
+     */
+    unlimitedFlight: boolean;
+    /** 返航高度(米) */
+    rthAltitude: number;
+    /** 风速 m/s */
+    windSpeed: number;
+    /** 风"吹向"的罗盘方位角(0=北,90=东) */
+    windDirection: number;
+    /** 低电量返航阈值 % */
+    lowBatteryPercent: number;
+    /** 严重低电量阈值 % */
+    criticalBatteryPercent: number;
+    /** 失效保护:遥控失联后的动作 */
+    rcFailsafe: 'rth' | 'hover' | 'land';
+    /** 时间倍速(1 = 实时) */
+    timeScale: number;
+    /**
+     * 飞行速度倍率(0 ~ 1000,数值本身就是倍数;1 = 真机原速)。
+     *
+     * 与 `timeScale` 不是一回事:时间倍速是"整个仿真跑快"(电池、自检、悬停计时一起加速),
+     * 而速度倍率**只改机体自己的运动能力**,相当于换了一台"几倍速"的机器 ——
+     * 手动摇杆速度、航线巡航速度、智能返航速度、起降速率与转向角速度整体乘这个系数,
+     * 挡位表、加速度配平、倾角标定都跟着等比缩放(满舵仍是该挡位的最大倾角)。
+     * 0 = 全部速度为 0(机体不动,连自动起飞/降落也会停住)。
+     */
+    speedScale: number;
+    /** 上电自检时长(秒):默认 0.3,整个上电流程控制在 1 秒内 */
+    selfCheckSeconds: number;
+    /** 传感器预热时长(秒):默认 0.28 */
+    warmupSeconds: number;
+    /** 搜星速率(颗/秒):默认 30,上电后约 0.6 秒即达满星 */
+    gnssAcquireRate: number;
+}
+/** 出厂默认参数:限高 120 m(合规上限)、限距 500 m、限高限距生效、无风、实时 */
+export declare const DEFAULT_CONFIG: SimConfig;
+/**
+ * 单个航点(对齐真机航点任务的字段子集)。
+ *
+ * 坐标与遥测同一套约定:x 向东、z 向南(与模型坐标一致),altitude 是**相对起飞点高度(AGL)**。
+ */
+export interface MissionWaypoint {
+    x: number;
+    z: number;
+    /** 目标高度(AGL,米) */
+    altitude: number;
+    /** 过点速度(m/s);0 = 使用任务巡航速度 */
+    speed: number;
+    /** 到点悬停时间(秒);0 = 不停留,直接飞下一个点 */
+    hoverSeconds: number;
+    /** 到点后云台俯仰角(度);null = 不动云台 */
+    gimbalPitch: number | null;
+    /** 到点动作 */
+    action: 'none' | 'photo';
+}
+/** 机头朝向策略:auto = 始终机头指向下一航点;fixed = 保持任务开始时的航向 */
+export type MissionHeadingMode = 'auto' | 'fixed';
+/** 过点方式:straight = 到点减速后再走;curved = 圆滑过点(不减速) */
+export type MissionPathMode = 'straight' | 'curved';
+/** 任务结束动作,对齐真机 WaypointMissionFinishedAction */
+export type MissionFinishAction = 'hover' | 'rth' | 'land';
+/** 航线任务的全局设置 */
+export interface MissionConfig {
+    /** 巡航速度(m/s):航点未单独指定速度时用它 */
+    autoSpeed: number;
+    headingMode: MissionHeadingMode;
+    pathMode: MissionPathMode;
+    /** 全部航点完成后 */
+    finishAction: MissionFinishAction;
+    /** 循环执行:完成后回到第一个航点继续 */
+    loop: boolean;
+}
+/** 任务状态:未执行 / 执行中 / 已暂停 */
+export type MissionStatus = 'idle' | 'running' | 'paused';
+/** 任务状态的中文标签 */
+export declare const MISSION_STATUS_LABELS: Record<MissionStatus, string>;
+/** 任务阶段的中文标签 */
+export declare const MISSION_STAGE_LABELS: Record<MissionStage, string>;
+/**
+ * 任务执行阶段。
+ *
+ * 飞第一个航点前有一段「启航四步」,和智能返航同款的分段机动:
+ * 先把高度调到首航点高度(**垂直段只动高度,不产生水平位移**,否则会斜着冲过去) →
+ * 再保持该高度水平飞向首航点 → 到了把高度收干净 → 最后原地把机头转到与航线一致,
+ * 之后才进入常规的 goto / hover 推进。
+ */
+export type MissionStage = 'idle' | 'depart-climb' | 'depart-cruise' | 'depart-settle' | 'depart-align' | 'goto' | 'hover';
+/** 是否为「启航段」阶段(首航点的分段机动) */
+export declare function isMissionDepartStage(stage: MissionStage): boolean;
+/** 出厂默认任务设置:巡航 6 m/s、机头自动指向下一航点、直线过点、完成后悬停 */
+export declare const DEFAULT_MISSION_CONFIG: MissionConfig;
+/** 出厂示例航线:环绕起飞点一圈(最高 40 m,悬在 13 m 的建筑之上,不会触发避障刹停) */
+export declare const DEFAULT_MISSION: MissionWaypoint[];
+/**
+ * 航点高度的**硬上限**(米)。
+ *
+ * 与 `SimConfig.maxAltitude`(可配置的限高)不是一回事:它是字段归一化的护栏,
+ * 挡住外部灌进来的离谱值(比如 1e9),默认 500 m 就已高于合规限高。
+ * `unlimitedFlight` 打开时内部会传 `Infinity` 把它一起放开。
+ */
+export declare const MISSION_ALTITUDE_HARD_LIMIT = 500;
+/**
+ * 单个航点字段归一化(手输/外部传入都可能越界)。
+ *
+ * @param maxAltitude 高度上限,默认 {@link MISSION_ALTITUDE_HARD_LIMIT};取消限高时传 `Infinity`
+ */
+export declare function normalizeMissionWaypoint(source: Partial<MissionWaypoint>, maxAltitude?: number): MissionWaypoint;
+/** 航线导出格式 */
+export type MissionExportFormat = 'json' | 'csv';
+/**
+ * 航线导出数据(JSON 形态)。
+ *
+ * 坐标系沿用引擎内部的**局部 ENU**:原点为返航点(起飞点),x 向东、z 向南(负值即向北),
+ * 单位米;高度为相对起飞点的 AGL。与面板列表里的 `E x / S z` 读数完全一致 ——
+ * 想落到真实经纬度,由宿主拿到 home 的真实经纬度后自行平移。
+ */
+export interface MissionExport {
+    /** 文件标识,便于导入方识别 */
+    format: 'drone-camera/mission';
+    version: number;
+    /** 导出时刻(ISO 8601) */
+    exportedAt: string;
+    /** 坐标约定说明(写进文件,换个工具打开也不至于误读) */
+    frame: {
+        origin: string;
+        unit: string;
+        x: string;
+        z: string;
+        altitude: string;
+    };
+    /** 返航点(局部坐标原点) */
+    home: {
+        x: number;
+        z: number;
+    };
+    /** 任务参数 */
+    config: MissionConfig;
+    /** 概览统计:点数 / 航程 / 预计耗时 / 高度范围 */
+    summary: {
+        points: number;
+        distance: number;
+        duration: number;
+        altitudeMin: number;
+        altitudeMax: number;
+    };
+    waypoints: MissionWaypoint[];
+}
+/**
+ * 由「航点 + 任务参数 + 返航点」组出导出数据(纯函数,两套渲染后端共用)。
+ *
+ * 航程按"返航点起飞 → 依次过点"的三维折线累计,耗时按每点自己的速度(0 = 巡航速度)
+ * 加上到点悬停折算,和引擎执行时的口径一致。
+ */
+export declare function buildMissionExport(waypoints: MissionWaypoint[], config: MissionConfig, home: {
+    x: number;
+    z: number;
+}): MissionExport;
+/** 航点表 → CSV(不含 BOM;落盘时由调用方按需添加) */
+export declare function missionToCsv(waypoints: MissionWaypoint[]): string;
+/**
+ * 导出航线文本。`json` 是完整存档(含坐标约定、任务参数、概览统计,可再喂回 `setMission`),
+ * `csv` 只出航点表 —— 表头中文、CRLF 换行,Excel / WPS 双击即可打开。
+ */
+export declare function exportMissionText(data: MissionExport, format?: MissionExportFormat): string;
+/**
+ * 新航点插到哪个位置:取"绕路最少"的那一格(three / Cesium 两个场景内编辑器共用)。
+ *
+ * 判据是插入后航线增加的长度(prev→新点→next 减去原来的 prev→next),
+ * 而不是"离哪一段最近" —— 后者在等距处会出现平手,可能把一个明明贴着前面航段的点
+ * 插到后面去,航线就绕了。最小绕路法天然没有这个歧义。
+ */
+export declare function findMissionInsertIndex(list: MissionWaypoint[], x: number, z: number, homeX: number, homeZ: number): number;
+/** 航线任务的实时进度(界面轮询用) */
+export interface MissionSnapshot {
+    status: MissionStatus;
+    statusLabel: string;
+    stage: MissionStage;
+    stageLabel: string;
+    /** 当前目标航点索引(0 基);-1 = 无 */
+    index: number;
+    total: number;
+    /** 已完成的整圈数 */
+    passes: number;
+    /** 任务已执行时长(秒) */
+    elapsed: number;
+    /** 剩余航程(米,含高度差) */
+    distanceLeft: number;
+    /** 按航程折算的完成度 0~1 */
+    progress: number;
+    /** 预计剩余时间(秒,含悬停) */
+    etaSeconds: number;
+    /** 暂停原因 */
+    pauseReason: string;
+    /** 当前目标航点副本 */
+    active: MissionWaypoint | null;
+    /** 航线航点列表副本(界面据此渲染) */
+    waypoints: MissionWaypoint[];
+    config: MissionConfig;
+}
+/** 事件日志级别 */
+export type EventLevel = 'info' | 'warn' | 'error' | 'success';
+/** 一条事件日志 */
+export interface SimEvent {
+    id: number;
+    time: number;
+    level: EventLevel;
+    text: string;
+}
+/** 轴对齐包围盒(AABB)障碍物,坐标与飞行位置同一套约定 */
+export interface ObstacleBox {
+    name: string;
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    minZ: number;
+    maxZ: number;
+    /** 是否需要绕开(否则只是地面建筑,飞过去即可) */
+    solid: boolean;
+}
+/** 当前帧的避障探测结果(机身坐标系六向) */
+export interface ObstacleReport {
+    /** 六个方向的最近距离(米),null 表示该方向无障碍 */
+    forward: number | null;
+    backward: number | null;
+    left: number | null;
+    right: number | null;
+    up: number | null;
+    down: number | null;
+    /** 本帧是否因避障刹停 */
+    braking: boolean;
+    /** 触发方向 */
+    brakingDirection: 'forward' | 'backward' | 'left' | 'right' | 'up' | 'down' | null;
+}
+/** 起飞前检查项 */
+export interface ChecklistItem {
+    id: string;
+    label: string;
+    ok: boolean;
+    detail: string;
+    /** 不通过是否阻止起飞 */
+    blocking: boolean;
+}
+/** 单向快照:界面/回放读取的全部遥测字段(数组字段已复制,改它不影响仿真) */
+export interface DroneSnapshot {
+    phase: FlightPhase;
+    phaseLabel: string;
+    mode: FlightMode;
+    modeLabel: string;
+    /** 当前生效的飞行速度倍率(0 ~ 1000,1 = 真机原速;见 SimConfig.speedScale) */
+    speedScale: number;
+    positionSource: PositionSource;
+    positionSourceLabel: string;
+    airborne: boolean;
+    motorsOn: boolean;
+    damaged: boolean;
+    batteryPercent: number;
+    batteryVoltage: number;
+    batteryCurrent: number;
+    batteryTemp: number;
+    batteryWhLeft: number;
+    batteryModeText: string;
+    altitude: number;
+    altitudeMax: number;
+    /** 相对起飞点的水平坐标:x 向东,z 向南(与模型坐标一致) */
+    positionX: number;
+    positionZ: number;
+    horizontalSpeed: number;
+    verticalSpeed: number;
+    heading: number;
+    tiltPitch: number;
+    tiltRoll: number;
+    distanceToHome: number;
+    homeRecorded: boolean;
+    altitudeLimitReached: boolean;
+    distanceLimitReached: boolean;
+    satellites: number;
+    hdop: number;
+    gpsBars: number;
+    rcBars: number;
+    visionAvailable: boolean;
+    gimbalPitch: number;
+    gimbalRoll: number;
+    gimbalYaw: number;
+    motorLoad: number;
+    /** 四电机归一化转速(悬停 ≈ 1):混控差动的读数口,面板/调试可视化用 */
+    motorSpeeds: Record<MotorPosition, number>;
+    armFold: number;
+    stick: StickState;
+    windSpeed: number;
+    windDirection: number;
+    windRelative: string;
+    flightTime: number;
+    totalTime: number;
+    remainingMinutes: number;
+    lowBattery: boolean;
+    criticalBattery: boolean;
+    lowBatteryCountdown: number;
+    rthStage: string;
+    /** 自动降落的细分阶段:approach=降向低位悬停位 / hold=低位悬停确认 / settle=缓慢触地 */
+    landingStage: string;
+    rthReason: string;
+    warnings: string[];
+    events: SimEvent[];
+    checklist: ChecklistItem[];
+    obstacle: ObstacleReport;
+    recording: boolean;
+    recordSeconds: number;
+    photoCount: number;
+    cameraZoom: number;
+    /** 航线任务进度 */
+    mission: MissionSnapshot;
+}
+/**
+ * 飞控仿真内核(不依赖 three)。
+ *
+ * 持有全部飞行状态与可调参数:`step(dt)` 按时间片推进状态机、飞行、电池与失效保护;
+ * 外部通过 getter / `snapshot()` 只读遥测,通过 powerOn / autoTakeOff / setStick / startMission 等下达指令。
+ * 状态字段虽为 public,但正常路径应只经 step 与上述方法修改。
+ */
+export declare class DroneSim {
+    config: SimConfig;
+    faults: FaultFlags;
+    obstacles: ObstacleBox[];
+    phase: FlightPhase;
+    mode: FlightMode;
+    /** 位置:y 为相对起飞点的高度(AGL),x/z 为水平偏移 */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    heading: number;
+    tiltPitch: number;
+    tiltRoll: number;
+    motorLoad: number;
+    /**
+     * 四电机归一化转速(悬停 ≈ 1.0,0 = 停转):由四旋翼混控得出 ——
+     * 总距(整体升力)+ 俯仰差动(前后)+ 横滚差动(左右)+ 偏航反扭矩差动(对角)。
+     * 真四旋翼正是靠这四路差动打破/恢复升力平衡来实现全姿态控制的,
+     * 渲染层按它给每个桨叶单独转速,不再四桨同速。
+     */
+    motorSpeeds: Record<MotorPosition, number>;
+    armFold: number;
+    damaged: boolean;
+    stick: StickState;
+    /** 外部(模型侧)提供的检查项,例如机臂是否展开 */
+    externalChecks: ChecklistItem[];
+    /** 相机状态 */
+    recording: boolean;
+    recordSeconds: number;
+    photoCount: number;
+    cameraZoom: number;
+    gimbalPitch: number;
+    gimbalRoll: number;
+    gimbalYaw: number;
+    /** 航线任务:航点列表(出厂带一条示例航线,方便一键演示) */
+    mission: MissionWaypoint[];
+    missionConfig: MissionConfig;
+    missionStatus: MissionStatus;
+    /** 当前目标航点索引(0 基),-1 表示没有在执行的航点 */
+    missionIndex: number;
+    /** 当前任务阶段(未执行任务时为 'idle') */
+    missionStage: MissionStage;
+    events: SimEvent[];
+    private time;
+    private phaseTime;
+    private flightTime;
+    /** 本步机身系加速度(米/秒²,由速度差分得出):倾角模型与混控都要用 */
+    private accelX;
+    private accelZ;
+    /** 倾角目标(度):mixer 用"目标 − 当前"衡量飞控正在多用力压杆 */
+    private tiltPitchTarget;
+    private tiltRollTarget;
+    /** 偏航角速度实际值(度/秒,一阶惯性):机身有转动惯量,转速建立/消失都需要时间 */
+    private yawRateCurrent;
+    /**
+     * 机身原地自转的目标方位角(度,绝对罗盘角);null = 没有在自转。
+     * 优先级高于摇杆偏航 —— 真机拍全景时偏航通道由飞控接管,人打杆不参与。
+     */
+    private spinHeading;
+    private spinRateDeg;
+    private batteryUsedWh;
+    private batteryTemp;
+    private satellites;
+    private visionAvailable;
+    private rcLinkQuality;
+    private rcLostTimer;
+    private lowBatteryCountdown;
+    private rthStage;
+    private rthReason;
+    private rthStickGrace;
+    private home;
+    private homeRecorded;
+    private altitudeMax;
+    private altitudeLimitReached;
+    private distanceLimitReached;
+    private obstacleReport;
+    private eventId;
+    private readonly warnedAt;
+    private landingTimer;
+    /** 降落细分阶段:先降向 1 米悬停位,停一下再缓速触地 */
+    private landingStage;
+    private landingHoldTimer;
+    /** 航线任务:已下发但等起飞完成后才开始执行 */
+    private missionPending;
+    /** 航线任务:起始航向(headingMode='fixed' 时保持不变) */
+    private missionStartHeading;
+    /** 航线任务:起步保护期,避免启动瞬间被残留摇杆指令打断 */
+    private missionStickGrace;
+    private missionHoverTimer;
+    /** 当前航点已耗时(超时保护) */
+    private missionWaypointTimer;
+    private missionElapsed;
+    private missionPasses;
+    private missionPauseReason;
+    /** 暂停前所处的阶段:继续执行时按它决定是接着走启航段还是直接飞航点 */
+    private missionPausedStage;
+    /** 任务起始时的总航程(米),仅用于进度条 */
+    private missionTotalDistance;
+    /** 按速度倍率缩放后的挡位参数缓存(见 specFor) */
+    private scaledSpec;
+    /** 降落细分标签:低位悬停确认是飞手最关心的一步,单独标出来 */
+    private get phaseLabel();
+    /** 是否已离地(起落架离地即算,含低空悬停) */
+    get airborne(): boolean;
+    /** 电机是否已启动(空中为 true;停桨后回 false) */
+    get motorsOn(): boolean;
+    /**
+     * 当前生效的限高(米)。`unlimitedFlight` 打开时为 `Infinity`,即不夹。
+     *
+     * 面板、航线编辑器、场景拖拽都通过 `getLimits()` 拿这个值来夹航点,
+     * 所以只要一个开关,UI 侧的输入上限也会同步失效 —— 不会出现"内核放开了但拖不出去"。
+     */
+    get altitudeCeiling(): number;
+    /** 当前生效的限距(米)。`unlimitedFlight` 打开时为 `Infinity`,即不夹。 */
+    get distanceCeiling(): number;
+    /**
+     * 增量修改仿真配置(限高限距开关 / 风 / 电量阈值等),立即生效,只覆盖传入的字段。
+     *
+     * 只改配置本身:不清位置、不清电量、不动正在执行的任务。若把 `unlimitedFlight`
+     * 从 `true` 改回 `false`,下一帧物理步进就会把机体夹回限高面 / 限距圆。
+     */
+    setConfig(patch: Partial<SimConfig>): void;
+    /** 当前生效的飞行速度倍率(夹到 0 ~ 1000;非法值退回 1) */
+    get speedScale(): number;
+    /**
+     * 设置飞行速度倍率(0 ~ 1000,数值即倍数)。
+     * 非有限值一律按 1(真机原速)处理 —— 面板滑杆中途可能给出空串/NaN。
+     */
+    setSpeedScale(scale: number): void;
+    /**
+     * 挡位参数按速度倍率缩放后的副本。
+     *
+     * 线性速度、加速度、刹车加速度、偏航角速度一起乘系数 —— 于是"满舵 = 该挡位最大倾角"
+     * 的标定关系不变(倾角模型的阻力系数由 horizontalSpeed 反推,自动跟着缩放),
+     * 观感就是同一台机器整体快/慢了几倍;`maxTiltDeg` 是物理上限,不缩放。
+     * 结果按(挡位, 倍率)缓存,倍率不动时每帧零分配。
+     */
+    private specFor;
+    /** 当前挡位参数(已按速度倍率缩放):速度上限 / 加速度 / 偏航角速度都取自它 */
+    get modeSpec(): ModeSpec;
+    /** 电量百分比 0~100(按真实容量积分,非线性掉电) */
+    get batteryPercent(): number;
+    /** 开路电压(只与电量有关,不依赖电流,避免与电流互为依赖) */
+    private get openCircuitVoltage();
+    /** 放电电流:按当前功率 / 近似电压估算 */
+    get batteryCurrent(): number;
+    /** 端电压 = 开路电压 − 内阻压降 */
+    get batteryVoltage(): number;
+    /** 当前定位来源:GNSS(≥6 星且指南针正常)→ 视觉 → 姿态模式 */
+    get positionSource(): PositionSource;
+    /** 当前总功耗(W):怠速 + 悬停(含平飞增益)+ 爬升功耗,再乘风速系数 */
+    get currentPowerWatts(): number;
+    /** 剩余可飞时间(分钟) */
+    get remainingMinutes(): number;
+    /** 上电:重置飞行状态与电量并进入自检;受损时拒绝 */
+    powerOn(): void;
+    /** 关机:仅地面可用;顺带作废未起飞的航线任务 */
+    powerOff(): void;
+    /** 切飞行挡位:'cine' 平稳 / 'normal' 普通 / 'sport' 运动(影响限速与倾角) */
+    setMode(mode: FlightMode): void;
+    /** 写摇杆连续量(Partial 合并;松杆由飞控刹停并定点悬停) */
+    setStick(stick: Partial<StickState>): void;
+    /** 内八掰杆启动电机(地面待机时可用) */
+    startMotors(): boolean;
+    /** 停止电机(仅地面已启动电机的状态可用);返回是否真的停下来了 */
+    stopMotors(): boolean;
+    /** 起飞:记录返航点并自动爬升到 1.2 米(需已启动电机) */
+    takeOff(): boolean;
+    /** 一键起飞(地面待机时自动完成电机启动 + 起飞) */
+    autoTakeOff(): boolean;
+    /** 触发自动降落(会先中止正在执行的航线任务) */
+    startLanding(): boolean;
+    /** 触发智能返航(reason 用于日志与快照);返航优先级高于航线,会中止任务 */
+    startRth(reason: string): boolean;
+    /** 取消正在执行的智能返航,转入手动飞行 */
+    cancelRth(reason?: string): void;
+    /**
+     * 紧急停桨(停桨保护)。
+     * ⚠️ **只在飞行器落地后允许**:空中停桨会直接导致坠机,本沙盒按用户要求禁止,
+     * 必须先把飞行器降落下来。空中调用会被拒绝(不改变任何飞行状态),只写一条警告日志。
+     */
+    emergencyStop(): boolean;
+    /** 重置到可再次起飞的状态(用于沙盒反复测试) */
+    reset(): void;
+    /** 推进一个仿真时间片(dtSeconds 秒;负值不推进,过大的值会被夹到单步上限) */
+    step(dtSeconds: number): void;
+    /** 分阶段推进:自检 → 预热 → 待机;起飞/降落/返航的自动段也在这里 */
+    private updatePhaseMachine;
+    /** 按下降落:高于悬停位则先降向 1 米,已经贴地则直接缓降 */
+    private beginLandingDescent;
+    /**
+     * 自动降落:降向 1 米悬停位 → 稳住一下 → 缓慢触地。
+     * 真机不会从巡航高度一路匀速直插地面;低位那一下停顿既是确认落点,也是留给飞手接管的时间。
+     */
+    private updateLanding;
+    /** 进入 1 米悬停位(手动降落与返航下降段共用) */
+    private enterLandingHold;
+    private finishLanding;
+    private applyGravityFall;
+    /** 水平速度归零(GPS/视觉保持位置,姿态模式保留风漂移) */
+    private settleHorizontal;
+    private updateFlight;
+    private updateGnssPositionFlight;
+    private integratePosition;
+    private applyYaw;
+    /**
+     * 机体倾斜:四旋翼靠"总升力矢量倾斜"产生水平分力,所以倾角由水平方向
+     * 需要的力决定 —— 稳态巡航时是气动阻力(∝ v²),加减速时叠加惯性力(m·a):
+     *   tan θ = (k·v² + m·a) / (m·g)
+     * 用挡位上限标定 k:满速平飞时倾角恰好 = maxTiltDeg。低速时倾角远小于
+     * 线性模型(真实阻力随速度平方增长),打杆瞬间则因惯性力额外下压机头、
+     * 刹车时反向抬头"拉飘" —— 与真机的加减速姿态一致。
+     * 采用航空惯例:俯仰正 = 抬头,横滚正 = 右倾。姿态模式叠加轻微摆动。
+     */
+    private updateTilt;
+    /**
+     * 四旋翼混控:把"总升力 + 三路姿态差动"分配到四个电机。
+     *
+     *  - 总距:motorLoad(含爬升/平飞的负载)已经承载整体转速;
+     *    机体倾斜 θ 后总升力还要除以 cos θ 才能托住重力,转速按推力开方折算。
+     *  - 俯仰差动:前倾(前进)由后侧两桨加速、前侧两桨减速产生 —— 机尾抬升、
+     *    机头下压,总升力的水平分力驱动前飞。差动量 ∝ 飞控正在施加的俯仰力矩,
+     *    即"目标倾角 − 当前倾角":打杆瞬间四桨差动最大,稳态匀速时回到近似同速
+     *    (只剩对抗气动俯仰力矩的微小配平)。
+     *  - 横滚差动:同理,向右压坡由左侧两桨加速、右侧两桨减速产生(右侧加速
+     *    会让右端抬起,是向左横滚)。
+     *  - 偏航差动:相邻桨反转、对角同向(本模型 前左/后右 = 顺时针)。桨旋转时
+     *    气动阻力给机身反扭矩,加速一组对角桨、减速另一组,总升力不变而净反扭矩
+     *    驱动原地转向 —— 差动量 ∝ 实际偏航角速度(转动全程都需要净扭矩)。
+     */
+    private updateMotorSpeeds;
+    private updateMotorLoad;
+    private updateRth;
+    private turnToward;
+    /**
+     * 航线内部的航点归一化:在字段护栏之外,把高度上限跟 `unlimitedFlight` 对齐。
+     *
+     * 默认仍是 {@link MISSION_ALTITUDE_HARD_LIMIT}(500 m);取消限高时传 `Infinity`,
+     * 否则会出现"限高放开了、航点却被 500 m 静默夹住"的矛盾。
+     */
+    private normalizeWaypoint;
+    /** 设置航点列表(执行中禁止修改,与真机"上传后不可改"一致) */
+    setMission(waypoints: Array<Partial<MissionWaypoint>>): boolean;
+    /**
+     * 只改一个航点(列表编辑与场景内拖拽共用)。
+     *
+     * 与 `setMission` 的区别:不整表替换、不重排,因此执行进度、其他航点的引用都保持原样 ——
+     * 场景里拖动航点时每帧都要下发一次,用整表替换会连带重建整套三维标记。
+     *
+     * 返回值是**归一化并夹紧后**的航点(限高/限距),调用方拿它当权威值,别用自己算的原始值。
+     */
+    updateMissionWaypoint(index: number, patch: Partial<MissionWaypoint>): MissionWaypoint | null;
+    /**
+     * 插入一个航点(场景内双击地面新增)。index 越界则追加到末尾,返回实际插入位置。
+     * 与真机一致:新航点的高度默认取相邻航点,避免插一个 0 米高、撞地的点。
+     */
+    addMissionWaypoint(waypoint: Partial<MissionWaypoint>, index?: number): number;
+    /** 删除一个航点,返回是否删掉了 */
+    removeMissionWaypoint(index: number): boolean;
+    /**
+     * 把一个航点夹进可执行范围:高度不超限高,水平距离不超限距(超出则沿返航点方向缩回)。
+     *
+     * `unlimitedFlight` 打开时两步都跳过(上限为 `Infinity`),只有"不低于 1 m"仍保留。
+     */
+    private constrainMissionWaypoint;
+    /** 增量更新航线任务的全局设置(只覆盖传入的字段) */
+    setMissionConfig(patch: Partial<MissionConfig>): void;
+    /** 恢复出厂示例航线 */
+    resetMissionToDefault(): void;
+    /**
+     * 启动航线任务。
+     * - 地面待机时先自动起飞,到 1.2 米后自动接上航线(对应 Pilot 里的"执行航线");
+     * - 已在空中则直接飞向第一个航点(正在返航会先中止返航);
+     * - 姿态模式(无定位)拒绝执行 —— 航点任务依赖 GNSS,真机同样如此。
+     */
+    startMission(): boolean;
+    /** 进入航线执行态(已在空中的入口) */
+    /**
+     * 进入航线执行态(已在空中 / 起飞到位后的入口)。
+     * 无论是地面起飞接上航线还是空中直接下发,都先从「启航四步」走起 ——
+     * 垂直调整到首航点高度 → 水平飞过去 → 高度收尾 → 对准航线方向,然后才开始推航点。
+     */
+    private beginMissionPath;
+    /** 暂停任务:交回手动控制并原地悬停,航点进度保留 */
+    pauseMission(reason?: string): boolean;
+    /** 继续任务:回到当前目标航点(首航点还没走完启航段的话接着走) */
+    resumeMission(): boolean;
+    /** 停止任务:飞机原地悬停,航线归零(真机"停止任务"不返航) */
+    stopMission(reason?: string): boolean;
+    /** 中止任务(内部使用:返航/降落等更高优先级动作会走到这里) */
+    private abortMission;
+    /** 航点合法性校验(限高限距):真机在上传航线时就会拦下这类航点;`unlimitedFlight` 打开时整段跳过 */
+    private validateMission;
+    /**
+     * 航线任务每帧推进。
+     *
+     * 真机飞航线的三个观感要点都在这里:
+     * - **先对准再前进**:headingMode='auto' 时机头没转到航向之前原地悬停转向,否则会飞出一条弧线;
+     * - **到点减速**:直线模式下按刹车距离提前收油,过点不甩过头;曲线模式则保持巡航速度、
+     *   距航点 3 米就切下一个点,形成圆滑切角;
+     * - **打杆即暂停**:执行中拨动摇杆 → 任务暂停并交回手动控制(与 Pilot 行为一致)。
+     */
+    private updateMission;
+    /**
+     * 启航段:飞往首航点的四步分段机动(与智能返航同款的分段逻辑)。
+     *
+     * 1. `depart-climb`  垂直调整到首航点高度 —— 这一段**只动高度**,水平速度锁死;
+     * 2. `depart-cruise` 保持该高度水平飞向首航点,机头朝行进方向;
+     * 3. `depart-settle` 到达后把高度收干净(水平位置锁死);
+     * 4. `depart-align`  原地把机头转到与航线一致,然后才交回常规航点推进。
+     */
+    private updateMissionDepart;
+    /**
+     * 暂停后按当前位置反推启航段走到了哪一步(幂等,可反复调用)。
+     * 判定顺序与启航四步一致:高度不对 → 先垂直;水平没到 → 再水平;高度没干净 → 收高度;否则对准。
+     */
+    private resolveMissionDepartStage;
+    /**
+     * 航线在某个航点处的「出航方向」(罗盘角)。
+     * 取该航点 → 下一个航点的方位;末航点没有出航段,退回上一段的方向(末点保持入航向)。
+     */
+    private missionRouteHeading;
+    private bearingBetween;
+    /** 到点:执行航点动作(云台 / 拍照 / 悬停),然后飞下一个点 */
+    private arriveWaypoint;
+    /** 推进到下一个航点;已到末尾则按结束动作收尾或循环 */
+    private advanceMission;
+    /** 全部航点执行完毕:按配置悬停 / 返航 / 降落 */
+    private finishMission;
+    /**
+     * 航线是否处于"已下发、等待起飞到位"状态。
+     * 地面点「执行航线」时 missionStatus 仍是 idle,真正的执行要等自动起飞到 1.2 米 ——
+     * 这段时间里航点列表同样不许改(改了下发的还是旧航线),所以外部需要这个判据。
+     */
+    get missionPendingStart(): boolean;
+    /** 剩余航程(米):沿剩余航点折线累计,含高度差 */
+    get missionDistanceLeft(): number;
+    private computeMissionDistanceLeft;
+    /** 航点完成度 0~1(按航程折算,暂停期间保持不变) */
+    get missionProgress(): number;
+    /** 预计剩余时间(秒):剩余航程 / 巡航速度 + 剩余悬停时间 */
+    get missionEtaSeconds(): number;
+    private updateGnss;
+    /** 水平精度因子(越小越好);无星时返回 99 表示不可用 */
+    get hdop(): number;
+    /** GPS 信号格数 0~5(按卫星数与 hdop 折算,面板显示用) */
+    get gpsBars(): number;
+    /** 遥控信号格数 0~5(按链路质量折算,面板显示用) */
+    get rcBars(): number;
+    /** 距返航点水平距离(米) */
+    get distanceToHome(): number;
+    /** 返航点(起飞点)水平坐标 */
+    get homePosition(): {
+        x: number;
+        z: number;
+    };
+    /** 是否已记录返航点(起飞那一刻记下)。界面据此决定画不画 H 标记与距离读数 */
+    get homeReady(): boolean;
+    /** 面板调试用:直接把电量设成某个百分比 */
+    forceBatteryLevel(percent: number): void;
+    private updateBattery;
+    /** 是否触发低电量(将进入智能返航) */
+    get lowBattery(): boolean;
+    /** 是否触发严重低电量(将强制降落) */
+    get criticalBattery(): boolean;
+    private updateFailsafe;
+    private applyObstacleBrake;
+    /**
+     * 让机身**原地自转**到绝对方位角 `headingDeg`(度,罗盘角);传 `null` 停止自转。
+     *
+     * 为什么需要它:Mini 4 Pro 的云台 Pan 机械行程只有 ±30°,靠云台转不出 180° 水平视野。
+     * 真机拍 180°/360° 全景是**机体原地自转**补水平、云台只做俯仰分层
+     * (见 `drone-panorama`),所以水平网格必须施加在机身上,而不是取景相机上。
+     *
+     * 只改航向:`applyYaw` 里自转优先于摇杆偏航,位置照常由定点保持锁住 —— 转的过程中
+     * 机体不位移("原地"的含义)。角速度同样吃 `speedScale`(倍率 0 时自转也停住)。
+     */
+    spinTo(headingDeg: number | null, rateDeg?: number): void;
+    /** 自转目标方位角(度,罗盘角);没有在自转时返回 null */
+    get spinTarget(): number | null;
+    /** 是否正在自转(目标未清除即为是,到位后目标仍在,直到调用方 `spinTo(null)`) */
+    get spinning(): boolean;
+    /** 自转是否已对准目标(容差 0.5°;没有自转时恒为 true) */
+    get spinAligned(): boolean;
+    /** 手动云台俯仰增量(度),正 = 抬头 */
+    nudgeGimbal(deltaPitch: number, deltaYaw?: number): void;
+    /** 设置云台俯仰角(度,正 = 抬头),自动夹到机型行程内 */
+    setGimbalPitch(pitch: number): void;
+    private updateCamera;
+    /** 切换录像开关;返回切换后是否在录 */
+    toggleRecording(): void;
+    /**
+     * 录像状态的唯一写入口(UI/引擎都走这里):
+     * 只负责状态、计时与事件日志;真正的录制(MediaRecorder)在 drone-fly 层,
+     * 由它按本状态启动/收尾,避免两处状态打架。
+     */
+    setRecordingState(active: boolean): void;
+    /** 停止录像并收尾成片(已在录才有效) */
+    stopRecording(): void;
+    /** 拍照:计数 +1 并记一条事件(实际成像由引擎层负责) */
+    takePhoto(): void;
+    /** 设置变焦倍数,夹在 1~4 倍之间 */
+    setZoom(zoom: number): void;
+    /** 起飞前检查项列表(外部注入项 + 内置项),每次读取即时构造 */
+    get checklist(): ChecklistItem[];
+    /** 是否满足起飞条件:阶段为待机/电机已启动,且所有阻塞项都通过 */
+    get canTakeOff(): boolean;
+    /** 当前生效的警告文案列表(界面红条用) */
+    get warnings(): string[];
+    private warnOnce;
+    private damageCheck;
+    /** 追加一条事件(面板事件流;level 决定颜色) */
+    pushEvent(level: EventLevel, text: string): void;
+    private pushEventInternal;
+    private formatDuration;
+    private windVector;
+    /** 风向相对机头的描述,例如"正逆风" */
+    get windRelative(): string;
+    /** 生成完整遥测快照(数组字段已复制,见 DroneSnapshot) */
+    snapshot(): DroneSnapshot;
+    /** 仿真累计时长(秒):含地面上电时间,与飞行时长 flightTime 不同 */
+    get elapsed(): number;
+}
+//# sourceMappingURL=drone-sim.d.ts.map