OpenSCAD Benutzerhandbuch/Customizer

Customizer

Die Customizer-Funktion bietet eine grafische Benutzeroberfläche, um Modellparameter zu bearbeiten – ohne dass du den Quellcode ändern musst. Entwickler:innen können Vorlagen für ein bestimmtes Modell erstellen und diese leicht an unterschiedliche Anforderungen oder Nutzer:innen anpassen. Außerdem lassen sich ganze Sätze von Parameterwerten speichern, wodurch effektiv Varianten eines Modells abgelegt werden können.

Aktivierung des Customizer-Panels

Falls das Customizer-Panel nicht sichtbar ist, wähle im Menü Fenster > Customizer ausblenden („Window > Hide customizer“), um es einzublenden. (Der Menüeintrag schaltet die Sichtbarkeit um – ist er aktiviert, wird das Panel ausgeblendet.)

Unterstützte Variablen

Der Customizer zeigt alle Variablen an, die folgende Kriterien erfüllen:

Die Variable wird in der Hauptdatei zugewiesen. Variablen aus per `include` oder `use` eingebundenen Dateien werden nicht angezeigt (bei `include` können sie aber im aufrufenden Skript referenziert werden).
Der Wert ist ein einfacher Literalwert – also Zeichenkette, Zahl oder boolescher Wert – oder eine Liste mit bis zu vier Zahlen.
Die Variable steht nicht in einem „Hidden“-Abschnitt, gekennzeichnet durch die Kommentarzeile `/* [Hidden] */` (siehe unten).
Die Zuweisung muss vor dem ersten `{`-Zeichen im Skript stehen. Manche Skripte enthalten daher bewusst ein leeres Modul am Anfang, z. B.:

    module __Customizer_Limit__ () {}  // Alles danach wird vom Customizer ignoriert.
    debug_mode = false;

Da `debug_mode` nach einem `{` steht, wird sie nicht im Customizer angezeigt. Dies ist eine veraltete Methode; heute gilt der Kommentar `/* [Hidden] */` als Best Practice.

Hinweis: Ein Modul oder eine Funktion ohne `{` unterbricht die Customizer-Erkennung nicht:

    module does_not_stop_customizer () echo("Some text");
    shown_by_customizer = true;        // wird weiterhin angezeigt

Wie oben erwähnt, sind nur einfache Literale und Arrays mit maximal vier Zahlen zulässig. Beispiele:

a = "Text";
b = 123;
c = 456.789;
d = [1,2,3,4];

Ausdrücke – selbst triviale – wie

e = str("String"," ","concat");
f = 12 + 0.5;

werden nicht unterstützt.

Syntax zur Generierung des Anpassungsformulars

// Beschreibung der Variable
variablenname = standardwert; // mögliche Werte

Der Beschreibungskommentar muss linksbündig am Anfang der Zeile stehen (keine führenden Leerzeichen).

Im Folgenden findest du die Syntax für verschiedene Eingabeelemente („Widgets“):

// Zahlen-Auswahl
Numbers = 2; // [0, 1, 2, 3]

// Text-Auswahl
Strings = "foo"; // [foo, bar, baz]

// Beschriftete Zahlen-Auswahl
Labeled_values = 10; // [10:S, 20:M, 30:L]

// Beschriftete Text-Auswahl
Labeled_value = "S"; // [S:Small, M:Medium, L:Large]

Schieberegler (Slider)

Nur für Zahlen. Unterstützt verschiedene Formate:

// Maximalwert (kompatibel mit Thingiverse)
sliderWithMax = 34; // [50]

// Bereich
sliderWithRange = 34; // [10:100]

// Schrittweite
stepSlider = 2;     // [0:5:100]

// Zentrierter Bereich mit Dezimal-Schritt
sliderCentered = 0; // [-10:0.1:10]

Checkbox

Beispiel 3: Checkbox

(Nicht von Thingiverse unterstützt.)

// Beschreibung
Variable = true;

Spinbox (Zahlenfeld mit Pfeilen)

Beispiel 4: Spinbox

// Ganzzahlige Schrittweite (implizit 1)
Spinbox = 5;

// Halbzahlige Schrittweite
Spinbox = 5.5; // .5

Textfeld

Datei:OpenSCAD-2017-11-05-experimental-build-configurator-5.png

Beispiel 5: Textfeld

Hinweis: Funktioniert ab Version 2021.01, ggf. nicht in zukünftigen Versionen.

// Einfaches Textfeld
String = "hello";

// Textfeld mit vorgegebener Breite (8 Zeichen)
String = "length"; // 8

Vektor-Eingabe (bis zu 4 Elemente)

Vector2 = [12,34];
Vector3 = [12,34,45];
Vector4 = [12,34,45,23];

Mit Bereichsangabe:

VectorRange3 = [12,34,46]; // [1:2:50]
VectorRange4 = [12,34,45,23]; // [1:50]

Nicht unterstützte Anpassungen

Folgende Funktionen sind derzeit nicht möglich:

Mehrzeilige Textfelder
Direkt editierbare numerische Felder (ohne Spinbox):

SerialNumber = 0; // [::non-negative integer]
Offset = 10.0;    // [::float]

Erstellen von Registerkarten (Tabs)

Parameter können in Tabs gruppiert werden. Die Syntax orientiert sich an Thingiverse:

/* [Tab Name] */

Auch möglich (nicht empfohlen): `/* [Tab] [Name] */`

Drei Tab-Namen haben besondere Bedeutung:

[Global]

Parameter in diesem Tab werden auf allen anderen Tabs angezeigt – es gibt keinen separaten „Global“-Tab.

[Hidden]

Parameter in diesem Tab (Großschreibung beachten!) werden niemals angezeigt – weder die Parameter noch der Tab selbst. Dient zur Kompatibilität mit Thingiverse und zum Ausblenden interner Variablen.

Du kannst mehrere Abschnitte unter `[Hidden]` verwenden (siehe auch #hidden_parameters).

parameters

Parameter, die keiner Tab-Gruppe zugeordnet sind, erscheinen unter einem Tab namens „parameters“. Auf Thingiverse werden sie ohne Tab angezeigt.

Beispiel mit den meisten Funktionen

/* [Drop down box:] */
Numbers = 2; // [0, 1, 2, 3]
Strings = "foo"; // [foo, bar, baz]
Labeled_values = 10; // [10:L, 20:M, 30:XL]
Labeled_value = "S"; // [S:Small, M:Medium, L:Large]

/* [Slider] */
slider = 34; // [10:100]
stepSlider = 2; // [0:5:100]

/* [Checkbox] */
Variable = true;

/* [Spinbox] */
Spinbox = 5;

/* [Textbox] */
String = "hello";

/* [Special vector] */
Vector1 = [12];      // [0:2:50]
Vector2 = [12,34];   // [0:2:50]
Vector3 = [12,34,46]; // [0:2:50]
Vector4 = [12,34,46,24]; // [0:2:50]

/* [Hidden] */
debugMode = true;

Speichern von Parametern in einer JSON-Datei

Du kannst alle aktuellen Parameterwerte in einer JSON-Datei speichern und später über die Kommandozeile wiederverwenden.

Kommandozeile

openscad -o model-2.stl -p parameters.json -P model-2 model.scad

Allgemeine Form:

openscad -o <Ausgabedatei> -p <JSON-Parameterdatei> -P <NameDesSets> <Eingabedatei.scad>

`-p`: Gibt die JSON-Datei mit den Parametern an.
`-P`: Gibt den Namen des Parametersets innerhalb der JSON-Datei an.

Beispiel-JSON-Struktur:

{
    "parameterSets": {
        "FirstSet": {
            "Labeled_values": "13",
            "Numbers": "18",
            "Spinbox": "35",
            "slider": "2",
            "stepSlider": "12",
            "string": "he"
        },
        "SecondSet": {
            "Labeled_values": "10",
            "Numbers": "8",
            "Spinbox": "5",
            "slider": "12",
            "stepSlider": "2",
            "string": "hello"
        }
    },
    "fileFormatVersion": "1"
}

GUI-Bedienung

Im Customizer-Panel findest du oben drei Optionen:

1. Automatic Preview: Bei Aktivierung wird das Modell automatisch neu gerendert, sobald ein Parameter geändert wird. 2. Show Details:

  - *Show Details*: Beschreibung unter dem Parameter  
  - *Inline Details*: Beschreibung neben dem Parameter (gekürzt bei langem Text)  
  - *Hide Details*: Nur bei Mausover sichtbar

3. Reset: Setzt alle Parameter auf ihre Standardwerte zurück.

Darunter folgt der Preset-Bereich mit vier Schaltflächen: - Dropdown: Auswahl eines gespeicherten Parametersets - +: Neues Set hinzufügen - –: Ausgewähltes Set löschen - Save preset: Aktuelles Set speichern/überschreiben

Schließlich kommen die eigentlichen Parameter-Eingabefelder.

Beispiel-Dateien in OpenSCAD:

`Parametric/sign.scad`
`Parametric/candleStand.scad`

Manuelle Erstellung von Datensätzen

Du kannst JSON-Dateien manuell bearbeiten. Beim Laden wird nur die im Set definierten Parameter geändert – alle anderen behalten ihren aktuellen Wert. So kannst du partielle Sets erstellen (z. B. nur Farben oder nur Größen).

Versteckte Parameter (Hidden)

Variablen im `[Hidden]`-Abschnitt werden zwar in die JSON-Datei geschrieben, aber nicht daraus geladen. Das bedeutet: Wenn du eine Variable später aus `[Hidden]` in einen sichtbaren Tab verschiebst, wird sie erst dann durch Presets beeinflusst – bestehende JSON-Dateien bleiben kompatibel. So kann z. B. eine „last saved with“-Versionsinfo in der JSON hinterlegt werden, ohne das UI zu beeinflussen.

Tipps und Tricks

Bereich und Schrittweite explizit angeben

Der Customizer rät automatisch Bereiche und Schritte – oft ungenau. Gib daher immer explizit an, was sinnvoll ist. Beispiel: Bei einer Handyhalterung soll die Größe auf reale Smartphone-Maße begrenzt sein. Wer sie für ein Tablet nutzen möchte, kann den Code direkt anpassen – und merkt so, dass ggf. Stützstrukturen fehlen.

Mausrad in Spinboxen

Klicke in eine Spinbox, um sie zu fokussieren, und nutze dann das Mausrad, um bequem den Wert zu ändern – viel einfacher als die kleinen Pfeiltasten.

Beispiel: Farbanpassung

cubeColor = [1,0.5,0]; // [0:0.1:1]
sphereColor = "blue"; // [red, green, blue]

echo(cubeColor);

color(cubeColor)
    cube();

color(sphereColor)
    sphere();