param-3d-glb · trimesh 参数化建模

环境准备

pip install -r requirements.txt

⚠️ openCV 二选一，务必按环境选：

Overview

用 Python 代码（trimesh + shapely）直接构建规则几何体的 GLB 模型。核心价值：面数 ×10 体积只 ×3~4——实测冰箱模型 33 零件 / 1,632 面仅 30 KB，比 AI 生成的同类模型（19.5~47.5 MB）小 1000 倍，且无贴图、无版权风险、任何 GLB 查看器直接兼容。规则几何体（家电/家具/箱体）优先走此路线，AI 生成留给曲面物体。

v1.1 新增能力：
- 图片输入工作流（回转体方向）：从一张侧面照片提取轮廓 → revolve 成 3D（瓶/罐/杯/灯罩）
- 布尔运算 boolean_op()：挖孔、切角、开口（需 manifold3d）
- 细分圆角 fillet()：直角盒磨圆成小家电/外壳质感
- 贴图材质 pbr_textured()：256/512px PBR 贴图（可选，纯色/贴图双模式）

适用判断

Workflow

Step 1 · 环境检查

Python 环境需安装（venv 内）：

pip install trimesh shapely mapbox-earcut "pyglet<2" opencv-python-headless manifold3d

• 缺 mapbox-earcut 时 extrude_polygon 会报三角化错误且不提示缺哪个包
• pyglet 必须 <2（2.x 与 trimesh 的 save_image 不兼容）
• opencv-python-headless：example_bottle.py 图片轮廓提取需要
• manifold3d：boolean_op 布尔引擎（纯 pip 安装）

Step 2 · 选择输入形态

Step 2.1 · 图片输入工作流（Phase 1，可选）

适用前提：物体是回转体（绕中轴对称），且只有一张正侧面照片。壶嘴、不规则雕塑不适用。

流程：
1. AI 看图输出结构化参数：让多模态模型输出 JSON：
json { "type": "revolve", "real_height_m": 0.30, "real_max_radius_m": 0.07, "asymmetry": "left-right symmetric" }
2. 调 example_bottle.py：
bash python scripts/example_bottle.py <图片路径> \ --height 0.30 --max_radius 0.07 --out bottle.glb
- OpenCV 自动提取轮廓 → 简化多边形 → revolve 成回转体
- 真实尺寸由 --height 和 --max_radius 控制（不传默认 height × 0.5）
- 无图片时 --demo 用内置正弦轮廓演示
3. 浏览器验证：GLB 丢任何 model-viewer 查看器即可交互旋转

局限：单侧轮廓只能复刻左右对称回转体；壶嘴、雕花等不对称细节丢失。

Step 3 · 建模（核心手法）

以 scripts/param_lib.py 为工具库（sys.path.insert 后 from param_lib import *）：

1. 定尺寸链：先写外包络 W/H/D 和壁厚，再逐层推导内腔有效尺寸（每加一层板减两倍板厚）。搁板/抽屉按有效内尺寸算——尺寸链算错的典型症状是零件薄成纸片。
2. 外露件用圆角盒 prism_z(w, d, r, thickness, center, material)：圆角矩形截面挤出，竖直棱+顶底边带圆弧（大件 r≈0.02m，小件 r≈0.012m）。水平板需再绕 x 转 90°。
3. 内部件用直角盒 box_m(extents, center, material)：最省面数（12 面）。
4. 锐边想磨圆用 fillet()：fillet(mesh, radius=0.01, sections=2) — subdivide + 拉普拉斯平滑。适合小件；大件建议用 prism_z 圆角截面更省。
5. 需要挖孔/切角用 boolean_op()：boolean_op(a, b, op='difference') — 引擎默认 manifold，需 pip install manifold3d。注意：布尔结果会丢材质，需重新 _bind()。
6. 内外双色靠结构：一个 mesh 只能绑一种材质——外壳板用金属材质，另做五面薄内衬板（厚 0.012m 即可）+ 门内衬盖住内侧，实现"外银灰、内纯白"。
7. 材质：纯色用 pbr() 工厂或预设（MAT_STEEL / MAT_WHITE / MAT_GLASS / MAT_LAMP_WARM / MAT_RUBBER / MAT_BLACK）；贴图材质用 pbr_textured(path, tex_size=256)——把 PNG/JPG 作为 PBR baseColorTexture，自动缩放到 256/512px，体积约 +20~200KB。
8. 门/盖板开启：所有门上零件先在关闭位摆好，统一 apply_transform(hinge_transform(轴点, 方向, 弧度))。角度正负先小角度试转确认。
9. 导出 export_scene(scene, "xxx.glb")——自动打印零件数/面数/体积并回读自检材质数。

scripts/example_fridge.py 是完整可跑示例（冰箱，31 零件 28KB）：

python <skill目录>/scripts/example_fridge.py output.glb

Step 4 · 预览交付

复制 assets/preview_template.html 到 GLB 同目录，替换 {{MODEL_FILE}} 为文件名，浏览器打开即可交互旋转。多模型对比用 tab + data-src 懒加载。

Resources

scripts/

• param_lib.py — 建模工具库：
• pbr 材质工厂 + 7 种材质预设
• pbr_textured() — 贴图 PBR 材质（256/512px）
• prism_z/box_m/cyl_m 几何封装（含圆角截面）
• boolean_op() — 布尔运算封装（manifold 引擎）
• fillet() — 细分圆角封装（subdivide + 拉普拉斯平滑）
• hinge_transform 门轴变换
• export_scene 体检导出
• example_fridge.py — 完整示例：银灰外壳+白色内衬单门冰箱，演示全部核心手法。
• example_bottle.py — 图片输入示例：从侧面照片提取轮廓 → revolve 旋转体 → 瓶子/杯子。支持 --demo 无图演示。

references/

• trimesh-notes.md — 实战踩坑：依赖版本坑（earcut/pyglet<2）、baseColorFactor 是 0~255、emissive 是 0~1、doubleSided 必开、圆角板旋转方向、体积规律实测数据。建模前必读。

assets/

• preview_template.html — model-viewer 单模型预览页模板，复制改文件名即用。

API 速查

已验证结论（实测数据）

• 冰箱 33 零件/1,632 面/30KB vs 混元 LowPoly 19.5MB vs MultiView 40MB——规则几何体参数化完胜。
• 面数 144→1,632（11×），体积 7.9→29.8KB（4×）：细节堆料对体积边际影响极小。
• GLB 无压缩扩展，零兼容性问题（对比 Draco 版需查看器支持）。
• 瓶子（图片轮廓）26 点 → 2,592 面 / 48 KB（输入合成图测得）。
• 布尔挖孔（立方体减圆柱）→ 144 面；细分圆角（直角盒磨圆）→ 192 面（sections=2）。
• 贴图材质：128px 输入 → 自动缩放到 256px，导出 +约 20KB（vs 纯色 +2KB）。