OpenSCAD User Manual/General

Comments

OpenSCAD uses a programming language to create the models that are later displayed on the screen. Comments are a way of leaving notes within the code (either to yourself or to future programmers) describing how the code works, or what it does. Comments are not evaluated by the compiler, and should not be used to describe self-evident code.

OpenSCAD uses C++-style comments:

// This is a comment
 
myvar = 10; // The rest of the line is a comment
 
/*
    Multi-line comments
    can span multiple lines.
*/

Variables

Variables in OpenSCAD are simply a name followed by an assignment via an expression

Example:

myvar = 5 + 4;

Vectors

Variables can be grouped together into Vectors by using brackets. Vectors are useful when dealing with X, Y, and Z coordinates or sizes.

Example

deck = [64, 89, 18];
cube(deck);

Output A cube with the sizes: X = 64, Y = 89, Z = 18.

Selection

You can also refer to individual values in a vector with vector[number].

Example

deck = [64, 89, 18];
translate([0,0,deck[2]]) cube(deck);

Output The same cube as the previous example would be raised by 18 on the Z axis.

Strings

Explicit double quotes or backslashes need to be escaped (\" and \\ respectively). Other escaped special characters are newlines (\n), tabs (\t) and carriage returns (\r).

NB! This behavior is new since OpenSCAD-2011.04. You can upgrade old files using the following sed command: sed 's/\\/\\\\/' non-escaped.scad > escaped.scad

Example:

 echo("The quick brown fox \tjumps \"over\" the lazy dog.\rThe quick brown fox.\nThe \\lazy\\ dog.");

Output:
ECHO: "The quick brown fox jumps "over" the lazy dog.
The quick brown fox.
The \lazy\ dog."

Variables are set at compile-time, not run-time

Note: Because OpenSCAD calculates its variable values at compile-time, not run-time, the last variable assignment will apply everywhere the variable is used. It may be helpful to think of them as override-able constants rather than as variables.

Example:

 // The value of 'a' reflects only the last set value
    a = 0;
    echo(a);
 
    a = 5;
    echo(a);

Output

ECHO: 5
ECHO: 5

This also means that you can not reassign a variable inside an "if" block:

Example:

a=0;
if (a==0) 
  {
  a=1; // <- this line will generate an error.
  }

Output Compile Error

This behavior however is scoped to either the root or to a specific call to a module, meaning you can re-define a variable within a module without affecting its value outside of it. However, all instances within that call will behave as described above with the last-set value being used throughout.

Example:

p = 4;
test(5);
echo(p);
:
: we start with p = 4.  We step to the next command 'test(5)', which calls the 'test' module.
: The 'test' module calculates two values for 'p', but the program will ONLY display the final value. 
: There will be two executions of echo(p) inside 'test' module, but BOTH will display '9' because it is the FINAL
: calculated value inside the module. ECHO: 9   ECHO: 9
:
: Even though the 'test' module calculated value changes for 'p', those values remained inside the module.  
: Those values did not continue outside the 'test' module.  The program has now finished 'test(5)' and moves to the next command 'echo(p)'.
: The call 'echo(p)' would normally display the original value of 'p'=4.  
: Remember that the program will only show the FINAL values.  It is the next set of commands that produce the final values....which is ECHO: 6
 
p = 6;
test(8);
echo(p);
:
: We now see 'p=6', which is a change from earlier.  We step to the next command 'test(8)', which calls the 'test' module.
: Again, the 'test' module calculates two values for 'p', but the program will ONLY display the final value.
: There will be two executions of echo(p) inside 'test' module, but BOTH will display '12' because it is the FINAL
: compiled value that was calculated inside the module.  
: Therefore, both echo(p) statements will show the final value of '12' ;
: Remember that the 'test' module final values for 'p' will remain inside the module.  They do not continue outside the 'test' module.
: ECHO:12   ECHO:  12
:
: The program has now finished 'test(8)' and moves to the next command 'echo(p)'.
: Remember at compile that the pgm will show the FINAL values.  The first value of 'echo(p)' would have showed a value of '4'...
: However, at compile time the final value of 'echo(p)' was actually '6'.  Therefore, '6' will be shown on both echo(p) statements.
: ECHO 6
 
module test(q)
{
    p = 2 + q;
    echo(p);
 
    p = 4 + q;
    echo(p);
}

Output

ECHO: 9
ECHO: 9
ECHO: 6
ECHO: 12
ECHO: 12
ECHO: 6

While this appears to be counter-intuitive, it allows you to do some interesting things: For instance, if you set up your shared library files to have default values defined as variables at their root level, when you include that file in your own code, you can 're-define' or override those constants by simply assigning a new value to them.

See the assign for more tightly scoped changing of values.

Getting input

Now we have variables, it would be nice to be able to get input into them instead of setting the values from code. There are a few functions to read data from DXF files, or you can set a variable with the -D switch on the command line.

Getting a point from a drawing

Getting a point is useful for reading an origin point in a 2D view in a technical drawing. The function dxf_cross will read the intersection of two lines on a layer you specify and return the intersection point. This means that the point must be given with two lines in the DXF file, and not a point entity.

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

Getting a dimension value

You can read dimensions from a technical drawing. This can be useful to read a rotation angle, an extrusion height, or spacing between parts. In the drawing, create a dimension that does not show the dimension value, but an identifier. To read the value, you specify this identifier from your script:

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.