openscad-language

OpenSCAD Language Reference

OpenSCAD is a script-based 3D CAD modeler. Models are defined programmatically — there is no interactive GUI modeling. Files use the .scad extension.

Core Concepts

• OpenSCAD is declarative — you describe geometry, not steps
• Everything is either a 2D shape, a 3D solid, a transformation, or a boolean operation
• The final geometry is whatever is in the top-level scope (not inside a module)
• Use $fn to control facet count (smoothness) for curved surfaces

3D Primitives

cube([x, y, z], center = true);
sphere(r = 5);                    // or sphere(d = 10);
cylinder(h = 10, r = 5);          // or r1, r2 for cone
cylinder(h = 10, r1 = 5, r2 = 0); // cone

2D Primitives (for extrusion)

circle(r = 5);
square([10, 20], center = true);
polygon(points = [[0,0], [10,0], [5,10]]);
text("Hello", size = 10);

Extrusions (2D to 3D)

linear_extrude(height = 10) circle(r = 5);     // cylinder
linear_extrude(height = 10, twist = 90) square([10, 2], center = true);
rotate_extrude() translate([10, 0]) circle(r = 3);  // torus

Transformations

translate([x, y, z]) child();
rotate([rx, ry, rz]) child();     // degrees around each axis
scale([sx, sy, sz]) child();
mirror([1, 0, 0]) child();        // mirror across YZ plane
color("red") child();
color([0.5, 0.5, 0.5, 0.8]) child();  // RGBA

Boolean Operations

union() { a(); b(); }          // combine shapes
difference() { a(); b(); }     // subtract b from a (first child is base)
intersection() { a(); b(); }   // keep only overlap

Modules (reusable components)

module bolt(diameter, length) {
    cylinder(h = length, d = diameter);
    translate([0, 0, length])
        cylinder(h = diameter * 0.6, d = diameter * 1.8);
}

bolt(6, 20);
translate([15, 0, 0]) bolt(8, 30);

Variables and Functions

wall = 2;
inner_r = 10;
outer_r = inner_r + wall;

function circumference(r) = 2 * PI * r;

Note: Variables in OpenSCAD are set at compile time, not at runtime. A variable can only be assigned once per scope.

Iteration

// Linear pattern
for (i = [0:5]) translate([i * 10, 0, 0]) cube(5);

// Circular pattern
for (a = [0:60:359]) rotate([0, 0, a]) translate([20, 0, 0]) cylinder(h=5, r=2);

// Grid
for (x = [0:10:50], y = [0:10:30]) translate([x, y, 0]) cube(3);

Conditionals

module mount(type = "round") {
    if (type == "round") cylinder(h = 5, r = 10);
    else cube([20, 20, 5], center = true);
}

Special Variables

Variable	Purpose	Typical Value
$fn	Fixed facet count for curves	32-128 for final, 16 for preview
$fa	Minimum angle per facet	12 (default)
$fs	Minimum facet size (mm)	2 (default)
$t	Animation parameter (0-1)	-

Import / Include

include <library.scad>    // include definitions AND execute top-level geometry
use <library.scad>         // include only module/function definitions
import("part.stl");        // import STL geometry

Hull and Minkowski

hull() { sphere(5); translate([20,0,0]) sphere(5); }  // convex hull
minkowski() { cube(10); sphere(2); }                    // rounded cube

Common Patterns

Rounded box

module rounded_box(size, radius) {
    minkowski() {
        cube([size.x - 2*radius, size.y - 2*radius, size.z - radius], center = true);
        sphere(r = radius);
    }
}

Shell (hollow solid)

module shell(outer_size, wall) {
    difference() {
        cube(outer_size, center = true);
        cube([outer_size.x - 2*wall, outer_size.y - 2*wall, outer_size.z], center = true);
    }
}

Mounting hole pattern

module mounting_holes(spacing, hole_d, depth) {
    for (x = [-1, 1], y = [-1, 1])
        translate([x * spacing/2, y * spacing/2, 0])
            cylinder(h = depth, d = hole_d, center = true);
}

Pipe / tube

module pipe(h, outer_r, wall) {
    difference() {
        cylinder(h = h, r = outer_r);
        translate([0, 0, -0.1])
            cylinder(h = h + 0.2, r = outer_r - wall);
    }
}

Best Practices

1. Define dimensions as variables at the top — never use magic numbers
2. Derive dependent dimensions — outer_r = inner_r + wall
3. Use modules for any shape used more than once
4. Use center = true for primitives that will be differenced or intersected
5. Set $fn globally or per-shape — higher values = smoother but slower
6. Use difference() for holes — the first child is the base, subsequent children are subtracted
7. Test with low $fn (16-24), increase for final output (64-128)
8. Keep the top-level clean — put geometry in modules, instantiate at top level

Debug Modifiers

• # — highlight (transparent red overlay): #cylinder(h=5, r=2);
• % — transparent preview: %cube(20);
• ! — show only this shape: !cylinder(h=5, r=2);
• * — disable (skip rendering): *cube(10);