SAM 参数化构件建模：从二维轮廓到三维网格 / SAM Parametric Component Modeling from 2D Profiles to 3D Meshes
📅 创建时间：2026-07-23
🏷️ 标签：#SAM #参数化建模 #CM2 #局部坐标 #增量网格
📚 前置知识：04-cpp-sdk-mesh-api
📖 系列导航：总目录 · 上一篇：04-cpp-sdk-mesh-api · 下一篇：06-agent-plugin-architecture
第7部分：参数化构件的完整执行链
以吊耳为例：
用户点击 Lug Modeling
↓
Qt 对话框输入 V/H/R、网格尺寸并选择3个节点
↓
GUI 校验参数
↓
omuArguments 组织命名参数
↓
omuMethodCall 调用 Part.createLiftingLug(...)
↓
C++ Fragment 取得当前 ptoKPart 和 bmeMesh
↓
三个节点建立局部坐标系
↓
直线/圆弧构造二维外轮廓和孔轮廓
↓
CM2 生成二维网格
↓
局部坐标映射到三维
↓
SAMReMesh.createNewElement2 增量写入
↓
必要时调用 Python 2 合并接触节点
↓
刷新 Mesh 与 Viewport参数化不是“把几个参数塞入一条 SAM 命令”，而是：
参数定义几何
+
几何定义拓扑边界
+
网格器生成连接关系
+
SAM 接口把结果写入当前模型参数与局部坐标的约束
参数首先要形成可验证的领域对象。长度和半径必须统一单位并满足几何不等式，网格尺寸需要大于数值容差且与最小特征相容。三个选中节点用于建立局部坐标系时，不能重合或近似共线；否则叉积长度接近零，归一化会放大误差并产生不稳定方向。
origin = P0
ex = normalize(P1 - P0)
ez = normalize(ex × (P2 - P0))
ey = ez × ex
local(u,v,w) -> origin + u*ex + v*ey + w*ez构造后要检查三个基向量的长度、正交性和手性，并记录从局部到全局的变换。轮廓在局部二维平面生成，能够简化直线、圆弧、孔和网格尺寸控制；最终写入模型前再统一映射到三维，避免几何算法同时承担任意空间方向。
从轮廓到有效网格
二维外边界和孔边界必须形成方向一致、无自交的闭合环。几何看起来正确，不代表网格器能够识别拓扑；短边、重复点、接近相切的圆弧和小于容差的间隙都可能导致失败。调用 CM2 前应生成诊断摘要，包括边界数量、包围盒、最小边长和目标网格尺寸。
网格生成后至少检查节点与单元数量、连接索引范围、退化单元、重复节点、法向方向和边界保留情况。增量写入不能假设新节点编号从旧数量连续递增，应使用 SAM 返回的稳定标识或显式映射。若写入中途失败，应撤销整个命令，不能在 Part 中留下半个构件。
与文档事务和撤销协作
参数对话框只收集意图，不直接逐步修改 Mesh。确认后创建一次 Command：冻结输入参数和选中节点，完成计算与校验，再以事务方式提交新增实体。撤销信息保存新增节点、单元和集合的稳定 ID，而不是临时数组下标。后台生成时还要携带 Part revision；用户已编辑模型后，旧结果应被拒绝或要求重新计算。
刷新 Viewport 是提交后的表现层动作。场景更新失败不应使领域网格回滚到未知状态，反过来渲染缓存也不能成为模型真相。模型成功后由变更事件驱动场景重建，便于测试和恢复。
失败处理与验收
参数化构件的验收不止是“视口里看到了形状”。需要保存并重新打开模型，核对节点、单元、集合和方向；导出求解输入，确认连接和属性引用完整；对典型尺寸、极限尺寸、反向节点顺序和共线节点分别测试。任何失败都应指出发生在参数、坐标、轮廓、网格还是提交阶段。
只有当相同参数和参考节点能够稳定重建等价拓扑，且错误输入不会污染当前 Part，参数化建模才从演示脚本成为可靠工程能力。
同时应保存参数 Schema 版本，使旧模型在参数含义变化后能够迁移或给出明确诊断。
参数 Schema
参数化构件首先需要稳定的参数契约。
每个字段至少定义：
- 稳定名称；
- 显示名称；
- 数据类型；
- 物理单位；
- 默认值；
- 最小和最大范围；
- 是否必填；
- 与其他字段的约束；
- Schema 版本；
- 迁移规则。
LugParameters v1
├─ width: Length > 0
├─ height: Length > 0
├─ outerRadius: Length
├─ holeRadius: Length
├─ thickness: Length
├─ meshSize: Length > tolerance
└─ referenceNodeIds[3]参数校验不能只在 GUI 中实现。 脚本、批处理和插件调用都必须复用相同领域校验。
跨字段约束示例：
- 孔半径小于外半径；
- 边缘净距满足最小值；
- 厚度与目标单元类型兼容；
- 网格尺寸能解析最小几何特征；
- 参考节点属于当前 Part；
- 参考节点没有重复；
- 当前 Mesh revision 与选择时一致。
错误消息应指出字段、输入值和违反的约束。
参数快照与可重复性
命令启动时冻结参数快照。 后台计算不能继续读取仍可编辑的对话框控件。
UI draft
-> validate
-> immutable parameter snapshot
-> geometry and mesh generation
-> transactional commit快照包含单位归一化后的值、参考实体稳定 ID、Part revision 和算法版本。
相同快照在相同算法版本下应生成拓扑等价结果。 节点编号可以不同，但几何、连接、集合和属性应满足等价规则。
局部坐标构造
三个点定义局部平面时，需要选择明确约定。
P0: origin
P1: positive local X direction
P2: selects local plane and positive normal计算流程：
vx = P1 - P0；- 检查
|vx|大于长度容差； temp = P2 - P0；vz = cross(vx, temp)；- 检查
|vz|大于面积相关容差； - 归一化
ex和ez； ey = cross(ez, ex)；- 检查正交性和手性；
- 建立正向和逆向变换。
绝对固定容差不适合所有模型尺度。 可以基于包围盒和输入长度定义相对容差，并设置合理上下限。
参考点顺序改变会翻转法向。 界面应预览方向，并允许用户确认或反转。
二维轮廓表示
轮廓不应只是一组无类型点。 它由有方向的线段、圆弧和闭合 Loop 组成。
Profile
├─ OuterLoop: CCW
│ ├─ Line
│ ├─ Arc
│ └─ Line
└─ InnerLoop: CW
└─ Circle / Arc sequence外环和孔环使用一致方向约定。 网格器才能判断材料区域和空洞。
轮廓校验包括：
- 首尾闭合；
- 连续端点在容差内一致；
- 无自交；
- 孔位于外环内部；
- 多孔之间不相交；
- 曲线长度大于容差；
- 圆弧半径有效；
- 切向和方向符合设计。
几何离散
曲线进入网格器前可能需要离散为边界点。 离散误差应与网格尺寸和曲率相关。
圆弧分段太少会显著改变孔和应力集中几何。 分段过多则增加网格规模和短边问题。
可以依据最大弦误差或最大角度选择分段。
arc segments = max(
minimumSegments,
segmentsForChordTolerance,
segmentsForMeshSize)离散策略属于算法版本的一部分。 修改策略后，旧参数模型重新生成可能得到不同网格。
CM2 输入准备
调用网格器前形成独立输入对象：
- 局部二维节点；
- 有向边；
- Loop 与孔；
- 目标尺寸；
- 局部加密；
- 单元类型；
- 质量限制；
- 边界标签；
- 算法选项。
网格器不应直接修改当前 Part。 它先返回临时候选网格和诊断。
网格结果校验
候选网格必须通过结构检查：
- 节点坐标有限；
- 单元索引在范围内；
- 无重复连接；
- 面积或体积大于容差；
- 单元方向一致；
- 边界标签完整；
- 孔没有被填充；
- 外边界没有缺口；
- 没有孤立节点；
- 质量统计可接受。
质量阈值应与单元类型和求解用途一致。 只检查平均质量会隐藏少量严重退化单元。
映射到三维
二维节点通过局部基映射到全局坐标。
global = origin + u * ex + v * ey映射后检查点到目标平面的距离和坐标有限性。
如果构件具有厚度或拉伸方向，还需要定义局部 w 和层数。 壳、实体和梁模型使用不同离散策略，不能只在最后切换单元类型。
增量写入
写入 SAM 前建立显式映射：
temporary node index -> SAM node ID
temporary element index -> SAM element ID
boundary tag -> SAM Set不要假设返回 ID 连续，也不要用旧节点数量推算新 ID。
如果新构件需要与现有 Mesh 合并，先在候选状态计算匹配关系。 合并容差、优先级和冲突处理必须明确。
写入过程由事务管理。 任何节点、单元或 Set 创建失败，都撤销本次新增。
撤销与重做
Command 保存：
- 参数快照；
- 参考实体稳定 ID；
- 新增节点 ID；
- 新增单元 ID；
- 新增 Set 和属性；
- 被合并实体的变更；
- 提交前后 revision。
撤销按依赖反序删除。 重做可以复用已验证快照重新生成，或恢复完整差异，具体取决于确定性和成本。
如果算法版本已变化，重做不应悄悄使用新算法生成不同拓扑。
视图与交互
参数输入阶段可以显示轻量预览。 预览不是 Document 真相，取消对话框后应直接丢弃。
提交成功后发出领域变更事件：
Document changed
-> table and tree models update
-> scene generation increments
-> render buffers rebuild
-> selection restored by stable IDsViewport 刷新失败不应回滚已经成功提交的领域事务。 渲染层可以根据 Document 重试重建。
后台执行与取消
大网格生成可以在 Worker 中运行。
任务输入包含不可变参数、参考点坐标和 Part revision。 Worker 只生成候选数据，不直接操作 GUI 或当前 Part。
取消检查点包括：
- 轮廓构造后；
- 网格器阶段之间；
- 质量扫描分块之间；
- 提交前。
进入 Document 事务后，取消要么在提交前生效，要么等待原子提交完成。 不能在一半写入时退出。
性能与内存
参数化构件性能分解为：
- 参数和选择校验；
- 坐标构造；
- 轮廓离散；
- CM2 网格；
- 质量检查；
- 三维映射；
- SAM 写入；
- Set 与合并；
- 场景重建。
测量端到端时间和峰值内存。 避免为每个节点创建重量级对象，优先使用连续数组和批量接口。
验证矩阵
测试至少包含：
- 标准尺寸；
- 最小允许尺寸；
- 大尺寸与细网格；
- 孔接近外边界；
- 反向参考点；
- 重复参考点；
- 近共线参考点；
- 不同模型尺度；
- 已有 Mesh 合并；
- 生成中取消；
- 保存和重开；
- 撤销和重做；
- 导出求解文件；
- 求解器读入；
- 旧参数 Schema 迁移。
每个失败必须确认当前 Part 没有被污染。
完成标准
可靠参数化能力应满足：
- 参数契约版本化；
- 输入错误可诊断；
- 坐标方向可预览；
- 轮廓和网格通过结构校验；
- 写入是原子事务；
- 撤销重做可靠；
- 后台结果受 revision 保护；
- 保存重开保持语义；
- 导出与求解验证通过；
- 性能在目标规模内可接受。