OpenSCAD: Dateien & Werkzeuge

Akademie

OpenSCAD: Dateien & Werkzeuge

include und use, Bibliotheken, Import, Export, Customizer und Kommandozeile.

Der Customizer: Parameter ohne Code ändern

Begriffe vorab

Customizer: Oberfläche, mit der sich Parameter ohne Codeänderung einstellen lassen.
Parametergruppe: Tab, der Parameter bündelt, per /* [Name] */ definiert.
Parameterset: Gespeicherter Satz von Werten in einer JSON-Datei.
Slider: Schieberegler für Zahlen mit Bereich.
Dropdown: Auswahlliste mit festgelegten Werten.

Wozu?

Der Customizer ist eine grafische Oberfläche, mit der sich Modellparameter einstellen lassen, ohne den Code zu bearbeiten – ideal, wenn du ein Modell an andere weitergibst. Er erfordert laut Doku Version 2019.05 oder neuer und wird über das Menü „Window“ ein- oder ausgeblendet.

Welche Variablen erscheinen?

Sie stehen in der Hauptdatei (nicht per include/use eingebunden).
Sie haben einen einfachen Literalwert: Zeichenkette, Zahl, Wahrheitswert oder Zahlenliste (bis zu 4 Elemente).
Sie stehen vor dem ersten { im Skript.
Sie liegen nicht im Bereich [Hidden].

Ausdrücke wie 12 + 0.5 oder str("a", "b") werden nicht unterstützt.

Steuerelemente per Kommentar

Direkt hinter der Variablen steht ein Kommentar, der das Steuerelement festlegt (linksbündig, ohne führende Leerzeichen):

Dropdown (Zahlen): n = 2; // [0, 1, 2, 3]
Dropdown (Text): s = "foo"; // [foo, bar, baz]
Dropdown mit Beschriftung: g = 10; // [10:S, 20:M, 30:L]
Slider mit Maximum: x = 34; // [50]
Slider mit Bereich: x = 34; // [10:100]
Slider mit Schritt: x = 2; // [0:5:100]
Checkbox: Wahrheitswert; Textfeld: Zeichenkette; Spinbox: Zahl, bei Dezimalschritt // .5.
Vektor mit 2 bis 4 Elementen: v = [12,34,46]; // [1:2:50].

Gruppen und Parametersets

Gruppen entstehen mit /* [Gruppenname] */. Spezielle Namen: [Global] (auf jedem Tab sichtbar) und [Hidden] (nie angezeigt). Parametersets speichert der Customizer als JSON-Datei, auf der Kommandozeile lädst du sie mit -p datei.json -P Name.

/* [Abmessungen] */
// Breite in mm
breite = 40;          // [20:5:100]
tiefe  = 30;          // [20:5:80]
hoehe  = 15;          // [5:1:40]

/* [Optionen] */
mit_loch = true;
farbe = "steelblue";  // [steelblue, tomato, seagreen]
rundung = 2;          // [0:0.5:5]

/* [Hidden] */
$fn = 32;

color(farbe)
difference() {
    cube([breite, tiefe, hoehe]);
    if (mit_loch)
        translate([breite / 2, tiefe / 2, -1]) cylinder(h = hoehe + 2, r = 5);
}

Beim Öffnen im Customizer erscheinen zwei Tabs (Abmessungen und Optionen) mit Schiebereglern, Checkbox und Auswahlliste. $fn bleibt unsichtbar.

Hinweise der Doku: Mehrzeilige Textfelder und direkte Zahleneingabefelder werden nicht unterstützt; versteckte Parameter werden in JSON gespeichert, aber nicht daraus geladen.

Lege die wichtigsten Maße als Customizer-Variablen an den Dateianfang – so wird dein Modell auch für andere benutzbar.

Zum Selbermachen

Mache dein letztes Projekt Customizer-fähig und gruppiere die Parameter.
Speichere zwei Parametersets (klein/groß) und lade sie nacheinander.

Quellen

OpenSCAD User Manual – Customizer (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Customizer)
OpenSCAD Cheat Sheet (openscad.org/cheatsheet, bezieht sich auf Version 2021.01)

Import und Export: Dateiformate

Begriffe vorab

import(): Lädt externe Geometrie in das Modell.
STL: Weit verbreitetes Format für 3D-Druck.
3MF: Containerformat für 3D-Druck-Modelle.
DXF / SVG: Zweidimensionale Formate.
surface(): Erzeugt aus Text- oder PNG-Daten ein Höhenfeld.

import()

import("datei.stl", convexity = 3); lädt externe Geometrie. file ist der Pfad (relativ zur importierenden Datei; unter Windows Schrägstriche oder doppelte Backslashes nutzen). convexity ist die maximale Zahl der Vorder- oder Rückseiten, die ein Strahl durchdringt (meist 10). layer wählt bei DXF und SVG eine Ebene. Weitere Parameter (center, id, $fn/$fa/$fs) nennt die Doku nur für Entwicklungs-Snapshots.

Importierbare Formate laut Doku

3D: STL (ASCII und binär), OFF, OBJ, AMF (veraltet), 3MF.
2D: DXF, PDF, SVG.
Daten: JSON (Snapshot).
Höhenfeld: PNG über surface().

import_stl() und import_dxf() gelten als veraltet; verwende import().

surface()

surface(file, center, invert, convexity) erzeugt aus einer Text- oder PNG-Datei ein Höhenfeld – die Helligkeit oder der Zahlenwert bestimmt die Höhe.

Export

Welche Formate zur Wahl stehen, hängt davon ab, ob das Ergebnis 2D oder 3D ist. Laut Export-Seite:

3D: STL (ASCII), OFF, AMF (ab 2015.03), 3MF (ab 2019.05).
2D: DXF, SVG (ab 2015.03), PDF in A4 (ab 2021.01).
Bild: PNG (ab 2019.05).
CSG: eine vereinfachte Darstellung des Skripts.

Die Kommandozeile nennt zusätzlich die Varianten asciistl und binstl für STL. Exportiert wird das gerenderte Modell: erst F6, dann Export (Menü „Design“ bzw. Export-Befehle).

Praxis

Für 3D-Druck sind STL oder 3MF üblich; prüfe, was dein Slicer erwartet.
Soll ein Profil in ein anderes Programm (z. B. Laserschneider), nutze DXF oder SVG.
Importierte STL-Dateien müssen manifold sein, sonst scheitert das Rendern (siehe Lektion zur Fehlersuche).

// Ein kleines Teil, das sich als STL exportieren lässt.
// Export im Programm: F6 (Rendern), dann Datei exportieren.
// Auf der Kommandozeile: openscad -o teil.stl dieses_skript.scad
difference() {
    cube([30, 20, 8]);
    translate([15, 10, -1]) cylinder(h = 10, d = 6, $fn = 48);
}

Das Beispiel enthält absichtlich keine Importzeile, damit es ohne externe Dateien läuft. In einem echten Projekt stünde dort etwa import("gehaeuse.stl");.

Importiere nur Modelle, die du selbst auf Manifold-Eigenschaft geprüft hast – sonst verlierst du Zeit beim Rendern.

Zum Selbermachen

Exportiere ein einfaches Teil als STL und als 3MF und vergleiche die Dateigrößen.
Exportiere ein 2D-Profil als SVG und öffne es in einem Vektorprogramm.

Quellen

OpenSCAD User Manual – Importing Geometry (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Importing_Geometry)
OpenSCAD User Manual – Export (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Export)
OpenSCAD User Manual – Using OpenSCAD in a command line environment (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Using_OpenSCAD_in_a_command_line_environment)
OpenSCAD Cheat Sheet (openscad.org/cheatsheet, bezieht sich auf Version 2021.01)

include, use und Bibliotheken

Begriffe vorab

include: Fügt den Inhalt einer Datei so ein, als stünde er im aktuellen Skript.
use: Importiert nur Module und Funktionen einer Datei.
Bibliothek: Sammlung wiederverwendbarer Module und Funktionen.
OPENSCADPATH: Umgebungsvariable mit zusätzlichen Bibliotheksordnern.
MCAD: Bibliothek, die mit OpenSCAD mitgeliefert wird.

include und use

Beide Anweisungen binden andere .scad-Dateien ein und nutzen spitze Klammern: include <datei.scad> und use <datei.scad>. Der Unterschied ist wichtig:

include verarbeitet die gesamte Datei, als stünde ihr Text im aktuellen Skript. Alles wird ausgeführt: Zuweisungen, Module und auch Geometrie auf oberster Ebene. Beide Dateien sehen die Variablen der jeweils anderen. Wird eine in der eingebundenen Datei gesetzte Variable im Hauptskript erneut zugewiesen, unterbleibt die sonst übliche Warnung – so können Bibliotheken Standardwerte liefern, die das Hauptskript überschreibt.
use importiert nur Module und Funktionen. Befehle auf oberster Ebene (also Geometrie) werden nicht ausgeführt. Globale Variablen der beiden Dateien bleiben füreinander unsichtbar.

Verschachtelte include– und use-Anweisungen innerhalb der eingebundenen Dateien werden ausgeführt; verschachteltes use wirkt laut Doku aber nur begrenzt auf die Hauptdatei. Platzhalter (*) für mehrere Dateien sind nicht möglich. Verwende Schrägstriche (/) als Pfadtrenner – sie funktionieren auch unter Windows.

Wo OpenSCAD sucht

Mit unvollständigen Pfaden sucht OpenSCAD in dieser Reihenfolge: (1) im Ordner der aufrufenden Datei, (2) in Pfaden aus OPENSCADPATH, (3) in den eingebauten Bibliotheksordnern, (4) im Bibliotheksordner der Installation. Die Standard-Bibliotheksordner sind:

Windows: My Documents\OpenSCAD\libraries
macOS: $HOME/Documents/OpenSCAD/libraries
Linux: $HOME/.local/share/OpenSCAD/libraries

Der Ordner lässt sich über „File → Show Library Folder…“ öffnen (ab 2014.03). OPENSCADPATH trennt mehrere Pfade unter Windows mit Semikolon, unter Linux/macOS mit Doppelpunkt; nach einer Änderung muss OpenSCAD neu starten.

Bekannte Bibliotheken

Mitgeliefert wird MCAD mit gängigen Formen (abgerundete Boxen, regelmäßige Vielecke, Polyeder), Zahnrad-Generatoren, Motorhalterungen, Befestigungsteilen und mathematischen Hilfen. Als beliebte Drittbibliotheken nennt das User Manual BOSL (Belfry OpenScad Library), BOLTS (Normteile) und DotSCAD sowie Spezialbibliotheken für Gewinde, Verrundungen und Lasercut-Teile; eine vollständige Liste führt das OpenSCAD-GitHub-Wiki.

// Dieses Skript zeigt das Prinzip mit lokalen Modulen,
// die in einer eigenen Datei "teile.scad" liegen würden:
//
//   include <teile.scad>;   // führt ALLES aus (auch Geometrie)
//   use     <teile.scad>;   // nur Module und Funktionen
//
// Hier simulieren wir die Datei durch Definitionen im selben Skript.
module schraube(l = 12, d = 3) {
    cylinder(h = l, d = d, $fn = 24);
    translate([0, 0, l]) cylinder(h = d * 0.6, d = d * 2, $fn = 24);
}
module platte(b = 30, t = 20, h = 4) { cube([b, t, h]); }

platte();
translate([15, 10, 4]) schraube();

Beide Module stehen hier im selben Skript, damit das Beispiel allein lauffähig bleibt. Lägen sie in teile.scad, würde use <teile.scad> genügen, um sie zu nutzen – ohne dass die Datei selbst etwas zeichnet.

Wähle use für reine Baustein-Bibliotheken und include nur, wenn du Variablen oder Konfigurationen teilen willst.

Zum Selbermachen

Lege eine Datei mit zwei Modulen an und binde sie einmal per use und einmal per include ein – vergleiche, was gezeichnet wird.
Öffne den Bibliotheksordner deines Systems und lege dort eine Bibliothek an.

Quellen

OpenSCAD User Manual – Include Statement (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Include_Statement)
OpenSCAD User Manual – Libraries (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Libraries)
OpenSCAD Cheat Sheet (openscad.org/cheatsheet, bezieht sich auf Version 2021.01)

OpenSCAD auf der Kommandozeile

Begriffe vorab

CLI: Command Line Interface, Bedienung per Text im Terminal.
-o: Option für die Ausgabedatei; die Endung bestimmt das Format.
-D: Setzt eine Variable vor der Ausführung.
Parameterset: JSON-Datei mit Werten aus dem Customizer.
Makefile: Build-Datei, die Exporte automatisiert.

Grundform

Das Modell lässt sich ohne Oberfläche exportieren – ideal für Automatisierung und Serien:

openscad -o ausgabe.stl eingabe.scad

Die Dateiendung der Ausgabe bestimmt das Format: stl, off, amf, 3mf, csg, dxf, svg, png oder pdf. Mit --export-format lässt sich das überschreiben; für STL gibt es asciistl und binstl.

Wichtige Optionen

-D name=wert definiert Variablen vorab. Zeichenketten brauchen Anführungszeichen, die du vor der Shell schützen musst: -D 'qualitaet="produktion"'.
-p datei.json und -P Name laden Customizer-Parametersets.
–imgsize breite,hoehe, –camera, –projection, –autocenter, –viewall, –colorscheme steuern PNG-Ausgaben.
–render oder –preview wählt den Modus beim Bildexport.
-d datei.deps erzeugt Makefile-Abhängigkeiten, -m make ruft ein Build-System für fehlende Dateien auf.
-q unterdrückt Ausgaben außer Fehlern, –version zeigt die Version, -h die Hilfe.

Plattformhinweise

Auf macOS liegt das Programm unter /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD. Unter Windows empfiehlt die Doku den Wrapper openscad.com für die Kommandozeile.

Serien mit einer Schleife

Mit -D baust du Varianten eines Modells, ohne die Datei zu ändern:

for h in 10 20 30; do
  openscad -o "saeule_$h.stl" -D "hoehe=$h" saeule.scad
done

Das Skript saeule.scad braucht dafür nur eine Variable hoehe, die per -D überschrieben wird. Beim Überschreiben per -D unterbleibt die sonst übliche Warnung über doppelte Zuweisung.

// saeule.scad – Variable "hoehe" lässt sich per -D überschreiben
hoehe = 20;
cylinder(h = hoehe, r = 5, $fn = 48);
echo(version = version());

Aufruf: openscad -o saeule.stl -D hoehe=35 saeule.scad. Die Variable aus der Kommandozeile hat Vorrang vor der Zuweisung im Skript.

Alles, was du im Programm klickst, lässt sich auch skripten – nutze die Kommandozeile für Serienexporte und Automatisierung.

Zum Selbermachen

Exportiere ein Modell per Kommandozeile als STL und PNG.
Erzeuge drei Varianten mit -D und einer Shell-Schleife.

Quellen

OpenSCAD User Manual – Using OpenSCAD in a command line environment (en.wikibooks.org/wiki/OpenSCAD_User_Manual/Using_OpenSCAD_in_a_command_line_environment)
OpenSCAD User Manual – General (en.wikibooks.org/wiki/OpenSCAD_User_Manual/General)
OpenSCAD Cheat Sheet (openscad.org/cheatsheet, bezieht sich auf Version 2021.01)

OpenSCAD: Dateien & Werkzeuge