OpenSCAD User Manual/The OpenSCAD Language Scripts in the OpenSCAD language are functional descriptions of how a designer's intent may realized in a solid model.

The statement is the basis of the language:

<perform named operations>;

The end of a statement is marked by a literal semi-colon (';').

Each statement either :

1. assigns the result of an expression to a variable
2. invokes one or more modules to instantiate a shape that appears in the preview panel
3. modifies the script's flow of execution.

Expressions are evaluated before any module in a statement.

The evaluation of an expression results in a value of a specific type and may replace a single variable or literal wherever syntax requires a value.

When used in a simple statement the result must be assigned to a variable

<Named Variable> = <expression>;

but in general the result of an expression is used immediately as a syntactic element.

• for( <loop variable> = <condition> ) <statement>
• [vector] = [for( <loop variable> = [<start>:<incr>:<end>] ) make_list_element( <loop variable> ) ]
• make_shape( <param>, <name>=<param> )
• echo( "giving feedback", <function_under_test>( <param> ) );

where <condition>, the <start>:<incr>:<end> values in the range, each parameter value in the call to the module, and the <function_under_test>, and <param> may all be expressions.

Modules are not like the subroutines that are the building blocks of procedural languages. OpenSCAD is all about constructing a model out of solid geometry elements, and has been designed to organize it elements in parent-child relationships.

Syntactically, the first module in a statement is a parent, and all following modules are its children. Likewise, every child is parent to any modules following them in a statement.

parent() { child(); child() { grandson() ggchild(); granddaughter() } }

The built-in modules are implemented without the ability to have children, meaning they should appear last in a statement. But user-defined modules may draw shapes and accept child modules().

Module parent-child structures may be created in the statements that are part of an If-Then-Else or For-Loop and vice versa:

module xx() {
    sphere();
    children();
    }

xx() for(i=[1,3]) translate([i*2,0,0]) cube();

This works because the xx module used a call to children() to "register" that it will accept the "responsibilities" of parenthood.

Note: Any flow of control or module following a built-in module will emit a warning and do nothing else. The module will draw its shape, but cannot handle children.

The normal operation of Constructive Solid Geometry (CSG) is to form complex shapes by combining primitive and derived shapes and performing operations on them.

To create a shape an Object Module is called:

 make_shape();

where "make_shape()" is a user defined module, but equally represents a call to any of the built-in modules. The built-in modules have default values for their parameters and will draw an appropriate shape using them when called with an empty argument list.

Note: data structure objects have been added to the language as of the 2025.07.* development snapshot releases. To clarify the language of this document, modules make curves and shapes, not objects. Only the object() function can create data structures of the object type.

To manipulate or modify an object any number of Operator Modules may be called before the make_shape():

operator() make_shape();
operator() operator() make_shape();

It is important to understand that the ability to act as parent, child, or both is part of the implementation of the "module" in OpenSCAD.

That said, it is convenient to treat the built-in modules as being of two types, operators, and shape builders, as a consequence of their implementation, as explained in the section on writing user-defined modules.

Any of the 2 Dimensional Primitives, Polygons, Text, and Imported 2D shapes may be the basis for extrusions that create 3D shapes.

Any of the 3 Dimensional Primitives, Polyhedrons, and Imported 3D Shapes may be the basis for Boolean Combinations that create 3D shapes. It is also possible to project a 3D shape onto a coordinate place to obtain its 2D silhouette.

Normally a statement does just one thing, and for assignment expressions that is enough. The choice between alternatives in an if-then-else, or the body of a for-loop, often need to perform more than one operation. OpenSCAD borrows the lexical structure of other programming languages to extend a single statement into a block of them.

A block of statements is created using braces to mark the beginning and end of the block:

{
operator() object();
operator() object();
}

This simple block is not much use as such, but it shows that any single statement may be replaced by a block of statements inside a pair of braces.

A better illustration would be:

{
for(...) { // A
    make_shape_1();
    if(...) then { // B
       operator() make_shape_2();
       operator() make_shape_3();
       } // end B
    else
       make_other_shape()
    } // end A
}

There is an overlap between the previously mentioned parent-child relations between modules and the lexical structure of this last example. Although the outer for-loop is not a module, its body being a block of statements means that it has children, the shapes drawn by make_shape_1() and the if-then-else. And that, further, it has grandchildren ... either two when the <condition> expression is true, or just one if false.

As with any structured programming language decision making and looping statements are critical features of OpenSCAD scripts. In a functional language the path, or flow, of execution through the code is controlled by the FoC statements.

The statements available are the if(cond)-else and the for([range]) loop. FoC statements are written to operate on single statements, thusly:

if(<condition>) <when true do this statement>;
else <when false do this statement>;

and with looping

for(i=[0:9]) object(); // make 10 objects

A more readable example:

if( is_string(s) )
    operator() object(file=s); // do this when <condition> == true
else
    object(file="default.dat"); // otherwise do this

Of course a single statement is often not enough. Different statement types and use cases have these coping mechanisms:

• When the statement is an assignment expression the calculation may be written into a function as calling a function is a valid expression.
• A sequence of actions may be written into a user-defined module as calling that is a single statement.
• in every case a block "{}" can replace a statement

if( is_string(s) )
    { // <condition> == true
    operator() object(file=s);
    if(<condition>)
        answer = MyOwnFunction();
    else
        answer = 12;
    }
else // <condition> == false
       // no block - the for() loop is the single statement
    for()
        { // but the target of the for loop is this block
        object(file="default.dat");
        operator() My_Own_Object();
        }

The for() and if() statements have an important secondary role in vector initialization, though it is not technically flow of control.

A third use of the for loop concept is special iteration_for() Operator Module for intersecting multiple instances of an object into a composite. Again, not technically not flow of control.

Named objects in OpenSCAD include Variables, Functions, and Modules.

To be valid a name:

• must begin with an alphabetic character [a..zA..Z] or an underscore ('_')
• and may continue with any mix of alphabetic characters, numeric digits, and the underscore
• and may not include accented characters, punctuation, nor Unicode characters.

Note: older versions of OpenSCAD allowed names to start with numeric digits but will generate run-time errors in more recent versions

The OpenSCAD convention on multi word names is to use the underscore to delimit them, as this_is_a_name

Named variables are created when they appear as the Left Hand Side of an assignment statement and will be given the value of the Right Hand Side expression.

result = <calculate something>;

Variables should normally be defined only once in a program as when the program runs the variable will have the last value assigned to it.

The location of a variable definition determines where it can be used, thus it has "scope", a concept discussed fully in the literature, with only a few issues germane to functional programming and OpenSCAD in particular needing to be covered in the following section.

A vector or list is a sequence of zero or more OpenSCAD values. Vectors are collections of numeric or boolean values, variables, vectors, strings or any combination thereof. They can also be expressions that evaluate to one of these. Vectors handle the role of arrays found in many imperative languages. The information here also applies to lists and tables that use vectors for their data.

A vector has square brackets, [] enclosing zero or more items (elements or members), separated by commas. A vector can contain vectors, which can contain vectors, etc.

Examples

   [1,2,3]
   [a,5,b]
   []
   [5.643]
   ["a","b","string"]
   [[1,r],[x,y,z,4,5]]
   [3, 5, [6,7], [[8,9],[10,[11,12],13], c, "string"]
   [4/3, 6*1.5, cos(60)]

use in OpenSCAD:

  cube( [width,depth,height] );           // optional spaces shown for clarity
  translate( [x,y,z] )
  polygon( [ [x0,y0],  [x1,y1],  [x2,y2] ] );

Vectors are created by writing the list of elements, separated by commas, and enclosed in square brackets. Variables are replaced by their values.

  cube([10,15,20]);
  a1 = [1,2,3];
  a2 = [4,5];
  a3 = [6,7,8,9];
  b  = [a1,a2,a3];    // [ [1,2,3], [4,5], [6,7,8,9] ]  note increased nesting depth

Vectors can be initialized using a for loop enclosed in square brackets.

The following example initializes the vector result with a length n of 10 values to the value of a.

n = 10;
a = 0;

result = [ for (i=[0:n-1]) a ];
echo(result); //ECHO: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

The following example shows a vector result with a n length of 10 initialized with values that are alternatively a or b respectively if the index position i is an even or an odd number.

n = 10;
a = 0;
b = 1;
result = [ for (i=[0:n-1]) (i % 2 == 0) ? a : b ];
echo(result); //ECHO: [0, 1, 0, 1, 0, 1, 0, 1, 0, 1]

Elements within vectors are numbered from 0 to n-1 where n is the length returned by len(). Address elements within vectors with the following notation:

e[5]           // element no 5 (sixth) at   1st nesting level
e[5][2]        // element 2 of element 5    2nd nesting level
e[5][2][0]     // element 0 of 2 of 5       3rd nesting level
e[5][2][0][1]  // element 1 of 0 of 2 of 5  4th nesting level

e = [ [1], [], [3,4,5], "string", "x", [[10,11],[12,13,14],[[15,16],[17]]] ];  // length 6

address       length  element
e[0]          1       [1]
e[1]          0       []
e[5]          3       [ [10,11], [12,13,14], [[15,16],[17]] ]
e[5][1]       3       [ 12, 13, 14 ]
e[5][2]       2       [ [15,16], [17] ]
e[5][2][0]    2       [ 15, 16 ]
e[5][2][0][1] undef   16
    
e[3]          6       "string"
e[3 ][2]      1       "r"
  
s = [2,0,5]; a = 2;
s[a]          undef   5
e[s[a]]       3       [ [10,11], [12,13,14], [[15,16],[17]] ]

The elements (characters) of a string can be accessed:

"string"[2]    //resolves to "r"

[Note: Requires version Dev Snapshot 2021.12.23 or later]

The components of vectors can be accessed using the following syntax:

e = [1, 2, 3, 4];
v = e.x + e.y; // yields 1 + 2 = 3

This is called swizzling. You can use x, y, z, or w, referring to the first, second, third, and fourth components, respectively. Alternatively, r, g, b, and a can be used instead of x,y,z,w.

Swizzling is named so because you can use it to repeat, reorder, or select a subset of components.

v1 = e.xyxx; // -> [1,2,1,1]
v2 = e.zyy;  // -> [3,2,2]
v3 = e.rrr;  // -> [1,1,1]
v4 = e.rg;   // -> [1,2]

You can use any combination of up to 4 of the letters to create a vector. Attempts to reference components which doesn't exist will result in an undef.

[Note: Requires version 2015.03]

concat() combines the elements of 2 or more vectors into a single vector. No change in nesting level is made.

 vector1 = [1,2,3]; vector2 = [4]; vector3 = [5,6];
 new_vector = concat(vector1, vector2, vector3); // [1,2,3,4,5,6]
  
 string_vector = concat("abc","def");                 // ["abc", "def"]
 one_string = str(string_vector[0],string_vector[1]); // "abcdef"

len() is a function that returns the length of vectors or strings. Indices of elements are from [0] to [length-1].

vector

Returns the number of elements at this level.

Single values, which are not vectors, raise an error.

string

Returns the number of characters in a string.

 a = [1,2,3]; echo(len(a));   //  3

See example elements with lengths

A matrix is a vector of vectors.

Example that defines a 2D rotation matrix
mr = [
     [cos(angle), -sin(angle)],
     [sin(angle),  cos(angle)]
     ];

Most of the other commonly available components of a structured programming language are included in OpenSCAD, namely

Named Objects and Scope

variables, functions, and modules

Data Types, Values, and Constants

64-bit floating point, boolean, string, and vector (or list)

Data Structures

Vectors and Objects

Expressions

arithmetic, string, bitwise, and logical

Built-In Functions

all the standard functions for use in expressions of all types

Syntactic Operators

The language has features that work like built-in modules but are different in detail, Echo, Let, Assert

User Defined Objects

custom modules and functions

Language Elements particularly needed for modelling are

Built-in 2D Object Modules

circle(), square(), polygon(), etc.

2D file import

Adding drawn shapes from SVG, DXF, image, and text data files

3D File Import

adding geometry from external sources

Built-In 3D Object Modules

sphere(), cube(), polyhedron(), etc.

Built-In Operator Modules

• 3D boolean operations: intersection(), difference(), union()
• Shape Modifications : linear_extrude(), rotate_extrude(), hull(), etc.
• Transformations : translate(), rotate(), etc.
• Color

Customizer

Compile time user input

A value in OpenSCAD is either a Number (like 42), a Boolean (like true), a String (like "foo"), a Range (like [0: 1: 10]), a Vector (like [1,2,3]), or the Undefined value (undef). Values can be stored in variables, passed as function arguments, and returned as function results.

[OpenSCAD is a dynamically typed language with a fixed set of data types. There are no type names, and no user defined types.]

Numbers are the most important type in OpenSCAD, and they are written in the decimal notation common to most programming languages:

42

the answer for everything

-1

a negative value

0x22

a hexadecimal value (34₁₀)

0.5

a decimal fraction

1.0123e-5

a very small fraction (0.000010123) in scientific notation

2.99792458e+8

a very large value in scientific notation

The internal form of numbers follows the 64-bit IEEE floating point number specification. Zero (0) and negative zero (-0) are treated as two distinct numbers by some of the math operations, and are displayed as such by 'echo', although they compare as equal. Complex numbers are not supported.

Integers are just 52-bit numbers without a fractional part. Literal hexadecimal values in a script are also evaluated to their integer value and stored as 52-bit binaries.

Values used in bitwise operations are an exception as their 64-bit encoding is binary, but only during the operation. The results of a bitwise expression are converted to the normal 64-bit floating format.

Limitation: Fractions are not represented exactly unless the denominator is a power of 2

• The largest value possible is about 1³⁰⁸. If an expression evaluates to a larger value it will be treated as "infinity" and printed as "inf" by echo.
• The most negative value is about -1³⁰⁸. Negative infinity is printed as "-inf" by echo.
• very small fractions may be displayed as 0 or -0 by echo().

As noted in the limitation above, power of 2 fractions, like 0.25 (1/4) and 0.375 (3/8), are represented exactly, but 2 divided by 10, 2/10 = 0.2 is only approximated. Also, 64-bit floating values are only accurate to 15-17 decimal digits, meaning that the least significant digit of a 17 digit number is undetermined.

In practice this means that two FP values calculated differently, but that should come to same result, may encoded to slightly different digits, which will cause a test for equality to fail. This happens when their differences are close to, or less than, the Min.Normal value derived from the numerical representation (see geekley's list of Number Limits).

A Quick and Dirty solution to the Nearly Equal problem is to see if the difference of the two values is smaller than an acceptable value, epsilon.

/**	returns true when two floating point values are within
  epsilons value of each other. */
function _nearly_equal( a, b, epsilon=0.00001 ) =
    abs(( a - b )/ b ) < epsilon 
    ;

A more elegant, and more numerically correct version is available in the numbers.scad file of the relativity library (soon to be released), provided here as an extract from the library.

C style hexadecimal constants are allowed to be assigned to variables.

hex1 = 0x32;     // ASCII space
hex2 = 0x98 - 1; // ASCII 'a'
num1 = 0x2334;   // 9012
num2 = 0x233411  // 2.30709e+6

[Note: Requires version Development snapshot].

OpenSCAD does not support octal notation for numbers.

These special numbers are defined:

PI

π, 3.141592 approximately. The ratio between the diameter and circumference of a circle.

infinities

there is no constant for inf nor -inf

NaN

Not a Number, nor is nan a real constant.

While there are no constants for inf, -inf, and nan they can be created by arithmetic operations and be assigned to variables for when needed:

inf = 1e200 * 1e200;
nan = 0 / 0;
echo(inf,nan); // ECHO: inf, nan

As mentioned at the top of this page, the 64-bit encoding of floating point values requires that both positive and negative infinity have to be able to be displayed in output messages. To be able to display something for undefined math results, like ${\displaystyle {\sqrt {-1}}}$ or Divide by Zero the industry "standard" is "Not A Number", or nan. The background for this issue is covered at the Open Group's site on math.h and the page on the IEEE 754 staqndard.

OpenSCAD has not implemented everything as it is in C/C++. For example, it uses degrees angles and trigonometric functions. This table shows the results of giving undefined inputs to built-in math functions taken from the regression test suite in 2015.

The value nan is the only OpenSCAD value that is not equal to any other value, including itself. The conditional expression x == 0/0 will fail with a run-time error. Instead, you must use 'x != x' to test if x is "nan".

The undefined value is a special value written as undef. It is the initial value of a variable that hasn't been assigned a value, and it is often returned as a result by functions or operations that are passed illegal arguments. Finally, undef can be used as a null value, equivalent to null or NULL in other programming languages.

All arithmetic expressions containing undef values evaluate as undef. In logical expressions, undef is equivalent to false. Relational operator expressions with undef evaluate as false except for undef==undef, which is true.

Note that numeric operations may also return 'nan' (not-a-number) to indicate an illegal argument. For example, 0/false is undef, but 0/0 is 'nan'. Relational operators like < and > return false if passed illegal arguments. Although undef is a language value, 'nan' is not.

A variable is created by the assignment statement that sets its value, thus defining it, and it cannot thereafter be changed. But, unlike constants in other languages, assignments may be overridden.

A second assignment to the same variable will cause a warning about its value being reassigned, and has the effect of replacing first assignment with the second one. In fact, the value that the variable holds throughout the run-time of the script is that set by the last assignment that uses it as the LHS.

a = 1;   // effectively replaced and never executed
echo(a); // 2
a = 2;   // as if executed at the a=1 statement
echo(a); // 2

There are two exceptions to this behavior:

• an assignment in an included file may be given a new value in the including file.
• an assignment in a script will take a new value from -D command line option
• likewise for a variable set in the Customizer.

This allows variables to be given default values in a shared library that are then given new values in scripts that include it.

// main.scad
include <lib.scad>
a = 2;
echo(b); // ECHO: 3

// lib.scad
a = 1;
b = a + 1;

An OpenSCAD program cannot prompt the user for interactive input while running, but it is possible to access data from files, the Customizer Panel, and the command line.

• the Customizer may be used to set values that modify the parsing and rendering of an .scad program
• If the app is opened from the command line a -D at the -D value argument
• read data from .stl, .dxf, or .png files.

OpenSCAD can import objects from STL files to be manipulated (translation, clipping, etc.) and rendered. The data in the STL file cannot be accessed.

Data in a DXF file may be accessed using this functions:

[X,Y,Z] = dxf_cross( file="name.dxf", layer="a.layer", origin=[0,0], scale=1.0 )

This function returns the intersection of two lines on the given layer.

N= dxf_dim( file="name.dxf", name="namedDimension", layer="a.layer", origin=[0, 0], scale=1);

The function looks for two lines on the given layer and calculates their intersection. The intersection may not be defined as a point entity.

OriginPoint = dxf_cross(file="drawing.dxf", layer="SCAD.Origin", 
                        origin=[0, 0], scale=1);

Dimensions in a DXF file that are named may be accessed for use in an OpenSCAD program using a call to dxf_dim();

TotalWidth = dxf_dim(file="drawing.dxf", name="TotalWidth",
                        layer="SCAD.Origin", origin=[0, 0], scale=1);

For a nice example of both functions, see Example009 and the image on the homepage of OpenSCAD.

OpenSCAD User Manual/The OpenSCAD Language

Creates a cube or rectangular prism (i.e., a "box") in the first octant. When center is true, the cube is centered on the origin. Argument names are optional if given in the order shown here.

cube(size = [x,y,z], center = true/false);
cube(size =  x ,     center = true/false);

parameters:

size

single value, cube with all sides this length

3 value array [x,y,z], rectangular prism with dimensions x, y and z.

center

false (default), 1st (positive) octant, one corner at (0,0,0)

true, cube is centered at (0,0,0)

default values:  cube();   yields:  cube(size = [1, 1, 1], center = false);

examples:

equivalent scripts for this example
 cube(size = 18);
 cube(18);
 cube([18,18,18]);
 .
 cube(18,false);
 cube([18,18,18],false);
 cube([18,18,18],center=false);
 cube(size = [18,18,18], center = false);
 cube(center = false,size = [18,18,18] );

equivalent scripts for this example
 cube([18,28,8],true);
 box=[18,28,8];cube(box,true);

With default parameters this module draws a unit sphere at the origin of the coordinate system, centered vertically on the X-Y plane. It appears as a five sided polyhedron when $fn is zero per the smoothness variables.

default sphere( 1, $fn = 0, $fa = 12, $fs = 2 )

Parameters

1) r

non-negative float, radius

d

non-negative float, diameter

$fn, $fs, $fa

Smoothness settings, see Rendering: Curve_Smoothness

Radius

The distance from the sphere's center to its surface. A negative value will emit a warning and draw nothing. The smoothness of the surface is determined by the smoothness parameters, $fn, $fs, $fa

Diameter

This must be given as a named parameter.

Usage Examples

sphere();       // radius = 1 by default
sphere(r = 2);
sphere(d = 4);  // same size as previous

To draw a very smooth sphere with a 2 mm radius:

sphere(2, $fn=100); 

// also creates a 2mm high resolution sphere but this one 
// does not have as many small triangles on the poles of the sphere
sphere(2, $fa=5, $fs=0.1); 

Creates a cylinder or cone centered about the z axis.

Called with no arguments, and $fn at its default, the module creates a 1 unit tall, pentagonal solid on the X-Y plane that is inscribed in a unit circle.

Parameter names are optional if the first three are given in the order of height, radius 1 (bottom radius), and radius 2 (top radius) as seen here:

cylinder(h, r1, r2);

Omitting r1 or r2 leaves them at their default values of one resulting in a truncated cone (a Conical Frustum). The named parameters may be given in any order, but for any of the diameter related ones only the first given is used. Giving a diameter/radius value of zero results in a cone shape, and setting both to zero make no shape at all.

Parameters

h : (pos 1) height of the cylinder, must be greater than zero

r1 : (pos 2) radius of bottom circular face.

r2 : (pos 3) radius of top circular face.

center : (pos 4)

false (default), height is from the X-Y plane to positive Z

true height is centered vertically on the X-Y plane

r  : radius of both end faces

d  : diameter of both end faces. [Note: Requires version 2014.03]

d1 : diameter of bottom circular face. [Note: Requires version 2014.03]

d2 : diameter of top circular face. [Note: Requires version 2014.03]

$fa : minimum angle (in degrees) of each fragment.

$fs : minimum circumferential length of each fragment.

$fn : fixed number of fragments in 360 degrees. Values of 3 or more override $fa and $fs

$fa, $fs and $fn must be named parameters. click here for more details,.

default values:
 cylinder($fn = 0, $fa = 12, $fs = 2, h = 1, r1 = 1, r2 = 1, center = false);
 cylinder($fn = 0, $fa = 12, $fs = 2, h = 1, d1 = 1, d2 = 1, center = false); // radius = 0.5

All of the following calls result in this conic frustum:

cylinder(h=15, r1=9.5, r2=19.5, center=false);
cylinder(  15,    9.5,    19.5, false);
cylinder(  15,    9.5,    19.5);
cylinder(  15,    9.5, d2=39  );
cylinder(  15, d1=19,  d2=39  );
cylinder(  15, d1=19,  r2=19.5);

All of these result in this cone:

cylinder(h=15, r1=10, r2=0, center=true);
cylinder(  15,    10,    0,        true);
cylinder(h=15, d1=20, d2=0, center=true);

• 
  center = false
• 
  center = true

equivalent scripts
 cylinder(h=20, r=10, center=true);
 cylinder(  20,   10, 10,true);
 cylinder(  20, d=20, center=true);
 cylinder(  20,r1=10, d2=20, center=true);
 cylinder(  20,r1=10, d2=2*10, center=true);

use of $fn

Larger values of $fn create smoother surfaces at the cost of greater rendering time. A good practice is to set it in the range of 10 to 20 during development of a shape, then change to a value larger than 30 for rendering image or exporting shape files.

However, use of small values can produce some interesting non circular objects. A few examples are show here:

scripts for these examples
 cylinder(20,20,20,$fn=3);
 cylinder(20,20,00,$fn=4);
 cylinder(20,20,10,$fn=4);

undersized holes

Using cylinder() with difference() to place holes in objects creates undersized holes. This is because circular paths are approximated with polygons inscribed within in a circle. The points of the polygon are on the circle, but straight lines between are inside. To have all of the hole larger than the true circle, the polygon must lie wholly outside of the circle (circumscribed). Modules for circumscribed holes

script for this example
 poly_n = 6;
 color("blue") translate([0, 0, 0.02]) linear_extrude(0.1) circle(10, $fn=poly_n);
 color("green") translate([0, 0, 0.01]) linear_extrude(0.1) circle(10, $fn=360);
 color("purple") linear_extrude(0.1) circle(10/cos(180/poly_n), $fn=poly_n);

In general, a polygon of radius ${\displaystyle r}$ has a radius to the midpoint of any side as ${\displaystyle r_{m}=r\cos(180/n)}$. If only the midpoint radius ${\displaystyle r_{m}}$ is known (for example, to fit a hex key into a hexagonal hole), then the polygon radius is ${\displaystyle r={\frac {r_{m}}{\cos(180/n)}}}$.

A polyhedron is the most general 3D primitive solid. It can be used to create any regular or irregular shape including those with concave as well as convex features. Curved surfaces are approximated by a series of flat surfaces.

polyhedron( points = [ [X0, Y0, Z0], [X1, Y1, Z1], ... ], triangles = [ [P0, P1, P2], ... ], convexity = N);   // before 2014.03
polyhedron( points = [ [X0, Y0, Z0], [X1, Y1, Z1], ... ], faces = [ [P0, P1, P2, P3, ...], ... ], convexity = N);   // 2014.03 & later

Parameters

points

vector of [x,y,z] vertices. Points may be defined in any order.

triangles

[Deprecated: triangles  will be removed in a future release. Use Use faces parameter instead instead] Vector of triangles that enclose the solid. Triangles are vectors containing three indices into the points vector.

faces

[Note: Requires version 2014.03] Vector of faces that collectively enclose the solid. Each face is a vector containing the indices (0 based) of 3 or more points from the points vector. Faces may be defined in any order, but the points of each face must be ordered correctly (see below). Define enough faces to fully enclose the solid, with no overlap. If points that describe a single face are not on the same plane, the face is automatically split into triangles as needed.

convexity

Integer, default=1

Facing and Points Order

In the list of faces, for each face it is arbitrary which point you start with, but the points of the face (referenced by the index into the list of points) must be ordered in clockwise direction when looking at each face from outside inward. The back is viewed from the back, the bottom from the bottom, etc.

Another way to remember this ordering requirement is to use the left-hand rule. Using your left hand, stick your thumb up and curl your fingers as if giving the thumbs-up sign, point your thumb away from the face, and order the points in the direction your fingers curl (this is the opposite of the STL file format convention, which uses a "right-hand rule"). Try this on the example below.

Example 1

Using polyhedron to generate a rectangular prism [ 10, 7, 5 ] :

CubePoints = [
  [  0,  0,  0 ],  //0
  [ 10,  0,  0 ],  //1
  [ 10,  7,  0 ],  //2
  [  0,  7,  0 ],  //3
  [  0,  0,  5 ],  //4
  [ 10,  0,  5 ],  //5
  [ 10,  7,  5 ],  //6
  [  0,  7,  5 ]]; //7
  
CubeFaces = [
  [0,1,2,3],  // bottom
  [4,5,1,0],  // front
  [7,6,5,4],  // top
  [5,6,2,1],  // right
  [6,7,3,2],  // back
  [7,4,0,3]]; // left
  
polyhedron( CubePoints, CubeFaces );

equivalent descriptions of the bottom face
  [0,1,2,3],
  [0,1,2,3,0],
  [1,2,3,0],
  [2,3,0,1],
  [3,0,1,2],
  [0,1,2],[2,3,0],   // 2 tris with no overlap
  [1,2,3],[3,0,1],
  [1,2,3],[0,1,3],

Example 2 A square base pyramid:

polyhedron(
  points=[ [10,10,0],[10,-10,0],[-10,-10,0],[-10,10,0], // the base
           [0,0,10]  ],                       // the apex point 
  faces=[ [0,1,4],[1,2,4],[2,3,4],[3,0,4],    // each triangle side
          [1,0,3],[2,1,3] ]                   // two triangles for square base
 );

Example 3 A triangular prism

module prism(l, w, h) {
    polyhedron(// pt      0        1        2        3        4        5
               points=[[0,0,0], [0,w,h], [l,w,h], [l,0,0], [0,w,0], [l,w,0]],
               // top sloping face (A)
               faces=[[0,1,2,3],
               // vertical rectangular face (B)
               [2,1,4,5],
               // bottom face (C)
               [0,3,5,4],
               // rear triangular face (D)
               [0,4,1],
               // front triangular face (E)
               [3,2,5]]
               );}
prism(10, 10, 5);

Mistakes in defining polyhedra include not having all faces in clockwise order (viewed from outside - a bottom need to be viewed from below), overlap of faces and missing faces or portions of faces. As a general rule, the polyhedron faces should also satisfy manifold conditions:

• exactly two faces should meet at any polyhedron edge.
• if two faces have a vertex in common, they should be in the same cycle face-edge around the vertex.

The first rule eliminates polyhedra like two cubes with a common edge and not watertight models; the second excludes polyhedra like two cubes with a common vertex.

When viewed from the outside, the points describing each face must be in the same clockwise order, and provides a mechanism for detecting counterclockwise. When the thrown together view (F12) is used with F5, CCW faces are shown in pink. Reorder the points for incorrect faces. Rotate the object to view all faces. The pink view can be turned off with F10.

OpenSCAD allows, temporarily, commenting out part of the face descriptions so that only the remaining faces are displayed. Use // to comment out the rest of the line. Use /* and */ to start and end a comment block. This can be part of a line or extend over several lines. Viewing only part of the faces can be helpful in determining the right points for an individual face. Note that a solid is not shown, only the faces. If using F12, all faces have one pink side. Commenting some faces helps also to show any internal face.

CubeFaces = [
/* [0,1,2,3],  // bottom
   [4,5,1,0],  // front */
   [7,6,5,4],  // top
/* [5,6,2,1],  // right
   [6,7,3,2],  // back */
   [7,4,0,3]]; // left

After defining a polyhedron, its preview may seem correct. The polyhedron alone may even render fine. However, to be sure it is a valid manifold and that it can generate a valid STL file, union it with any cube and render it (F6). If the polyhedron disappears, it means that it is not correct. Revise the winding order of all faces and the two rules stated above.

Example 4

a more complex polyhedron with mis-ordered faces When you select 'Thrown together' from the view menu and compile (preview F5) the design (not compile and render!) the preview shows the mis-oriented polygons highlighted. Unfortunately this highlighting is not possible in the OpenCSG preview mode because it would interfere with the way the OpenCSG preview mode is implemented.)

Below you can see the code and the picture of such a problematic polyhedron, the bad polygons (faces or compositions of faces) are in pink.

// Bad polyhedron
polyhedron
    (points = [
	       [0, -10, 60], [0, 10, 60], [0, 10, 0], [0, -10, 0], [60, -10, 60], [60, 10, 60], 
	       [10, -10, 50], [10, 10, 50], [10, 10, 30], [10, -10, 30], [30, -10, 50], [30, 10, 50]
	       ], 
     faces = [
		  [0,2,3],   [0,1,2],  [0,4,5],  [0,5,1],   [5,4,2],  [2,4,3],
                  [6,8,9],  [6,7,8],  [6,10,11], [6,11,7], [10,8,11],
		  [10,9,8], [0,3,9],  [9,0,6], [10,6, 0],  [0,4,10],
                  [3,9,10], [3,10,4], [1,7,11],  [1,11,5], [1,7,8],  
                  [1,8,2],  [2,8,11], [2,11,5]
		  ]
     );

A correct polyhedron would be the following:

polyhedron
    (points = [
	       [0, -10, 60], [0, 10, 60], [0, 10, 0], [0, -10, 0], [60, -10, 60], [60, 10, 60], 
	       [10, -10, 50], [10, 10, 50], [10, 10, 30], [10, -10, 30], [30, -10, 50], [30, 10, 50]
	       ], 
     faces = [
		  [0,3,2],  [0,2,1],  [4,0,5],  [5,0,1],  [5,2,4],  [4,2,3],
                  [6,8,9],  [6,7,8],  [6,10,11],[6,11,7], [10,8,11],
		  [10,9,8], [3,0,9],  [9,0,6],  [10,6, 0],[0,4,10],
                  [3,9,10], [3,10,4], [1,7,11], [1,11,5], [1,8,7],  
                  [2,8,1],  [8,2,11], [5,11,2]
		  ]
     );

Face Orientation in Polyhedra

If you don't really understand "orientation", try to identify the mis-oriented pink faces and then invert the sequence of the references to the points vectors until you get it right. E.g. in the above example, the third triangle ([0,4,5]) was wrong and we fixed it as [4,0,5]. Remember that a face list is a circular list. In addition, you may select "Show Edges" from the "View Menu", print a screen capture and number both the points and the faces. In our example, the points are annotated in black and the faces in blue. Turn the object around and make a second copy from the back if needed. This way you can keep track.

Clockwise technique

Orientation is determined by clockwise circular indexing. This means that if you're looking at the triangle (in this case [4,0,5]) from the outside you'll see that the path is clockwise around the center of the face. The winding order [4,0,5] is clockwise and therefore good. The winding order [0,4,5] is counter-clockwise and therefore bad. Likewise, any other clockwise order of [4,0,5] works: [5,4,0] & [0,5,4] are good too. If you use the clockwise technique, you'll always have your faces outside (outside of OpenSCAD, other programs do use counter-clockwise as the outside though).

Think of it as a "left hand rule":

If you place your left hand on the face with your fingers curled in the direction of the order of the points, your thumb should point outward. If your thumb points inward, you need to reverse the winding order.

Succinct description of a 'Polyhedron'

• Points define all of the points/vertices in the shape.
• Faces is a list of polygons 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 automatically enumerated starting from zero for use in the faces list (0,1,2,3,... etc).

Each face, in the faces list, is defined by selecting 3 or more of the points (using the point order number) out of the point list.

e.g. faces=[ [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 face from the outside, the face must list all points in a clockwise order.

The point list of the polyhedron definition may have repetitions. When two or more points have the same coordinates they are considered the same polyhedron vertex. So, the following polyhedron:

points = [[ 0, 0, 0], [10, 0, 0], [ 0,10, 0],
          [ 0, 0, 0], [10, 0, 0], [ 0,10, 0],
          [ 0,10, 0], [10, 0, 0], [ 0, 0,10],
          [ 0, 0, 0], [ 0, 0,10], [10, 0, 0],
          [ 0, 0, 0], [ 0,10, 0], [ 0, 0,10]];
polyhedron(points, [[0,1,2], [3,4,5], [6,7,8], [9,10,11], [12,13,14]]);

define the same tetrahedron as:

points = [[0,0,0], [0,10,0], [10,0,0], [0,0,10]];
polyhedron(points, [[0,2,1], [0,1,3], [1,2,3], [0,3,2]]);

Using the projection() function, you can create 2d drawings from 3d models, and export them to the dxf format. It works by projecting a 3D model to the (x,y) plane, with z at 0. If cut=true, only points with z=0 are considered (effectively cutting the object), with cut=false(the default), points above and below the plane are considered as well (creating a proper projection).

Example: Consider example002.scad, that comes with OpenSCAD.

Then you can do a 'cut' projection, which gives you the 'slice' of the x-y plane with z=0.

projection(cut = true) example002();

You can also do an 'ordinary' projection, which gives a sort of 'shadow' of the object onto the xy plane.

projection(cut = false) example002();

Another Example

You can also use projection to get a 'side view' of an object. Let's take example002, rotate it, and move it up out of the X-Y plane:

translate([0,0,25]) rotate([90,0,0]) example002();

Now we can get a side view with projection()

projection() translate([0,0,25]) rotate([90,0,0]) example002();

Links:

• More complicated example from Giles Bathgate's blog

OpenSCAD User Manual/The OpenSCAD Language All 2D primitives can be transformed with 3D transformations. They are usually used as part of a 3D extrusion. Although they are infinitely thin, they are rendered with a 1-unit thickness.

Note: Trying to subtract with difference() from 3D object will lead to unexpected results in final rendering.

By default this module draws a unit square in the first quadrant, (+X,+Y), starting at the origin [0,0]. Its four lines have no thickness but the shape is drawn as a 1 unit high, filled plane.

The module's arguments may be written in the order <size>, center=<bool> without being named, but the names may be used as shown in the examples:

Parameters

size

has two forms: single value or vector

single - non-negative float, length of all four sides

array[x,y] of two non-negative floats, the length of the sides in the x and y directions

center

boolean, default false, to set the shape's position in the X-Y plane

Center When false, as it is by default, the shape will be drawn from its first point at (0,0) in the First Quadrant, (+X,+Y). With center set to true the shape is drawn centered on the origin.

Examples

Except for being 10 cm square this is a default square:

 square(size = 10, center=false);
 square(10,false);
 square([10,10]);

And to draw a 20x10 rectangle, centered on the origin, like this:

 square([20,10],true);
 a=[20,10]; square(a,true);

By default this module draws a unit circle centered on the origin [0,0] as a pentagon with its starting point on the X-axis at X=1. Its lines have no thickness but the shape is drawn as a 1 unit high, filled plane.

The circle() shape is drawn as if inscribed in a circle of the given radius, starting at a point on the positive x axis.

The argument radius may be given without being named, but the r and d arguments must be named.

Parameters

1) radius

non-negative float, radius of the circle

r

non-negative float, radius of the circle

d

non-negative float, diameter of the circle

$fa

Special Variable

$fs

Special Variable

$fn

Special Variable

The default circle displays as a pentagram as that is the minimum number of fragments used to approximate a curved shape calculated from the default values for $fs and $fa. To have it draw as a smooth shape increase the $fn value, the minimum number of fragments to draw, to 20 or more (best $fn < 128).

An alternative method to draw a very smooth circle scale is to scale down a very large circle.

scale( 0.001 ) circle(200);

Equivalent scripts for this example

 circle(10);
 circle(r=10);
 circle(d=20);

There is no built-in module that for generating an ellipse, but the scale() or resize() operator modules may be used to form an ellipse. See OpenSCAD User Manual/Transformations

Examples

 resize([30,10]) circle(d=20); // change the circle to X and Y sizes

 scale([1.5,0.5]) circle(d=20); // apply X and Y factors to circle dimensions

There is no built-in module for generating regular polygons.

It is possible to use the special variable $fn rendering parameter to set the number of sides to use when drawing the circle().

 circle(r=1, $fn=4); // generate a unit square

Examples

The following script draws these these examples:

translate([-42,  0])
    {circle(20,$fn=3);  %circle(20,$fn=90); }
translate([  0,  0]) circle(20,$fn=4);
translate([ 42,  0]) circle(20,$fn=5);
translate([-42,-42]) circle(20,$fn=6);
translate([  0,-42]) circle(20,$fn=8);
translate([ 42,-42]) circle(20,$fn=12);
  
color("black"){
    translate([-42,  0,1])text( "3",7);
    translate([  0,  0,1])text( "4",7);
    translate([ 42,  0,1])text( "5",7);
    translate([-42,-42,1])text( "6",7);
    translate([  0,-42,1])text( "8",7);
    translate([ 42,-42,1])text("12",7);
    }

Another way to solve the lack of a built-in module for regular polygons is to write a custom one: module regular_polygon()

The polygon() module draws lines between the points given in a vector of [x,y] coordinates using, optionally, one or more "paths" that specify the order of the points to draw lines between, overriding the "natural" order. Polygons are always created in the X-Y plane and are co-planar by definition.

A polygon is the most general of the 2D objects in that it may be used to generate shapes with both concave and convex edges, have interior holes, and effectively perform boolean operations between shapes defined by paths.

Note that the order of the points sets how the lines will be drawn so complex shapes made with crossing lines can be achieved without using a path argument, but making interior holes do require the use of at least two paths to set the interior and exterior boundary lines.

The determination of which parts of the polygon to fill and to leave empty is handled automatically and it is only the filled parts that will be extruded, if the shape will be used as a basis for that operation. Note also that a shape drawn entirely within a "hole" will be filled in, and any shape its interior will again be a hole, and so on.

polygon(points, paths = undef, convexity = 1);

Parameters

points

required and positional - A vector of [x,y] coords that define the points of the polygon

paths

optional, default=undef - a vector of vectors of indices into the points vector with no restrictions on order or multiple references.

convexity

Integer, default=1 - complex edge geometry may require a higher value value to preview correctly.

Points Parameter A list of X-Y coordinates in this form:

[[1, 1], [1, 4], [3, 4], [3, 1], [1, 1]]

which defines four points and makes it explicit that the last one is the same as the first.

Including the first point twice is not strictly necessary as this:

[[1, 1], [1, 4], [3, 4], [3, 1]]

gives the same result.

Paths Parameter

This optional parameter is a nested vector of paths.

A "path" is a list of index values that reference points in the points vector. It can explicitly describe a closed loop by its last index being the same as its first, as in:

[1, 2, 3, 4, 1]

but this is equivalent to:

[1, 2, 3, 4]

Paths that cross each other can implicitly perform boolean operations but to cut holes in the interior of the polygon paths will have to be used.

Notice that the points vector is simple list, while each path is a separate vector. This means that paths, that are lists of references to points, have to "know" which points it needs to include. This can be an issue if the polygon is assembled from a number of shapes at run time as the order of adding shapes affects their point's index values. . Convexity

Shapes with a lot of detail in their edges may need the convexity parameter increased to preview correctly. See Convexity

Example With No Holes

This will draw a slanted rectangle:

polygon(points=[[0,0],[100,0],[130,50],[30,50]]);

and the same shape with the path vector:

polygon([[0,0],[100,0],[130,50],[30,50]], paths=[[0,1,2,3]]);

Note that the path can index the points starting with any one of them, so long as the list of references "walks" around the outside of the shape.

Example With One Hole

Using vector literals to draw a triangle with its center cut out. Note the two paths:

polygon(
   [[0,0],[100,0],[0,100],[10,10],[80,10],[10,80]],
   [[0,1,2],[3,4,5]]
   );

And using variables:

triangle_points =[[0,0],[100,0],[0,100],[10,10],[80,10],[10,80]];
triangle_paths =[[0,1,2],[3,4,5]];
polygon(triangle_points,triangle_paths);

When there is a shape wholly inside the bounds of another it makes a hole.

Example With Multiple Holes

[Note: Requires version 2015.03] (for use of concat())

We are using "a" for the point lists and "b" for their paths:

a0 = [[0,0],[100,0],[130,50],[30,50]];     // outer boundary
b0 = [1,0,3,2];
a1 = [[20,20],[40,20],[30,30]];            // hole 1
b1 = [4,5,6];
a2 = [[50,20],[60,20],[40,30]];            // hole 2
b2 = [7,8,9];
a3 = [[65,10],[80,10],[80,40],[65,40]];    // hole 3
b3 = [10,11,12,13];
a4 = [[98,10],[115,40],[85,40],[85,10]];   // hole 4
b4 = [14,15,16,17];
a  = concat( a0,a1,a2,a3,a4 ); // merge all points into "a"
b  = [b0,b1,b2,b3,b4]; // place all paths into a vector
polygon(a,b);
      //alternate 
polygon(a,[b0,b1,b2,b3,b4]);

2D to 3D by Extrusion

A polygon may be the basis for an extrusion, just as any of the 2D primitives can. This example script may be used to draw the shape in this image:

[Deprecated: import_dxf()  will be removed in a future release. Use Use import() Object Module instead. instead]

Read a DXF file and create a 2D shape.

Example

linear_extrude(height = 5, center = true)
		import_dxf(file = "example009.dxf", layer = "plate");

Example with Import()

linear_extrude(height = 5, center = true)
		import(file = "example009.dxf", layer = "plate");

Being able to use text objects as a part of a model is valuable in a lot of design solutions. The text() module is used to draw a string of text as a set of 2D shapes according to the specifications of the given font. The fonts available to use in a script are from the system that OpenSCAD is running in with the addition of those explicitly added by the script itself. To be able to format text, or to align text in relation to other shapes, a script needs information about the text objects that the script is working on, and also about the structure and dimensions of the fonts in use.

The text() object module draws a single string of text as a 2D geometric object, using fonts installed on the local system or provided as separate font file. The shape starts at the origin and is drawn along the positive X axis. Vertical alignment, as set by the valign parameter, is relative to the X axis, and horizontal alignment ( halign ) to the Y axis

[Note: Requires version 2015.03]

text

String. A single line of any character allowed. Limitation: non-printable ASCII characters like newline and tab rendered as placeholders

font

a formatted string with default font of "Liberation Sans:style=Regular"

size

non-negative decimal, default=10. The generated text has a height above the baseline of approximately this value, varying for different fonts but typically being slightly smaller.

halign

String, default="left". The horizontal alignment for the text. Possible values are "left", "center" and "right".

valign

String, default="baseline". The vertical alignment for the text. Possible values are "top", "center", "baseline" and "bottom".

spacing

float, default=1. Multiplicative factor that increases or decreases spacing between characters.

direction

String, default="ltr". Direction of text. Possible values are "ltr" (left-to-right), "rtl" (right-to-left), "ttb" (top-to-bottom) and "btt" (bottom-to-top).

language

String. The language of the text (e.g., "en", "ar", "ch"). Default is "en".

script

String, default="latin". The script of the text (e.g. "latin", "arabic", "hani").

$fn

higher values generate smoother curves (refer to Special Variables)

Example

text("OpenSCAD");

The "name" of a font is a string starting with its logical font name and variation, optionally followed by a colon (":") separated list of font specifications like a style selection, and a set of zero or more features.

The common variations in a font family are sans and serif though many others will be seen in the list of fonts available. Each font variation can be drawn with a style to support textual emphasis.

The default, upright appearance is usually called "Regular" with "Bold", "Italic", and "Bold Italic" being the other three styles commonly included in a font. In general the styles offered by a font may only be known by using the platform's font configuration tools or the OpenSCAD font list dialog.

In addition to the main font variations, some fonts support features for showing other glyphs like "small-caps" (smcp) where the lower case letters look like scaled down upper case letters, or "old-numbers" (onum) where the numbers are designed in varying heights instead of the way modern lining draws numbers the same size as upper case letters.

The fontfeatures property is appended to the font name after the optional style parameter. Its value is a semi-colon separated list of feature codes, each prefixed by a plus, "+", to indicate that it is being added,

font = "Linux Libertine G:style=Regular:fontfeatures=+smcp;+onum");

Basic Font Parameter Example

 square(10);
 
 translate([15, 15]) {
   text("OpenSCAD", font = "Liberation Sans");
 }
 
 translate([15, 0]) {
   text("OpenSCAD", font = "Liberation Sans:style=Bold Italic");
 }

Size Parameter

Text size is normally given in points, and a point is 1/72 of an inch high. The formula to convert the size value to "points" is pt = size/3.937, so a size argument of 3.05 is about 12 points.

Note: Character size the distance from ascent to descent, not from ascent to baseline.

Vertical Alignment

One of these four names must be given as a string to the valign parameter.

top

The text is aligned so the top of the tallest character in your text is at the given Y coordinate.

center

The text is aligned with the center of the bounding box at the given Y coordinate. This bounding box is based on the actual sizes of the letters, so taller letters and descending below the baseline will affect the positioning.

baseline

The text is aligned with the font baseline at the given Y coordinate. This is the default, and is the only option that makes different pieces of text align vertically, as if they were written on lined paper, regardless of character heights and descenders.

bottom

The text is aligned so the bottom of the lowest-reaching character in your text is at the given Y coordinate.

Note: only the "baseline" vertical alignment option will ensure correct alignment of texts that use mix of fonts and sizes.

 text = "Align";
 font = "Liberation Sans";
 
 valign = [
   [  0, "top"],
   [ 40, "center"],
   [ 75, "baseline"],
   [110, "bottom"]
 ];
 
 for (a = valign) {
   translate([10, 120 - a[0], 0]) {
     color("red") cube([135, 1, 0.1]);
     color("blue") cube([1, 20, 0.1]);
     linear_extrude(height = 0.5) {
       text(text = str(text,"_",a[1]), font = font, size = 20, valign = a[1]);
     }
   }
 }

Horizontal Alignment

One of these three names must be given as a string to the halign parameter.

left

The text is aligned with the left side of the bounding box at the given X coordinate.

center

The text is aligned with the center of the bounding box at the given X coordinate.

right

The text is aligned with the right of the bounding box at the given X coordinate.

 text = "Align";
 font = "Liberation Sans";
 
 halign = [
   [10, "left"],
   [50, "center"],
   [90, "right"]
 ];
 
 for (a = halign) {
   translate([140, a[0], 0]) {
     color("red") cube([115, 2,0.1]);
     color("blue") cube([2, 20,0.1]);
     linear_extrude(height = 0.5) {
       text(text = str(text,"_",a[1]), font = font, size = 20, halign = a[1]);
     }
   }
 }

Spacing Parameter

Characters in a text element have the size dictated by their glyph in the font being used. As such their size in X and Y is fixed. Each glyph also has fixed advance values (it is a vector [a,b], see textmetrics) for the offset to the origin of the next character. The position of each following character is the advance.x value multiplied by the space value. Obviously letters in the string can be stretched out when the factor is greater than 1, and can be made to overlap when space is a fraction closer to zero, but interestingly, using a negative value spaces each letter in the opposite of the direction parameter.

Simulating Formatted Text

When text needs to be drawn as if it was formatted it is possible to use translate() to space lines of text vertically. Fonts that descend below the baseline need to be spaced apart vertically by about 1.4*size to not overlap. Some word processing programs use a more generous spacing of 1.6*size for "single spacing" and double spacing can use 3.2*size.

The fonts available for use in a script are thosed:

• registered in the local system
• included in the OpenSCAD installation
• imported at run-time by a program

A call to fontmetrics() using only default settings shows the installation's standard font and settings:

echo( fontmetrics() );

gives this output (formatted for readability)

{ 
nominal = {
  ascent = 12.5733;
  descent = -2.9433;
  };
max = {
  ascent = 13.6109; descent = -4.2114;
  };
interline = 15.9709;
font = {
  family = "Liberation Sans";
  style = "Regular";
  };
}

In general the styles offered by a font may only be known by using the platform's font configuration tools or the OpenSCAD font list dialog.

The menu item Help > Font List shows the list of available fonts and the styles included in each one.

None of the platforms OpenSCAD is available on include the Liberation font family so having it as part of the app's installation, and making it the default font, avoids problems of font availability. There are three variations in the family, Mono, Sans, and Serif.

Note: It was previously noted in the docs that fonts may be added to the installation by drag-and-drop of a font file into the editor window, but as of version 2025 Snapshot this is not the case

In the following sample code a True Type Font, Andika, has been added to the system fonts using its Font Management service.

It is also possible to add fonts to a particular project by importing them with the use statement in this form:

text( "sample", font="Andika:style=bold" ); // installed in system fonts

use <Andika-Italic.ttf>;

translate( [0,-10, 0] )
    color("green")
        text( "test", font="Andika:style=italic");

Supported font file formats are TrueType fonts (*.ttf) and OpenType fonts (*.otf). Once a file is registered to the project the details of the fonts in it may be seen in the font list dialog (see image) so that the logical font names, variations, and their available styles are available for use in the project.

Text can be changed from a 2 dimensional object into a 3D object by using the linear_extrude function.

//3d Text Example
linear_extrude(4)
    text("Text");

[Note: Requires version Development snapshot]

The textmetrics() function accepts the same parameters as text(), and returns an object describing how the text would be rendered.

The returned object has these members:

position

a vector [X,Y], the origin of the first glyph, thus the lower-left corner of the drawn text.

size

a vector [a,b], the size of the generated text.

ascent

positive float, the amount that the text extends above the baseline.

descent

negative float, the amount that the text extends below the baseline.

offset

a vector default [0, 0], the lower-left corner of the box containing the text, including inter-glyph spacing before the first glyph.

advance

a vector default [153.09, 0], amount of space to leave to any following text.

This example displays the text metrics for the default font used by OpenSCAD:

s = "Hello, World!";
size = 20;
font = "Liberation Serif";
    
tm = textmetrics(s, size=size, font=font);
echo(tm);
translate([0,0,1])
    text("Hello, World!", size=size, font=font);
color("black") translate(tm.position)
    square(tm.size); // "size" is of the bounding box

displays (formatted for readability):

ECHO: {
   position = [0.7936, -4.2752];
   size = [149.306, 23.552];
   ascent = 19.2768;
   descent = -4.2752;
   offset = [0, 0];
   advance = [153.09, 0];
   }

The fontmetrics() function accepts a font size and a font name, both optional, and returns an object describing global characteristics of the font.

Parameters

size

Decimal, optional. The size of the font, as described above for text().

font

String, optional. The name of the font, as described above for text().

Note that omitting the size and/or font may be useful to get information about the default font.

Returns an object:

• nominal: usual dimensions for a glyph:
  • ascent: height above the baseline
  • descent: depth below the baseline
• max: maximum dimensions for a glyph:
  • ascent: height above the baseline
  • descent: depth below the baseline
• interline: design distance from one baseline to the next
• font: identification information about the font:
  • family: the font family name
  • style: the style (Regular, Italic, et cetera)

   echo(fontmetrics(font="Liberation Serif"));

yields (reformatted for readability):

   ECHO: {
       nominal = {
           ascent = 12.3766;
           descent = -3.0043;
       };
       max = {
           ascent = 13.6312;
           descent = -4.2114;
       };
       interline = 15.9709;
       font = {
           family = "Liberation Serif";
           style = "Regular";
       };
   }

Extrusion is the process of creating an object with a fixed cross-sectional profile. OpenSCAD provides two commands to create 3D solids from a 2D shape: linear_extrude() and rotate_extrude().

Linear extrusion is similar to pushing clay through a die with a profile shape cut through it.

Rotational extrusion is similar to the process of applying a profile to clay spinning on a potter's wheel.

Both extrusion methods work on a (possibly disjointed) 2D shape normally drawn in the relevant plane (see below).

A Linear Extrusion must be given a 2D child object, as in this statement:

linear_extrude( h=2 ) square();

This child object is first projected onto the X-Y plane along the Z axis to create the starting face of the extrusion. The start face is duplicated at the Z position given by the height parameter to create the extrusion's end face. The extrusion is then formed by creating a surface that joins each point along the edges of the two faces.

The 2D shape may be any 2D primitive shape, a 2d polygon, an imported 2D drawing, or a boolean combination of them. The 2D shape may have a Z value that moves it out of the X-Y plane, and it may even be rotated out of parallel with it. As stated above, the extrusion's starting face is the projection of the 2D shape onto the X-Y plane, which, if it is rotated, will have the effect of fore-shortening it normal to the axis of the rotation.

Using a 3D object as the extrusion's child will cause a compile time error. Including a 3D object in a composition of 2D objects (formed using boolean combinations on them) will be detected, the 3D object(s) will be deleted from it and the remaining 2D objects will be the basis for projecting their shape onto the X-Y plane.

There are no required parameters. The default operation is to extrude the child by 100 units vertically from the X-Y Plane, centered on the [0,0] origin.

1) height

a non-negative integer, default 100, giving the length of the extrusion

2) v - twist axis vector

a vector of 3 signed decimal values, default [0,0,1], used as an eigen vector specifying the axis of rotation for the twist. [Note: Requires version Development snapshot]

3) center

a boolean, default false, that, when true, causes the resulting solid to be vertically centered at the X-Y plane.

4) convexity

a non-negative integer, default 1, giving a measure of the complexity of the generated surface. See the Section on Convexity later on this page.

5) twist

a signed decimal, default 0.0, specifying how many degrees of twist to apply between the start and end faces of the extrusion. 180 degrees is a half twist, 360 is all the way around, and so on.

6) scale

either : a non-negative, decimal value, default 1.0, minimum 0.0, that specifies the factor by which the end face should be scaled up, or down, in size from that of the start face.

or : an [x,y] vector that scales the extrusion in the X and Y directions separately.

7) slices

a non-negative integer for the number of rows of polygons that the extr.

8) segments

Similar to slices but adding points on the polygon's segments without changing the polygon's shape.

h

a named parameter, synonym to height

$fn $fs $fa

Special Parameters - given as named parameters.

This parameter affects only affects the vertical position or the extrusion. Its X-Y position is always that of the projection that sets its starting face.

This is multiplicative factor that affects the size of extrusion's end face. As such 1.0 means no change, a value greater than one expands the end face, and a value between 0.001 and less than 1 shrinks it. A value of 0.0 causes the end face to degenerate to a point, turning the extrusion into a pyramid, cone, or complex pointy shape according to what the starting shape is.

Using the vector form sets the scale factor in the X and Y directions separately

Twist is applied, by default, as a rotation about the Z Axis. When the start face is at the origin a twist creates a spiral out of any corners in the child shape. If the start face is translated away from the origin the twist creates a spring shape.

A positive twist rotates clockwise, negative twist the opposite.

The second parameter is an [x,y,z] eigen vector that specifies the axis of rotation of the applied twist. The ratios of the three dimensional values to their respective coordinate axes specify the tilt away from the default axis, [0,0,1], the Z-Axis. For instance, v=[cos(45),0,1] tilts the extrusion at 45 degrees to the X axis.

The start and end faces are always normal to the Z-axis, even when the twist axis is tilted. The extruded and twisted surfaces are thus distorted from what might be expected in an extruded shape. The more expected result may be achieved by applying a rotation to then twisted extrusion on the Z Axis to tilt it into the desired position.

The special variables must be given as named parameters and are applied to the extrusion, overriding the global setting. When the same special variables are set on the base shape its values override their use as parameters on the extrusion.

Example of linear extrusion of a 2D object imported from a DXF file.

linear_extrude(height = fanwidth, center = true, convexity = 10)
   import (file = "example009.dxf", layer = "fan_top");

Generate an extrusion from a circle 2 units along the X Axis from the origin, centered vertically on the X-Y plane, with no twist. The extrusion appears to have a pentagonal cross-section because the extrusion's child is a 2D circle with the default value for $fn.

linear_extrude(height = 10, center = true, convexity = 10, twist = 0)
    translate([2, 0, 0])
        circle(r = 1);

The same circle, but now with 100 degrees of counter-clockwise twist.

linear_extrude(height = 10, center = true, convexity = 10, twist = -100)
    translate([2, 0, 0])
        circle(r = 1);

The same circle, but now with 100 degrees of clockwise twist.

linear_extrude(height = 10, center = true, convexity = 10, twist = 100)
    translate([2, 0, 0])
        circle(r = 1);

The same circle, but made into a spiral by 500 degrees of counter-clockwise twist.

linear_extrude(height = 10, center = true, convexity = 10, twist = -500)
    translate([2, 0, 0])
        circle(r = 1);

With center=false, the default, the extrusion is based on the X-Y plane and rises up in the positive Z direction.

When true it is centered vertically at the X-Y plane, as seen here:

The slices parameter defines the number of intermediate points along the Z axis of the extrusion. Its default increases with the value of twist. Explicitly setting slices may improve the output refinement. Additional the segments parameter adds vertices (points) to the extruded polygon resulting in smoother twisted geometries. Segments need to be a multiple of the polygon's fragments to have an effect (6 or 9.. for a circle($fn=3), 8,12.. for a square() ).

linear_extrude(height = 10, center = false, convexity = 10, twist = 360, slices = 100)
translate([2, 0, 0])
circle(r = 1);

The special variables $fn, $fs and $fa can also be used to improve the output. If slices is not defined, its value is taken from the defined $fn value.

linear_extrude(height = 10, center = false, convexity = 10, twist = 360, $fn = 100)
translate([2, 0, 0])
circle(r = 1);

Scales the 2D shape by this value over the height of the extrusion. Scale can be a scalar or a vector:

 linear_extrude(height = 10, center = true, convexity = 10, scale=3)
 translate([2, 0, 0])
 circle(r = 1);

 linear_extrude(height = 10, center = true, convexity = 10, scale=[1,5], $fn=100)
 translate([2, 0, 0])
 circle(r = 1);

Note that if scale is a vector, the resulting side walls may be nonplanar. Use twist=0 and the slices parameter to avoid asymmetry.

 linear_extrude(height=10, scale=[1,0.1], slices=20, twist=0)
 polygon(points=[[0,0],[20,10],[20,-10]]);

A common usage of this function is to import a 2D svg

 linear_extrude(height = 10, center = true)
 import("knight.svg");

Rotational extrusion spins a 2D shape around the Z-axis to form a solid which has rotational symmetry. One way to think of this operation is to imagine a Potter's wheel placed on the X-Y plane with its axis of rotation pointing up towards +Z. Then place the to-be-made object on this virtual Potter's wheel (possibly extending down below the X-Y plane towards -Z). The to-be-made object is the cross-section of the object on the X-Y plane (keeping only the right half, X >= 0). That is the 2D shape that will be fed to rotate_extrude() as the child in order to generate this solid. Note that the object started on the X-Y plane but is tilted up (rotated +90 degrees about the X-axis) to extrude.

Since a 2D shape is rendered by OpenSCAD on the X-Y plane, an alternative way to think of this operation is as follows: spins a 2D shape around the Y-axis to form a solid. The resultant solid is placed so that its axis of rotation lies along the Z-axis.

Just like the linear_extrude, the extrusion is always performed on the projection of the 2D polygon to the XY plane. Transformations like rotate, translate, etc. applied to the 2D polygon before extrusion modify the projection of the 2D polygon to the XY plane and therefore also modify the appearance of the final 3D object.

• A translation in Z of the 2D polygon has no effect on the result (as also the projection is not affected).
• A translation in X increases the diameter of the final object.
• A translation in Y results in a shift of the final object in Z direction.
• A rotation about the X or Y axis distorts the cross section of the final object, as also the projection to the XY plane is distorted.

Don't get confused, as OpenSCAD displays 2D polygons with a certain height in the Z direction, so the 2D object (with its height) appears to have a bigger projection to the XY plane. But for the projection to the XY plane and also for the later extrusion only the base polygon without height is used.

You cannot use rotate_extrude to produce a helix or screw thread. Doing this properly can be difficult, so it's best to find a thread library to make them for you.

The 2D shape must lie completely on either the right (recommended) or the left side of the Y-axis. More precisely speaking, every vertex of the shape must have either x >= 0 or x <= 0. If the shape spans the X axis a warning appears in the console windows and the rotate_extrude() is ignored. If the 2D shape touches the Y axis, i.e. at x=0, it must be a line that touches, not a point, as a point results in a zero thickness 3D object, which is invalid and results in a CGAL error. For OpenSCAD versions prior to 2016.xxxx, if the shape is in the negative axis the resulting faces are oriented inside-out, which may cause undesired effects.

rotate_extrude(angle = 360, start=0, convexity = 2) {...}

In 2021.01 and previous, you must use parameter names due to a backward compatibility issue.

convexity : If the extrusion fails for a non-trival 2D shape, try setting the convexity parameter (the default is not 10, but 10 is a "good" value to try). See explanation further down.

angle [Note: Requires version 2019.05] : Defaults to 360. Specifies the number of degrees to sweep, starting at the positive X axis. The direction of the sweep follows the Right Hand Rule, hence a negative angle sweeps clockwise.

start [Note: Requires version Development snapshot] : Defaults to 0 if angle is specified, and 180 if not. Specifies the starting angle of the extrusion, counter-clockwise from the positive X axis.

$fa : minimum angle (in degrees) of each fragment.

$fs : minimum circumferential length of each fragment.

$fn : fixed number of fragments in 360 degrees. Values of 3 or more override $fa and $fs

$fa, $fs and $fn must be named parameters. click here for more details,.

rotate_extrude(convexity = 10)
   import (file = "example009.dxf", layer = "fan_side", origin = fan_side_center);

→

A simple torus can be constructed using a rotational extrude.

rotate_extrude(convexity = 10)
    translate([2, 0, 0])
        circle(r = 1);

→

Increasing the number of fragments composing the 2D shape improves the quality of the mesh, but takes longer to render.

rotate_extrude(convexity = 10)
    translate([2, 0, 0])
        circle(r = 1, $fn = 100);

→

The number of fragments used by the extrusion can also be increased.

rotate_extrude(convexity = 10, $fn = 100)
    translate([2, 0, 0])
        circle(r = 1, $fn = 100);

Using the parameter angle (with OpenSCAD versions 2016.xx), a hook can be modeled .

eps = 0.01;
translate([eps, 60, 0])
    rotate_extrude(angle=270, convexity=10)
        translate([40, 0]) circle(10);
rotate_extrude(angle=90, convexity=10)
    translate([20, 0]) circle(10);
translate([20, eps, 0])
    rotate([90, 0, 0]) cylinder(r=10, h=80+eps);

Extrusion can also be performed on polygons with points chosen by the user.

Here is a simple polygon and its 200 step rotational extrusion. (Note it has been rotated 90 degrees to show how the rotation appears; the rotate_extrude() needs it flat).

rotate([90,0,0])        polygon( points=[[0,0],[2,1],[1,2],[1,3],[3,4],[0,5]] );

rotate_extrude($fn=200) polygon( points=[[0,0],[2,1],[1,2],[1,3],[3,4],[0,5]] );

→→

For more information on polygons, please see: 2D Primitives: Polygon.

If you're making a round 360 degree extrusion, it doesn't matter where it starts. If, on the other hand, you're using $fn to make an extrusion with some specific number of sides, it can matter. With an odd number of sides, there will be a vertex on either the left or the right, and a side opposite it.

With angle not specified, the extrusion starts along the negative X axis, to the left of the origin. With an odd number of sides, there is a vertex on the left and a side on the right. (Note that this is inconsistent with the behavior for angle less than 360, and with the behavior for circle and other round primitives.)

With angle specified, and not equal to 360, the extrusion starts along the positive X axis, to the right of the origin.

For 2021.01 and earlier, if angle is equal to 360, the extrusion starts along the negative X axis, as for angle not being specified.

For the development snapshot, if angle is 360, the extrusion starts along the positive X axis, as for other cases where angle is specified. Explicitly specifying angle=360 thus yields results consistent with other round primitives.

A future release may change this behavior so that when angle is not specified the extrusion starts along the positive X axis, making all of these cases consistent.

start directly controls the start point. [Note: Requires version Development snapshot]

convexity

an integer that works as a measure of complexity based on the maximum number of sides a ray might penetrate as it passes through a shape.

For instance, the convexity of a sphere is one and the convexity of a torus is two. From any point of view there is only a single surface showing for a sphere. But with a torus a given pixel may be showing the front most face, the back part of the doughnut, or the background. Setting convexity greater than the default 1 informs the renderer of the need to be more careful in its work.

Arbitrarily setting convexity to 10 should solve most preview rendering issues, at the expense of slowing preview rendering. When a model has several convoluted shapes values more than 15 can slow rendering to the point of freezing the application.

The issue of Convexity is an issue in Preview Rendering.

height

a non-negative integer, default 100, giving the length of the extrusion

center

a boolean, default false, that, when true, causes the resulting solid to be vertically centered at the X-Y plane.

twist

a signed decimal, default 0.0, specifying how many degrees of twist to apply between the start and end faces of the extrusion

scale

a non-negative, decimal value, default 1.0, greater than 0.0, that specifies the factor by which the end face should be scaled up, or down, in size from that of the start face.

a vector containing these values in this order

[

slices

a non-negative integer value that acts on the extruded surface as $fn does, but which is not applied to the child 2D shape.

segments

Similar to slices but adding points on the polygon's segments without changing the polygon's shape.

$fn

the special variable but applied only to the extrusion

$fs

the special variable but applied only to the extrusion

$fa

the special variable but applied only to the extrusion

]

Note

1. centering the extrusion only affects its vertical position. Its X-Y position is always set by its starting face.
2. A Scale Factor greater than one increases the size of the extrusion's end face, while a value greater than 0.0 and less than 1 shrink it. A value of 0.0 causes the end face to degenerate to a point, turning the extrusion into a pyramid, cone, or complex pointy shape according to what the starting shape is.

OpenSCAD User Manual/The OpenSCAD Language

Transformations are applied to modify position, orientation, or size by writing them at the beginning of a line of OpenSCAD code that defines a new node. Nodes are defined as primitive shapes or CSG Modelling Operations or looping and conditional statements that form syntactic groups.

The simplest form for statements that define shapes is

<transform>*<child node>;

meaning that zero or more (shown by *) calls to transform modules can precede code that defines a node. The node thus created may be as simple as a single shape, or may be a complex of nested language elements that define an assembly of shapes, but in all cases the combined effect of the transforms are applied to the single child node that must be the last item on the line. Indentation is commonly used to make the child nodes more visible for the reader, but as this example shows, these two statements are identical.

translate([10,20,30]) cube(10);
translate([10,20,30])
    cube(10);

In the OpenSCAD language semicolons mark the end of a line of code so if one is placed after a transform module call it means there will be no child node created.

Transform modules can be applied to grouped statements using braces ( '{ }' to enclose the sub-tree in this manner:

translate([0,0,-5])
    {
    cube(10);
    cylinder(r=5,h=10);
    }
translate([0,0,-5]) { cube(10); cylinder(r=5,h=10); }

Like the previous code example the two statements are identical in meaning but indentation makes the first more readable. Also note that a statement group is not ended by a semi-colon, but each separate line in the group but be ended by one, including the last.

Indentation is commonly used to show the scope of transform module calls but they are always applied outwards from the child object, not in the sequence written in the statement.

rotate([45,45,45])
    translate([10,20,30])
        cube(10);

The order of calls to transform modules makes no difference to the correctness of a statement syntactically, but for some the order of operations is significant. A call to set the colour of an object may be inserted anywhere, but those that affect the child geometry have to be correctly ordered.

color("red")     translate([0,10,0])  rotate([45,0,0]) cube(5);
rotate([45,0,0]) translate([0,10,0])  color("green")   cube(5);

Both translation and rotation module calls are the same, but moving the second cube and then rotating it, is not the same as first rotating the first cube, then moving it away from the origin. In the second case the rotation causes the cube to move along an arc 10 units from the origin, the first the cube is rotated them moved along the Y axis.

OpenSCAD uses a different library to preview simple transforms (translate, rotate, etc.) than for more advanced transforms, like resize. The effects of modifier characters, specifically "#" and "%", on the rendered objects may not match expectations. A shape with only simple transforms applied will be rendered in its post-transformation form, while the highlight for a resized shape will be applied to its original form.

Scales its child elements using the specified vector. Using the name of the argument is optional.

Usage Example:
scale(v = [x, y, z]) { ... }

cube(10);
translate([15,0,0]) scale([0.5,1,2]) cube(10);

This module actually changes the form of the child node by the amount given by the x,y, and z dimensions of the given vector. If an amount is zero that dimension is not changed

resize() is an operation from the CGAL library and as such operates on the full geometry of the child node and its use can make for longer rendering time in preview mode.

Usage Example:

// resize the sphere to extend 30 in x, 60 in y, and 10 in the z directions.
resize(newsize=[30,60,10]) sphere(r=10);

// resize the 1x1x1 cube to 2x2x1
resize([2,2,0]) cube();

If the 'auto' parameter is set to true, it auto-scales any 0-dimensions to match. For example.

// resize the 1x2x0.5 cube to 7x14x3.5
resize([7,0,0], auto=true) cube([1,2,0.5]);

The 'auto' parameter can also be used if you only wish to auto-scale a single dimension, and leave the other as-is.

// resize to 10x8x1. Note that the z dimension is left alone.
resize([10,0,0], auto=[true,true,false]) cube([5,4,1]);

Scale vs Resize

In many cases the effect of scale() will be the same as for resize(), but when the child to be modified is not a symmetrical shape the effects can be seen to be different.

This image shows a default cube and a cube([3,2,5]) in white, both transformed by resize([2,2,0]) and then scaled by scale([2,2,1]). The scale.z value must be 1 to preserve the cube's Z dimension.

The resize operation on the cube([3,2,5]) shortens it to match the [2,2,0] size while the scale just makes it bigger in all dimensions.

This module acts to rotate its children through a given angle about an axis. The angle and the axis may be given in different forms to facilitate programming needs. The argument names are optional when values are given in the order of the following specification.

The angle of rotation must be given in degrees and may be a decimal fraction. In its simplest form the effect is to rotate the child around the Z-axis by the given value, "angle", in degrees. This is useful in 2D contexts where that is the only axis for rotation.

rotate( <angle> );

The angle may also be given as a named parameter "a", thus: rotate( a=<angle> ).

For example:

rotate(45) square(10);

as seen in this image

An optional argument, "v", may be given to define the axis about which the child is rotated. It its simplest form just one of the X, Y, or Z elements will have value one (1) to specify the single coordinate axis will be the basis for rotation. For example to rotate 180 degrees around the Y-axis we can use:

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

The "v=[x,y,z]" parameter is as a Euler vector that can define any arbitrary axis for rotation. The three components may be given as signed, decimal float values that define a line in 3-space around which the child node will be rotated. This does not give the same result as using the a=[x_rot,y_rot,z_rot] form shown in a following section, but has the same mathematical basis.

For example using the "v" form to rotate a child node by 45 degrees around an axis halfway between the X and Y coordinate axes uses the vector [1,1,0] as in this code:

rotate(a=45, v=[1,1,0]) { ... }

giving this result:

In its full form the module call has this form:

rotate(a = deg_a, v = [x, y, z]) // named parameters
rotate( a, [x, y, z] ) // positional parameters

rotate( 30, [.5,.5,.5] )
    cube([2,4,6]);

Combination of Three Rotations

Alternately the angle of rotation may be given as a vector of angles:

rotate(a = [x_rot, y_rot, z_rot]) // named parameter "a"
rotate([deg_x, deg_y, deg_z])     // positional parameters

In this form the axis argument ("v") is ignored. The three angular rotations are applied in order of x_rot first, then y_rot, and finally z_rot. The following code fragment is a reminder that the transform "closest" to the child node is the operation carried out first.

rotate(a=[0,0,az])
    rotate(a=[0,ay,0])
        rotate(a=[ax,0,0])
            { <child node> }

Rotate vs Mirror

It is worth noting that while in some cases rotating an object by 180 degrees around an axis results in the same geometry as mirroring it in a suitable plane, mathematically these are different operations that create unique geometries, as the following code will illustrate:

transf = true; // [true,false]

mirr = transf ? 1 : 0;
rotat = transf ? 180 : 0;

mirror([0,0,mirr])
union(){
    color("yellow", alpha=.30)
    cube( [5,8,2],center=true );
    translate( [-1,0,-2] )
        color("red")
        cube( [3,3,5] );
    translate( [0,-5,-2] )
        color("green")
        cube( [3,3,5] );
    }

translate( [-10,0,0] )
    rotate([rotat,0,0])
union(){
    color("yellow", alpha=.30)
    cube( [5,8,2],center=true );
    translate( [-1,0,-2] )
        color("red")
        cube( [3,3,5] );
    translate( [0,-5,-2] )
        color("green")
        cube( [3,3,5] );
    }

For the case of:

rotate([a, b, c]) { ... };

"a" is a rotation about the X axis, from the +Y axis, toward the +Z axis.
"b" is a rotation about the Y axis, from the +Z axis, toward the +X axis.
"c" is a rotation about the Z axis, from the +X axis, toward the +Y axis.

These are all cases of the Right Hand Rule. Point your right thumb along the positive axis, your fingers show the direction of rotation.

Thus if "a" is fixed to zero, and "b" and "c" are manipulated appropriately, this is the spherical coordinate system.
So, to construct a cylinder from the origin to some other point (x,y,z):

x= 10; y = 10; z = 10; // point coordinates of end of cylinder
 
length = norm([x,y,z]);  // radial distance
b = acos(z/length); // inclination angle
c = atan2(y,x);     // azimuthal angle

rotate([0, b, c]) 
    cylinder(h=length, r=0.5);
%cube([x,y,z]); // corner of cube should coincide with end of cylinder

Translate moves its child node for the distances given in the three elements of the given vector. The argument name, "v", is optional.

Example:

translate(v = [x, y, z]) { ... }

In the following code there is a cube of 2 units square centered on the origin with no transform applied, with a unit sphere as a child node of a X=5 units translation.

cube(2,center = true); 
translate([5,0,0]) 
   sphere(1,center = true);

The effect of this transform is to project the geometry of its child node through a mirror plane to the equidistant position on the plane's other side. Mirrors are planes that pass through the origin with the orientation given by its Normal Vector. This specific normal vector is given as the "v=[x,y,z]" parameter to mirror() which is is a Euler vector with values being signed, decimal floats.

In its simplest form just one of the elements will have a non-zero value. So to mirror something in the Y-Z plane the vector is the X-axis ( v=[1,0,0] ). Note that a Euler vector takes the ratios between its components for its direction, not the absolute values. Thus the proportions of v=[1,0,0], v=[-1,0,0], v=[0.05,0,0], and v=[100,0,0] all describe the same vector, the X-axis.

In general the signs of the vector elements are significant, so for instance the planes for v=[1,1,0] and v=[1,-1,0] are at right angles to each other. But the lines for v=[1,1,0] and v=[-1,-1,0] are the same line, just in opposite directions.

The operation of the transform is to project each point of the child node to the mirror plane along a line drawn normal to the plane. Each point is then projected through the mirror for the same distance on the other side to create the mirrored child node.

For example, for a cube entirely in the positive X half of the modelling space applying mirror([1,0,0]), changes the x coordinate of its every point from positive to negative.

It is worth pointing out that mirror() "moves" the child node, it does not make a new copy of it.

mirror(v= [x, y, z] ) { ... }

The original is on the right hand side.

• 
  hand(); // original
mirror([1,0,0]) hand();
• 
  hand(); // original
mirror([1,1,0]) hand();
• 
  hand(); // original
mirror([1,1,1]) hand();

 // original
 rotate([0,0,-30]){
   cube([23,12,10]);
   translate([0.5, 4.4, 9.9]){
     color("red", 1.0){
       linear_extrude(height=2){
         text("OpenSCAD", size= 3);
       }
     }
   }
 }
 // mirrored
 mirror([1,0,0]){
   rotate([0,0,-30]){
     cube([23,12,10]);
     translate([0.5, 4.4, 9.9]){
       color("red", 1.0){
         linear_extrude(height=2){
           text("OpenSCAD", size= 3);
         }
       }
     }
   }
 }

Multiplies the geometry of all child elements with the given affine transformation matrix, where the matrix is 4×3 - a vector of 3 row vectors with 4 elements each, or a 4×4 matrix with the 4th row always forced to [0,0,0,1].

Usage: multmatrix(m = [...]) { ... }

This is a breakdown of what you can do with the independent elements in the matrix (for the first three rows):

The fourth row is forced to [0,0,0,1] and can be omitted unless you are combining matrices before passing to multmatrix, as it is not processed in OpenSCAD. Each matrix operates on the points of the given geometry as if each vertex is a 4 element vector consisting of a 3D vector with an implicit 1 as its 4th element, such as v=[x, y, z, 1]. The role of the implicit fourth row of m is to preserve the implicit 1 in the 4th element of the vectors, permitting the translations to work. The operation of multmatrix therefore performs m*v for each vertex v. Any elements (other than the 4th row) not specified in m are treated as zeros.

This example rotates by 45 degrees in the XY plane and translates by [10,20,30], i.e. the same as translate([10,20,30]) rotate([0,0,45]) would do.

angle=45;
multmatrix(m = [ [cos(angle), -sin(angle), 0, 10],
                 [sin(angle),  cos(angle), 0, 20],
                 [         0,           0, 1, 30],
                 [         0,           0, 0,  1]
              ]) union() {
   cylinder(r=10.0,h=10,center=false);
   cube(size=[10,10,10],center=false);
}

The following example demonstrates combining affine transformation matrices by matrix multiplication, producing in the final version a transformation equivalent to rotate([0, -35, 0]) translate([40, 0, 0]) Obj();. Note that the signs on the sin function appear to be in a different order than the above example, because the positive one must be ordered as x into y, y into z, z into x for the rotation angles to correspond to rotation about the other axis in a right-handed coordinate system.

module Obj() {
   cylinder(r=10.0,h=10,center=false);
   cube(size=[10,10,10],center=false);
}

// This itterates into the future 6 times and demonstrates how multimatrix is moving the object around the center point
for(time = [0 : 15 : 90]){
    y_ang=-time;
    mrot_y = [ [ cos(y_ang), 0,  sin(y_ang), 0],
               [         0,  1,           0, 0],
               [-sin(y_ang), 0,  cos(y_ang), 0],
               [         0,  0,           0, 1]
             ];
    mtrans_x = [ [1, 0, 0, 40],
                 [0, 1, 0,  0],
                 [0, 0, 1,  0],
                 [0, 0, 0,  1]
               ];

    echo(mrot_y*mtrans_x);
    
    // This is the object at [0,0,0]
    Obj();
    
    // This is the starting object at the [40,0,0] coordinate
    multmatrix(mtrans_x) Obj();
    
    // This is the one rotating and appears 6 times
    multmatrix(mrot_y * mtrans_x) Obj();
};

This example skews a model, which is not possible with the other transformations.

M = [ [ 1  , 0  , 0  , 0   ],
      [ 0  , 1  , 0.7, 0   ],  // The "0.7" is the skew value; pushed along the y axis as z changes.
      [ 0  , 0  , 1  , 0   ],
      [ 0  , 0  , 0  , 1   ] ] ;
multmatrix(M) {  union() {
    cylinder(r=10.0,h=10,center=false);
    cube(size=[10,10,10],center=false); 
} }

This example shows how a vector is transformed with a multmatrix vector, like this all points in a point array (polygon) can be transformed sequentially. Vector (v) is transformed with a rotation matrix (m), resulting in a new vector (vtrans) which is now rotated and is moving the cube along a circular path radius=v around the z axis without rotating the cube.

angle=45;
 m=[
        [cos(angle), -sin(angle), 0, 0],
        [sin(angle),  cos(angle), 0, 0],
        [         0,           0, 1, 0]
   ];
              
v=[10,0,0];
vm=concat(v,[1]); // need to add [1]
vtrans=m*vm;
echo(vtrans);
translate(vtrans)cube();

Learn more about it here:

• Affine Transformations on wikipedia
• http://www.senocular.com/flash/tutorials/transformmatrix/

Displays the child elements using the specified RGB color + alpha value. This is only used for the F5 preview as CGAL and STL (F6) do not currently support color. The alpha value defaults to 1.0 (opaque) if not specified.

Function Form

color( c = [r, g, b, a] ) { ... }
color( c = [r, g, b], alpha = 1.0 ) { ... }
color( "#hexvalue" ) { ... }
color( "colorname", 1.0 ) { ... }

Note that the r, g, b, a values are limited to floating point values in the range [0,1] rather than the more traditional integers { 0 ... 255 }. However, nothing prevents you from using R, G, B values from {0 ... 255} with appropriate scaling: color([ R/255, G/255, B/255 ]) { ... }

[Note: Requires version 2011.12] Colors can also be defined by name (case insensitive). For example, to create a red sphere, you can write color("red") sphere(5);. Alpha is specified as an extra parameter for named colors: color("Blue",0.5) cube(5);

[Note: Requires version 2019.05] Hex values can be given in 4 formats, #rgb, #rgba, #rrggbb and #rrggbbaa. If the alpha value is given in both the hex value and as separate alpha parameter, the alpha parameter takes precedence.

Warning: alpha channel processing (transparency) is order-sensitive. Transparent objects must be listed after non-transparent objects to display them correctly. Some combinations involving multiple transparent objects cannot be handled correctly. See issue #1390.

The available color names are taken from the World Wide Web consortium's SVG color list. A chart of the color names is as follows,
(note that both spellings of grey/gray including slategrey/slategray etc are valid):

Here's a code fragment that draws a wavy multicolor object

  for(i=[0:36]) {
    for(j=[0:36]) {
      color( [0.5+sin(10*i)/2, 0.5+sin(10*j)/2, 0.5+sin(10*(i+j))/2] )
      translate( [i, j, 0] )
      cube( size = [1, 1, 11+10*cos(10*i)*sin(10*j)] );
    }
  }

↗ Being that -1<=sin(x)<=1 then 0<=(1/2 + sin(x)/2)<=1 , allowing for the RGB components assigned to color to remain within the [0,1] interval.

Chart based on "Web Colors" from Wikipedia

In cases where you want to optionally set a color based on a parameter you can use the following trick:

 module myModule(withColors=false) {
    c=withColors?"red":undef;
    color(c) circle(r=10);
 }

Setting the colorname to undef keeps the default colors.

[Note: Requires version 2015.03]

Offset generates a new 2d interior or exterior outline from an existing outline. There are two modes of operation: radial and delta.

• The radial method creates a new outline as if a circle of some radius is rotated around the exterior (r > 0) or interior (r < 0) of the original outline.
• The delta method creates a new outline with sides having a fixed distance outward (delta > 0) or inward (delta < 0) from the original outline.

The construction methods produce an outline that is either inside or outside of the original outline. For outlines using delta, when the outline goes around a corner, it can be given an optional chamfer.

Offset is useful for making thin walls by subtracting a negative-offset construction from the original, or the original from a positive offset construction.

Offset can be used to simulate some common solid modeling operations:

• Fillet: offset(r=-3) offset(delta=+3) rounds all inside (concave) corners, and leaves flat walls unchanged. However, holes less than 2*r in diameter vanish.
• Round: offset(r=+3) offset(delta=-3) rounds all outside (convex) corners, and leaves flat walls unchanged. However, walls less than 2*r thick vanish.

Parameters

The first parameter may be passed without a name, in which case it is treated as the r parameter below. All other parameters must be named if used.

r or delta

Number. Amount to offset the polygon. When negative, the polygon is offset inward.

• r (default parameter if not named) specifies the radius of the circle that is rotated about the outline, either inside or outside. This mode produces rounded corners. The name may be omitted; that is, offset(c) is equivalent to offset(r=c).
• delta specifies the distance of the new outline from the original outline, and therefore reproduces angled corners. No inward perimeter is generated in places where the perimeter would cross itself.

chamfer

Boolean. (default false) When using the delta parameter, this flag defines if edges should be chamfered (cut off with a straight line) or not (extended to their intersection). This parameter has no effect on radial offsets.

$fa, $fs, and $fn

The circle resolution special variables may be used to control the smoothness or facet size of curves generated by radial offsets. They have no effect on delta offsets.

Positive r/delta value

Negative r/delta value

Result for different parameters. The black polygon is the input for the offset() operation.

Examples

// Example 1
 
linear_extrude(height = 60, twist = 90, slices = 60) {
   difference() {
     offset(r = 10) {
      square(20, center = true);
     }
     offset(r = 8) {
       square(20, center = true);
     }
   }
 }

// Example 2
 
module fillet(r) {
   offset(r = -r) {
     offset(delta = r) {
       children();
     }
   }
}

[Note: Requires version Development snapshot]

The fill() operation removes holes from polygons without changing the outline. For convex polygons the result is identical to hull().

Examples

// Example 1
 
t = "OpenSCAD";

linear_extrude(15) {
	text(t, 50);
}
color("darkslategray") {
	linear_extrude(2) {
		offset(4) {
			fill() {
				text(t, 50);
			}
		}
	}
}

Displays the minkowski sum of child nodes.

Usage example:

Say you have a flat box, and you want a rounded edge. There are multiple ways to do this (for example, see hull below), but minkowski is elegant. Take your box, and a cylinder:

 $fn=50;
 cube([10,10,1]);
 cylinder(r=2,h=1);

Then, do a minkowski sum of them (note that the outer dimensions of the box are now 10+2+2 = 14 units by 14 units by 2 units high as the heights of the objects are summed):

$fn=50;
minkowski()
{
  cube([10,10,1]);
  cylinder(r=2,h=1);
}

NB: The origin of the second object is used for the addition. The following minkowski sums are different: the first expands the original cube by +1 in -x, +x, -y, +y from cylinder, expand 0.5 units in both -z, +z from cylinder. The second expands it by +1 in -x, +x, -y, +y and +z from cylinder, but expand 0 in the -z from cylinder.

minkowski() {
	cube([10, 10, 1]);
	cylinder(1, center=true);
}

minkowski() {
	cube([10, 10, 1]);
	cylinder(1);
}

Warning: for high values of $fn the minkowski sum may end up consuming lots of CPU and memory, since it has to combine every child node of each element with all the nodes of each other element. So if for example $fn=100 and you combine two cylinders, then it does not just perform 200 operations as with two independent cylinders, but 100*100 = 10000 operations.

Warning: if one of the inputs is compound, such as:

    {
         translate([0, 0, collar])
         sphere(ball);
         cylinder(collar, ball, ball);
    }

it may be treated as two separate inputs, resulting in an output which is too large, and has features between surfaces that should be unaltered with respect to one another. If so, use union().

Displays the convex hull of child nodes.

Usage example:

hull() {
    translate([15,10,0]) circle(10);
    circle(10);
}

The Hull of 2D objects uses their projections (shadows) on the xy plane, and produces a result on the xy plane. Their Z-height is not used in the operation.

Referring to the illustration of a convex hull of two cylinders, it is computationally more efficient to use hull() on two 2D circles and linear_extrude the resulting 2D shape into a 3D shape, rather than using hull() on two cylinders, even though the resulting object appears identical. Complex geometries involving hull() can be rendered faster by starting out in 2D, if possible.

OpenSCAD User Manual/The OpenSCAD Language

• 
  union ( or )
  circle + square
• 
  difference ( and not )
  square - circle
• 
  difference ( and not )
  circle - square
• 
  intersection ( and )
  circle - (circle - square)

 union()       {square(10);circle(10);} // square or  circle
 difference()  {square(10);circle(10);} // square and not circle
 difference()  {circle(10);square(10);} // circle and not square
 intersection(){square(10);circle(10);} // square and circle

• 
  union ( or )
  sphere + cube
• 
  difference ( and not )
  cube - sphere
• 
  difference ( and not )
  sphere - cube
• 
  intersection ( and )
  sphere - (sphere - cube)

 union()       {cube(12, center=true); sphere(8);} // cube or  sphere
 difference()  {cube(12, center=true); sphere(8);} // cube and not sphere
 difference()  {sphere(8); cube(12, center=true);} // sphere and not cube
 intersection(){cube(12, center=true); sphere(8);} // cube and sphere

Creates a union of all its child nodes. This is the sum of all children (logical or).
May be used with either 2D or 3D objects, but don't mix them.

 //Usage example:
 union() {
 	cylinder (h = 4, r=1, center = true, $fn=100);
 	rotate ([90,0,0]) cylinder (h = 4, r=0.9, center = true, $fn=100);
 }

Remark: union is implicit when not used. But it is mandatory, for example, in difference to group first child nodes into one.

Note: It is mandatory for all unions, explicit or implicit, that external faces to be merged not be coincident. Failure to follow this rule results in a design with undefined behavior, and can result in a render which is not manifold (with zero volume portions, or portions inside out), which typically leads to a warning and sometimes removal of a portion of the design from the rendered output. (This can also result in flickering effects during the preview.) This requirement is not a bug, but an intrinsic property of floating point comparisons and the fundamental inability to exactly represent irrational numbers such as those resulting from most rotations. As an example, this is an invalid OpenSCAD program, and will at least lead to a warning on most platforms:

 // Invalid!
 size = 10;
 rotation = 17;
 union() {
    rotate([rotation, 0, 0])
       cube(size);
    rotate([rotation, 0, 0])
       translate([0, 0, size])
       cube([2, 3, 4]);
 }

The solution is to always use a small value called an epsilon when merging adjacent faces like this to guarantee overlap. Note the 0.01 eps value used in TWO locations, so that the external result is equivalent to what was intended:

 // Correct!
 size = 10;
 rotation = 17;
 eps = 0.01;
 union() {
    rotate([rotation, 0, 0])
       cube(size);
    rotate([rotation, 0, 0])
       translate([0, 0, size-eps])
       cube([2, 3, 4+eps]);
 }

This operator does nothing when given a single child:

difference() cube();

Having it operate on two or more children performs the logical And-Not operation by deleting the shapes following the first from it.

Intersection may be applied to 2D or 3D objects, but should be applied to objects of only one type. Mixing 2D and 3D child nodes will give indeterminate results, if any.

Usage example:
difference() {
	cylinder (h = 4, r=1, center = true, $fn=100);
	rotate ([90,0,0]) cylinder (h = 4, r=0.9, center = true, $fn=100);
}

Note: It is mandatory that surfaces that are to be removed by a difference operation have an overlap, and that the negative piece being removed extends fully outside of the volume it is removing that surface from. Failure to follow this rule can cause preview artifacts and can result in non-manifold render warnings or the removal of pieces from the render output. See the description above in union for why this is required and an example of how to do this by this using a small epsilon value.

Note, in the second instance, the result of adding a union of the 1st and 2nd children.

// Usage example for difference of multiple children:
$fn=90;
difference(){
    cylinder(r=5,h=20,center=true);
    rotate([00,140,-45])
        color("LightBlue")
            cylinder(r=2,h=25,center=true);
    rotate([00,40,-50])
        cylinder(r=2,h=30,center=true);
    translate([0,0,-10])
        rotate([00,40,-50])
            cylinder(r=1.4,h=30,center=true);
}
   
// second instance with added union
translate([10,10,0]){
    difference(){
      union(){        // combine 1st and 2nd children
                                                cylinder(r=5,h=20,center=true);
        rotate([00,140,-45]) color("LightBlue") cylinder(r=2,h=25,center=true);
      }
      rotate([00,40,-50])                       cylinder(r=2,h=30,center=true);
      translate([0,0,-10])rotate([00,40,-50])   cylinder(r=1.4,h=30,center=true);
    }
}

Creates the intersection of its child nodes. This logical and operation creates an object that is the overlapping part of all the child nodes together

Intersection may be applied to 2D or 3D objects, but should be applied to objects of only one type. Mixing 2D and 3D child nodes will give indeterminate results, if any.

//Usage example:
intersection() {
	cylinder (h = 4, r=1, center = true, $fn=100);
	rotate ([90,0,0])
        cylinder (h = 4, r=0.9, center = true, $fn=100);
    }

OpenSCAD User Manual/The OpenSCAD Language

A module that will invoke its child module(s) repeatedly.

Format

for( <loop_var> ) <child expression>;

As with any module, the child of a for() may be a block of code in braces:

for( <loop_var> ) { one(); two(); x=12 };

Parameters

<loop_vars>

the loop variable determines how many times the <child expression> will be invoked. It is also a local variable in the scope of the <child expression>.

<child expression>

the loop will invoke this expression once for each value of the loop variable. It may be a statement, module call, or a block of statements in braces.

A for() loop must operate a fixed number of times as set by the loop variable. There are a number of formats for specifying the value that the loop variable will have in each iteration.

Range

for( r=[start:incr:end] ), 'r' will be a number in the sequence of the range.
for( r= [start : end] )

Vector

for( v = [vector] ), 'v' will be elements of the vector and so may be of any data type, or an unnamed function (a lambda function).

String

for( s = "string" ), 's' will be a single letter string

Object

for( o = object ), 'o' will be a string containing the name of a member of the object, in the order members were defined in.

Note: Loop variables for an object are only indirect references to the content of its members, unlike the other types. To access the members of an object the String-Index form may be used, member=object[o]

The normal way to use a range:

 for (a =[3:5])echo(a);     // 3 4 5

Counting down using a range [Deprecated: start > end is deprecated after 2015.03 and will be removedin a future release. Use negative increment instead]

 for (a =[3:0]){echo(a);}   // 0 1 2 3
 for (a =[3:-1:0]){echo(a);} // negative increment : 0 1 2 3

Note: The End must be less than start when increment is less than zero

Counting by fractions

 for (a =[3.0 :0.5: 5.0])echo(a); // 3 3.5 4 4.5 5

Loop will stop when current_value + Increment > end so the end value may not be reached

 for (a =[0:2:5])echo(a);   // 0 2 4 : a + 2 > 4 stops the loop

The loop value is defined with each element of the vector in order:

 for (a =[3,4,1,5]) echo(a); // 3 4 1 5

It will be whatever data type the element is

 for (a =[[1,2],6,"s",[[3,4],[5,6]]]) echo(a);  // [1,2] 6 "s" [[3,4],[5,6]] 

[Note: Requires version Development snapshot]

The loop value is defined with the name of each member of the object, in the order they were defined in.

thing = object( this="str", that=12 );
for( o=thing ) echo( o, thing[o] );

shows:

ECHO: "this", "str"
ECHO: "that", 12

There are built-in functions that return objects:

tm = textmetrics("Hello, World!");
for (name = tm) echo(name, tm[name]);

The for() is a module that invokes its child module repeatedly. The loop variable(s) are local to the scope of the for() and are defined separately in each branch of a tree of instances.

Hence:

for (i=[0:3])
   translate([i*10,0,0])
     cube(i+1);

Using menu Design > Display-CSG-Tree shows how the loop is unrolled and the variables are given fixed values in each instance:

group() {
    multmatrix([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]) {
        cube(size = [1, 1, 1], center = false);
    }
    multmatrix([[1, 0, 0, 10], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]) {
        cube(size = [2, 2, 2], center = false);
    }
    multmatrix([[1, 0, 0, 20], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]) {
        cube(size = [3, 3, 3], center = false);
    }
    multmatrix([[1, 0, 0, 30], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]) {
        cube(size = [4, 4, 4], center = false);
    }
}

Thus the for() is replaced by a group() containing a sequence of four instances of multmatrix() ( for the translate() ) that each have a child cube().

Very different from the way a procedural language would have one block of code that would be executed four times.

While it is reasonable to nest multiple for() statements such as:

for(z=[-180:45:+180])
  for(x=[10:5:50])
    rotate([0,0,z]) translate([x,0,0]) cube(1);

instead, all ranges/vectors can be included in the same for() operator.

for ( variable1 = <range or vector> , variable2 = <range or vector> ) <do something using both variables>

 example for() nested 3 deep
 
 color_vec = ["black","red","blue","green","pink","purple"];
 for (x = [-20:10:20] )
 for (y = [0:4] )color(color_vec[y])
 for (z = [0,4,10] )
     {translate([x,y*5-10,z])cube();}
 
 shorthand nesting for same result
 
 color_vec = ["black","red","blue","green","pink","purple"];
 for (x = [-20:10:20],
 y = [0:4],
 z = [0,4,10] )
     translate([x,y*5-10,z]){color(color_vec[y])cube();}

Examples using vector of vectors

example 1 - iteration over a vector of vectors (rotation)
  
 for(i = [ [  0,  0,   0],
           [ 10, 20, 300],
           [200, 40,  57],
           [ 20, 88,  57] ])
{
   rotate(i)
   cube([100, 20, 20], center = true);
}

example 2 - iteration over a vector of vectors (translation)
  
for(i = [ [ 0,  0,  0],
          [10, 12, 10],
          [20, 24, 20],
          [30, 36, 30],
          [20, 48, 40],
          [10, 60, 50] ])
{
   translate(i)
   cube([50, 15, 10], center = true);
}

example 3 - iteration over a vector of vectors
for(i = [ [[ 0,  0,  0], 20],
          [[10, 12, 10], 50],
          [[20, 24, 20], 70],
          [[30, 36, 30], 10],
          [[20, 48, 40], 30],
          [[10, 60, 50], 40] ])
{
  translate([i[0][0], 2*i[0][1], 0])
  cube([10, 15, i[1]]);
}

Iterate over the values in a range or vector and create the intersection of objects created by each pass.

Besides creating separate instances for each pass, the standard for() also groups all these instances creating an implicit union. intersection_for() is a work around because the implicit union prevents getting the expected results using a combination of the standard for() and intersection() statements.

intersection_for() uses the same parameters, and works the same as a For Loop, other than replacing the implicit union with an intersection.

example 1 - loop over a range:
intersection_for(n = [1 : 6]) { rotate([0, 0, n * 60]) { translate([5,0,0]) sphere(r=12); } }

example 2 - rotation :
intersection_for(i = [ [ 0, 0, 0], [ 10, 20, 300], [200, 40, 57], [ 20, 88, 57] ]) { rotate(i) cube([100, 20, 20], center = true); }

A module that evaluates an expression as a boolean value and then selects which of its children to invoke. The first child is written normally following the if() with the optional second child following the keyword "else".

if (test) doWhenTrue
if (test) doWhenTrue else doWhenFalse

As with any module, the child of an if(), or of an else, may be a block of statements in braces:

if (test) { one(); two(); x=12 }
if (test) {some=4;thing=5} else {some="a";thing="b";else="c"}

which may be empty to act as placeholders:

if (a==4) {} else  echo("a is not 4");

Parameters

test: Usually a boolean expression, but can be any value or variable.

See here for true or false state of values.

See here for boolean and logical operators

Do not confuse the assignment operator '=' with the equal operator '=='

doWhenTrue: expression to perform when true.

doWhenFalse: expression to perform when false.

Functional Examples

if( true )
    cube(4);

if( false)
    sphere(5);
else
    cube(5);

The code generated is shown by doing Design > Display CSG Tree...

group() {
    cube(size = [4, 4, 4], center = false);
}
group() {
  cube(size = [5, 5, 5], center = false);
}

Note that code is only generated for the parts of an if() for which the test is true. If the true value in the first if() was changed to false there would be nothing in the model's tree from that statement.

Other languages may have a way to select between a number of actions based on a selector variable:

      if(test=="a") {scope1}
 else if(test=="b") {scope2}
 else if(test=="c") {scope3}
 else if(test=="d") {scope4}
 else               {scope5} // default action when test is out of range "a":"d"

Code will be generated only for the statements in the selected scope. Of course, the conditional test may be any expression:

if( (k>8)&&(k<100) ) cube(10);
else if(y==6)       {sphere(6);cube(10);}
else                 echo("any other condition");

A ternary function that uses a test to determine which of 2 expressions to do.

 a =   test ? doWhenTrue : doWhenFalse;
 echo( test ? doWhenTrue : doWhenFalse);

It works like the ?: operator in other languages like 'C' or Java.

Parameters

test: Usually a boolean expression, but can be any value or variable.

See here for true or false state of values.

See here for boolean and logical operators

Tip: Do not confuse assignment '=' with equal '=='

doWhenTrue: the expression to do when test evaluates to true.

doWhenFalse: the expression to do when test evaluates to false

Note: The true and false expressions may not define variables using assignment, '='. A syntax error will be emitted.

Examples

 a=1; b=2; c= a==b ? 4 : 5 ;            //  returns the number '5'
 a=1; b=2; c= a==b ? "a==b" : "a!=b" ;  //  returns the string "a!=b"

 a=5; test = a==1;           // save boolean result
 echo( test ? true: false ); // false
  
 L = 75; R = 2; test = (L/R)>25;
 TrueVector  = [test,L,R,L/R,cos(30)];   // define the true vector
 FalseVector = [test,L,R,sin(15)];       // define the false vector
 a1 = test ? TrueVector: FalseVector;    // [true, 75, 2, 37.5, 0.866025]

The Conditional "?:" operator is of particular use in terminating a recursion.

Note: There is a limit for recursion to prevent an application crash. When a function or module calls itself enough times the function returns undef.

Some forms of tail-recursion elimination are supported.

Example

A function to sum the values in a vector from the Start index to the End index. When the 's' is not given it will default to zero, the first element of the vector, and the 'e' argument must be given by name. When the end index, 'e', is not given the let sets the local index, 'i', to the last index of the vector.

v = [10,20,30,40];
function sumv(v, s=0, e=undef) = 
    let( i = is_undef( e ) ? len(v)-1 : e )
    i == s ? 
        v[i]
    : v[i] + sumv(v, s, i-1 )
    ;

echo( sumv( v, 0, len(v)-1) );   // 100
echo( sumv( v ) );               // 100
echo( sumv( v, 1, 2 ) );         //  50

Multiple nested conditionals can become difficult to understand. Formatting them like multi-line indented "if/else" statements is clearer.

// find the maximum value in a vector
function maxv(v, m=-999999999999, i=0) = 
    (i == len(v) ) 
    ?     m 
    :     (m > v[i]) 
          ?    maxv(v, m, i+1) 
          :    maxv(v, v[i], i+1);

v=[7,3,9,3,5,6];
echo("max",maxv(v));   // ECHO: "max", 9

[Deprecated: assign()  will be removed in a future release. Use Let() instead]

Set variables to a new value for a sub-tree.

Parameters

The variables that should be (re-)assigned

example:

for (i = [10:50])
{
    assign (angle = i*360/20, distance = i*10, r = i*2)
    {
        rotate(angle, [1, 0, 0])
        translate([0, distance, 0])
        sphere(r = r);
    }
}

for (i = [10:50])
{
    angle = i*360/20;
    distance = i*10;
    r = i*2;
    rotate(angle, [1, 0, 0])
    translate([0, distance, 0])
    sphere(r = r);
}