第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 渲染？
• 极端参数是否触发可读错误？
• 模块是否可作为差集刀具使用？
• 是否存在隐藏全局状态？
• 是否能在多个项目中独立复用？
• 是否有最小示例和预览图？
• 是否避免过度复杂的通用化？