openscad

OpenSCAD 技能

创建、验证和导出 OpenSCAD 3D 模型。支持自定义参数、多角度视觉预览，以及导出 STL 文件，以便用于 MakerWorld 等 3D 打印平台。

前提条件

必须安装 OpenSCAD。通过 Homebrew 安装：

brew install openscad

工具

此技能在 tools/ 目录中提供了多个工具：

预览生成

# Generate a single preview image
./tools/preview.sh model.scad output.png [--camera=x,y,z,tx,ty,tz,dist] [--size=800x600]

# Generate multi-angle preview (front, back, left, right, top, iso)
./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 文件后：

1. 使用 multi-preview.sh 生成多角度预览
2. 使用 read 工具查看每张生成的图片
3. 从多个角度检查问题：
   • 前面／后面：验证对称性、特征和比例
   • 左侧／右侧：检查深度和侧面轮廓
   • 顶部：确保顶部特征正确
   • 等轴测视图：验证整体形状
4. 根据需要迭代：如果发现问题，修复代码并重新验证

仅靠语法验证无法发现以下问题，而视觉验证可以发现：

• 法线反转或几何体内外颠倒
• 特征未对齐或布尔运算不正确
• 比例与预期设计不符
• 几何体缺失或悬空
• Z-fighting 或表面重叠

未从多个角度目视确认模型正确无误之前，绝不要交付 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 通常需要：

1. 使用 export-stl.sh 导出的 STL 文件
2. 预览图片（至少一张效果良好的等轴测视图）
3. 可自定义参数的说明

可以创建包含元数据的 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);