drone-camera 0.0.0-stage → 0.1.2

package/lib/drone-reconstruction-preview.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Small, renderer agnostic adapter for previewing a reconstructed 3D Tileset.
+ *
+ * Cesium is deliberately injected by the host.  Keeping this class free of a
+ * Cesium import means it can be used from a worker or tested with plain
+ * objects, while a Cesium application can pass `Cesium3DTileset.fromUrl`
+ * (or an object exposing `fromUrl`/`load`) as the loader.
+ */
+export type ReconstructionPreviewCompareMode = 'original' | 'reconstructed' | 'both';
+export interface ReconstructionPrimitiveCollection<T> {
+    add(primitive: T): T;
+    remove(primitive: T): boolean;
+}
+export interface ReconstructionPreviewViewer<T = unknown> {
+    scene?: {
+        primitives?: ReconstructionPrimitiveCollection<T>;
+    };
+}
+export interface ReconstructionTilesetLoader<T> {
+    /** A generic loader used by tests and non-Cesium hosts. */
+    load?: (url: string) => Promise<T> | T;
+    /** Cesium3DTileset.fromUrl compatible entry point. */
+    fromUrl?: (url: string) => Promise<T> | T;
+}
+export type ReconstructionTilesetLoaderInput<T> = ReconstructionTilesetLoader<T> | ((url: string) => Promise<T> | T);
+export interface ReconstructionPreviewOptions<TTileset, TOriginal = unknown> {
+    viewer: ReconstructionPreviewViewer<TTileset>;
+    loader: ReconstructionTilesetLoaderInput<TTileset>;
+    /** Existing scene primitive(s) used for the original/reconstructed comparison. */
+    original?: TOriginal | readonly TOriginal[];
+    compareMode?: ReconstructionPreviewCompareMode;
+    visible?: boolean;
+}
+export interface ReconstructionPreviewState<TTileset, TOriginal = unknown> {
+    url: string | null;
+    tileset: TTileset | null;
+    original: TOriginal | readonly TOriginal[] | undefined;
+    compareMode: ReconstructionPreviewCompareMode;
+    visible: boolean;
+    destroyed: boolean;
+}
+/**
+ * Manage one reconstructed primitive and an optional original primitive set.
+ * The original primitives are owned by the caller and are never removed or
+ * destroyed by this class.
+ */
+export declare class ReconstructionPreview<TTileset, TOriginal = unknown> {
+    readonly viewer: ReconstructionPreviewViewer<TTileset>;
+    readonly loader: (url: string) => Promise<TTileset> | TTileset;
+    private readonly primitives;
+    private original;
+    private currentTileset;
+    private currentUrl;
+    private compareMode;
+    private visible;
+    private destroyed;
+    private loadVersion;
+    private readonly originalVisibility;
+    constructor(options: ReconstructionPreviewOptions<TTileset, TOriginal>);
+    get tileset(): TTileset | null;
+    get url(): string | null;
+    get mode(): ReconstructionPreviewCompareMode;
+    get isVisible(): boolean;
+    get isDestroyed(): boolean;
+    get state(): ReconstructionPreviewState<TTileset, TOriginal>;
+    /** Load, mount, and return a tileset through the injected adapter. */
+    load(url: string): Promise<TTileset>;
+    /** Change which scene layers are shown. */
+    setCompareMode(mode: ReconstructionPreviewCompareMode): void;
+    /** Toggle the complete preview while preserving the compare mode. */
+    setVisible(visible: boolean): void;
+    /** Replace the caller-owned original primitive used by comparison mode. */
+    setOriginal(original: TOriginal | readonly TOriginal[] | undefined): void;
+    /** Remove and destroy the loaded reconstruction. Safe to call repeatedly. */
+    destroy(): void;
+    private assertAlive;
+    private rememberOriginalVisibility;
+    private restoreOriginalVisibility;
+    private applyVisibility;
+    private unmount;
+    private destroyPrimitive;
+}
+export default ReconstructionPreview;
+//# sourceMappingURL=drone-reconstruction-preview.d.ts.map

package/lib/drone-reconstruction-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drone-reconstruction-preview.d.ts","sourceRoot":"","sources":["../../src/lib/drone-camera/drone-reconstruction-preview.ts"],"names":[],"mappings":"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"}

package/lib/drone-rig.d.ts

@@ -0,0 +1,385 @@
+import * as THREE from 'three';
+/**
+ * 无人机模型的机械驱动。
+ *
+ * 全部通过语义节点名操作(见《DJI Mini 4 Pro 模型 ID 与名称对应表》),不做索引假设:
+ * - 桨叶:CTRL_Prop_<位置>_Spin 绕自身局部 Y 轴自转(导出到 Three.js 后 Blender 的局部 Z 即局部 Y),
+ *   对角两个电机同向。桨叶桨距已由模型出厂烘进几何(实测 ~15°,与自转方向配对),
+ *   这里不做任何几何补烘,尊重出厂状态。
+ * - 机臂:骨骼化导出驱动 ARM_<位置>_Fold_Bone(旧模型退回 CTRL_Arm_<位置>_Fold)。
+ *   折叠 = 绕机体竖轴(父系 +Y)的旋转,前乘在出厂装配四元数上——骨节自带
+ *   烘焙旋转,直接改 Euler 会把折叠轴带偏。折叠角度不是猜的,而是载入时用
+ *   "铰链 → 桨心"向量与该机臂应有的收纳方向(前臂朝机尾、后臂朝机头)算出来的。
+ * - 云台:CTRL_Gimbal_Yaw / Pitch / Roll 三轴。真机云台是增稳平台,
+ *   所以这里做反向补偿:机体倾斜多少,云台就往回摆多少(超出机械行程才让画面跟着歪)。
+ * - 起落架腿:LEG_<位置>_<关节>(Hip/Knee/Ankle)三关节链,收腿 = 各关节绕局部 +X
+ *   前乘固定折叠角(哈士奇机体几何实测,见 LEG_FOLD_ANGLES)。没有这些节点的
+ *   机体(真机 GLB)整套腿功能自动停用。
+ * - 机体姿态:整体倾斜施加在 CTRL_DJI_Root(模型内部根节点,原点≈机身重心)上。
+ */
+/** 机臂位置标签(前/后 × 左/右),同时用作 PROP_SPIN_SIGN / ARM_LABELS 等表的键。 */
+export type ArmPosition = 'FrontLeft' | 'FrontRight' | 'RearLeft' | 'RearRight';
+/** 四个机臂的固定遍历顺序(前左→前右→后左→后右):各处初始化、自检、建场都按它展开。 */
+export declare const ARM_POSITIONS: ArmPosition[];
+/**
+ * 对角反转:前左/后右 一组,前右/后左 一组,旋转方向相反。
+ * 符号不是猜的:实测出厂桨叶法线与自转轴的桨距角 φ(前左/后右 ≈ +15°,
+ * 前右/后左 ≈ −15°)。要产生向上拉力,φ>0 的桨必须俯视顺时针转(自转角递减),
+ * φ<0 的桨必须俯视逆时针转(自转角递增)——据此取反。
+ *
+ * 导出给机体模型使用:程序化机体(见 drone-husky-model)要按同一张表把两组
+ * 对角桨的桨叶反装(顺桨/逆桨),才与这里的自转方向配对。
+ */
+export declare const PROP_SPIN_SIGN: Record<ArmPosition, number>;
+/**
+ * 云台机械行程。
+ * rollLimit 取 45°:挡位倾角上限最高 35°(运动挡),留 10° 余量 —— 否则满舵侧倾
+ * 就把横滚轴顶到机械限位,补偿被截断,回正瞬间画面会"抖一下"。
+ */
+export declare const GIMBAL_LIMITS: {
+    readonly pitchMin: -90;
+    readonly pitchMax: 60;
+    readonly rollLimit: 45;
+    readonly yawLimit: 5;
+};
+/** 模型自检结果(测试沙盒里逐项显示) */
+export interface RigPartReport {
+    id: string;
+    label: string;
+    found: boolean;
+    /** 该部件是否可被驱动 */
+    drivable: boolean;
+}
+/**
+ * ————————————————— 统一坐标系约定(全项目唯一声明) —————————————————
+ *
+ * 世界系(Three.js 标准):
+ *   +X 东, +Y 上, -Z 北。航向 heading 从正北顺时针,0°=北 90°=东。
+ *
+ * 机体系(模型局部,glTF 导出后):
+ *   -Z 机头(云台), +Z 机尾(电池), -X 左 / +X 右, +Y 上。
+ *
+ * 机体姿态角(相对世界水平面):
+ *   pitch 正 = 抬头(绕机体系 X 轴), roll 正 = 右压坡(绕机体系 Z 轴取负)。
+ *
+ * 整机按「刚体」驱动,变换层级自外向内:
+ *   model(世界位置+航向) → CTRL_DJI_Root(俯仰/横滚) → 机臂折叠 → 转子/桨叶自转
+ *   云台是挂载载荷,在 CTRL_DJI_Root 内部做增稳补偿,不属于刚体位姿。
+ * 整机位姿只有一个写入入口:applyBodyPose()。
+ */
+/** 整机刚体位姿:位置为世界系(米),角度为度 */
+export interface DroneBodyPose {
+    /** 世界系 X(东为正) */
+    x: number;
+    /** 世界系 Y(离地高度,米) */
+    y: number;
+    /** 世界系 Z(南为正) */
+    z: number;
+    /** 航向角:正北 0°,顺时针增加 */
+    headingDeg: number;
+    /** 俯仰:正 = 抬头 */
+    pitchDeg: number;
+    /** 横滚:正 = 右压坡 */
+    rollDeg: number;
+}
+/**
+ * 无人机模型的机械驱动层:载入后按语义节点名解析出机臂/转子/桨叶/云台,
+ * 并对外提供折叠、自转、云台增稳、整机位姿四类写入接口及自检报告。
+ *
+ * 唯一的世界系/机体系约定见文件顶部「统一坐标系约定」;所有长度比较都在世界系(米)做,
+ * 给节点平移赋值前须乘 localUnits 换算回节点局部单位(见后文注释)。
+ * 整机位姿只有 applyBodyPose() 一个写入入口;骨骼化重导出的模型必须同时驱动
+ * CTRL_DJI_Root 与 RIG_DJI_Arms_Props 两个节点,否则机体会与机臂"撕开"。
+ */
+export declare class DroneRig {
+    readonly model: THREE.Group;
+    readonly parts: RigPartReport[];
+    private readonly root;
+    /**
+     * 骨骼架根节点(RIG_DJI_Arms_Props)。重导出的模型把机臂/电机/桨叶/脚撑
+     * 挂到了这个与 CTRL_DJI_Root 平级的顶级骨架下(为骨骼动画导出),
+     * 刚体俯仰/横滚必须同时施加在两个节点上,否则飞行时机体会"散架"。
+     * 旧模型(无骨骼)此值为 null,自动退回单节点模式。
+     */
+    private readonly rigBonesRoot;
+    private readonly props;
+    private readonly arms;
+    private readonly legs;
+    private gimbalYaw;
+    private gimbalPitch;
+    private gimbalRoll;
+    /** 云台载荷(相机外壳)节点;取景时相机必须越过它的前端,否则拍进自己的壳 */
+    private gimbalPod;
+    /**
+     * 载荷前端面到云台枢轴的沿光轴(-Z)距离(**roll 局部单位,与模型缩放无关**)。
+     * 取景相机要摆到这段距离之外(换算成米后),外壳才不会挡住视线。
+     */
+    private gimbalClearanceLocal;
+    /**
+     * 挂点前方"机体外形"的前伸量(模型局部单位):哈士奇鼻尖在挂点前 0.84 单位。
+     * 相机前移量必须同时越过它,否则云台上仰时会把机体外观拍进画面(见 measureBodyClearance)。
+     */
+    private gimbalBodyClearanceLocal;
+    /** 云台偏航节点出厂位置(枢轴 P,父系局部单位) */
+    private readonly gimbalBindPosition;
+    /** 相机中心 C − 枢轴 P(父系局部单位);C≈P 时为零向量,补偿自动无效 */
+    private readonly gimbalCenterOffset;
+    /**
+     * 云台枢轴在**机体局部系**的挂点(出厂水平态实测):位置解耦用。
+     * 取景相机按"机体平移 + 航向旋转 + 该挂点"定位,不随机体倾斜绕横滚轴画弧
+     * (实测侧倾 27° 时旧做法镜头横移 ±6.7 cm,就是"回正时画面明显晃"的主因)。
+     */
+    private readonly gimbalMountLocal;
+    private gimbalMountReady;
+    /**
+     * 相机在"航向已剥离"参考系下的安装朝向(出厂水平态实测):姿态解耦用。
+     * 取景相机的世界朝向直接由 `R_y(航向+云台偏航)·R_x(云台俯仰)·R_z(0) ⊗ 本偏置`
+     * 解出,不再读骨骼链世界变换 —— 于是关节一阶跟随的滞后、机械行程夹紧、
+     * 层级数值误差全部不会传到画面上(模型那边照旧,只是相机不再"采样"它)。
+     */
+    private readonly gimbalMountQuat;
+    private gimbalOrientationReady;
+    private readonly gimbalScratchQuat;
+    /** 云台关节当前角(弧度):一阶跟随用,代表电机实际到位的位置 */
+    private gimbalJointYaw;
+    private gimbalJointPitch;
+    private gimbalJointRoll;
+    private readonly gimbalBodyQuat;
+    private readonly gimbalTargetQuat;
+    private readonly gimbalJointQuat;
+    /**
+     * 云台关节一阶跟随时间常数(秒)。>0 时关节不瞬时到位(模拟无刷电机响应),
+     * 0 = 立即到位。默认 20 ms。
+     */
+    gimbalResponse: number;
+    private readonly disposables;
+    private fold;
+    private spinAngle;
+    private lastLoad;
+    /** 起落架腿收放度(1 = 放下,0 = 完全收起);出厂即放下 */
+    private legDeployState;
+    /**
+     * 桨叶张开度(0 = 叠拢,1 = 自然张开):有自己的缓动节奏——
+     * 机臂完全展开后才开始缓慢张开(与真机一致),收纳时快速叠拢。
+     */
+    private bladeOpenState;
+    /** 展开态停放配平抬头角(度,几何实测):前脚撑与机尾底部同时落地 */
+    private stancePitchOpen;
+    /** 展开态配平整体下沉量(米),保证静止时脚撑恰好贴地 */
+    private stanceDropOpen;
+    /** 收纳态下沉量(米):机身平贴地面(俯仰 0),脚撑随机臂收起不再接地 */
+    private stanceDropFolded;
+    /** 绑定机体模型根节点,建立机臂/桨叶/云台/起落架的机械控制 */
+    constructor(model: THREE.Group);
+    /** 机臂当前折叠度(0 = 展开,1 = 完全收纳) */
+    get armFold(): number;
+    /** 桨叶张开度(0 = 叠拢,1 = 张开):起飞自检要求完全张开 */
+    get bladeOpen(): number;
+    /** 桨叶是否已开始旋转 */
+    get motorsSpinning(): boolean;
+    /** 设置机臂折叠度(0 = 展开,1 = 完全收纳);变化量 <1e-4 直接返回,避免每帧重复写节点。 */
+    setArmFold(fold: number): void;
+    /**
+     * 机臂折叠的唯一写入口:绕机体竖轴(父系 +Y)旋转,前乘在出厂装配四元数上。
+     * 旧模型折叠节点出厂四元数为单位阵,等价于直接写 rotation.y;骨骼化重导出后
+     * 折叠骨节自带烘焙旋转,直接改 Euler 的 y 分量会把折叠轴带偏(实测偏 32°,
+     * 机臂甩出水平面),必须四元数整体前乘。
+     */
+    private applyArmFold;
+    /** 起落架腿当前收放度(1 = 放下,0 = 完全收起);无腿节点的机体恒为 1 */
+    get legDeploy(): number;
+    /**
+     * 设置起落架腿收放度(1 = 放下,0 = 完全收起)。
+     * 与机臂折叠同一条纪律:旋转四元数整体前乘在出厂姿态上 —— 哈士奇腿关节出厂
+     * 四元数是单位阵(等价于直接写 rotation.x),但保持同构写法,未来带烘焙姿态的
+     * 骨骼导出也不跑偏。没有 LEG_* 节点的机体(真机 GLB)是 no-op。
+     */
+    setLegDeploy(deploy: number): void;
+    /** 收集起落架腿:按 LEG_<位置>_(Hip|Knee|Ankle) 语义名扫描(见 drone-husky-model 适配层) */
+    private collectLegs;
+    /**
+     * 桨叶姿态的唯一写入口(每帧调用):
+     * - 叠拢/张开:bladeOpen 以自己的节奏缓动。机臂完全展开(fold < 0.02)
+     *   且电机未转时目标为张开,以慢速率"缓缓转回原位";收纳时以快速率先叠拢。
+     * - 收纳抬升:仅当叠拢姿态求不出零侵入时的兜底(当前几何下四桨均为 0,
+     *   桨毂保持坐在电机钟罩内);折叠时转子沿电机轴抬起 foldLift。
+     */
+    updateBlades(deltaSeconds: number): void;
+    /** 叠拢/张开姿态:绕电机轴(桨叶父系表示的 bladeFoldAxis)偏航 stackYaw×factor */
+    private applyBladeFold;
+    /**
+     * 自转姿态的唯一写入口:对每个自转件前乘"绕父系表示的电机轴"的旋转:
+     *   q = Q(axisParent, angle) ⊗ 出厂姿态
+     * 与旧版"后乘局部 Y"在世界系完全等价(同一根电机轴、同向、同角)。
+     * 自转节点本体带动桨毂;骨骼化导出还把两片桨叶挂进独立折叠骨节
+     * (PROP_*_Blade_*_Fold_Bone,与自转节点同级),必须一并驱动,
+     * 否则桨毂转而桨叶不转。
+     */
+    private applyPropRotation;
+    /**
+     * 驱动桨叶:load 为电机负荷 0~1;也可传入按机臂位置索引的四电机转速表
+     * (悬停 ≈ 1,来自 DroneSim 的四旋翼混控)—— 前飞时后桨快、前桨慢,
+     * 转向时一组对角桨快、另一组慢,与真机的升力差/反扭矩机制一致。
+     */
+    updateProps(load: number | Partial<Record<ArmPosition, number>>, deltaSeconds: number): void;
+    /**
+     * 整机刚体位姿的唯一写入入口:世界位置 + 航向施加在模型根节点,
+     * 俯仰/横滚施加在 CTRL_DJI_Root(模型内部重心)。机臂、转子、云台
+     * 全部挂在这条变换链下游,自动跟随整机运动,无需单独处理。
+     *
+     * 停放配平随折叠度过渡:展开态机身上仰 stancePitchOpen(电机轴前倾的
+     * 补偿,前脚撑与机尾同时着地);收纳态机身平贴(俯仰 0,像真机收纳
+     * 后平放在桌面上)。pose.y 语义是"触地点高度",下沉量在这里内部消化。
+     */
+    applyBodyPose(pose: DroneBodyPose): void;
+    /**
+     * 云台增稳(三轴解耦):传入相对水平面的期望角度,机体倾斜由云端解算一次性反掉。
+     *
+     * 做法:先组装"相机应有的世界姿态"——航向 = 模型航向 + 云台偏航命令,俯仰 =
+     * 云台俯仰命令,横滚恒为 0(锁水平);再除以云台挂载父节点的世界姿态,得到
+     * 云台链应处的**局部位姿**,按 YXZ 顺序(偏航→俯仰→横滚,与模型关节链一致)
+     * 分解成三个关节角。
+     *
+     * 为什么不用"期望角 − 机体角"直接相减:欧拉角不可交换,机体同时俯仰+横滚时
+     * 旧做法会漏出交叉耦合(实测侧倾机动中镜头 roll 残差 0.6°、pitch 波动 2.5°,
+     * 回正时残差反向 → 画面转一下 + 点一下头)。解算后残差在数学上归零。
+     * 关节仍受机械行程夹紧,超程部分保留 —— 大角度机动时画面会跟着歪,与真机一致。
+     *
+     * @param pitchDeg 云台俯仰期望角(度,相对水平面,正 = 抬头)
+     * @param rollDeg  云台横滚期望角(度,相对水平面,通常恒 0 = 锁水平)
+     * @param yawDeg   云台偏航命令(度,相对机身,受 ±yawLimit 限制)
+     * @param bodyPitch 旧版角度相减参数,现已由机体世界姿态取代,保留仅为兼容调用
+     * @param bodyRoll  同上
+     * @param deltaSeconds 帧间隔(秒):>0 时关节按一阶惯性跟随电机响应,0 = 立即到位
+     */
+    setGimbalAttitude(pitchDeg: number, rollDeg: number, yawDeg: number, bodyPitch?: number, bodyRoll?: number, deltaSeconds?: number): void;
+    /** 云台相机的世界位置与朝向(机载视角用) */
+    getGimbalCameraTransform(target: THREE.Object3D): boolean;
+    /**
+     * 机载相机的**位置解耦**挂点(世界坐标):机体只贡献"平移 + 航向",不含倾斜。
+     *
+     * 真机上镜头挂在重心下方约 0.14 m,机体侧倾会带着它绕横滚轴画弧(侧倾 27° 即
+     * 横移 ±6.7 cm)。姿态已经被三轴解算锁平,位置再跟着画弧,画面就"整体左右平移"
+     * —— 人眼对平移比对角度的容差低得多,这就是回正时"明显晃"的来源。
+     * 真机云台的橡胶减震球 + 电子增稳在观感上也等价于"镜头被稳稳托住",所以这里
+     * 把位置一起解耦:挂点随机体平移、随航向旋转,不随机体俯仰/横滚摆动。
+     *
+     * @param target 写入世界坐标
+     * @param forwardOffset 沿**云台光轴**的前移量(米):相机要越过载荷外壳与机体外形前端
+     * @param pitchDeg 云台俯仰真值(度,正 = 抬头):决定光轴方向
+     * @returns 云台挂点未就绪(模型无云台)时返回 false
+     *
+     * ⚠️ 前移必须沿**光轴**而不能只沿航向(纯水平):云台上仰时光轴朝前上方,机体的
+     * 前上方外形(哈士奇狗鼻尖在挂点上方 0.16 m、前方 0.26 m)在**相机空间**里就落在
+     * 镜头前面 —— 世界 z 上"相机在鼻子之前"是错觉,判据是沿光轴的距离。实测只做水平
+     * 前移时仰到 60° 仍有 0.72% 的画面被鼻壳占据(差异像素全在画面顶部一带)。
+     * 沿光轴前移 = 真机云台俯仰时镜头绕俯仰轴画弧,位置随仰角自然抬起。
+     */
+    getGimbalCameraMount(target: THREE.Vector3, forwardOffset: number, pitchDeg?: number): boolean;
+    /**
+     * 机载相机的**姿态解耦**朝向(世界四元数):直接由飞控真值解算,不读骨骼链。
+     *
+     * 与位置解耦配套:`引擎给出期望姿态 → 相机照做`,而不是`模型转成什么样 → 相机照抄`。
+     * 骨骼链上那些"拟真副作用"(关节一阶跟随的 20 ms 滞后、机械行程夹紧、层级数值残差)
+     * 只留在模型外观上,不会再传进画面 —— 这正是真机三轴云台"硬件解耦"在做的事:
+     * 机身怎么动都只是被隔离掉,镜头自己稳稳对着目标。
+     *
+     * @param target 写入世界四元数
+     * @param pitchDeg 云台俯仰期望角(度,相对水平面,正 = 抬头)
+     * @param rollDeg  云台横滚期望角(度,通常恒 0 = 锁水平)
+     * @param yawDeg   云台偏航命令(度,相对机身)
+     * @returns 云台未就绪(模型无云台)时返回 false
+     */
+    getGimbalCameraOrientation(target: THREE.Quaternion, pitchDeg: number, rollDeg: number, yawDeg: number): boolean;
+    /** 释放本类记录的可释放资源(几何/材质);模型本体归调用方所有,不在此销毁。 */
+    destroy(): void;
+    /** 逐项核对 ID 表里的部件是否存在(缺失的会列进自检报告) */
+    private collectParts;
+    private buildProps;
+    /**
+     * 实测每个桨的"叠拢偏航角"(与真机一致:收纳时两片桨叶绕桨夹转拢、
+     * 叠在一起指向机臂方向)。临时折叠到 1,量出桨叶径向与机臂方向的夹角;
+     * 再整圈扫描整体偏航,取对机身/机臂/其他桨叶侵入最小的角度。求不出
+     * 零侵入时才用残余侵入量 + 余量作收纳抬升兜底(当前四桨均为 0)。
+     */
+    private computeBladeFold;
+    /**
+     * 当前(已由 measureStackPenetration 摆好的)叠拢姿态下,桨叶 1 相对电机
+     * 的水平方向与机身纵轴(世界 Z,载入时机身无旋转)的对齐度:0~1,越大越顺轴。
+     */
+    private stackAxisAlignment;
+    /** 临时施加"叠拢 + 偏移"姿态,量桨叶顶点对实体场(机身 + 已定姿的其他桨叶)的最大侵入(世界系/米) */
+    private measureStackPenetration;
+    /**
+     * 机身实体场:BODY_/ARM_/MOTOR_ 顶点按 (x,z) 0.01m 网格归入竖直区间
+     * (下沿~上沿)。只有顶点真正落入区间内部才算侵入 —— 桨叶从折叠臂
+     * 下方/上方掠过不算,避免"最高点高度场"把擦边当成穿透。
+     */
+    private buildBodyHeightfield;
+    /**
+     * 折叠角由几何推算:取"铰链 → 桨心"在水平面的方向,与收纳方向作差。
+     * 前臂收向机尾(+Z),后臂收向机头(-Z) —— 与 Mini 系列的实际收纳姿态一致。
+     * 驱动点优先取骨骼化导出的折叠骨节 ARM_*_Fold_Bone(其子树 = 折叠子树:
+     * 臂网格 + 电机 + 桨),旧模型退回 CTRL_Arm_*_Fold。
+     */
+    private buildArms;
+    /**
+     * 实测"停放配平"(分展开/收纳两态,随折叠度过渡):
+     * - 展开态:前脚撑(GEAR_* 最低点)与机尾底部(BODY_* 机尾区域最低点)
+     *   是两个触地带,机身平放时只有前脚撑着地、机尾悬空。解出让两带同高
+     *   的抬头角并整体下沉,静止时"机尾轻触地、机头微抬"地停放。
+     * - 收纳态:脚撑随机臂翻起不再接地,真机收纳后是机身平贴桌面 —— 俯仰 0,
+     *   下沉量 = 机身系(不含脚撑/桨叶)最低点。
+     * 角度按几何解算,不写死数值,模型日后重导出也能自适应。
+     */
+    private computeStanceTrim;
+    /** 刚体俯仰(弧度)统一写入:机身根 + 骨骼架根(若存在)同步施加 */
+    private setBodyPitchRad;
+    /**
+     * 电机轴前倾角(弧度,展开姿、机身水平时量测):四个转子节点局部 Y(=电机轴)
+     * 的世界方向,取前向分量的均值。调用前须已把机臂展开并 updateMatrixWorld。
+     */
+    private measureMotorForwardTilt;
+    /** 所有匹配前缀网格的世界最低点;toModelLocal 提供时返回模型系坐标 */
+    private measureLowest;
+    /** 触地带扫描:前脚撑最低点 + 机尾底部最低点(模型局部系) */
+    private scanStanceContacts;
+    private bindGimbal;
+    /**
+     * 量"云台载荷沿光轴(-Z)的前端面到枢轴的距离"(roll 局部单位)。
+     *
+     * 取景相机默认摆在枢轴沿光轴前移一小段处;若这段距离没越过载荷前端,
+     * 相机就泡在相机外壳里,画面正中是一颗对着的镜头(fpv 视角"看相机"的根因)。
+     *
+     * 做法:载荷包围盒 8 个角变换到 roll 局部系取最小 Z(前方为 -Z)。
+     * pod 是 roll 的子节点,几何相对 roll 固定,量一次即可;局部值与模型
+     * 缩放无关,使用方(getGimbalCameraClearance)按当前世界缩放换算成米。
+     */
+    private measureGimbalClearance;
+    /**
+     * 量"挂点前方、光轴口径内"的机体外形前伸量(模型局部单位)。
+     *
+     * 与 measureGimbalClearance(载荷壳体自身)是两件事:那条是"别泡进自己的相机壳",
+     * 这条是"别把机体外观拍进画面"。哈士奇的云台枢轴在机头下方,而狗鼻尖伸到枢轴
+     * 前 0.84 单位(0.27 m)—— 相机若只按壳体前移,就还落在鼻子后面:平视看不到
+     * (鼻子在视野上边界之外),但云台上仰超过 ~35° 后画面下缘扫过鼻头(实测
+     * pitch 60° 时鼻壳最近 0.139 m,画面里挂着半个狗鼻子)。
+     *
+     * 做法:遍历所有网格的包围盒 8 角,换算到模型局部系,只统计"在挂点前方(Δz<0)
+     * 且落在光轴口径内(|Δx|、|Δy| ≤ BODY_CLEARANCE_RADIUS_M)"的点,取最大前伸量。
+     * 相机前移量取本值与载荷前端的较大者后,机体外观整体落在相机背后,
+     * 任何俯仰角都不再入镜。
+     */
+    private measureBodyClearance;
+    /**
+     * 云台载荷沿光轴(-Z)的前端距离(**米**)。
+     * 取景相机沿光轴前移量必须大于该值(外加小余量),外壳才不会挡住视线。
+     * 同时取"挂点前方的机体外形前伸量"的较大者:否则机体自己的外观
+     * (哈士奇的狗鼻子)会在云台上仰时入镜,见 measureBodyClearance。
+     * 云台未就绪返回 null,调用方退回自己的默认偏移。
+     */
+    getGimbalCameraClearance(): number | null;
+    /** 机臂折叠枢轴节点(状态灯等机臂附件挂到它下面即可跟随折叠/展开) */
+    getArmFoldNode(position: ArmPosition): THREE.Object3D | null;
+}
+//# sourceMappingURL=drone-rig.d.ts.map

package/lib/drone-rig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drone-rig.d.ts","sourceRoot":"","sources":["../../src/lib/drone-camera/drone-rig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;;;;;;;;;;;;;GAiBG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,WAAW,CAAA;AAE/E,iDAAiD;AACjD,eAAO,MAAM,aAAa,EAAE,WAAW,EAAyD,CAAA;AAIhG;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAKtD,CAAA;AA0CD;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAA;AAEV,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,OAAO,CAAA;IACd,gBAAgB;IAChB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAgID;;;;;;;;;;;;;;;;GAgBG;AAEH,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAA;IACT,oBAAoB;IACpB,CAAC,EAAE,MAAM,CAAA;IACT,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAA;IACT,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,CAAK;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAA8B;IAChD,0CAA0C;IAC1C,OAAO,CAAC,SAAS,CAA8B;IAC/C;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAI;IAChC;;;OAGG;IACH,OAAO,CAAC,wBAAwB,CAAI;IACpC,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IACzD,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IACzD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsB;IACvD,OAAO,CAAC,gBAAgB,CAAQ;IAChC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,sBAAsB,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,oCAAoC;IACpC,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD;;;OAGG;IACH,cAAc,SAA0B;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmD;IAC/E,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,QAAQ,CAAI;IACpB,qCAAqC;IACrC,OAAO,CAAC,cAAc,CAAI;IAC1B;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAI;IAC1B,sCAAsC;IACtC,OAAO,CAAC,eAAe,CAAI;IAC3B,gCAAgC;IAChC,OAAO,CAAC,cAAc,CAAI;IAC1B,yCAAyC;IACzC,OAAO,CAAC,gBAAgB,CAAI;IAE5B,oCAAoC;gBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;IAc9B,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,sCAAsC;IACtC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,gBAAgB;IAChB,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,yDAAyD;IACzD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAKpB,6CAA6C;IAC7C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAclC,wEAAwE;IACxE,OAAO,CAAC,WAAW;IAmBnB;;;;;;OAMG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAuBxC,4DAA4D;IAC5D,OAAO,CAAC,cAAc;IAatB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAkB5F;;;;;;;;OAQG;IACH,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAqBxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,SAAI,EACb,QAAQ,SAAI,EACZ,YAAY,SAAI,GACf,IAAI;IA6DP,0BAA0B;IAC1B,wBAAwB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,OAAO;IAQzD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO;IAgBzF;;;;;;;;;;;;;OAaG;IACH,0BAA0B,CACxB,MAAM,EAAE,KAAK,CAAC,UAAU,EACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,OAAO;IAQV,4CAA4C;IAC5C,OAAO,IAAI,IAAI;IASf,oCAAoC;IACpC,OAAO,CAAC,YAAY;IA4EpB,OAAO,CAAC,UAAU;IA2FlB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAyHxB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAY1B,2DAA2D;IAC3D,OAAO,CAAC,uBAAuB;IA+B/B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAuBjB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAyDzB,uCAAuC;IACvC,OAAO,CAAC,eAAe;IAKvB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAe/B,6CAA6C;IAC7C,OAAO,CAAC,aAAa;IAiBrB,oCAAoC;IACpC,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,UAAU;IAmDlB;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,oBAAoB;IAmC5B;;;;;;OAMG;IACH,wBAAwB,IAAI,MAAM,GAAG,IAAI;IAWzC,uCAAuC;IACvC,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,KAAK,CAAC,QAAQ,GAAG,IAAI;CAG7D"}