# 3d-print-skill
[English](#3d-print-skill-1) | [中文](#中文)
---
## 中文
给 Claude Code 的 3D 打印 skill（v0.2.0）。建模前先搜索真实规格，用 `manifold3d` 生成流形网格，支持 Bambu Studio、PrusaSlicer、Cura。
### 解决什么问题
AI 辅助建模有三个坑：尺寸是编的、网格不是流形的、复杂形状无法生成。这个 skill 强制执行一套工作流：
- **先查尺寸**：`search_specs.py` 搜不到时，AI 主动用 `search_web` 去查 datasheet
- **动态建模**：`generate_model.py` 是参考示例，不是上限——遇到预设外的形状，AI 现写 manifold3d 脚本
- **自省修复**：验证失败时回溯几何根因，不依赖 `--fix` 蒙混过关
- **自动对接**：AI 直接读 `specs_cache.json`，把文字描述映射到建模变量
### 安装
```bash
pip install manifold3d trimesh numpy requests
ln -sf /path/to/3d-print-skill ~/.claude/skills/3d-print
```
装好后 Claude Code 自动识别。跟它说"帮我打印一个镜头盖"或"设计一个带卡扣的支架"，工作流就启动了。
### 工作流
**1. 搜索真实规格**
```bash
python3 scripts/search_specs.py "Canon EF 40mm f2.8 外径"
```
结果缓存到 `specs_cache.json`，有效期 30 天。搜不到具体毫米数时，AI 自动用 `search_web` 工具查产品官网或 datasheet。
**2. 生成模型**
预设形状直接调用：
```bash
python3 scripts/generate_model.py --preset cube # 20mm 标定方块
python3 scripts/generate_model.py --preset tube # 空心圆柱
python3 scripts/generate_model.py --preset bracket # 带孔矩形块
```
预设外的形状（卡扣、倒角、旋转体、异形截面等），AI 现写脚本：
```python
import manifold3d as m3d
from generate_model import export_3mf, export_stl
# ... 用 manifold3d 组合建模，见 references/manifold-examples.md
```
**3. 验证网格**
```bash
python3 scripts/validate_mesh.py output/part.stl
```
检查项：watertight、法线一致、体积为正、无退化面、无重复面、尺寸合理。验证失败时 AI 回溯几何根因修复，不是无脑跑 `--fix`。
**4. 切片**
把 `.3mf` 导入 Bambu Studio / PrusaSlicer / Cura，预期结果：0 错误。
### 为什么用 manifold3d
`numpy-stl` 和原始 STL 布尔运算不保证输出是 watertight 的。`manifold3d` 从数学上保证。直接消灭了 Bambu Studio 里"244 non-manifold edges"这类报错。
### 参考文档
| 文件 | 内容 |
|------|------|
| `references/formats.md` | STL vs 3MF vs STEP 对比 |
| `references/tolerances.md` | FDM 精度、收缩率、配合间隙 |
| `references/design-rules.md` | 流形要求、壁厚、悬臂限制 |
| `references/manifold-examples.md` | manifold3d API：拉伸、旋转体、凸包、倒角、卡扣、螺纹 |
FDM 常用公差（0.4mm 喷嘴，PLA/PETG）：
- 孔：半径补偿 +0.1–0.2mm
- 过盈配合：孔减小 0.1–0.3mm
- 滑动配合：每侧留 0.2mm 间隙
- 无支撑最大悬臂：45°（PETG），50°（PLA）
- 最小壁厚：1.2mm（3 圈）
### 标定
先打印 `assets/calibration_cube.scad`，用游标卡尺量，算出你的打印机实际补偿量，更新到 `references/tolerances.md`。
### 依赖
```
manifold3d — 保证流形的布尔运算
trimesh — 网格验证与修复
numpy — 几何计算
requests — 规格搜索
```
### 许可证
MIT
---
## 3d-print-skill
A Claude Code skill for 3D printing workflows (v0.2.0). Searches for real specs before modeling, generates manifold-safe output for Bambu Studio, PrusaSlicer, and Cura.
## The problem it solves
AI-assisted modeling has three failure modes: fabricated dimensions, non-manifold geometry, and being locked into preset shapes. This skill addresses all three:
- **Search first**: if `search_specs.py` returns no concrete numbers, the AI uses its `search_web` tool to query datasheets directly
- **Dynamic modeling**: `generate_model.py` is a reference, not a limit — for non-preset shapes the AI writes a custom manifold3d script on the fly
- **Self-repair loop**: validation failures trigger root-cause analysis, not just `--fix`
- **Automatic spec mapping**: AI reads `specs_cache.json` and maps prose descriptions to modeling variables without manual intervention
## Install
```bash
pip install manifold3d trimesh numpy requests
ln -sf /path/to/3d-print-skill ~/.claude/skills/3d-print
```
After installing, Claude Code picks up the skill automatically. Say "3D print a lens cap with snap tabs" or "make a printable hook with chamfer" and the full workflow starts.
## Workflow
**1. Search for real specs**
```bash
python3 scripts/search_specs.py "Canon EF 40mm f2.8 outer diameter"
```
Results cached to `specs_cache.json` for 30 days. If no concrete millimeter values are found, the AI falls back to `search_web` to query the manufacturer's datasheet or Wikipedia.
**2. Generate the model**
Use a preset for simple shapes:
```bash
python3 scripts/generate_model.py --preset cube # 20mm calibration cube
python3 scripts/generate_model.py --preset tube # hollow cylinder
python3 scripts/generate_model.py --preset bracket # box with through-hole
```
For anything else (snap fits, chamfers, revolved profiles, multi-body assemblies), the AI writes a custom script using `manifold3d` directly and reuses the `export_3mf`/`export_stl` functions from `generate_model.py`. See `references/manifold-examples.md` for the full API cookbook.
**3. Validate**
```bash
python3 scripts/validate_mesh.py output/part.stl
```
Checks: watertight, consistent normals, positive volume, no degenerate faces, no duplicates, reasonable size. Failures are traced back to geometry root cause and fixed in the build script.
**4. Slice**
Import the `.3mf` into Bambu Studio / PrusaSlicer / Cura. Expected: 0 errors.
## Why manifold3d
`numpy-stl` and raw STL boolean operations don't guarantee watertight output. `manifold3d` does — mathematically. This eliminates the "244 non-manifold edges" class of errors in Bambu Studio.
## Reference files
| File | Contents |
|------|----------|
| `references/formats.md` | STL vs 3MF vs STEP |
| `references/tolerances.md` | FDM accuracy, shrinkage, fit clearances |
| `references/design-rules.md` | Manifold rules, wall thickness, overhang limits |
| `references/manifold-examples.md` | manifold3d API: extrusion, revolve, hull, chamfer, snap-fit, threads |
Key tolerances for FDM (0.4mm nozzle, PLA/PETG):
- Holes: add +0.1–0.2mm radius compensation
- Press fit: reduce mating hole by 0.1–0.3mm
- Sliding fit: add +0.2mm clearance per side
- Max overhang without supports: 45° (PETG), 50° (PLA)
- Min wall: 1.2mm (3 perimeters)
## Calibration
Print `assets/calibration_cube.scad` first. Measure with calipers, calculate your printer's actual hole compensation, update `references/tolerances.md` with real values.
## Dependencies
```
manifold3d — guaranteed manifold boolean operations
trimesh — mesh validation and repair
numpy — geometry math
requests — spec search
```
## License
MIT