openscad

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSCAD Skill

OpenSCAD 技能

Create, validate, and export OpenSCAD 3D models. Supports parameter customization, visual preview from multiple angles, and STL export for 3D printing platforms like MakerWorld.

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

Prerequisites

前置条件

OpenSCAD must be installed. Install via Homebrew:

bash

brew install openscad

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

bash

brew install openscad

Tools

工具

This skill provides several tools in the

tools/

directory:

本技能在

tools/

目录下提供了多个工具：

Preview Generation

预览图生成

bash

undefined

bash

undefined

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/

undefined

./tools/multi-preview.sh model.scad output_dir/

undefined

STL Export

STL导出

bash

undefined

bash

undefined

Export to STL for 3D printing

导出为STL文件用于3D打印

./tools/export-stl.sh model.scad output.stl [-D 'param=value']

undefined

./tools/export-stl.sh model.scad output.stl [-D 'param=value']

undefined

Parameter Extraction

参数提取

bash

undefined

bash

undefined

Extract customizable parameters from an OpenSCAD file

从OpenSCAD文件中提取可自定义参数

./tools/extract-params.sh model.scad

undefined

./tools/extract-params.sh model.scad

undefined

Validation

语法验证

bash

undefined

bash

undefined

Check for syntax errors and warnings

检查语法错误和警告

./tools/validate.sh model.scad

undefined

./tools/validate.sh model.scad

undefined

Visual Validation (Required)

视觉验证（必填步骤）

Always validate your OpenSCAD models visually after creating or modifying them.

After writing or editing any OpenSCAD file:

Generate multi-angle previews using
```
multi-preview.sh
```
View each generated image using the
```
read
```
tool
Check for issues from multiple perspectives:
- Front/back: Verify symmetry, features, and proportions
- Left/right: Check depth and side profiles
- Top: Ensure top features are correct
- Isometric: Overall shape validation
Iterate if needed: If something looks wrong, fix the code and re-validate

This catches issues that syntax validation alone cannot detect:

Inverted normals or inside-out geometry
Misaligned features or incorrect boolean operations
Proportions that don't match the intended design
Missing or floating geometry
Z-fighting or overlapping surfaces

Never deliver an OpenSCAD model without visually confirming it looks correct from multiple angles.

创建或修改OpenSCAD模型后，务必进行视觉验证。

编写或编辑完OpenSCAD文件后：

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

这一步可以捕捉到仅靠语法验证无法发现的问题：

法向反转或内外颠倒的几何体
特征错位或布尔运算错误
比例与预期设计不符
缺失或悬空的几何体
Z轴冲突或重叠表面

绝对不要在未从多视角确认模型外观正确的情况下交付OpenSCAD模型。

Workflow

工作流程

1. Creating an OpenSCAD Model

1. 创建OpenSCAD模型

Write OpenSCAD code with customizable parameters at the top:

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();
}

Parameter comment format:

```
// [min:max]
```
- numeric range
```
// [min:step:max]
```
- numeric range with step
```
// [opt1, opt2, opt3]
```
- dropdown options
```
// Description text
```
- plain description

在文件顶部编写包含可自定义参数的OpenSCAD代码：

openscad

// 可自定义参数
wall_thickness = 2;        // [1:0.5:5] 壁厚（毫米）
width = 50;                // [20:100] 宽度（毫米）
height = 30;               // [10:80] 高度（毫米）
rounded = true;            // 添加圆角

// 下方是模型代码
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. Validate the Model

2. 验证模型

bash

./tools/validate.sh model.scad

bash

./tools/validate.sh model.scad

3. Generate Previews

3. 生成预览图

Generate preview images to visually validate the model:

bash

./tools/multi-preview.sh model.scad ./previews/

This creates PNG images from multiple angles. Use the

read

tool to view them.

生成预览图以进行视觉验证：

bash

./tools/multi-preview.sh model.scad ./previews/

这会创建多视角的PNG图片。使用

read

工具查看这些图片。

4. Export to STL

4. 导出为STL

bash

./tools/export-stl.sh model.scad output.stl

bash

./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'

undefined

./tools/export-stl.sh model.scad output.stl -D 'width=60' -D 'height=40'

undefined

Camera Positions

相机位置

Common camera angles for previews:

Isometric:
```
--camera=0,0,0,45,0,45,200
```
Front:
```
--camera=0,0,0,90,0,0,200
```
Top:
```
--camera=0,0,0,0,0,0,200
```
Right:
```
--camera=0,0,0,90,0,90,200
```

Format:

x,y,z,rotx,roty,rotz,distance

预览图常用的相机角度：

等轴测：
```
--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 Publishing

MakerWorld 发布

For MakerWorld, you typically need:

STL file(s) exported via
```
export-stl.sh
```
Preview images (at least one good isometric view)
A description of customizable parameters

Consider creating a

model.json

with metadata:

json

{
  "name": "Model Name",
  "description": "Description for MakerWorld",
  "parameters": [...],
  "tags": ["functional", "container", "organizer"]
}

针对MakerWorld，你通常需要：

通过
```
export-stl.sh
```
导出的STL文件
预览图（至少包含一张清晰的等轴测视图）
可自定义参数的说明

建议创建包含元数据的

model.json

文件：

json

{
  "name": "Model Name",
  "description": "Description for MakerWorld",
  "parameters": [...],
  "tags": ["functional", "container", "organizer"]
}

Example: Full Workflow

示例：完整工作流程

bash

undefined

bash

undefined

1. Create the model (write .scad file)

1. 创建模型（编写.scad文件）

2. Validate syntax

2. 验证语法

./tools/validate.sh box.scad

3. Generate multi-angle previews

3. 生成多视角预览图

./tools/multi-preview.sh box.scad ./previews/

4. IMPORTANT: View and validate ALL preview images

4. 重要步骤：查看并验证所有预览图

Use the read tool on each PNG file to visually inspect:

使用read工具查看每张PNG文件以进行视觉检查：

- 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!

如果发现任何问题，回到步骤1进行修复！

5. Extract and review parameters

5. 提取并查看参数

./tools/extract-params.sh box.scad

6. Export STL with default parameters

6. 使用默认参数导出STL

./tools/export-stl.sh box.scad box.stl

7. Export STL with custom parameters

7. 使用自定义参数导出STL

./tools/export-stl.sh box.scad box_large.stl -D 'width=80' -D 'height=60'


**Remember**: Never skip the visual validation step. Many issues (wrong dimensions, boolean operation errors, inverted geometry) are only visible when you actually look at the rendered model.

./tools/export-stl.sh box.scad box_large.stl -D 'width=80' -D 'height=60'


**注意**：绝对不要跳过视觉验证步骤。许多问题（如尺寸错误、布尔运算错误、几何体反转）只有在查看渲染后的模型时才会显现。

OpenSCAD Quick Reference

OpenSCAD 速查参考

Basic Shapes

基础形状

openscad

cube([x, y, z]);
sphere(r = radius);
cylinder(h = height, r = radius);
cylinder(h = height, r1 = bottom_r, r2 = top_r);  // cone

openscad

cube([x, y, z]);
sphere(r = radius);
cylinder(h = height, r = radius);
cylinder(h = height, r1 = bottom_r, r2 = top_r);  // 圆锥

Transformations

变换操作

openscad

translate([x, y, z]) object();
rotate([rx, ry, rz]) object();
scale([sx, sy, sz]) object();
mirror([x, y, z]) object();

openscad

translate([x, y, z]) object();
rotate([rx, ry, rz]) object();
scale([sx, sy, sz]) object();
mirror([x, y, z]) object();

Boolean Operations

布尔运算

openscad

union() { a(); b(); }        // combine
difference() { a(); b(); }   // subtract b from a
intersection() { a(); b(); } // overlap only

openscad

union() { a(); b(); }        // 合并
 difference() { a(); b(); }   // 从a中减去b
intersection() { a(); b(); } // 仅保留重叠部分

Advanced

高级操作

openscad

linear_extrude(height) 2d_shape();
rotate_extrude() 2d_shape();
hull() { objects(); }        // convex hull
minkowski() { a(); b(); }    // minkowski sum (rounding)

openscad

linear_extrude(height) 2d_shape();
rotate_extrude() 2d_shape();
hull() { objects(); }        // 凸包
minkowski() { a(); b(); }    // 闵可夫斯基和（圆角处理）

2D Shapes

2D形状

openscad

circle(r = radius);
square([x, y]);
polygon(points = [[x1,y1], [x2,y2], ...]);
text("string", size = 10);

openscad

circle(r = radius);
square([x, y]);
polygon(points = [[x1,y1], [x2,y2], ...]);
text("string", size = 10);