Hob3l

100x Faster Slicing of SCAD Files for 3D Printing

What is This?

Hob3l is a command line tool for reading SCAD files and writing STL files for 3D printing. The focus is on speed and robustness.

OpenSCAD can convert SCAD to STL, too, but it is very slow, because it first produces a 3D object. And the CGAL library used by OpenSCAD is not very robust: I often get spurious error messages due to unstable 3D arithmetics: 'object may not be a valid 2-manifold'.

Instead, Hob3l uses stable arithmetics to produce an STL file suitable for 3D printing. It first pre-slices the basic 3D objects from the SCAD file into layers and then uses 2D operations on each layer. The 2D operations are much faster than 3D operations, and arithmetically much simpler, and thus easier to get stable.

Hob3l is very robust -- the 2D base library was fuzzed to get rid of numeric instability problems. Hob3l uses integer arithmetics and a snap rounding algorithm to stay within the input coordinate precision. It reads and writes normal floating point numbers, and the float<->int conversions are exact within float precision (the native STL binary number format). If necessary, the precision can be scaled (by default, the unit is 1/8192mm).

How Is It Fast?

To be faster than OpenSCAD, Hob3l replaces 3D operations by faster 2D operations. For this, Hob3l first cuts slices and then applies the boolean operations.

Instead, OpenSCAD applies 3D operations to compute a single 3D object. This is very expensive math, and often arithmetically unstable. But for 3D printing, that single 3D object is not needed: it is cut into slices anyway.

So hob3l reverses the internal workflow. Instead of 'compute in 3D, then slice':

it does 'slice, then compute in 2D':

The idea is explained in more detail in my blog.

Hob3l's main output formats are

• STL for printing
• JavaScript/WebGL for viewing and prototyping

Hob3l reads OpenSCAD's native SCAD format, it can import STL files (for 3D imports), and SVG files (for 2D imports).

SCAD Input Format

My SCAD format documentation defines what exactly is supported by Hob3l, and what is different from OpenSCAD.

For the full SCAD format syntax, OpenSCAD can be used as a preprocessor: OpenSCAD can read the full SCAD format and write a simplified version, with only structurs that Hob3l supports. This is a fast preprocessing step, and still avoids OpenSCAD's expensive 3D operations:

    openscad thing.scad -o thing.csg
    hob3l thing.csg -o thing.stl

See Using This Tool.

Valid 2-Manifolds

Hob3l produces only valid 2-manifolds.

Well, if the input polyhedra are really bad, like missing faces, then Hob3l may fail to produce a valid output. But you need blatantly broken input polyhedra for this. This cannot happen unless you use polyhedron() manually in SCAD. Hob3l is not supposed to fail just because you subtract an object from another object and the two share a part of a face (when you get flickering in OpenSCAD): Hob3l either subtracts everything properly, or it leaves a small (valid) polyhedron -- but it does not become unstable and fail on you.

If Hob3l shows unstable behaviour, then that is a bug. Getting it stable took the majority of the development time, because I found this the most annoying problem with OpenSCAD (or the underlying CGAL library).

Status, Stability, Limitations, Future Work, TODO

This tool has been tested very thoroughly for stability and arithmetic robustness, in order to get rid of any floating point instabilities, using a fuzzer and many millions of tests.

The tool can read the specified subset of SCAD (possibly from a preprocessing step by OpenSCAD's to resolve unsupported syntax). Hob3l then slices the input objects, applies the 2D boolean operations (AKA polygon clipping), and then triangulates the resulting polgygons. Then it writes STL format or WebGL/JS.

After that, Slic3r (and probably PrusaSlicer and Cura) can read the STL files Hob3l produces. This step is still necessary, although Hob3l slices the input file, too, because the slicer also does the path planning and G-code generation, which Hob3l does not do.

The input polyhedra must be 2-manifold. However, Hob3l accepts quite a few non-2-manifold input polyhedra. Polyhedra with holes (i.e., missing faces), however, will not work. OpenSCAD (or the CGAL library) probably now has more constraints on well-formedness than Hob3l. E.g., Hob3l's algorithms are robust against wrong handedness of faces.

Hob3l can import STL files (both text and binary formats) for 3D objects and SVG files for 2D objects. Because SVG is a very complex format, only a useful subset is supported, e.g., no CSS styling is implemented. E.g, SVG files written by Inkscape can be read by Hob3l.

The output STL contains separate layers instead of a single solid. In the future, Hob3l may generate one contiguous object. It would be more processing and is not strictly necessary. But if you hit split in Slic3r on the current output of Hob3l, you'll get many separate layer objects -- which is not useful.

Memory management has leaks. I admit I don't care enough, because Hob3l basically starts, allocates, exits, i.e., it does not run for long, so the memory leaks do not build up.

There are never enough tests. However, Hob3l's core algorithms have survived many millions of fuzzing tests with afl.

Supported Output Formats

STL: This is the main output format of Hob3l for which it was first developed. The input SCAD files can be converted to STL and then used as input to a slicer for 3D printing. Both ASCII STL (more precise) and binary STL (smaller) are supported.

PS: For debugging and documentation, including algorithm visualisation, Hob3l can output in PostScript. This is how the overview images on this page where generated: by using single-page PS output, converted to PNG using GraphicsMagick. For debugging, mainly multi-page debug PS output was used, which allows easy browsing (I used gv for its speed and other nice features). Also, this allows to compare different runs and do a step-by-step analysis of what is going on during the algorithm runs. The PS modules has a large number of command line options to customise the output.

WEBGL/JS: For prototyping SCAD files, a web browser can be used as a 3D model viewer by using the WebGL/JavaScript output format. The SCAD file can be edited in your favourite editor, then for visualisation, Hob3l can generate WebGL data (possibly with an intermediate step to let OpenSCAD simplify the input file using its .csg output), and a reload in the web browser will show the new model. This package contains auxiliary files to make it immediately usable, e.g. the surrounding .html file with the WebGL viewer that loads the generated data. See the hob3l-js-copy-aux script.

SCAD: For debugging intermediate steps in the parser and converter, Hob3l can write SCAD format of several of its processing stages. In intermediate stages, however, Hob3l's polyhedra may not be strictly correct when printed in SCAD debug output (they may use wrong handedness of polyhedra faces) and then loaded into OpenSCAD for inspection. (But STL and WebGL/JS output do produce correctly oriented faces.)

JavaScript/WebGL Output

Here's a screenshot of my browser with a part of the Prusa i3 MK3 3D printer rendered by Hob3l:

There is an online version available here to play with.

The conversion from .scad to .js takes about 0.7s on my machine, so this is very well suited for prototyping: write the .scad in a text editor, run 'make', reload in browser. To run this conversion yourself, after building, run:

    make clean-test
    time make test-out/curry.js

This should print something like:

./hob3l.exe scad-test/curry.scad -o test-out/curry.js.new.js
Info: Z: min=0.1, step=0.2, layer_cnt=75, max=14.9
mv test-out/curry.js.new.js test-out/curry.js

real  0m0.650s
user  0m0.592s
sys   0m0.044s

Building

Building relies on GNU make and gcc, and uses no automake or other meta-make layer. Both Linux native and the MinGW Windows cross compiler have been tested.

Make variables can be used to switch how the stuff is compiled. Some GCC extensions are used, but I tried not to overdo it (({...}) and __typeof__ are used frequently, though), it should be compilable without too much effort.

Compilation is straight-forward:

    make clean
    make
    make test

Parallel building is supported using the -j option to make.

Some Perl scripts are used to generate C code during compilation.

The resulting executable is called 'hob3l.x'. It is renamed during installation (hob3l on Linux, hob3l.exe on Windows).

Different Build Variants

The makefile supports 'normal', 'release', and 'devel' build variants, which can be switched using the MODE=normal (default), MODE=release, or MODE=devel command line variables for make. The selection is stored in a file .mode.d, so next time you invoke 'make' without a MODE parameter, the previous build variant will be chosen.

E.g.:

    make clean
    make MODE=release
    make test

Different Compiler Targets

To compile with the standard 'gcc', whatever that is, for x86:

    make

To compile with gcc for x86_64 (e.g., 64 bit x86 Linux):

    make TARGET=gcc64

To compile with gcc for i686 (e.g., 32 bit x86 Linux):

    make TARGET=gcc32

To compile with Clang:

    make TARGET=clang

To cross compile for Windows 64 using