OpenSCAD

CSG Modeling

CSG modeling (Constructive Solid Geometry) is vector modeling of graphic elements, in our case 3D models. Basic primitives (sphere, cone/cylinder, cuboid…) are composed into a CSG tree using edges of transformations (translation, scaling, rotation…) and nodes of boolean operations (difference, intersection, union).

In the image you can see an illustration of a CSG tree. Here, for simplification, primitives are already rotated.

OpenSCAD allows writing such trees using code and rendering from them the resulting 3D model in the form of triangular mesh (we’ll learn about that later).

User Interface

The program window consists of three parts:

After writing code in the editor, you need to "compile" the model. There’s a fast (not always accurate) preview using OpenGL (Design → Display, F5) and a full render to 3D model for export (unfortunately calculated on CPU, Design → Render, F6). In the Design menu you can also enable Automatic Reload and Preview; after saving, the preview is then performed automatically.

In the View menu you’ll find many options for display preview; we recommend enabling axes and scales.

You’ll later use the mouse to navigate the model (try different buttons).

To see anything, however, you need source code. You can choose from a rich selection in File → Examples.

Syntax

The syntax at first glance is very similar to C/C++/Java – it contains semicolons, curly braces, comments are written the same way. Among other things, you can write numbers (either whole or with floating decimal point (notation using dot or scientific)) – 1, 0, -5, 5.3, 9.99998, 185e-5; vectors/coordinates in square brackets – [1, 2, 3]; strings in "double quotes", boolean true/false.

You can use variables (which aren’t declared, but behave non-standardly, we’ll get to that later), mathematical expressions and functions, constant PI…

Primitives

cube(150, center=true); 1
sphere(100); 2

Transformations

Now that you know how to create primitive geometric solids, it’s good to learn to perform individual transformations with them.

Transformations are applied by writing before the object you want to transform: transformation() object();. They can also be chained; they’re applied sequentially from "closest" to farthest. They can also be applied to multiple objects at once, by wrapping objects in curly braces and prefacing them.

transformation() {
  object1();
  object2();
}

color("green") rotate([0,0,60]) translate([30,0,0]) cube(5); 1
color("red") translate([30,0,0]) rotate([0,0,60]) cube(5); 2

Boolean Operations

The foundation of CSG modeling are three boolean operations:

union() {
  cube(150, center=true);
  sphere(100);
}

difference() {
  cube(150, center=true);
  sphere(100);
}

intersection() {
  cube(150, center=true);
  sphere(100);
}

All these operations have no arguments but process any number of objects. Such objects are called children of the given operation. In Czech this means children, but we prefer not to translate this term.

Using Variables

It’s not necessary to use values directly everywhere; in OpenSCAD you can also use variables.

awesome = 42;
cylinder(h=awesome, r=awesome/2);

Keep in mind, however, that everything happens at once. Therefore you can’t redefine a variable; well, you can, but it behaves differently than you’re used to.

awesome = 42;
echo(awesome); 1
awesome = 4242; 2
echo(awesome);

The result is twice printed ECHO: 4242 🤯 The reason is that it doesn’t matter when you set the variable; its value applies throughout the scope. If you set a variable twice in one scope, the later stated value applies; take this only as an implementation detail and never do this.

It helps to think of variables as constants for a given scope. So far we only know one (global) scope, but that will soon change.

Loops

For syntax is a bit different from C and looks something like this:

for (var = [...]) { 1
    ... 2
}

Let’s pause for a moment at vector notation, which can be written in several ways:

We often use this in for loop notation.

for (i = [0:10:100]) echo(i); // => ECHO 10, 20, 30...

intersection_for(n = [1 : 6]) {
  rotate([0,0,n*60]) translate([5,0,0]) sphere(12);
}

Loops can of course be nested; there’s even a shortcut for this.

for (xpos=[0:3]) {
  for (ypos=[2,4,6]) { 1
    ...
  }
}

for (xpos=[0:3], ypos=[2,4,6]) { 2
  ...
}

1. Nested loop
2. Shortcut (syntactic sugar) for nested loop

Given how the for loop works in OpenSCAD, here we highlight several pieces of information that the attentive reader has surely already figured out:

Conditionals

OpenSCAD contains two types of conditionals: if and ternary operator.

if (...) { 1
  ... 2
} else if (...) { 3
  ... 4
} else { 5
  ... 6
}

num = 42;

if (num > 0) {
  sign = 1;
} else if (num < 0) {
  sign = -1;
} else {
  sign = 0;
}

echo(sign); // WARNING: Ignoring unknown variable 'sign'.

num = 42;

// var =   test ? TrueValue : FalseValue;

sign = num > 0 ? 1 : (num < 0 ? -1 : 0); 1
echo(sign); // ECHO: 1

Functions

Similarly to the ternary operator, functions are written. Functions don’t create parts of the CSG tree; they only calculate some value from their input. They’re single-expression shortcuts.

function name ( parameters ) = expression;

We don’t deal much with functions in this course, but curious students can of course use them. More about functions in the manual.

Modules

The equivalent to a function for the CSG tree is a module. A module is more similar to functions as we know them from programming languages, except it doesn’t return any value but a node (or edge) of the CSG tree.

In layman’s terms: a module "draws" something where it’s used.

Just like a function, a module accepts parameters that can have default values. Additionally, it can accept (process) children().

Modules (and functions) can exist in separate files (libraries); in your own file with a model you can use use or include:

module rounded_cylinder(h=20, r=5, center=false) {
  baseh = h-2*r;
  translate([0, 0, center ? -baseh/2 : r]) {
    cylinder(h=baseh, r=r);
    sphere(r);
    translate([0, 0, baseh]) sphere(r);
  }
}

// to display you must call the module
rounded_cylinder(center=true);

children()

Besides modules that create shapes only based on input parameters (arguments), you can also create modules that accept children().

This is used for modifying or incorporating any object.

children()

represents all passed objects

children(n)

represents n-th passed object

children([n1, …​, nx])

represents n-first through n-x-th passed object

$children

magic (with dollar) constant with number of passed objects

children([1 : 2 : $children])

every second passed object

module elongate() {
  scale([10 , 1, 1])
    children();
}

elongate() {
  sphere(30);
  cube(45, center=true);
  cylinder(r=10, h=50);
}

Debugging

For debugging models it’s good to learn several modifiers:

difference() {
  sphere(45);
  #cube(65, center=true);
}

Helpers

Special operations in OpenSCAD are minkowski() and hull(). Using them you can create complex shapes that would otherwise be very difficult to create.

Minkowski Sum

Minkowski sum is a set operation where all points from one set are added to all points from the second set. The following image best captures this:

You can imagine it by grasping one of the objects at the coordinate origin and driving with it over the surface of the second object, leaving a trail. This is a commutative and associative operation, so it doesn’t matter which object you drive over which. In practice, this operation is usually used with a sphere for rounding, but be careful, the rounded object will enlarge.

minkowski() {
  cube(300);
  sphere(30);
}

Varování:

Calculating the Minkowski sum can take very long.

Convex Hull

Convex hull (convex hull) of objects is such smallest convex object that contains all objects in it. Again it’s a commutative and associative set operation.

hull() {
  cube(100);
  sphere(30);
}

Varování:

Calculating the convex hull can take quite long.

Two-Dimensional Subsystem

So far we’ve only created three-dimensional objects. In OpenSCAD you can also use a two-dimensional subsystem where you work only on one plane.

In the 2D subsystem you can create 2D primitives: circle(), square() and polygon().

Using linear_extrude() or rotate_extrude() you can create a 3D object from a 2D object. Conversely, projection() serves for projecting 3D objects to 2D.

When working in the 2D subsystem, you can use everything you already know; only the API of some operations appropriately changes (e.g., translate() takes a vector of 2 values, rotate() takes only one angle…).

hull() {
  rotate(45) square([25, 15]);
  translate([12, 7]) circle(7);
}

Operations hull() and minkowski() are relatively fast in the 2D subsystem. So if possible, it’s better to perform them in it.

offset()

For rounding two-dimensional shapes you can use offset(). It has several ways of use:

linear_extrude()

Operation linear_extrude() pulls a 2D shape into space and thus creates a 3D shape. You can set several parameters:

height

extrusion height

center

false extrudes only upward, true in both directions (each by half the height)

twist

by how many degrees the 2D shape rotates during extrusion

slices

number of steps for twist

scale

how many times the 2D shape enlarges during extrusion

convexity

value affecting preview; chef advises: "if you don’t know, put 10"

linear_extrude(height=20, twist=180, slices=100, center=true) {
  square(5);
  square(5, center=true);
}

rotate_extrude()

Another way to convert a 2D shape to a 3D shape is to rotate it. For this serves rotate_extrude(), which rotates a 2D shape into space.

Rotation happens around the Y axis, but the object "stands up" around the Z axis (we still don’t know why).

rotate_extrude()
  polygon(points=[[0,0],[20,10],[10,20],[10,30],[30,40],[0,50]]);

projection()

Projection (projection()) projects a 3D object onto the XY plane. Parameter cut allows using only the intersection with the XY plane. The result of projection is always a 2D shape; you can then use it again to create a 3D shape.

projection(cut=true)
  translate([0, 0, -15])
    rotate([45, 0, 0])
      cylinder(r1=0, r2=500, h=500);

import()

To use already existing 2D or 3D shapes you can use import(), which allows inserting STL and DXF files into the CSG tree. The argument is the file path (relative or absolute).

When importing 2D shapes (DXF), pay particular attention to the resulting size; it’s advisable to use resize().

rotate_extrude()
  resize([20, 0], auto=[false, true])
    import("bottle.dxf");

Imported files can be used for any further operations. Foreign STL files don’t always render successfully; they first need to be repaired; we’ll get to that in the exercise about mesh repair.

difference() {
  import("kangaroo.stl"); // http://www.thingiverse.com/thing:33273 CC BY-NC-SA
  translate([0, -10, 80])
    cube(30, center=true);
}

surface()

An alternative way to use external files is surface(), which serves for converting images to height maps.

Resolution

You’ve surely noticed that round things in OpenSCAD are angular. The smaller they are, the more noticeable it is.

Using special variables $fn, $fa and $fs you can change resolution, see manual. In practice, variable $fn is most often set, which sets the absolute number of edges on a circle (minimum 3). Shapes are created so that the given size is the size of the circumscribed circle. Variable $fn can be used, for example, to create an n-gon.

These special variables can be set globally, in scope, or as an argument to any operation, primitive, or module. When creating modules, it’s not necessary to include these variables in the specification.

Simple – 2-Manifold

For correct STL file export, it’s necessary for the model to be Simple – 2-Manifold. This means, among other things, that model walls can’t intersect in all sorts of ways. Almost all possible problems are solved by the final implicit union(). Some problems can still arise, however, for example with incorrect use of polyhedron.

One problem that can arise simply is a shared edge of two objects. If you imagine two cubes (e.g., from the image below), in the real world they can’t have a shared edge. Either you can "pass" from one cube to another, or you can "pass" between them; in other words, either it’s two cubes or one double-cube.

cube(20);
translate([20, 20, 0]) cube(20);

e=0.0001;
cube(20);
translate([20-e, 20-e, 0]) cube(20);

e=0.0001;
cube(20);
translate([20+e, 20+e, 0]) cube(20);

MCAD Library

Using modules you can create various libraries for OpenSCAD. Some already exist; one of them is the MCAD library, which is often distributed together with OpenSCAD.

The MCAD library contains many elementary and advanced things:

To use the MCAD library you need to use include, not use.

include <MCAD/stepper.scad>
motor(Nema17);

Advanced Work with Variables

Examples from Exercises