viewer.explode — ExplodeManager

设计意图

viewer.explode 是零件爆炸域:按结构树把零件沿「自身中心 − 模型中心」方向散开,用于观察装配内部。核心抽象是爆炸程度是一个 0–1 的连续量——set(scale) 而不是开 / 关,滑块、动画、分步演示都建立在这个连续参数上;ExplodeOptions 提供两个形态旋钮(magnitude 散开倍率、depthDampening 深度衰减)与动画开关。

爆炸是纯视图态:不修改模型数据,只给实例叠加偏移,reset() 一步复原,切换模型自动复位。个别零件可锁定在原位(lockNodes,典型如底座 / 机架),锁定按叶子记账,非叶节点自动展开到其叶子。零件被推出原始包围盒时,引擎同步外扩场景包围球并广播 model-bounds-changed,相机 near / far 自动适配,散开的零件不会被裁掉。

何时用它:装配讲解与拆解演示、检查被遮挡的内部零件、配合 getNodeOffset 给散开零件挂自定义标注。「隐藏外壳看内部」的另一条路是节点显隐,归 viewer.model。

典型用法

滑块连续驱动爆炸程度(0 = 复原,1 = 完全散开,默认带约 400ms 缓动):

slider.oninput = () => viewer.explode.set(Number(slider.value)); // 0–1
resetBtn.onclick = () => viewer.explode.reset(); // 立即复原,无动画

锁定底座再爆炸(深层装配用深度衰减防内层飞太远):

viewer.explode.lockNodes(viewer.model.findNodesByName("BASE_FRAME"));
viewer.explode.set(0.8, { magnitude: 5, depthDampening: 1 });
// ……结束演示
viewer.explode.clearLocks();
viewer.explode.reset();

给散开的零件挂标注(偏移是世界单位 Vec3,无偏移返回零向量):

const off = viewer.explode.getNodeOffset(nodeId); // 无偏移返回零向量
label.moveTo(anchor.x + off.x, anchor.y + off.y, anchor.z + off.z);

注意事项

• 未加载模型时 set 静默返回,不抛错;scale 超出 0–1 自动钳制。
• magnitude / depthDampening 一经设置即保留,后续 set 不传也沿用;默认值 magnitude 4、depthDampening 0、animate true。
• 动画期间 getScale() 返回逐帧推进的即时值,不是目标值;reset() 等价于 set(0, { animate: false })。
• 爆炸会触发 model-bounds-changed(包围球按最大偏移外扩)——依赖模型包围信息的自定义逻辑要注意爆炸态下的值已不是原始模型包围。
• 锁定按叶子记账:lockNodes / unlockNodes 接受单个或数组,非叶节点展开到叶子;isLocked(id) 也按叶子查询;已处于爆炸状态时锁定 / 解锁立即重算偏移。

完整签名与延伸

• ExplodeManager — 全部方法的精确签名。
• ExplodeOptions — 散开倍率 / 深度衰减 / 动画选项。
• 指南:爆炸视图 — 行为要点逐条说明与可交互 demo。
• 概念:事件系统 — model-bounds-changed 事件参考。