Tutorials – OpenSCAD

If you do a superficial search online, it would seem that there are two things you can do with your new 3D printer: the first is print benchies (castles and skulls with which to adorn your bookshelf); the second is to create the bits of your next Comic Con cosplay costume you can't make with a sewing machine.

Then there is a subgroup of people who seem to think that 3D printing is an aim in itself, and that the best use of their filament is to build things that further enhance their machines. I am one of them.

Printer Pimping

Truth be said, I have not been this excited over a gadget in years. I was in awe of my first prints and realized this was a thing I wanted to keep in good working order for ever. I found a post on Thingiverse [1] that explained that my printer model had a design flaw: The vent over the electronics was facing upwards; hence dust and little bits of plastic from the prints could fall in and damage the fan. The solution was to print an exhaust vent cover that would propel the flow of air towards the front.

That led to a down-the-rabbit-hole situation in which I ended up printing a drawer that would hold all the printer's bric-a-brac (spare nozzles, screws, bolts, and belts), a tool holder, and an improved filament feeder.

What I could not find was a decent camera holder. You see, continuing with the topic of "3D printer as an aim in itself," a lot of people attach cameras to their printers and then turn the videos into time-lapses, giving birth to that genre of videos on YouTube that show objects seemingly growing from nothing on a printer's hotbed.

There is also a practical reason for training a lens on your prints: Some print managers like Atelier [2] allow you to monitor your prints from afar. If the camera shows the print going wrong, you can abort it before things get really messed up.

None of the available camera holders were any good, either because they didn't fit my cheapo Chinese sports cam, or they didn't fit my printer.

So, I decided to make my own.

CAD Applications

This meant getting up to speed with CAD software for Linux. Blender is great for making artistic stuff for printing, but it is massive overkill just to print cubes, cylinders, and spheres. Because, as I soon discovered, most mechanical pieces are made out of those parts, you don't have to wrap your head around Blender for that.

Besides, you want a simple way of measuring precise lengths, widths, heights, and angles and applying constraints to each and all of them. So far, the best programs I have been able to find for that are OpenSCAD [3] and FreeCAD [4].

In this issue, we'll be looking at OpenSCAD. We'll tackle FreeCAD further down the road in a separate tutorial.

OpenSCAD is interesting because you use a programming language to describe all the objects that make up your pieces. This may sounds scary, but it is not. And, believe me, FreeCAD is much more mind-bending.

Interface

OpenSCAD's relative straightforwardness starts with its interface. The main window is divided into roughly three panes (Figure 1). On the left, you have the script editor, which is where you write your programs. The editor has syntax highlighting and auto-indents lines when you use the JavaScript-like code formatting style (see Listing 1).

// Method 1
translate ([5, 5, 5]) rotate([45, 45, 45]) cube (5);
// Method 2
translate ([5, 5, 5]) {
 rotate([45, 45, 45]) {
  cube (5);
 }
}
// Method 3
translate ([5, 5, 5])
  rotate([45, 45, 45])
    cube (5);

Figure 1: OpenSCAD uses a programming language to describe objects and their location to the renderer.

On the right, at the top, you have the preview pane that shows your objects. Use the left mouse button to rotate the view, the wheel on your mouse zooms in and out, and holding down the right mouse button and dragging pans the view.

Finally, on the right under the preview, you have the console. OpenSCAD shows messages here as it renders your objects. It will also show error messages if it encounters syntax errors or has problems with the objects.

Although everything is important, the File | Examples option in the menu across the top of the window is especially worth exploring. The projects in there will help you get a better grasp of how OpenSCAD works.

Also check out the View menu, since it contains options for updating and changing what you see in the preview, along with keyboard shortcuts to make your workflow more agile. Some of the options available from View are also available in the toolbar under the preview pane.

This covers the essential interface bits. Things get really interesting when it's time to write scripts.

Language Basics

Here too the basics are, well, basic:

cube (5);

prints a cube with sides measuring 5 units. In my case, that translates to millimeters when I send it to my printer. The cube's lower left-hand corner on its front face is at the [0, 0, 0] position (Figure 1 again), so the cube is drawn to the right, up, and back from the viewer's initial point of view.

Although this is the default, you can add another parameter to the cube as follows:

cube (5, center = true);

to make the center of the cube coincide with [0, 0, 0], and then the cube is drawn around its central reference point.

You can also create in a similar way spheres, cylinders, and polyhedrons, the latter being customized 3D shapes.

To make the object appear in the preview pane, press the render button in the toolbar at the top of the script editor pane (second from right), or in the toolbar under the preview pane (second from left). You can also hit the F6 key.

You can move things around with the translate () function and rotate them with the rotate() function. To make this work, you embed the shape you want to modify within the function that modifies it. Listing 1 shows several ways you can do that.

• In Method 1, you simply put all the commands on one line, with the inner-most nested element last and moving outwards as you move backwards to the beginning of the line.
• Method 2 is a bit clearer, as it uses a notation similar to JavaScript or C/C++, where you user braces ({}) to enclose nested blocks of code. As we are on the topic of C/C++, notice how the OpenSCAD's language uses C/C++ style comments, with // to indicate a line comment and /* ... */ for multiple lines of comments.
• Method 3 is similar to Python, as you use indentation at the beginning of the line to indicate which block of code is nested within which container.

In our example, you may be tempted to think that there is some sort of invisible 3D cursor at work. When you write

translate ([x, y, z])

it moves said cursor to coordinate x, y, and z. Then, when the renderer executes

rotate ([a, b, c])

it rotates the cursor in 3D space and then draws the cube.

However, that is not what happens. In fact, the renderer executes commands inner-most first and moves out from there. Think of it like this: The renderer first locates the object it has to actually draw. The operation nearest to the object gets applied first, then the next to nearest, and so on, until all operations have modified the object. In the example above, that would be the rotation is applied first and then the translation.

This is important, because the order in which modifications are applied to a body matter. In fact,

translate ([5, 5, 5]) rotate([45, 45, 45]) cube (5);

will give you a quite different result to:

rotate([45, 45, 45]) translate ([5, 5, 5]) cube (5);

Figure 2 shows both. The green cube shows what happens when you rotate first and then translate, and the red cube shows what happens when you translate and then rotate. They are in different positions because with the green cube, you rotate the cube while it is still located at [0, 0, 0] and then move it to where you want it to be (which is what you probably wanted to do all along). With the red cube, you move the object and then rotate, but the rotation takes the original point as its reference, so it moves the cube on a 45 degree arc measuring 5, with its origin at [0, 0, 0].

Figure 2: The order in which you apply modifiers to your objects can change where they are located.

Adding and Subtracting

There are several ways of creating complex parts in OpenSCAD. One of them is by adding, intersecting, and subtracting one object from another. Listing 2 shows a cube that has had a sphere subtracted from it (Figure 3).

difference () {
  cube (10, center = true);
  sphere (6.5, center = true);
}

Figure 3: A cube that has had a sphere subtracted from it.

The way this works is that the second object (sphere ()) is subtracted from the first (cube ()). Notice that, due to OpenSCAD's scripting nature, objects never "go away" when you operate on them. In fact, you can still show subtracted pieces by typing a # in front of them and then hitting Preview (the F5 key). The "ghost" objects will show up as a translucent piece in the display pane (Figure 4).

Figure 4: You can show subtracted pieces as translucent bodies by using the # in front of the commands that create them.

Another way of showing all the bodies that make up a piece is by marking the checkbox at View | Thrown together in the menu.

The other two Boolean operations available are intersection (), in which you are left with an object that shares the space common to the two original objects (Figure 5), and union (), which just melds both objects together.

Figure 5: A cube intersected by a sphere leaves the space that both objects share.

Special Variables

You will notice that the sphere in the example above is looking a bit chunky. There are several inbuilt variables that can help with that. $fn, for example, sets the number of subdivisions in a curve. Use it like this

sphere (6.5, $fn=25);

to create a sphere with 25 subdivisions on each of its parallels.

In Figure 6, you can see what three spheres look like with, from left to right, the $fn variable set to 5, 25, and 50. The "sphere" (to call it something) on the left has north and south poles and an equator made from pentagons. Meanwhile, the sphere with a $fn of 50 looks much more sphere-like.

Figure 6: Use the $fn variable to make curved surfaces smoother.

You may be tempted to make $fn equal to 500 or 1000 to get a perfectly smooth sphere. Don't do that. Anything over 100 will eat up cycles from your CPU like candy, probably crashing your system. Besides, you are producing objects to print on a 3D printer. You'd need a crazily precise printer to be able to distinguish between a sphere with a $fn of 50 and another with a $fn of 500.

Modules

At some point, things are going to get complex. You are going to have objects twisted around other objects, modifying other objects that are used in combination with yet more objects.

It helps then that openSCAD supports modules to organize stuff. Modules are simply a bunch of instructions that go together.

To illustrate how they work, let's make a funnel as shown in Figure 7.

Figure 7: A funnel built using modules.

A funnel is made up by two parts: a hollow, cut-off conical object that I am going to call the hat (I couldn't find formal names for the parts of a funnel, so I am improvising here), and a hollow cylinder I am calling the pipe.

Turns out both the hat and the pipe can be made entirely from cylinders, since the hat, for openSCAD, is a cylinder with two different diameters at each end. As you need it to be hollow, you make another cylinder with a slightly smaller radius at both ends and subtract that from the bigger one. The module for that would look like Listing 3.

module hat () {
  difference () {
    cylinder (r1=8, r2=2, h=10, center=true, $fn=50);
    cylinder (r1=7.5, r2=1.5, h=10, center=true, $fn=50);
  }
}

The pipe module is even simpler (Listing 4), but you do have to remember to translate the lower end of the pipe to the top of the hat (line 2).

01 module pipe () {
02   translate ([0,0,10]) {
03     difference () {
04       cylinder (r=2, h=10, center=true, $fn=50);
05       cylinder (r=1.5, h=10, center=true, $fn=50);
06     }
07   }
08 }

With these two modules, you can create a funnel () module that calls the other two (Listing 5, lines 17 to 20). Then call the funnel () module to actually show something in the preview pane (Listing 5, line 22).

01 module hat () {
02   difference () {
03     cylinder (r1=8, r2=2, h=10, center=true, $fn=50);
04     cylinder (r1=7.5, r2=1.5, h=10, center=true, $fn=50);
05   }
06 }
07
08 module pipe () {
09   translate ([0,0,10]) {
10     difference () {
11       cylinder (r=2, h=10, center=true, $fn=50);
12       cylinder (r=1.5, h=10, center=true, $fn=50);
13     }
14   }
15 }
16
17 module funnel () {
18   hat ();
19   pipe ();
20 }
21
22 funnel ();

You can take this modularity further and save a set of modules into a separate .scad file altogether. You can then import them back into other files using either the include or the use methods.

The include </path/to/file.scad> method imports the whole thing, modules and commands that are not in modules, integrating the whole imported file into your current file. The use </path/to/file.scad> method, on the other hand, only imports the modules so you can use them as library modules with the code in your current file.

This means that, to get a funnel with include, all you have to do is:

include <funnel.scad>;

To do the same with use, you would also have to call the funnel () method like this:

use <funnel.scad>;
funnel ();

Conclusion

This article has covered the most essential bits and pieces of the OpenSCAD language. With this and the user manual's excellent documentation [5], you should be able to start creating your first 3D pieces.

That said, there is quite a lot more to learn regarding OpenSCAD. We'll be looking at more advanced things in next month's issue. We will also be creating a real piece to print and showing how you can go all the way from concept to real physical object.

Until then, have fun!