|
|
# FreeCAD FCStd 电气设备模板制作设计
|
|
|
|
|
|
## 1. 目标
|
|
|
|
|
|
把普通 STEP / STP / STE 几何模型加工成可复用的 `.FCStd` 电气设备模板。
|
|
|
|
|
|
模板保存设备几何和端子槽位语义。后续不同工程、不同人员导入这个 FCStd 时，FreeCADExchange 能识别其中的端子 LCS，并把工程里的真实 `terminal_uuid` 绑定到这些槽位上。
|
|
|
|
|
|
## 2. 非目标
|
|
|
|
|
|
- 不修改 FreeCAD C/C++ 内核。
|
|
|
- 不在模板文件里保存工程级 `terminal_uuid`、`project_uuid`、`instance_id`。
|
|
|
- 不做自动布线。
|
|
|
- 不把完整接线路径写入数据库。
|
|
|
- 不要求第一版做完整 UI 面板。
|
|
|
|
|
|
## 3. 核心原则
|
|
|
|
|
|
STEP / STP / STE 是几何输入，FCStd 是正式设备模板输出。
|
|
|
|
|
|
模板端子描述“这个设备模型哪里可以接线”。工程端子描述“当前工程的哪个 2D 端子绑定到哪个 3D 端子对象”。两者不能混用。
|
|
|
|
|
|
## 4. 模板文件结构
|
|
|
|
|
|
以电流互感器为例：
|
|
|
|
|
|
```text
|
|
|
电流互感器.FCStd
|
|
|
ModelGeometry
|
|
|
Terminal_P1
|
|
|
Terminal_P2
|
|
|
```
|
|
|
|
|
|
`Terminal_P1` 和 `Terminal_P2` 是 LCS 对象。它们的位置就是模型上真实接线位置，方向就是后续出线方向参考。
|
|
|
|
|
|
## 5. 模板端子属性
|
|
|
|
|
|
模板端子至少写入：
|
|
|
|
|
|
```text
|
|
|
Role = Terminal
|
|
|
CanWire = true
|
|
|
QetTemplateSlotName = P1
|
|
|
QetTerminalLabel = P1
|
|
|
QetTerminalType = primary
|
|
|
```
|
|
|
|
|
|
模板端子不写入：
|
|
|
|
|
|
```text
|
|
|
QetProjectUuid
|
|
|
QetElementUuid
|
|
|
QetTerminalUuid
|
|
|
QetInstanceId
|
|
|
```
|
|
|
|
|
|
这些字段只属于具体工程场景。
|
|
|
|
|
|
## 6. 新模块
|
|
|
|
|
|
新增模块：
|
|
|
|
|
|
```text
|
|
|
src/Mod/FreeCADExchange/TemplateAuthoring.py
|
|
|
```
|
|
|
|
|
|
职责：
|
|
|
|
|
|
- 创建模板端子 LCS。
|
|
|
- 给 LCS 写入模板语义属性。
|
|
|
- 校验当前文档中的模板端子。
|
|
|
- 保存或辅助保存 `.FCStd` 模板。
|
|
|
|
|
|
不负责：
|
|
|
|
|
|
- 工程 `2d_to_3d.json` 导入。
|
|
|
- 工程端子 UUID 绑定。
|
|
|
- 手动连线。
|
|
|
- `3d_to_2d.json` 回写。
|
|
|
|
|
|
## 7. 第一版命令
|
|
|
|
|
|
第一版先做两个命令：
|
|
|
|
|
|
```text
|
|
|
QET_Template_AddTerminal
|
|
|
QET_Template_ValidateTerminals
|
|
|
```
|
|
|
|
|
|
`QET_Template_AddTerminal`：
|
|
|
|
|
|
1. 用户选择一个模型对象或模型上的点位。
|
|
|
2. 执行命令。
|
|
|
3. 输入端子槽位名，例如 `P1`。
|
|
|
4. 在选择位置创建 LCS。
|
|
|
5. 自动写入模板端子属性。
|
|
|
|
|
|
`QET_Template_ValidateTerminals`：
|
|
|
|
|
|
1. 扫描当前文档中的端子 LCS。
|
|
|
2. 检查是否有 `Role="Terminal"`。
|
|
|
3. 检查是否有 `QetTemplateSlotName`。
|
|
|
4. 输出端子列表和问题。
|
|
|
|
|
|
保存动作第一版直接使用 FreeCAD 自带保存为 `.FCStd`。后续再补 `QET_Template_SaveAsFCStd`。
|
|
|
|
|
|
## 8. 第一版点位策略
|
|
|
|
|
|
第一版按简单稳定策略实现：
|
|
|
|
|
|
1. 如果用户选择对象的子元素，并且能取到选择点，就使用该点。
|
|
|
2. 如果只能选到对象，则使用对象包围盒中心。
|
|
|
3. 如果没有选择，则拒绝创建端子。
|
|
|
|
|
|
端子方向第一版使用默认旋转。后续再增加方向编辑，例如沿面法向、沿用户选择边方向或手动输入轴角。
|
|
|
|
|
|
## 9. 与现有导入流程的关系
|
|
|
|
|
|
现有项目导入流程保持不变：
|
|
|
|
|
|
```text
|
|
|
ExchangeBootstrap
|
|
|
-> DeviceImport
|
|
|
-> TerminalImport
|
|
|
-> ExchangeWriteBack
|
|
|
```
|
|
|
|
|
|
`TerminalImport` 已经支持读取 FCStd 模板中的 `Role="Terminal"` LCS。模板制作工具只负责把这些 LCS 方便、规范地放进 FCStd。
|
|
|
|
|
|
项目导入时的优先级仍是：
|
|
|
|
|
|
1. FCStd 模板 LCS。
|
|
|
2. sidecar JSON。
|
|
|
3. bbox fallback。
|
|
|
|
|
|
## 10. 用户流程
|
|
|
|
|
|
以电流互感器为例：
|
|
|
|
|
|
1. 打开 FreeCAD。
|
|
|
2. 导入 `电流互感器.step`。
|
|
|
3. 选择 P1 接线位置。
|
|
|
4. 执行 `QET_Template_AddTerminal`，输入 `P1`。
|
|
|
5. 选择 P2 接线位置。
|
|
|
6. 执行 `QET_Template_AddTerminal`，输入 `P2`。
|
|
|
7. 执行 `QET_Template_ValidateTerminals`。
|
|
|
8. 保存为 `电流互感器.FCStd`。
|
|
|
9. 在 LightWork3D 设备 3D 资源中使用该 FCStd。
|
|
|
|
|
|
## 11. 验收标准
|
|
|
|
|
|
- 能从普通 STEP 模型创建 `Terminal_P1` 和 `Terminal_P2`。
|
|
|
- 端子对象是 LCS。
|
|
|
- 端子对象带 `Role="Terminal"` 和 `CanWire=true`。
|
|
|
- 端子对象带 `QetTemplateSlotName`。
|
|
|
- 保存为 FCStd 后重新打开，端子和属性仍存在。
|
|
|
- 使用该 FCStd 作为工程模型时，端子位置来自模板 LCS，不再使用 bbox fallback。
|
|
|
|
|
|
## 12. 风险和处理
|
|
|
|
|
|
选择点不可用：
|
|
|
|
|
|
- 第一版退回对象包围盒中心。
|
|
|
- 如果连对象也没有选择，则直接提示错误。
|
|
|
|
|
|
端子重名：
|
|
|
|
|
|
- 第一版自动使用唯一对象名，例如 `Terminal_P1_1`。
|
|
|
- `QetTemplateSlotName` 保持用户输入，用于槽位语义。
|
|
|
|
|
|
模板里混入工程端子属性：
|
|
|
|
|
|
- 校验命令提示警告。
|
|
|
- 第一版不自动删除，避免误删用户数据。
|
|
|
|
|
|
方向不准确：
|
|
|
|
|
|
- 第一版只保证位置和语义。
|
|
|
- 后续补方向编辑命令。
|
|
|
|
|
|
## 13. 实施顺序
|
|
|
|
|
|
1. 新增 `TemplateAuthoring.py`。
|
|
|
2. 在 `CMakeLists.txt` 加入该模块。
|
|
|
3. 在 `InitGui.py` 注册模板命令。
|
|
|
4. 实现添加端子命令。
|
|
|
5. 实现校验命令。
|
|
|
6. 增加 Python 单元测试，覆盖属性写入和校验逻辑。
|
|
|
7. 用电流互感器模型手工验证一次完整流程。
|