FMB Viewer

Appearance

面组染色 ​

面组(FaceGroupId)是比节点更细的染色粒度:叶子节点的网格按来源 CAD 的 BREP 面划分成面组,viewer.model.setFaceGroupColor() 可以只给节点内的单个面组设覆盖色,而不影响零件其余表面。整件染色用节点级的 setNodesColor(),两者都是可撤销的覆盖色,不改原始材质。

下面的 demo 给每个叶子零件的 0 号面组染上调色板色,直观展示「一个零件内只有部分面变色」:

可交互 demo · 每个叶子零件的 0 号面组已被染色,鼠标拖拽旋转,空格键 fit在新窗口打开 ↗

核心 API ​

ts
import { SelectionMask, colorFromHex } from "@modelcubes/viewer-core";

// 拾取拿到面组 id(节点 id + 面组 id 成对出现)
const item = viewer.selection.pick(x, y, SelectionMask.Face);
if (item?.faceGroupId !== undefined) {
  viewer.model.setFaceGroupColor(item.nodeId, item.faceGroupId, colorFromHex(0xff5566));
}

// 撤销单个 / 查询 / 全部清除
viewer.model.unsetFaceGroupColor(nodeId, fgId);
viewer.model.getFaceGroupColor(nodeId, fgId); // 未设置过返回 null
viewer.model.resetFaceGroupColors();

行为要点 ​

  • FaceGroupId 概念:面组对应来源 CAD 模型的 BREP 面分组,是节点内部的细分单元。所有面组 API 都成对接受 (nodeId, faceGroupId)——面组 id 以节点为作用域使用。
  • 获取面组 id 的途径:拾取(viewer.selection.pick / pickBox,掩码含 SelectionMask.Face 时命中项带 faceGroupId)、selection-changed / hover-changed 事件里的 SelectionItem,以及 SVG 导出输出的 data-face-group-id 属性。
  • 与节点级染色的区别:setNodesColor(ids, color) 覆盖整个零件的所有表面,适合按状态给整件着色(如 BOM 高亮、检索结果标记);setFaceGroupColor 只染节点内单个面组,适合标记加工面、配合面等局部特征。两者都是覆盖色,经各自的 unset* / reset* 撤销后恢复原始材质色。
  • 撤销与查询:unsetFaceGroupColor(id, fg) 撤销单个面组,resetFaceGroupColors() 清除全部面组级覆盖;getFaceGroupColor(id, fg) 未设置过返回 null。
  • 前置条件:染色类方法要求模型已加载,否则抛 ViewerError(ModelNotLoaded)。

相关 API ​