SAM 二次开发指南：架构总览与系列索引 / SAM Secondary Development Architecture and Series Index

本系列依据本机 D:\Program Files\SAM、D:\wx702\OpenOLTranSim-main\SAMSDK 和已有 00～08 篇开发记录整理。SDK 有约 3000 个头文件，本系列选择二次开发主链上的 48 个核心类型，按职责拆分介绍。

1. 系列文章

文档	内容
09 架构总览与系列索引	启动流程、插件扫描、DLL/PYD/Python/C++ 职责边界
10 GUI、Toolset 与交互类 API	SAMApp、主窗口、Module、Toolset、Menu、Form、Dialog
11 命令桥、Python 与 PYD API	cmdGCommandDeliveryRole、omu*、pyoModule、Fragment
12 数据模型、Part 与 Mesh API	basBasis、basMdb、Model、Part、Feature、Node、Element
13 场景、显示表示与渲染 API	Scene、Editor、Renderer、显示/选择/高亮
14 编译、部署与故障排查	CMake、MSVC、DLL/PYD 复制、CLion 和常见错误

2. SAM 的整体架构

SAM 是 C++/Qt GUI、内嵌 Python 2.7、C++ PYD、Kernel 模型数据库和渲染系统组成的混合应用。

用户界面层
  SAMApp / SAMMainWindow / Module / Toolset / Form / Dialog
        |
        | 生成并发送 Python 命令
        v
命令桥
  cmdGCommandDeliveryRole / cmdGCommandDoneCB
        |
        v
Python 与扩展层
  mdb 用户 API / Python 脚本 / 业务 PYD
        |
        v
模型层
  basBasis / basMdb / basNewModel / ptoKPart / Feature / Mesh
        |
        v
显示层
  DisplayRep / gdyScene / gdyEditor / gdrRenderer

3. 从双击到主界面

3.1 sam.bat

本机启动文件：

D:\Program Files\SAM\Release\sam.bat

它配置 Python 2.7、PySide2、shiboken2、Qtitan、VTK、OCCT、HDF5、OrientCommon、ZeroMQ 等依赖路径，最后启动：

SAMCAE.exe

3.2 customApp.py

本机应用脚本：

D:\Program Files\SAM\SubModule\customApp.py

核心流程：

from SAMGuiPy import *

app = SAMApp(sys.argv)
app.init()

mw = SAMBasicMainWindow("Client")
mw.registerModule("Part", "Part")
mw.registerModule("Property", "Property")
mw.registerModule("Assembly", "Assembly")
mw.registerModule("Mesh", "Mesh")
mw.registerModule("Job", "Job")
mw.registerModule("Visualization", "Visualization")

mw.registerToolset(...)

app.create()
app.run()

对应步骤：

1. SAMCAE.exe 初始化 Qt、Kernel 和嵌入式 Python；
2. SAMApp.init() 初始化应用服务；
3. 创建 SAMBasicMainWindow；
4. 注册 Part、Mesh、Job 等 Module；
5. 注册内置 Toolset；
6. SAMApp.create() 创建界面和插件对象；
7. SAMApp.run() 进入 Qt 事件循环。

4. GUI Toolset DLL 的加载

本机已验证的插件目录：

D:\Program Files\SAM\Release\FilePlugin

Toolset DLL 通过 Qt 插件接口接入：

class SAMToolsetGuiInterface
{
public:
    virtual void registerToolset() = 0;
};

#define SAMToolsetGuiPlugin_iid "SAM.Pre.ToolsetGuiPlguin"
Q_DECLARE_INTERFACE(SAMToolsetGuiInterface,
                    SAMToolsetGuiPlugin_iid)

插件实现通常还需要 Q_PLUGIN_METADATA 和 Q_INTERFACES。SAM 发现插件后调用 registerToolset()，由插件创建并注册自己的 SAMToolsetGui。

FilePlugin 的完整目录遍历和失败处理位于 SAM 私有二进制中；公开 SDK 可以证实插件接口和加载入口，但不能证明私有扫描算法的全部细节。

5. PYD 的加载

PYD 是 Windows CPython 原生扩展模块，由 Python 执行以下命令时加载：

import YourModule

本机常用部署目录：

D:\Program Files\SAM\Release

PYD 不是 Qt Toolset 插件，不由 FilePlugin 的 GUI 插件接口加载。

6. DLL、PYD、Python 和 Kernel 的职责

GUI Toolset DLL

• 注册菜单、工具栏和面板；
• 创建 Form、Dialog、按钮和 Qt 信号槽；
• 收集参数和取得当前 GUI 上下文；
• 生成 Python 命令并显示执行结果；
• 处理临时高亮、交互和视口刷新。

Python

• 提供 mdb.models[...] 等用户级 API；
• 编排可回放、可批处理的业务流程；
• 调用 PYD 暴露的 C++ 算法；
• 组织命令、宏和自动化脚本。

PYD

• 将 C++ 函数、类和 Fragment 注册给 Python；
• 访问底层 Model、Part、Feature 和 Mesh；
• 运行大量节点/单元或高性能算法；
• 将结果包装为 Python 可识别对象。

SAM Kernel

• 保存真正的模型数据库；
• 执行建模、网格、材料、载荷和分析命令；
• 返回结果和异常；
• 通知 GUI 更新模型树和场景。

7. 一次菜单操作的完整调用链

用户点击菜单
  -> GUI DLL 中的 QAction 槽函数
  -> 启动 SAMForm/SAMDataDialog
  -> 收集和校验参数
  -> 生成 Python 命令字符串
  -> cmdGCommandDeliveryRole
  -> SAM Python/Kernel
       +-- 直接操作 mdb
       `-- import 业务 PYD
             `-- C++ 访问 Part/Mesh 或执行算法
  -> 返回 Reply/异常
  -> GUI 弹窗和 Message Area
  -> 模型树/Scene 更新

如果功能只是弹出警告框，调用链可以在 GUI DLL 内结束；如果需要修改可保存的 Part，则必须进入模型层，而不是只在 Renderer 中画几条线。

8. SAM 的底层数据主链

basBasis
  `-- basMdb
        `-- basModelMap
              `-- basNewModel
                    `-- ptoKPartRepository
                          `-- ptoKPart
                                `-- ftrFeatureList
                                      `-- bmeMesh / omeMesh
                                            +-- bmeNodeData
                                            +-- bmeElementData
                                            `-- bmeElementClass

Python 中：

mdb.models['Model-1'].parts['Part-1']

是该 C++ 数据结构的用户级包装视图。详细 API 见第 12 篇。

9. 模型和渲染的边界

Model/Part/Feature/Mesh
  -> DisplayRep
  -> Scene
  -> Editor
  -> Renderer

• 面积和坐标是计算结果；
• Part、Feature 和 Mesh 是模型数据；
• DisplayRep 和 Scene 是显示数据；
• Renderer 负责把点、线、面真正画出来。

因此“计算成功”不等于“模型已创建”，也不等于“视口已经生成图形”。详细内容见第 13 篇。

10. 48 个核心类型的分类

分类	数量	代表类型
应用、窗口、Module、Toolset、菜单	9	SAMApp、SAMMainWindow、SAMModuleGui、SAMToolsetGui
Mode、Form、Dialog	5	SAMGuiMode、SAMForm、SAMDialog、SAMDataDialog
命令桥	3	cmdGCommandDeliveryRole、cmdGCommandDoneCB
Python/PYD 绑定	11	omuPrimitive、omuArguments、pyoModule、Fragment
数据模型与网格	13	basBasis、basMdb、ptoKPart、bmeMesh
场景与渲染	7	gdyScene、gdyEditor、gdrRenderer
合计	48	本系列主链类型，不是 SAM 全部类型

11. 推荐阅读顺序

1. 先读本篇，理解 SAM 的总体边界；
2. 开发菜单和弹窗时读第 10 篇；
3. 需要调用 PYD 或发送命令时读第 11 篇；
4. 需要读取 Part、节点、单元时读第 12 篇；
5. 需要显示图形、选择和高亮时读第 13 篇；
6. 编译或运行失败时查第 14 篇。

12. 最关键的认识

1. Toolset DLL 和 PYD 是两条不同的加载链。
2. DLL 负责 GUI 接入，PYD 负责 Python 可调用的 C++ 能力。
3. 复制文件只解决发现，不建立 DLL 与 PYD 的业务通信。
4. Python 用户 API 是底层 C++ 模型对象的包装视图。
5. 修改模型和显示图形是两个阶段。
6. 最稳定的开发流程是：GUI 收参 → Python 命令 → PYD/Kernel → 更新模型 → 更新场景 → GUI 反馈。