Release status: WIP

OpenSCAD is a free software application for creating solid 3D CAD objects. It is not an interactive modeler, but rather a 3D-compiler. OpenSCAD reads from a script and renders a 3D model from it. OpenSCAD is available for Microsoft Windows], Linux and Mac OS X. It does constructive solid geometry (CSG). OpenSCAD can also extrude forms from AutoCAD DXF files.

As of 2011, it uses Computational Geometry Algorithms Library (CGAL) as the basic Computational Solid Geometry engine, taking care of details such as intersection, difference and minkowski sums. The results can be rendered into 3D STL (file format)|STL files. It uses OpenCSG and OpenGL for fast previewing of models: rendering with CGAL (as with other CSG geometry engines) can sometimes take several minutes or hours.
-- Wikipedia

# Tutorials

This tutorial copies the information from the Thingiverse tutorial blog. The reasons for doing this are

• A blog lists later articles before earlier ones. A tutorial should be read from the top down, so the wiki format is better, IMHO.
• I prefer a tutorial on just one subject. In this case: openSCAD.

This tutorial is not meant to replace the openSCAD manual, but to

• Include things in order of how they might be learned. Each coding example uses things that have been described earlier in the tutorial.
• Include things that a beginner might not know, but that a more experienced user would regard as "clutter".
• Facilitate the expansion of the tutorial by many users.

Visualizations of the code are not included here in order that you might be inspired to cut and paste it into a running openSCAD to see how it looks. You should change some of the code to experiment with it.

## Terms used within Definitions

### Vector

A vector is a number of values between [], as [x,x,x]. The most common vectors are [width, depth, height] or [X,Y,Z] in defining shapes. In defining color values, the vectors are [red, green, blue] or [R,G,B]. They are valued from 0 to 100. Here are some vector values to be used for color
``` black = [0,0,0]; red = [1,0,0]; green = [0,1,0]; blue = [0,0,1]; magenta = [1,0,1]; white = [100,100,100]; ```

### Convexity

This is an integer. The convexity parameter specifies the maximum number of front or back sides a ray intersecting the object might penetrate. This parameter is only needed for correctly displaying the object in OpenCSG preview mode and has no effect on the polyhedron rendering.

### Subtree

A subtree is the code following a module call up to the next semicolon that is outside braces ({}). In the code

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

`cube(20)` is a subtree. This could be made more clear by writing

``` translate([0,0,0]) {cube(20);} ```
A semicolon after the "}" is required if there are statements after the subtree.

## Shapes

### cube

Here is the code for a cube that is 40mm on a side.

``` cube(40); ```
Here is a cube with a vector. Because the vector values are not the same, the "cube" is actually a rectangular prism. "true" causes the prism to be centered on the axes; "false" causes the prism to be drawn starting at one corner.

``` cube([40,40,4],true); ```

### cylinder

Here is the code for a "cylinder" (actually a cone) with the top trimmed off. It is 40mm high. Its bottom has a radius of 15mm. Its top has a radius of 5mm.

``` cylinder(40,15,5); ```

### sphere

The code for a sphere has a radius of 20mm.

``` sphere(20); ```

### polyhedron

A polyhedron is a geometric solid in three dimensions with flat faces and straight edges, or so says Wikipedia. At least this definition is more understandable than the one in the manual. The following polyhedron is a triangular prism. It consists of a number of beginning points, followed by the definition of the triangle to be drawn at each point (I think).

``` polyhedron(points=[[0,0,0],[100,0,0],[0,100,0],[0,100,100]], triangles=[[0,1,2],[1,0,3],[0,2,3],[2,1,3]]); ```

## translate

Translate locates (or moves) the thing from the junction of the X,Y and Z axes by the specified number of millimeters. It is followed by a subtree.

``` translate([x,y,z]) ```

Locate the thing in the subtree 10mm to the right (X), 20mm forward (Y) and 30mm up (Z) from the junction of the axes.

``` translate([10,20,30]) ```

Locate the thing in the subtree 10mm to the left (X), 20mm backward (Y) and 30mm down (Z) from the junction of the axes.

``` translate([-10,-20,-30]) ```

## color

After defining the vectors for the needed colors, we'll create a red cube, 30mm on a side. Then, we'll create a magenta cube 40mm on a side, set 30mm to the right of the red cube.

``` red = [1,0,0]; magenta = [1,0,1]; color(red) cube(30); translate([30,0,0]) color(magenta) cube(40); ```

## union

Render the things within the outer subtree as one thing.

``` union(){ ```

``` cube(40); translate([10, 10, 30]){ cube(20); } ```

```} ```

Here's a thing that looks like a pawn in a Staunton chess set (sort of). The base is a square platform, 40mm x 40mm that is 4mm thick. In the middle of it is a truncated cone 40mm high. Its base has a radius of 15mm. Its top has a radius of 5mm. A sphere with a radius of 10mm is placed (by "translate") 40mm up from the axes. It is centered by the 0,0 on the X and Y axes.

``` union(){ ```

``` cube([40,40,4],true); cylinder(40,15,5); translate([0,0,40])sphere(10); ```

```} ```

## echo

echo is a statement that is good for debugging (and not much else).

``` a = 5; echo(a); ```

This will echo a 5 in the lower right window of openSCAD.

## assign

assign will change the value of a variable, but it is valid just for the following subtree.

``` a = 5; assign (a=20) {echo(a);}; // This echoes a 20 echo(a); // This echoes a 5 ```

## module

A module declaration consists of the word "module", followed by the module name, the parameters in parentheses (), and a subtree. In the following example the subtree is the line beginning with "translate".
A module declaration is not executed until it is called by later code.

``` module placeIt(foo) translate([foo*3,0,0]) sphere(foo); a=5; placeIt(a); // placeIt is a call to the module with a value of 5. assign (a=20) {echo(a);placeIt(a);}; // This is a call to placeIt with a value of 20. assign(a=40) placeIt(a); // This draws a third sphere echo(a); // This echoes a 5 ```

This module will, when it's called, draw a pawn in the position indicated by the parameters:

``` module Pawn(xpos, ypos, zpos){ ```

``` translate([xpos,ypos,zpos]){ union(){ cube([40,40,4],true); cylinder(40,15,5); translate([0,0,40])sphere(10); } } } union() { Pawn(0,0,0); Pawn(45,0,0); ```

```} ```

## rotate

Rotates the object "deg" degrees around the vector.

``` rotate(deg, [x, y, z]) { ... } ```

An object may be rotated a number of degrees on all three planes. To flip an object upside-down, you might do this:

``` rotate(a=[0,180,0]) { ... } ```

## for

This will cause 4 pawns to be drawn next to one another.

``` module Pawn(xpos, ypos, zpos){ ```

``` translate([xpos,ypos,zpos]){ union(){ cube([40,40,4],true); cylinder(40,15,5); translate([0,0,40])sphere(10); } } } union(){ for(i=[0:3]){ Pawn(40*i,0,0); } ```

```} ```

The following loop sweeps the sphere around in a circle to create a ring of spheres. For each value of i from 0 to 19, a new sphere is placed with a different rotation. (The translate step moves the sphere so that the rotate step is rotating it around a point 50 units off center.)
``` union(){ ```

``` for (i = [0:19]){ rotate([0,0,i*360/20])translate([-50,0,0])sphere(10); } ```

```} ```

Here, we rotate and scale a cube by a set of primes.
The for loop works in OpenSCAD with the CSG toolset, so you can union or difference objects generated by for loops to create complex structures. (You can use intersections as well, but you’ll have to use the workaround described in the documentation.)
``` for (i = [3, 5, 7, 11]){ ```

``` rotate([i*10,0,0])scale([1,1,i])cube(10); ```

```} ```

This tutorial copies the information from the Thingiverse tutorial blog. The reasons for doing this are

• A blog lists later articles before earlier ones. A tutorial should be read from the top down, so the wiki format is better, IMHO.
• I prefer a tutorial on just one subject. In this case: openSCAD.

This tutorial is not meant to replace the openSCAD manual, but to

• Include things in order of how they might be learned. Each coding example uses things that have been described earlier in the tutorial.
• Include things that a beginner might not know, but that a more experienced user would regard as "clutter".
• Facilitate the expansion of the tutorial by many users.

Visualizations of the code are not included here in order that you might be inspired to cut and paste it into a running openSCAD to see how it looks. You should change some of the code to experiment with it.

You can also see this  : video tutorials

## Terms used within Definitions

### Vector

A vector is a number of values between [], as [x,x,x]. The most common vectors are [width, depth, height] or [X,Y,Z] in defining shapes. In defining color values, the vectors are [red, green, blue] or [R,G,B]. They are valued from 0 to 100. Here are some vector values to be used for color

```   ```
black = [0,0,0];
red = [1,0,0];
green = [0,1,0];
blue = [0,0,1];
magenta = [1,0,1];
white = [100,100,100];
```
```

### Convexity

This is an integer. The convexity parameter specifies the maximum number of front or back sides a ray intersecting the object might penetrate. This parameter is only needed for correctly displaying the object in OpenCSG preview mode and has no effect on the polyhedron rendering.

### Subtree

A subtree is the code following a module call up to the next semicolon that is outside braces ({}). In the code

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

`cube(20)` is a subtree. This could be made more clear by writing

``` translate([0,0,0]) {cube(20);} ```
A semicolon after the "}" is required if there are statements after the subtree.

## Shapes

### cube

Here is the code for a cube that is 40mm on a side.

``` cube(40); ```
Here is a cube with a vector. Because the vector values are not the same, the "cube" is actually a rectangular prism. "true" causes the prism to be centered on the axes; "false" causes the prism to be drawn starting at one corner.

``` cube([40,40,4],true); ```

### cylinder

Here is the code for a simple cylinder 20mm in height and radius 15mm :

``` cylinder(20,r=15); ```

You can use "r" for the radius or "d" for diameter.
Here is the code for a simple cylinder 20mm in height and diameter 30 mm :

``` cylinder(20,d=30); ```

Here is the code for a "cylinder" (actually a cone) with the top trimmed off. It is 40mm high. Its bottom has a radius of 15mm. Its top has a radius of 5mm.

``` cylinder(40,15,5); ```

### sphere

The code for a sphere has a radius of 20mm.

``` sphere(20); ```

### polyhedron

A polyhedron is a geometric solid in three dimensions with flat faces and straight edges, or so says Wikipedia. At least this definition is more understandable than the one in the manual. The following polyhedron is a triangular prism. It consists of a number of beginning points, followed by the definition of the triangle to be drawn at each point (I think).

``` polyhedron(points=[[0,0,0],[100,0,0],[0,100,0],[0,100,100]], triangles=[[0,1,2],[1,0,3],[0,2,3],[2,1,3]]); ```

Succinct description of a 'Polyhedron'

```* Points define all of the points/vertices in the shape.
* Triangles is a list of triangles that connect up the points/vertices.
```

Each point, in the point list, is defined with a 3-tuple x,y,z position specification. Points in the point list are given an identifier starting at zero for use in the triangle list (0,1,2,3,... etc).

Each triangle, in the triangle list, is defined by selecting 3 of the points (using the point identifier) out of the point list.

e.g. triangles=[ [0,1,2] ] defines a triangle from the first point (points are zero referenced) to the second point and then to the third point.

When looking at any triangle from the outside, the triangle must list their 3 points in a clockwise order.

## translate

Translate locates (or moves) the thing from the junction of the X,Y and Z axes by the specified number of millimeters. It is followed by a subtree.

``` translate([x,y,z]) ```

Locate the thing in the subtree 10mm to the right (X), 20mm forward (Y) and 30mm up (Z) from the junction of the axes.

``` translate([10,20,30]) ```

Locate the thing in the subtree 10mm to the left (X), 20mm backward (Y) and 30mm down (Z) from the junction of the axes.

``` translate([-10,-20,-30]) ```

## color

After defining the vectors for the needed colors, we'll create a red cube, 30mm on a side. Then, we'll create a magenta cube 40mm on a side, set 30mm to the right of the red cube.

```   ```
red = [1,0,0];
magenta = [1,0,1];
color(red) cube(30);
translate([30,0,0]) color(magenta) cube(40);
```
```

## union

Render the things within the outer subtree as one thing.

``` ```
union(){
cube(40);
translate([10, 10, 30]){
cube(20);
}
}
```
```

Here's a thing that looks like a pawn in a Staunton chess set (sort of). The base is a square platform, 40mm x 40mm that is 4mm thick. In the middle of it is a truncated cone 40mm high. Its base has a radius of 15mm. Its top has a radius of 5mm. A sphere with a radius of 10mm is placed (by "translate") 40mm up from the axes. It is centered by the 0,0 on the X and Y axes.

``` ```
union(){
cube([40,40,4],true);
cylinder(40,15,5);
translate([0,0,40])sphere(10);
}
```
```

## echo

echo is a statement that is good for debugging (and not much else).

``` ```
a = 5;
echo(a);
```
```

This will echo a 5 in the lower right window of openSCAD.

## assign

assign will change the value of a variable, but it is valid just for the following subtree.

``` ```
a = 5;
assign (a=20) {echo(a);}; // This echoes a 20
echo(a);                  // This echoes a 5
```
```

## module

A module declaration consists of the word "module", followed by the module name, the parameters in parentheses (), and a subtree. In the following example the subtree is the line beginning with "translate".
A module declaration is not executed until it is called by later code.

``` ```
module placeIt(foo)
translate([foo*3,0,0]) sphere(foo);
a=5;
placeIt(a);               // placeIt is a call to the module with a value of 5.
assign (a=20) {echo(a);placeIt(a);}; // This is a call to placeIt with a value of 20.
assign(a=40) placeIt(a);  // This draws a third sphere
echo(a);                  // This echoes a 5
```
```

This module will, when it's called, draw a pawn in the position indicated by the parameters:

``` ```
module Pawn(xpos, ypos, zpos){
translate([xpos,ypos,zpos]){
union(){
cube([40,40,4],true);
cylinder(40,15,5);
translate([0,0,40])sphere(10);
}
}
}
union() {
Pawn(0,0,0);
Pawn(45,0,0);
}
```
```

## rotate

Rotates the object "deg" degrees around the vector.

``` rotate(deg, [x, y, z]) { ... } ```

An object may be rotated a number of degrees on all three planes. To flip an object upside-down, you might do this:

``` rotate(a=[0,180,0]) { ... } ```

## for

This will cause 4 pawns to be drawn next to one another.

``` ```
module Pawn(xpos, ypos, zpos){
translate([xpos,ypos,zpos]){
union(){
cube([40,40,4],true);
cylinder(40,15,5);
translate([0,0,40])sphere(10);
}
}
}
union(){
for(i=[0:3]){
Pawn(40*i,0,0);
}
}
```
```

The following loop sweeps the sphere around in a circle to create a ring of spheres. For each value of i from 0 to 19, a new sphere is placed with a different rotation. (The translate step moves the sphere so that the rotate step is rotating it around a point 50 units off center.)

``` ```
union(){
for (i = [0:19]){
rotate([0,0,i*360/20])translate([-50,0,0])sphere(10);
}
}
```
```

Here, we rotate and scale a cube by a set of primes.
The for loop works in OpenSCAD with the CSG toolset, so you can union or difference objects generated by for loops to create complex structures. (You can use intersections as well, but you’ll have to use the workaround described in the documentation.)

``` ```
for (i = [3, 5, 7, 11]){
rotate([i*10,0,0])scale([1,1,i])cube(10);
}
```
```