用途
OpenSCAD Skill 用于创建、校验和导出 OpenSCAD 3D 模型。它支持参数自定义、多角度可视化预览，以及为 MakerWorld 等 3D 打印平台导出 STL 文件。
前置条件
必须已安装 OpenSCAD。可通过 Homebrew 安装：
brew install openscad
工具
该技能在 tools/ 目录下提供以下工具。
预览生成
生成单张预览图：
./tools/preview.sh model.scad output.png [--camera=x,y,z,tx,ty,tz,dist] [--size=800x600]
生成多角度预览（前、后、左、右、顶、等轴测）：
./tools/multi-preview.sh model.scad output_dir/
STL 导出
# Export to STL for 3D printing
./tools/export-stl.sh model.scad output.stl [-D 'param=value']
参数提取
# Extract customizable parameters from an OpenSCAD file
./tools/extract-params.sh model.scad
校验
# Check for syntax errors and warnings
./tools/validate.sh model.scad
视觉校验（必需）
创建或修改 OpenSCAD 模型后，始终要对模型进行视觉校验。
编写或编辑任何 OpenSCAD 文件后：
- 使用 multi-preview.sh 生成多角度预览
- 使用 read 工具查看每张生成的图片
- 从多个视角检查问题：
- 前/后：验证对称性、特征和比例
- 左/右：检查深度和侧面轮廓
- 顶：确保顶部特征正确
- 等轴测：整体形状校验
- 必要时迭代：如果看起来有问题，修复代码并重新校验
这能捕获仅靠语法校验无法发现的问题：
- 法线反转或内外翻转的几何体
- 特征错位或布尔运算错误
- 与预期设计不符的比例
- 缺失或悬浮的几何体
- Z 冲突或重叠表面
绝不能在未从多个角度视觉确认模型正确的情况下交付 OpenSCAD 模型。
工作流程
1. 创建 OpenSCAD 模型
编写 OpenSCAD 代码，在顶部放置可自定义参数：
// Customizable parameters
wall_thickness = 2; // [1:0.5:5] Wall thickness in mm
width = 50; // [20:100] Width in mm
height = 30; // [10:80] Height in mm
rounded = true; // Add rounded corners
// Model code below
module main_shape() {
if (rounded) {
minkowski() {
cube([width - 4, width - 4, height - 2]);
sphere(r = 2);
}
} else {
cube([width, width, height]);
}
}
difference() {
main_shape();
translate([wall_thickness, wall_thickness, wall_thickness])
scale([1 - 2*wall_thickness/width, 1 - 2*wall_thickness/width, 1])
main_shape();
}
参数注释格式：
- // [min:max] - 数值范围
- // [min:step:max] - 带步长的数值范围
- // [opt1, opt2, opt3] - 下拉选项
- // Description text - 纯描述
2. 校验模型
./tools/validate.sh model.scad
3. 生成预览
生成预览图以视觉校验模型：
./tools/multi-preview.sh model.scad ./previews/
这会从多个角度创建 PNG 图片。使用 read 工具查看它们。
4. 导出为 STL
./tools/export-stl.sh model.scad output.stl
# With custom parameters:
./tools/export-stl.sh model.scad output.stl -D 'width=60' -D 'height=40'
相机位置
预览常用相机角度：
- 等轴测：--camera=0,0,0,45,0,45,200
- 前：--camera=0,0,0,90,0,0,200
- 顶：--camera=0,0,0,0,0,0,200
- 右：--camera=0,0,0,90,0,90,200
格式：x,y,z,rotx,roty,rotz,distance
MakerWorld 发布
对于 MakerWorld，通常需要：
- 通过 export-stl.sh 导出的 STL 文件
- 预览图（至少一张好的等轴测视图）
- 可自定义参数的描述
可考虑创建带元数据的 model.json：
{
"name": "Model Name",
"description": "Description for MakerWorld",
"parameters": [...],
"tags": ["functional", "container", "organizer"]
}
示例：完整工作流
# 1. Create the model (write .scad file)
# 2. Validate syntax
./tools/validate.sh box.scad
# 3. Generate multi-angle previews
./tools/multi-preview.sh box.scad ./previews/
# 4. IMPORTANT: View and validate ALL preview images
# Use the read tool on each PNG file to visually inspect:
# - previews/box_front.png
# - previews/box_back.png
# - previews/box_left.png
# - previews/box_right.png
# - previews/box_top.png
# - previews/box_iso.png
# Look for geometry issues, misalignments, or unexpected results.
# If anything looks wrong, go back to step 1 and fix it!
# 5. Extract and review parameters
./tools/extract-params.sh box.scad
# 6. Export STL with default parameters
./tools/export-stl.sh box.scad box.stl
# 7. Export STL with custom parameters
./tools/export-stl.sh box.scad box_large.stl -D 'width=80' -D 'height=60'
记住：绝不要跳过视觉校验步骤。许多问题（错误尺寸、布尔运算错误、几何体反转）只有在你真正查看渲染模型时才可见。
OpenSCAD 快速参考
基础形状
cube([x, y, z]);
sphere(r = radius);
cylinder(h = height, r = radius);
cylinder(h = height, r1 = bottom_r, r2 = top_r); // cone
变换
translate([x, y, z]) object();
rotate([rx, ry, rz]) object();
scale([sx, sy, sz]) object();
mirror([x, y, z]) object();
布尔运算
union() { a(); b(); } // combine
difference() { a(); b(); } // subtract b from a
intersection() { a(); b(); } // overlap only
高级
linear_extrude(height) 2d_shape();
rotate_extrude() 2d_shape();
hull() { objects(); } // convex hull
minkowski() { a(); b(); } // minkowski sum (rounding)
2D 形状
circle(r = radius);
square([x, y]);
polygon(points = [[x1,y1], [x2,y2], ...]);
text("string", size = 10);