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 注意事项

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

四、FreeCAD 注意事项

FreeCAD 主要担任"转换器"：打开 STEP → 逐实体输出网格。它不是必需环节，但开源免费、可脚本化（freecadcmd 无界面批量跑）。
GLB 导出现状：FreeCAD 稳定版没有内置可靠的 glb 导出。
- 自验：文件 → 导出，看格式列表里有没有 glTF/glb；若你的版本有，选"整个文档"导出即可，其它步骤全免。
- 没有的话，用下面第五节脚本管线。
导入 STEP 后，用树视图确认每个零件是独立对象；用 Part 容器/装配工作台组织好再导出。
实体 → 网格精度：MeshPart.meshFromShape 的 LinearDeflection（线性偏差） 参数，毫米单位建议 0.05~0.2mm，越小越精细、文件越大；大平面用角度参数控制。
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 里的零件对应
点任意部件：能选中高亮（蓝色描边）
给它设"正常/预警/故障/停机"颜色，刷新页面后颜色仍在
模型朝上方向正确（不是躺着）
页面加载流畅、无卡顿（面数是否过高）
放大细节不糊得离谱（面数是否过低）

建模与GLB转换指南.md 5.7 KB Histórico Raw