# 3D 机械图建模与 GLB 转换注意事项

> 面向本程序（网页 3D 查看 + 每部件独立着色）的建模与导出规范。
> 演示程序：`3d/`（FastAPI 服务端 + Ant Design Vue 客户端），
> 运行 `python3 3d/backend/run.py`，模型放 `3d/models/*.glb`。详见 `3d/README.md`。

---

## 一、核心原则（务必理解）

网页"给某个部件上色"＝ 该部件在模型里是一个**独立的、可识别的对象**。

- 换色只认"对象"（glTF 里的 node/网格），不认颜色。CAD 里给部件涂了什么颜色**不会**传到网页。
- 所以：**每个要单独上色的零件，必须是一个独立实体/独立网格**，绝不能合并成一个整体再导出。
- 部件的"名字"会成为网页里部件列表的名字，命名请规范、有意义。

一句话：**"一个零件 = 一个独立体 + 一个有意义的名字"，导出后即可选可着色。**

---

## 二、通用要求（不管用哪个 CAD）

| 项目 | 要求 | 原因 |
|---|---|---|
| 零件结构 | 一个实体对应一个部件，不要布尔合并后导出 | 每部件才能独立选/着色 |
| 零件命名 | 有意义、稳定、**推荐英文/数字 + 下划线**（如 `piston_01`、`crank_02`）；避免空格和特殊字符 | 名字会变成网页部件名；避免部分工具链/编码坑 |
| 隐藏/基准 | 基准面、草图、坐标系、辅助线、被抑制/隐藏的零件**不要导出** | 防止出现多余对象 |
| 精度(三角面) | 圆柱/圆弧分段适中；螺纹、微小倒角、装饰纹如果让网格暴涨就简化或抑制 | 面数决定 glb 体积和浏览器流畅度 |
| 参考量级 | 单个部件几千~几万面即可；整机几十万~几百万面网页没问题（当前演示发动机 glb≈1.8MB/115 部件） | — |
| 单位 | 统一用 mm | 减少混乱（网页端会自动适配大小，单位不影响显示） |
| 朝向 | CAD 一般是 Z 轴朝上，glTF/three.js 是 Y 轴朝上，**导出时绕 X 轴旋转 -90°** 或由脚本处理 | 否则模型"躺着"，底部网格方向不对 |
| 材质/颜色 | 不用管 CAD 外观颜色；需要默认底色时在导出脚本里给每个部件指定一个 albedo 色即可 | 网页按状态实时上色 |
| 对称/阵列/镜像 | 可导出为多个独立零件（程序会自动显示为 `名称 [2]`、`[3]`） | 每个实例可独立着色 |
| 部件数量 | 数百个部件体验良好（当前演示 115 个）；上千时需优化遍历/列表 | — |

---

## 三、SolidWorks 注意事项

1. **输出格式首选：装配体另存为 STEP（`.step`）**
   - 保留装配树和零件结构/名称，是后续转 GLB 最稳的中间格式。
2. SolidWorks 不导出 glTF，**不要直接指望"另存为"里有 glb**。
3. 若你只想快速看效果：`文件 → 另存为 → STL`（勾选"保存为装配体结构/各实体分开"相关选项），但 STL 是单色无结构，一般不如走 STEP 路线。
4. 导出 STL 精度在"选项 → 输出"里用**自定义**分辨率，控制弦高/角度误差，别用最细档把面数堆爆。
5. 导出前检查：零部件是否被"轻化/抑制/隐藏"；装配配合隐藏不影响导出但会多零件。
6. 命名在特征树里就写好，SolidWorks 零件名会被带到 STEP 再带到 GLB。

---

## 四、FreeCAD 注意事项

1. **FreeCAD 主要担任"转换器"**：打开 STEP → 逐实体输出网格。它不是必需环节，但开源免费、可脚本化（`freecadcmd` 无界面批量跑）。
2. **GLB 导出现状**：FreeCAD 稳定版**没有内置可靠的 glb 导出**。
   - 自验：`文件 → 导出`，看格式列表里有没有 glTF/glb；若你的版本有，选"整个文档"导出即可，其它步骤全免。
   - 没有的话，用下面第五节脚本管线。
3. 导入 STEP 后，用**树视图确认每个零件是独立对象**；用 Part 容器/装配工作台组织好再导出。
4. 实体 → 网格精度：`MeshPart.meshFromShape` 的 **LinearDeflection（线性偏差）** 参数，毫米单位建议 0.05~0.2mm，越小越精细、文件越大；大平面用角度参数控制。
5. FreeCAD 里的外观颜色同样不会进网页，可忽略。

---

## 五、STEP → GLB 推荐转换管线

> 目标产物：`xxx.glb`（每部件一个 node + 独立材质，node 名=CAD 部件名），放 `3d/models/` 即完成接入。

**管线 A（推荐，免费可脚本化）**
```
SolidWorks/FreeCAD 装配体
        │  导出
        ▼
STEP (.step，含装配结构+名称)
        │  freecadcmd 脚本 或 CadQuery (Python)
        ▼
逐实体转网格(精度参数控制) → 按部件名收集
        │  trimesh / pygltflib 打包
        ▼
xxx.glb   (每部件 = 1 节点 + 1 独立材质，白/默认色)
```

- 每部件节点名 = CAD 零件名 → 网页部件列表、上色、持久化全部自动对上。
- 需要的脚本我可以直接帮你写好（含轴旋转 -90° 处理 Z→Y up）。

**管线 B（有 Blender 时）**
FreeCAD 导出 STEP → Blender 导入(实体) → 需重建部件命名 → 导出 glb。适合手工调整，自动化不如 A。

**管线 C（预算充足，最省心）**
CAD Exchanger SDK / Datakit CrossManager：一条命令 STEP→GLB，保留部件名，支持命令行/API 集成。

---

## 六、交付自检清单

打开网页（`python3 3d/backend/run.py`，默认 http://127.0.0.1:5182）后逐项确认：

- [ ] 顶部下拉能选到你的模型
- [ ] 部件列表数量、名称与你 CAD 里的零件对应
- [ ] 点任意部件：能选中高亮（蓝色描边）
- [ ] 给它设"正常/预警/故障/停机"颜色，刷新页面后颜色仍在
- [ ] 模型朝上方向正确（不是躺着）
- [ ] 页面加载流畅、无卡顿（面数是否过高）
- [ ] 放大细节不糊得离谱（面数是否过低）