How to use Openscad, tricks and tips to design a parametric 3D object

Part 1/3: Introduction to constructive solid geometry with Openscad

So first, what is Openscad? Within the CAD family, it is a 3D modeler: a software that helps you to create 3D objects. There are many such tools, but this one is used extensively in the 3D printing community, not only because it is free but because is it really efficient for some kind of objects.

It may or may not suit your mind, but with time I am able to "see" the shape I describe, not as text but directly as shapes. I guess it depends on people, but I am sure there are people that are not programmers that can think alike. And if you are already a programmer with no industrial goal then you really should give it a try. It will be a breeze to use up to a productive level, especially if you do not want to invest time in a new and hellish interactive user interface!

The official manual is OK but it does not really work as an introduction. The navigation is also sometimes difficult to the point goggle is more useful. There is a nice raw cheat sheet also but it has no link to the respective functions (what a pity!). In any case these fail to help learning Openscad quickly in my humble opinion.



Why Openscad?

The software shines whenever you want:

1) precise placement of object (as all objects have explicit numbered coordinates and sizes)

2) easily modifiable design, e.g. when you want to make a wall thicker or a hole larger, and the whole design adapts to the new numbers automatically. It is thus easy to find the "optimum" geometry, weight or robustness for real life applications.

3) a text-readable design, and easily recyclable components or behaviors


It is no surprise that Openscad is best suited to mechanical designs. As we said, compared to other 3D modelers, it shines when a number of iterations are required before the optimum geometry is obtained, because everything is controlled by numbers that can be tweaked extremely easily and at will (when it is programmed correctly).

Now reciprocally, Openscad fails badly with organic shapes though: it is not the right tool to design a mascot, statue, or non-abstract art. My only attempt at art was the arguable bird-o-matic generator, which create simplified bird shapes with a few geometric shapes ;)

An attempt to generate bird shapes from one single design Openscad usually not a good tool for artists.

Introduction

Openscad is still programmed. Designs are described withing a text file, that it parses to generate and show 3D shapes. The mouse is only useful to view, zoom and rotate around the generated shape.

But do not be afraid if you are not a programmer as you still can do a lot by following very intuitive rules.

CSG and incremental design

The basic ideas of constructive solid geometry is not unlike the process an artist follows when he works with clay: he starts with nothing, and then he adds or removes material to make a shape that becomes closer and closer to his final idea. Parts of the object can also be made separately, like hands or arms for a statue that are stuck to the trunk once finalized.

Openscad and CSG in general works the exact same way, except that each of the step is described with names and explicit commands, that are applied one after another. "Carving" is even easier than in real life because any shape can be removed (including complex ones that are themselves built by adding elements!).

Encoding of a 3D object

You can bypass this section when you do not care or if you get  feel lost, but it may help understand better.

A 3D sphere! Actually it is a mesh of triangles that approximates what we think is a perfect sphere.

Virtual 3D designs are fed to printers through a slicer, which computes the many commands to move the printer motors and temperatures. The most common file format to give to a slicer is STL, which is a primitive but powerful way to encode a 3D geometrical shape.

But... it is only an approximation of the 3D object, wit a mesh of 3D triangles, also called a wireframe.

The STL file can even be opened with a text editor to show that it is a dumb list of triangles, that themselves rely of a set of points (known as 3D vertices). In fact, STL files can easily be generated by homemade programs to create mathematical shapes.

Note: newer formats are slowly emerging, like the AMF, (appropriately named "Additive Manufacturing File Format"). Indeed, STL only stores really basic information, while more and more is expected: curved surfaces, material, densities, heads, settings and so. In some time Voxels formats may raise, especially well suited to local material and properties. But for now they have their own set of serious problems (mostly memory requirements).

How to edit an openscad file: huh, forget the embedded editor!

Openscad language mostly looks like the C computing language, or even Java, Javascript or... well many of the modern languages. But keep reading please, because it is also way simpler both to write and to debug!

Of course typos are still forbidden, as they generate dreaded "syntax errors". When Openscad does not understand what you are trying to tell him (i.e. it seems not to react to your change), you should check the "console" of Openscad (disable the tick mark in the "View / Hide Console" menu). This is where you read the erroneous line number. Then go back to your editor and fix the error!

Each command you give to Openscad must end with a semicolon. This is to tell Openscad that it has to do something at this point, while the former elements are preparing the work to do, like positioning the item or applying a transformation, and eventually telling the shape:

  sphere(20);

As you can see, the parameters are given in a pair of parentheses. Here we tell that the "sphere" has a radius of 20. Units are all millimeters, so if you want a huge and out of bounds 20 inch ball, just multiply the value:

  sphere(20 * 25.4); // as 1 inch is 25.4 millimeters

See also above? I wrote a comment in the source. Easy: Openscad ignores all text which is past a tight pair of slash characters until the end of the line. So this is where you put reminders, todos or any kind of useful information, mostly to be able to read the source months later! I highly recommend you put comments at every place that you may stumble upon later and ask "what the heck did I do here?".

Of course you can add, subtract, multiply or divide numbers. But there are a small set of usual mathematical functions like abs(x) for the absolute value of the number x, cosines and so. Usually there is no need to check the list if you ever programmed once.

Enough for the theory, as it will be made easier with examples.

Basic shapes and language items

The rollerstruder, a filament driver for 3D printers. Still made only of cubes, spheres and cylinders, but 1000+ lines of Openscad!

The primitive sphere, and how to view your shape


Let's start with the minimal or so-called primitive shapes. These are the basic building blocks, not unlike lego bricks except that there are fewer of them, and that we are going to distort them a lot later!

Just write the following in a file named "temp.scad", which you open with Openscad. Use F5 to refresh the view after you save the file, unless you have configured it for an automatic refresh (see above).

  sphere(20);

It will create and show a sphere that has a radius of 20 mm (i.e. a diameter of 40 mm). As shown, the sphere is centered on the three X,Y,Z axes by default.

A dumb sphere of radius 20 mm.

You can move around the object with:
 - left click + drag to rotate the view
 - right click + drag to translate the view
Additionally you can zoom with the mouse wheel (or shift + right click + drag).
None of these will change the shape nor its position in space: only your point of view will vary.
If you get lost, you can restore "easy" point of views with the well-named "View" menu.

The origin is shown as the intersection of the main long line segments of course, buried in the sphere above. But check the tiny (X,Y,Z) axes at the bottom left of the screen: they really helps when you start to translate objects for example, as the design becomes more complex.

Back to the sphere...

  sphere(20);

Now, and contrary to many languages, Openscad lets you name explicitly the parameters. I highly recommend this usage. Here you would re-write the above statement this way:

  sphere(r=20);

Default cylinder placement: flat on the (X,Y) plane.

Explicitly "centered" cylinder: it is now halfway into the (X,Y) plane.

Specifying the number of facets of a cylinder for a hexagonal shape with the $fn variable.

The cube, and [X,Y,Z] vectors in Openscad

Mathematically speaking, these are cuboids (non symmetric cubes), but that's how Openscad names them.
Anyhow, they use a special notation or "syntax": instead of explicit naming, you must provide the 3 sizes along the X, Y, and Z axes respectively, and this way :

  cube([20,10,5]);

See the three-numbers-in-brackets? They define a 3-element "vector", where the components sets the dimensions of the cube on the X, Y and Z directions respectively.

Do not forget the square brackets or Openscad will yell at you in the "console" windows (once again it is almost necessary to leave it open -- not shown on the screenshots here though!).

Cube (default placement is towards the positive X,Y,Z directions)

So we have created here a cube that is 40 mm along the X axis, 10 mm on Y and 5 mm high.

One problem with cubes is they are either in the positive quadrant (X,Y,Z) as above, or they are fully centered on the origin of the axes when the "center" parameter is true like below:

Cube (centered on all three axes)

We are going to see how to "fix" this now.

Basic operations: where it all starts!

First of all, let us translate some cube (i.e. shift the position of the object)


As we have seen, there is no way to lay a cube like cylinders, i.e. centered on X,Y where the bottom is kept at position Z=0. But Openscad, as any CSG modeler, has a set of basic geometrical transformations.

And the easiest one is the translation which is exactly what we need here. But contrary to the primitive shapes, a translation does not define an object. Instead, it modifies the object that follows!

Like the cube, translations expects a vector of 3 values, one per axis.

We can now translate our cube, with the following syntax:

  translate([0,0,2.5]) cube([20,10,5],center=true);

It does not matter how much space or new lines you put in between the two, or after of before the commas and other symbols. But you should write the semicolon only at the end, after you are done telling that something really is done, and "translate" expects a shape!

Once again, translations as all the other non-primitive operations do not do anything by themselves, they just "modify" shapes that comes after them.

We raised the previously centered cube flat on the (X,Y) plane, thanks to a translation of half its size toward positive Z.

What it does is to leave the cube at the same X and Y positions (zero offset on X and on Y), but it moves the cube up by 2.5 mm on Z (of course, negative numbers would sink the cube towards the bottom).

In our case, the cube was 5 mm tall, and positioned halfway on the (X,Y) plane. This is why we are raising it by 2.5 mm, i.e. half of its height: the result is a cube centered only on X and Y, and which is now flat on the (X,Y) plane at Z=0.

Just like default cylinders are laid out!


Union of shapes: where "constructive solid geometry" start to make sense!


Now for a new and important operation! So called "unions" are also the default behavior in Openscad when you write more than one shape. What happens is that they get added/merged together.

So when you write:
  sphere(14);

Then Openscad creates a new shape which surface really becomes a mix of a cube and a sphere, as shown below!

Union (addition) of a cube and a slightly larger sphere in Openscad. The union( ) operator is implicit. The result really is a mix of both.

Oh, by the way: to make it clearer, you can give a color to one of the shapes, by specifying a vector of three R,G,B values (they are numbers within 0 and 1, and not 255 as usual):

Using colors to understand what happens!

Actually, you will get the exact same behavior with this slightly more verbose way. Writing explicit "unions( )" operators really are useful, as we will see in a short moment.

  union()
  {
    cube([20,20,20], center=true);
    sphere(14);
  }

This creates a new (non-primitive) shape by fusing the primitives that are given within the curly braces, merging them into each other.
The above syntax is new however. Easy! You can consider curly braces { like this } to be nothing more than a way to group shapes, so that a former operator like our "union( )" is applied to the whole group.

We use curly braces in many cases: for example, to translate the two object by 10 mm further on the Y axis and 3 mm downwards on the Z, we would use this syntax:

  translate([0,10,-3])
  {
    cube([20,20,20], center=true);
    sphere(14);
  }

Of course you are not limited to two shapes: you can add as many as you want.

Make sure to understand the importance of these curly braces, because only the cube would be shifted if written like this:

  translate([0,10,-3])
    cube([20,20,20], center=true);
    sphere(14);



Now for some real difference...


As much as you can add one primitive to another, you can also subtract one shape from another, effectively carving the first shape by means of the second shape.

The "difference( )" operator also applies on a number of shapes, just as the union above. Now the order is important though, because it create the first shape as usual (positive shape), and then it subtract the shape of every other subsequent item (negative shapes), i.e. removing material each time.

Consider this example:

  difference()
  {
    cube([20,20,20], center=true);
    sphere(14);
  }

Difference (subtraction) of a cube and a slightly larger sphere in Openscad Do you see how the sphere became a "negative shape"? The first shape is "solid", and all subsequent shapes remove material from it.

Terribly wrong! This definition leaves the top hole surface undefined: hey, is it within or outside of the object? This surface has no thickness!

The right way to subtract a shape in CSG: the shape to remove must not leave undefined surface, so it must protrude a bit from the shape to carve.

Debugging a designs, looking for non-manifold issues

Using a dash to double check that the cylinder to subtract protrudes from the cube on both sides. When rendered (F6), it will still be removed from the shape.

A propeller design from the official website, where the enclosure is a "ghost" just to provide a context. Only the propeller will make it to the STL when exported to STL.

Disabling perspective is useful to check alignment (bottom)

Using the "!" prefix is really useful to work in upright coordinates. Rotated shapes makes life harder as axes no more match that of the main view. See also how we had to use a union to "group" the two shapes?

Designing more complex shapes

Intersection of two objects. The order no more imports.

A simple mug with a slightly more comple shape.

A larger mug by using the scale operator.

Bugging behaviors of Openscad...

Be patient! Sometimes it gets really slow crunching all the numbers. It will most probably not happen with the primitives and operators that were given in this post. But next two posts really can stress your CPU. Some particular construction may also crash the programs, so make sure you save regularly (a good practice whatever the software anyway).

Openscad upgrades are quite rare, but this is not a real issue as it already has most of the necessary tools even for complex designs (you know KISS ?). And even if it has a few "oddities", it really is an extraordinary and productive tool to create parametric engineering designs, for 3D printing or other uses.

Always use comments, so that you can read yourself again next time! And try to keep parts of the design together, that match functions in the final designs (e.g. clearly separated door, hinge, and body).

I wish the CSG manifold constraints are enforced automatically in some cases. It should be possible to know automatically when the the negative shape shall extend slightly beyond the boundary. But for now it is up to you to take care of this. It is extremely important otherwise you may run in trouble with complex shapes when its nasty effects suddenly appears so bad that Openscad refuses to generate the STL with F6!

No ruler, no scale is available on the display and there is no "professional" layout. Quite annoying for any professional usage. Obviously people designed rulers shapes with Openscad itself, but they are slowing things and they are not as convenient as if it was in the software (with automatic numbering according to the scale, etc).

If you need such a professional document, then Openscad is no good.

Local coordinate systems are tricky, especially after rotations. But life is made much simple with the use of the exclamation mark (aka "show only this part of the design"). And... there are better practice with so-called modules, which is part of the next article in this tutorial.

Indeed, if or when you are fine with the concepts shown in this post, you may switch to the next level. It will be all about variables, modules and parametric designs. Just where Openscad starts to get most of its value in my opinion.