第08章：参数化零件库与复用设计
1. 为什么需要库
当模型从一个零件发展到一组产品时，重复代码会迅速失控。孔、圆角板、螺丝柱、卡扣、盒体、齿轮、滑轨、铰链、标识文字都应该抽象成可复用模块。OpenSCAD 的库设计不追求面向对象层级，而追求简单、纯粹、参数明确。
2. 库文件原则
一个好的库文件应满足：
- 顶层不生成实际几何，避免被
include时意外显示。 - 模块参数有默认值，能独立预览。
- 坐标原点、方向、单位在注释中说明。
- 参数校验清晰，错误信息可读。
- 不依赖隐含全局变量，除非是明确的配置文件。
- 示例与测试模型单独放置。
3. 基础紧固件模块
module clearance_hole(d = 3.2, h = 10) {cylinder(h = h, d = d, center = true);
}module counterbore(d = 3.2, head_d = 6.2, head_h = 3, h = 10) {union() {cylinder(h = h, d = d, center = true);translate([0,0,h/2-head_h/2]) cylinder(h = head_h, d = head_d, center = true);}
}
使用时作为差集刀具：
difference() {cube([40, 20, 6], center = true);counterbore(h = 8);
}
4. 圆角板模块
module rounded_plate(size = [60, 30, 4], r = 4) {assert(size[0] >= 2*r && size[1] >= 2*r, "corner radius too large");hull() {for (x = [-size[0]/2+r, size[0]/2-r])for (y = [-size[1]/2+r, size[1]/2-r])translate([x,y,0]) cylinder(h = size[2], r = r, center = true);}
}
注意这个模块的原点在板中心，厚度沿 Z 对称。调用者可以轻松装配和布尔。
5. 配置文件模式
项目可把产品规格放在配置文件中：
// config_small.scad
box_size = [60, 40, 20];
wall = 2;
hole_d = 3.2;
主文件：
include <config_small.scad>
use <parts/box.scad>box(size = box_size, wall = wall);
如果要命令行覆盖，也可使用 -D 'box_size=[80,50,25]'。需要注意命令行表达式的引号和 shell 转义。
6. MCAD 与第三方库
官方仓库子模块中包含 MCAD 库。社区也常用 BOSL/BOSL2 等库。使用第三方库时应关注：
- 许可证是否适合项目。
- 支持的 OpenSCAD 版本。
- 模块命名是否与自有代码冲突。
- 是否影响渲染性能。
- 是否有稳定文档和示例。
- 是否需要把库作为 Git 子模块、包管理依赖或直接复制。
学习时可以借鉴库的参数设计，但团队项目不建议无选择地引入大量第三方模块。
7. 装配入口设计
常见做法是用一个变量控制显示内容：
show = "assembly";if (show == "base") base();
else if (show == "cover") cover();
else if (show == "exploded") exploded_view();
else assembly();
命令行导出不同零件：
openscad -D 'show="base"' -o base.stl main.scad
openscad -D 'show="cover"' -o cover.stl main.scad
8. 坐标接口
库模块之间最容易出错的是坐标接口。建议为每个模块定义：
- 原点位置。
- X/Y/Z 正方向含义。
- 安装面在哪个平面。
- 输入尺寸是外尺寸还是内尺寸。
- 孔位坐标相对哪个基准。
- 返回几何是否居中。
这些约定应写在模块注释或教程文档中。
9. 版本兼容
OpenSCAD 语言特性会随版本演进。共享库时应说明最低 OpenSCAD 版本。若使用较新的列表推导、let、assert 或实验特性，应在文档中注明。
10. 库质量检查
- 默认参数是否能正常 F6 渲染？
- 极端参数是否触发可读错误？
- 模块是否可作为差集刀具使用？
- 是否存在隐藏全局状态？
- 是否能在多个项目中独立复用？
- 是否有最小示例和预览图？
- 是否避免过度复杂的通用化？