RBF 解算器使用说明
# RBF 解算器使用说明
# 使用说明
工具在场景中建立「一根驱动骨骼的局部旋转 → 多根被驱动骨骼的局部 TRS」的径向基函数（RBF）插值关系，适用于姿态驱动、辅助骨骼跟随等绑定工作流。
# 开发节点
工具原型开发（开始2026-4-28 ~）
[X] 驱动配置保存到 .Max文件，打开插件即可自动加载配置。
[ ] RBF驱动镜像，例如设置好左腿驱动，直接镜像到右脚。
[ ] 匹配目标POSE范围的可视化，参考 UE5中的PoseDriver 节点。
[ ] 多驱动模式，当前的RBF仅支持一个驱动骨骼。 需扩展多个驱动骨骼控制一个被驱动骨骼，例如裙摆的中间骨骼被左右腿控制。
C++ 实时解算版本。
# 环境与运行方式
- 软件：Autodesk 3ds Max 2015 +
- 运行：直接将工具拖拽进3dsMax窗口即可。
# 核心概念
| 术语 | 含义 |
|---|---|
| 驱动骨骼（Driver） | 拾取的单一节点；其相对父级的局部旋转四元数作为 RBF 输入特征的来源。 |
| 被驱动列表（Driven） | 可多选添加的多根骨骼；每个姿态样本记录它们的局部 Position / Rotation / Scale。 |
| 姿态样本（Pose） | 某一时刻下：驱动局部四元数 + 所有被驱动局部 TRS 的一组快照。第一个样本在 Twist/Swing 模式下作为「绑定参考」，用于计算相对旋转 |
| 构建 RBF | 根据当前模式与样本，计算核矩阵并求逆（或缓存特征），将isBuilt置为可用。 |
| 配置（Config） | 内存中一套或多套「驱动配置」；可保存/加载为INI 文件。 |
| 驱动槽（Driver Slot） | 同一 INI「配置」下的多套独立驱动：每槽有各自的驱动骨、被驱动、样本与 RBF 参数，可在列表中切换。 |
# 界面分区说明
# 驱动配置
- 下拉列表：在多条内存配置之间切换；切换前会保存当前编辑到该配置项。
- 新建 / 删除：增加或删除整条配置（至少保留一条）。
- 保存 / 加载：将当前所有配置序列化为
.ini，或从文件反序列化。 - 存场景： 将当所有配置序列化为
.ini并保存到场景中，打开插件时将自动加载配置。 - 读场景： 手动读取当前场景中的 驱动配置。
# 节点设置
驱动骨骼列表：同一文件配置内的多个「驱动槽」。单击切换槽位；双击可修改槽在列表中的显示名称（不影响节点名）。
新建驱动 / 删除驱动：增减驱动槽（至少保留一个槽）。
拾取驱动骨骼：为当前槽指定驱动节点。
重建骨骼姿势： 先清理驱动和被驱动骨骼的动画，再以一帧间隔将样本POSE设置到驱动和被驱动骨骼上，方便调试Pose。
添加 / 删除（被驱动） ：从当前选择批量加入被驱动列表，或删除列表选中项。增删被驱动后，各姿态里的通道数会自动对齐（新增通道可能为
undefined，需补录姿态）。创建姿势：弹出对话框输入姿态名，记录当前驱动局部旋转与各被驱动局部 TRS。
删除姿势：删除最后一个姿态样本。
POSES 列表：双击某条可修改该姿态的显示名称。
# 姿态样本
- 显示样本数与被驱动数量摘要。
- 清除所有：仅清空所有姿态样本与 RBF 构建缓存；不清除当前驱动骨、被驱动列表、核类型、Epsilon、旋转模式等（确认框中有说明）。
# RBF 参数
- 驱动 RBF 旋转：见下文 驱动旋转模式。
- Epsilon：核函数尺度参数（ spinner 与内部
sphereRBF.epsilon同步）。 - 核函数：Gaussian / Multiquadric / Inverse Multiquadric / Thin Plate（界面为中文标签）。
- 构建 RBF：应用当前参数并尝试构建；样本数须 ≥ 2。
说明：脚本内 正则化（regularization） 在 UI 中默认隐藏，构建 Twist/Swing 时会在内部临时放大正则以避免病态矩阵，构建后恢复原值。
# 运行
解算当前帧：按当前时间驱动读值，对被驱动写插值结果。
解算动画：在当前 animationRange 内烘焙；可选仅在有驱动关键帧的时间采样。
解算全部驱动动画：对当前配置文件中所有驱动槽依次执行动画烘焙。
调试信息：在 Listener 输出管理器与插值器状态；样本足够时还会测试距离分布。
实时更新调试：如下视频
# 推荐工作流程
- 保存 Max 场景，确认驱动骨层级与轴向符合绑定规范。
- 运行脚本打开面板，必要时 加载 已有 INI 或 新建配置。
- 选中目标驱动槽 → 拾取驱动骨骼 → 添加 被驱动骨骼（可多选）。
- 摆好 绑定 / T-Pose（或文档约定的参考姿势） → 创建姿势，命名为例如
Bind 或Pose 1（作为样本 1）。 - 依次摆出其它关键姿势，多次 创建姿势（至少 2 个样本）。
- 选择合适的 驱动 RBF 旋转 模式与 核函数，调节 Epsilon，点击 构建 RBF。
- scrub 时间轴用 解算当前帧 检查；满意后用 解算动画 或 解算全部驱动动画 烘焙。
- 保存 INI 以便下次加载或与同事共享（注意节点句柄与会话绑定，见下文）。
# 驱动旋转模式（Quat / Twist-X / Swing-Quat）
界面三项与内部枚举对应关系：
| UI | 内部模式 | 含义概要 |
|---|---|---|
| Quat | #full | 使用相对绑定后的完整局部旋转四元数；样本间距离为S³ 上归一化测地角（实现于SphereQuatData.sphereDistanceTo）。 |
| Twist-X | #twist_angle | 仅保留绕骨骼局部 X 轴的扭转分量；构建时用扭转特征四元数间的圆上距离。求值阶段使用IDW（反距离平方）权重，避免出现负 RBF 系数，并与帧间半球连续性处理配合。 |
| Swing-Quat | #swing_quat | Swing-Twist 分解后取Swing部分；RBF 距离定义为局部 X 轴被旋转后的单位方向在球面S²上的夹角除以 π（不是Swing 四元数在 S³ 上的测地距）。求值同样走IDW权重。 |
务必注意：
- 切换模式、修改 第一个样本、或改动驱动局部绑定关系后，应重新 构建 RBF。
- Twist/Swing 语义依赖「样本 1」作为绑定参考；文档与tooltip强调：第一个样本请保持蒙皮/绑定参考姿势。
# RBF 参数与核函数
- Epsilon：控制核函数随距离衰减或增长的快慢；过小可能导致过拟合或数值不稳定，过大则过渡平滑、细节不足。需结合姿态间距与模式试验。
- 核类型：与高斯、多二次、逆多二次、薄板样条等经典 RBF 核一致（实现见
SphereRBFInterpolator.rbfKernel）。
若 Listener 出现「原始系数和≈0」类警告，脚本会退回均匀权重；可尝试调整 Epsilon、检查样本分布或重建。
# 解算与动画烘焙
- 局部空间：采样与写回均基于节点 相对父级的变换（
getNonePoseTm /getNonePoseTmRot一类接口）。 - 四元数混合：对被驱动旋转采用与样本对齐半球后的加权混合策略（避免路径翻转）。
- 动画范围：烘焙使用当前时间轴
animationRange.start 与animationRange.end。
请在烘焙前确认时间范围覆盖所需片段，并做好场景备份。
# 配置文件（INI）格式
- 扩展名：
.ini - 顶层
[Meta]：ConfigCount、CurrentIndex（当前选中的配置序号）。 - 每个配置：
[Config_i]保存配置名、驱动槽数量、当前槽索引。 - 每个驱动槽：
[Config_i_Slot_j] 保存该槽显示名、RBFManagerData 扁平字段（驱动句柄/名称/父名、被驱动列表、Epsilon、正则、核类型、DriverRotationMode、样本数等）。 - 每个姿态：
[Config_i_Slot_j_Pose_k] 保存姿态名、驱动四元数字符串、每条被驱动的#(pos, quat, scale)字符串。
脚本 兼容旧版 INI：若某 Config_i 下没有 DriverSlotCount，则把整个节当作单槽扁平数据读入。
保存时会写入当前内存中全部配置；加载会替换 rbfConfigList 并刷新 UI。
# 节点解析与场景迁移
INI 中除节点 handle 外还保存 节点名 与 父节点名（rbfResolveNode），用于在新会话或引用变更后尽量找回对象。
限制说明：
- 句柄在 Max 会话内有效，跨会话依赖名称 + 父级匹配。
- 若重命名、重组层级或合并场景导致匹配失败，需在 UI 中重新拾取驱动并检查被驱动列表。
# 常见问题与注意事项
- 至少需要 2 个姿态样本 才能构建；状态栏会提示「需要构建 RBF」直到构建成功。
- 清除所有 只删样本，不删驱动与被驱动；删样本后须重新 创建姿势 并 构建 RBF。
- 新增被驱动 后，旧姿态中新通道无数据，需针对新骨骼补采样或重新录入姿势。
- Twist-X / Swing-Quat 与 Quat（Full） 的几何含义不同，请勿混用概念。
