OpenSCAD User Manual/FAQ

General

How is OpenSCAD pronounced?

The intended pronunciation is: Open - ESS - CAD

What is the meaning of the S in OpenSCAD?

The S stands for Solid as Solid modeling.

Using OpenSCAD for Windows in VM's or via Remote desktop (Windows RDP or Linux XfreeRDP etc)

It is likely that your VM or session does not support the required version of OpenCSG/OpenGL for correct OpenSCAD previews.

This can be resolved by use of software rendering via the Mesa driver from the MSYS2 package.

Download the Repo (the link at File: in the URLs below) for the 64-bit, or 32-bit version as appropriate for your Windows installation:

64bit - mingw64 Repo at https://packages.msys2.org/package/mingw-w64-x86_64-mesa?repo=mingw64
32bit - mingw32 Repo at https://packages.msys2.org/package/mingw-w64-i686-mesa?repo=mingw32

That file is a ...pkg.tar.xz compressed file, a format unsupported in Windows. Use 7-zip or WinRAR to extract the file contents.

Extract the file mingw[64 or 32]\bin\opengl32.dll, (the file is still named opengl32.dll for the 64bit version).

Copy opengl32.dll to the OpenSCAD installation directory, i.e. with the openscad.exe file, likely a sub-directory of c:\program files [for 64bits] or c:\program files(x86) [for 32bits].

Restart OpenSCAD and preview should function normally.

Display

Preview doesn't appear to work at all

Force Goldfeather

Some systems, in particular Intel GPUs on Windows, tend to have old or broken OpenGL drivers. This affects preview rendering when using difference or intersection operators.

The following tends to improve the situation: Edit->Preferences->Advanced->Force Goldfeather (see screenshot).

What are those strange flickering artifacts in the preview?

OpenSCAD display issue with coincident faces

This is typically caused by differencing objects that share one or more faces, e.g.:

cube_size = 20;
difference() {
  cube(cube_size, center = true);
  cylinder(r = 10, h = cube_size, center = true);
}

In some cases the final render works fine, but designs with coincident resulting faces should be considered a design with undefined behavior, as a proper render result is not guaranteed. The fundamental source of the issue is not a bug, but an intrinsic property of the inability to rigorously compare floating point values which might have undergone trigonometric operations (like rotations) resulting in irrational values that simply cannot be represented exactly in any manner. Because of this you can get near-coincident surfaces where part of the surface is inside and part of the surface is outside, or zero-volume regions, resulting in a render error that the output is not manifold. In simple tests like this example, the render will typically be okay giving false confidence in this approach, but if both pieces were subject to an equal rotation it can fail to render in a manner which is slightly dependent on the platform the program is running on. This will typically result in a warning at render, and a rendered piece being removed from the final output.

The solution to this is to always provide a clear overlap for surfaces which are to be removed, such as by adding a small value called an epsilon:

cube_size = 20;
difference() {
  cube(cube_size, center = true);
  cylinder(r = 10, h = cube_size+0.01, center = true);
}

Note that a similar issue occurs with unions, where coincident faces to be merged must also be given an epsilon value to guarantee they are always inside.

There is a second preview-only flickering result which can also occur with faces that are not even supposed to be visible in the final result, for example because they're were negative faces used for removal by a difference() operation. This second case impact of fully properly removed faces (or negative faces) is an artifact of the library used for drawing the preview, and will not affect the render. If a clean preview result is desired such as for imaging output, these can be adjusted by an epsilon value in the same manner. See this discussion for other details.

Why are some parts (e.g. holes) of the model not rendered correctly?

OpenSCAD display issue with convexity setting too low

This can happen when using features like linear_extrude() or when importing objects. The convexity of the objects is not known. For more complex objects, the convexity parameter can be used to specify the value. Note that higher values cause a slowdown in preview.

difference() {
    linear_extrude(height = 15 /* , convexity = 2 */) {
        difference() {
            square([50, 50]);
            translate([10, 10]) circle(5);
        }
    }
    translate([25, 25]) cube([5, 5, 40], center = true);
}

The user manual (section Extrude parameters for all extrusion modes) describes how to calculate the number that should be given to the convexity parameter.

And other workaround might be to use render() to forces the generation of a mesh even in preview mode.

Why does difference (or intersection) sometimes not work in preview?

Sphere with cube subtracted, with camera outside the invisible cube.

The same model, with the view rotated slightly so the camera is inside the invisible cube.

difference() {
    sphere(10);
    cube(100);
}

In perspective mode, the previewer does not process differences or intersections where the camera is inside the invisible object. This is most commonly seen when using a large object to cut away significant parts of the model.

Workarounds:

• Keep the camera outside the invisible objects.
• Keep the invisible objects modest-sized so that it is easier to keep the camera outside them.
• Wrap render() around the difference or intersection.
• Use orthogonal mode.

Why is my model appearing with F5 but not F6?

OpenSCAD polyhedron with flipped face

This can be caused by polyhedrons with flipped faces.

This can be visualized in "Thrown Together" display mode. See misordered faces for details.

points = [[5,5,0],[5,-5,0],[-5,-5,0],[-5,5,0],[0,0,3]];
faces = [[0,1,4],[1,2,4],[2,3,4],[3,4,0],[1,0,3],[2,1,3]];
polyhedron(points, faces);

If the model imports external STL files, see also import related question. It is confusing that the error only occurs if there is more than one object involved, ie it "works" until you add another item.

Why is the preview so slow?

http://forum.openscad.org/Why-is-for-so-slow-tp11511p11531.html

This is hard to explain, but in essence, having intersections (or a difference) as the negative objects in difference is expensive. The preview rendering algorithm allows having only primitive objects as negatives, and everything else has to be unpacked.

For example (using A+B = union() / A-B = difference() / A*B = intersection()):

A - B*C - D*E

becomes: A-B-D + A-B-E + A-C-D + A-C-E

..and if A is more complex:

A+B - C*D - E*F

becomes: A-C-E + A-C-F + A-D-E + A-D-F + B-C-E + B-C-F + B-D-E + B-D-F

All combinations have to be rendered, which can take some time, especially on older GPUs, and especially on low-end Intel GPUs.

Import

Why is my imported STL file appearing with F5 but not F6?

This is mostly caused by bad STL files, the best bet is to verify the STL file in a tool like Blender, MeshLab or NetFabb and fix the issues. In essence the model needs to be manifold to be processed in OpenSCAD.

The reason for the model still appearing in preview mode is that there is no real geometry calculation going on yet. The preview simply draws the triangles from the STL.

There is one specific issue that causes problems called "Zero faces" (meaning the STL contains triangles with zero area because all 3 points are on one line), which is currently not handled well in OpenSCAD.

Using MeshLab

MeshLab has a filter to remove zero faces by flipping edges of polygons

Filters -> Cleaning and Repairing -> Remove T-Vertices by Edge-Flip.

Set the Ratio to a high value (e.g. 1000000), otherwise it's possible the model gets distorted.

Using Blender

Blender has a 3D-Printing-Toolbox Plug-in (needs to be enabled in the UserSettings) that can show issues with the STL file. See http://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Modeling/PrintToolbox

Using NetFabb/Microsoft cloud service

The Microsoft 3D Model Repair service can help with fixing STL files. Make sure to read the service conditions before posting files. See https://modelrepair.azurewebsites.net/

I'm getting "Unsupported DXF Entity" warnings when importing DXF files. What does that mean?

DXF import sometimes produces warning messages like Unsupported DXF Entity 'SPLINE' (1c1) in "file.dxf". This means the DXF file is using features that the OpenSCAD importer does not know how to handle. The importer simply ignores those unknown entities that could result in an incomplete model.

When using Inkscape, the easiest way to produces DXF files without unsupported entities is to convert all Bezier curves to short line segments using

Extensions -> Modify Path -> Flatten Beziers

The value given in the dialog determines the length of the line segments. Lower values produce smoother results, but also more line segments. As export file format, use "Desktop Cutting Plotter (AutoCAD DXF R14)".

A more detailed tutorial is available at http://repraprip.blogspot.de/2011/05/inkscape-to-openscad-dxf-tutorial.html

Export

How can I export multiple parts from one script?

Answer based on comments in related issue on github https://github.com/openscad/openscad/pull/1534#issuecomment-227024209

There is a way to generate a bunch of geometric primitives and export them as STL files from a single script, without commenting/uncommenting code.

The variable PARTNO indicates which part is being exported in the current run. If PARTNO is 'undef', then nothing is exported.

Image exported with PARTNO=0

 PARTNO = undef; // default part number
 
 module tree() {
   color("green") cylinder(r1 = 12, r2 = 1, h = 30);
   // ...
 }
 
 module trunk() {
   color("brown") cylinder(r = 3, h = 10);
   // ...
 }
 
 module base() {
   color("white") translate([-10, -10, 0]) cube([20, 20, 5]);
   // ...
 }
 
 if (PARTNO == 1) tree();
 if (PARTNO == 2) trunk();
 if (PARTNO == 3) base();
 
 // optionally use 0 for whole object
 if (PARTNO == 0) {
   base();
   translate([0, 0, 5]) trunk();
   translate([0, 0, 15]) tree();
 }

When working interactively, the PARTNO variable at the top of the file can be set to the number of the part to be shown/exported from the GUI.

It's possible to automate the process of exporting all of the parts by writing a shell script on MacOS or Linux, or a batch file on Windows. The shell script would look something like this:

 # export parts as STL
 openscad -DPARTNO=1 -o tree.stl model.scad
 openscad -DPARTNO=2 -o trunk.stl model.scad
 openscad -DPARTNO=3 -o base.stl model.scad
 
 # export image of all the parts combined
 openscad -DPARTNO=0 -o model.png model.scad

Running this script once from the command line exports all of the parts to separate files.

How can I export screenshots with higher resolution than the current window

Right now that is not possible from the GUI, as the images are restricted to the actual display context. Using the File->Export->Export As Image menu always exports at viewport resolution.

It is however possible to generate higher resolution images via command line using the --imgsize parameter. This uses a separate drawing context, size-limited by memory and the graphics driver, to generate the image. For example, on Linux, the Mesa driver for Intel UHD Graphics 620 (Kabylake GT2) seems to max out at an image resolution of about 16000×16000.

 $ openscad --imgsize 16000,16000 -o CSG.png CSG.scad
 ECHO: version = [2019, 1, 0]
 Compiling design (CSG Products normalization)...
 Normalized CSG tree has 6 elements
 $ file CSG.png 
 CSG.png: PNG image data, 16000 x 16000, 8-bit/color RGB, non-interlaced

Language

Why am I getting an error when writing a = a + 1?

http://forum.openscad.org/A-A-1-tp11385p11411.html

First of all, the question why we have these "limitations" become more clear once we start better exploiting the opportunities.

• We need a "reduce" function to help collecting information depending on a list of input. Recursion is fine, but people tend to struggle with it and we could offer some help.
• We should probably disallow any attempt of reassignment, to make it more clear what's going on. The only real reason we partially allow it is to allow cmd-line variable overrides.

To help think about things:

• Imagine every expression in OpenCAD being executed in parallel. Any dependency of existing expressions must be made explicit by hierarchical grouping. This should quell the idea of iterating for the purpose of accumulating information.
• In terms of functions: Imagine a function expression being something you'd type into a spreadsheet cell. Not totally mappable, but it might help framing it.
• The spreadsheet analogy applies also to iterations. A cell in a spreadsheet cannot increment itself; attempting to do so results in a circular reference error in the spreadsheet.

Now, we could add all kinds of sugar to help people apply their existing programming problem solving skills. The questions are more if it really helps us, and who would spearhead the design of such language extensions, as we currently don't really have attachment for these ideas on the dev-team.

If you think about the OpenSCAD language as something similar to HTML, but for 3D modeling, you'd still have a need for various programs generating code in this language (similar to the plethora of HTML generators out there). There exist a number of tools for helping with OpenSCAD code generation from existing programming languages (python, ruby, C++, haskell, clojure off the top of my head) and there are tools offering Javascript interfaces for similar purposes (OpenJSCAD, CoffeeSCAD). Until we have a really good reason to do so in OpenSCAD proper, and a really good candidate for which language to support, it's better to keep these things separate.

See also for help: List Comprehension, Tips & Tricks, Recursive Functions

User Interface

OpenSCAD isn't adhering to my GTK desktop theme

You may need to install package "qt5-style-plugins" on debian-based systems and "qt5-qtstyleplugins" on Fedora-based systems, then set environment variable when calling openscad QT_QPA_PLATFORMTHEME=gtk2 openscad

To make the setting permanent, add export QT_QPA_PLATFORMTHEME=gtk2 to your user's ~/.profile

OpenSCAD GUI is not scaled in Gnome on a 4K / HIDPI Monitor

The GUI Framework Qt used by OpenSCAD seems to need an extra hint to automatically scale correctly for 4K / HIDPI Monitors on Gnome/X11 (e.g. reported on Ubuntu 22.10 with fractional scaling set to 125%).

• Copy openscad.desktop from /usr/share/applications/ to ~/.local/share/applications
• Change Exec=openscad to Exec=env QT_AUTO_SCREEN_SCALE_FACTOR=1 openscad

I'm not getting any menubar when running OpenSCAD in Ubuntu, how can I get it back?

This seems to be caused by Ubuntu messing with Qt to move the menubar somewhere else (e.g. top of the screen).

That problem hits other applications too, see https://bugs.launchpad.net/ubuntu/+source/appmenu-qt5/+bug/1307619

There are two things that could help:

• Set the QT_QPA_PLATFORMTHEME environment variable to an empty string (the default value is probably "appmenu-qt5") or simply run OpenSCAD with QT_QPA_PLATFORMTHEME= openscad
• Remove the appmenu-qt5 package to globally disable menubar changes for all applications

Why are the error line numbers wrong?

That is a limitation/bug in the current parser that handles include<> basically as copy&paste of content. In some cases it's possible to work around the issue by placing the include<> statements at the end of the file.

When depending on libraries, it's recommended to use use<> instead which does not have that problem and also automatically inhibits any top-level geometry of that file (which might be there as demo for the library).

I don't like the editor, can I use my favourite editor instead?

Yes, OpenSCAD supports a special mode that reloads the files if they are modified externally. To enable this mode, check the Design -> Automatic Reload and Preview option and just close the editor window (or use View -> Hide Editor).

See also the section in the user manual: Using an external Editor with OpenSCAD

As an example, here's a script that runs vim as editor and also starts OpenSCAD, which takes the model viewer role.

It supports 3 modes

• Run with no parameters, it opens a temp file for quick testing, which it deletes.
• Run with the name of a non-existent file, it starts the file with a default license header.
• Run with the name of an existing file, it simply opens it.

#!/bin/bash
  
FILE="$1"
AUTHOR="Your Name Here"
YEAR="$(date "+%Y")"
LICENSE="// Created in $YEAR by $AUTHOR.\n// This work is released with CC0 into the public domain.\n// https://creativecommons.org/publicdomain/zero/1.0/"

# increase stack size to allow deeper recursion
ulimit -s 65536

if [ "$FILE" == "" ]
then
  TEMPF=`mktemp --suffix=.scad`
  openscad "$TEMPF" >/dev/null 2>/dev/null &
  vim "$TEMPF"
  rm -f "$TEMPF"
  exit
fi

if [ ! -e "$FILE" ]
then
  echo -e "$LICENSE" >> "$FILE"
fi

openscad "$FILE" >/dev/null 2>/dev/null &
vim "$FILE"

Errors / Problems

Why am I getting "no top level geometry to render"?

This can have different reasons, some common ones include

Missing / Commented out module call

module model() {
  cube(20);
}
%model();

Using the % modifier does not only make the part transparent, it also causes the part to be excluded in the final render!

Difference / Intersection with wrong translated objects

The easiest way to solve this type of issues is to highlight the objects using the # modifier and see if the objects are placed at the position where they should be.

Importing broken STL files

See Why is my imported STL file appearing with F5 but not F6?

OpenSCAD crashed/was killed, are my unsaved changes lost?

Before starting a preview or render process, the OpenSCAD editor writes a backup file in case there are unsaved changes.

This file is stored in the users documents folder in a separate directory (e.g. on Linux this is normally $HOME/.local/share/OpenSCAD/backups). The actual path can be checked in the Help->Library Info dialog where it is listed as "Backup Path".

OpenSCAD crashes when clicking "New" or loading a file on Windows

OpenSCAD crashes on some machines with Intel graphics drivers, for more details, see https://github.com/openscad/openscad/issues/2442

OpenSCAD fails to run refering to EVR.dll, MF.dll or MFPlat.dll on Windows

This is an issue with the special Windows N (Europe) and KN (Korea) versions which have the Windows Media Framework ripped out as a result of a ruling for anti-competitive practices by the European Commission in 2004.

OpenSCAD, starting with release 2019.05, depends on some of the features so it fails to run on those systems.

The missing Windows Media Framework can be added by installing the correct "Media Feature Pack for N versions" from the list Microsoft provides in KB3145500. For Windows 10 version N, there's a dedicated download page with Windows version selector at: https://www.microsoft.com/en-us/software-download/mediafeaturepack.

Starting with Windows 10 1909 you can't download the Media Features from the Microsoft Website directly - instead you have to use Windows Settings > Apps > Apps and Features > Optional Features > Add a Feature and find the Media Feature Pack in the list of available Optional Features. Afterwards reboot and it should work.

Reporting bugs, Requesting features

How do I report bugs?

Bugs in OpenSCAD are best reported in the github issue tracking system at https://github.com/openscad/openscad/issues. If you are not sure it's a bug, asking on the mailing list/forum can help clarifying things.

Please try searching through the existing issues if the bug was already reported. If you find something similar or if you are unsure, create a new issue, but mention the (possibly) related one.

The bug report should give as much information as possible to help with reproducing it, including but not limited to

• The OpenSCAD version
• The Operating System name and version
• A description of the scenario that produces the issue
• In case of graphics issues, the OpenGL driver information
• If possible, a trimmed down script reproducing the issue

Most of the technical version information can be found in menu Help -> Library Info, or via the command line openscad --info.

How do I request new features?

New features or changes/extensions to existing features can be requested in the github issue tracking system at https://github.com/openscad/openscad/issues too.

Please make an effort to clearly explain the new feature / change as detailed as possible. Including some background about why you think this feature would be useful to you and other people helps a lot and increases the chances of it being implemented.

How do I report bugs that are related to the Operating System I use?

Windows

The Windows version is currently maintained by the OpenSCAD team, so please use the github issue tracker for reporting bugs.

Mac OSX

The Mac OSX version is currently maintained by the OpenSCAD team, so please use the github issue tracker for reporting bugs.

Linux

The OpenSCAD versions included in / distributed by the various Linux distributions are usually maintained by people/teams working with the distributions.

Specific bugs can be reported in the respective bug tracking systems, e.g.

• Debian - See "please report it" directions at https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=openscad

• Ubuntu - See "Report a bug" directions at https://launchpad.net/ubuntu/+source/openscad

• Fedora / Red Hat - See https://apps.fedoraproject.org/packages/openscad/bugs and https://bugzilla.redhat.com/buglist.cgi?component=openscad

• Arch Linux - See "reporting bug guidelines" directions at https://bugs.archlinux.org/index.php?string=openscad&status%5B%5D=

The nightly builds hosted on the openSUSE build service are maintained by the OpenSCAD team, so please use the github issue tracker for reporting issues with those packages.