OpenSCAD User Manual/Customizer

Customizer

[Note: Requires version 2019.05]

The Customizer Panel allows model parameters to be adjusted "on the fly", without editing and reloading the current file. Options can enable features of the model and set the sizes of model elements to match the intention of the user. The parameter values may be saved as a set, independently of the model file, allowing a particular model variant to be recalled when needed.

This panel supports the use of OpenSCAD files on Thingiverse and vice versa.

Activation of Customizer panel

The visibility of the Customizer Panel is controlled by the menu item Window > Customizer.

Most Global Variables Can Be Parameters

The Customizer displays the variables defined in the global scope, that is, before the first object that defines a local scope, to make them available as Parameters to the Model. A local scope is created by using braces as part of a module definition or a flow control statement.

A parameter is any variable defined simply as a string, number, or boolean, effectively setting its default value. It may also be a vector of one to four numeric elements.

Global variables may be selectively excluded from the Panel by creating a "Hidden" section using this specifically formed comment /* [Hidden] */ as shown below.

An older method to exclude definitions after a certain point is to use an empty module definition:

    module __Customizer_Limit__ () {}  // Hide following assignments from Customizer.
    debug_mode = false; // example variable to be excluded

This will stop the action of the Customizer as a side effect of the "up to first local scope" rule.

Using the /* [Hidden] */ comment is considered the best practice for limiting customizer definitions as it may be used multiple times, but still only up to the first local scope definition.

Note: A module or flow control statement that includes only one statement, and so does not use braces ( {} ) to define a local scope, would not stop the Customizer from displaying subsequent variables. 

    module does_not_stop_customizer () echo("Some text");
    shown_by_customizer = true;        // still displayed by Customizer

Included Files Are a Sort of Local Scope

Variables from files brought in via include and use are not seen in the global scope of the main file, and so are not included in the Panel.

Examples of Simple Parameter Definitions

Examples of acceptable parameter definitions using simple literals are:

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

Any sort of expression on the right hand side of the equals sign excludes it as a Customizer parameter, as seen here:

e = str("String"," ","concat");
g = 21 + b;
h = ["xxx"];

Customizer Panel Widgets

The panel offers several input elements, or widgets, for limiting and formatting the values assigned to parameters. The widget to apply to each parameter is set in specially formatted comments, the general form of which is shown here

// parameter description as one as a single, preceding comment line
parameter_name = defaultValue; // [ specification ]
  • the parameter description must be the line immediately above the parameter assignment statement with the comment double slash mark ( "//" ) starting in the first character position of the line.
  • a block comment ( /* */ )will be ignored, as will any "//" comment lines before the description.
  • the specification must start with a "//" comment mark followed by, and contained in, square brackets ( "[]" ), though there are a few exceptions, as will be seen.
  • any further text following a specification will cause it to be ignored.

Note: The application of a value limiting specification to a parameter does not restrict what the default value may be set to. A default may be given a value out of the min/max limits, or even one that does not fall on the given increment. The default value need not even be the same type as the specification. The Panel responds by including the default as a replacement list element, or as a min/max limit, while applying the increment as best it can. Generally these issues will not cause run-time errors so the only sign of a mismatch may be unexpected results.

List of Specific Values Widget

For Parameters that may only have values from a list the specification should be a comma separated list of those values. All of the values in the list must be of the same type, but as a literal list they will appear in the order given. The default value set by the right hand side of the assignment need not be one of the elements of the list - the default value is added as a list element, but the code of the list specification is not altered.

experimental-build customizer example 1
// selection from a list
Numbers=2; // [-30, 1, 20, 300]

When the selection list is of strings quotes are not needed and spaces (blanks) are ignored.

// a strings selection list
Strings="xxx"; // [foo,bar,baz]            // << this is the same specification as..
Strings="foo"; // [ "foo", "bar", "baz" ]  // << that.
Named List Elements

The list elements may be named for the convenience of the user. The specification is still a comma separated list, but now each element is a value:label pair with a colon ( ':' ) separator. The first example selector widget will show a drop down list of the three labels, S, M, and L but will assign the related value, 10, 20, or 30, to the variable.

// labeled list of numbers
Labeled_number=10; // [10:S, 20:M, 30:L]

//labeled list of strings
Labeled_string="S"; // [S:Small, M:Medium, L:Large]
Fractions = 0.25; // [0:zero, 0.25:"1/4", 0.5:"1/2", 0.75:"3/4", 1:one]

Problems with labels that could be interpreted as expressions or as numeric values may be avoided by the use of quotes, as seen just above.

It is possible to specify a selection list for a boolean value, but a boolean default value will cause it to be rendered as a checkbox, as will be seen below.

Spin-Box Widget

All numeric parameters are rendered as spin-boxes, which include an editable numeric entry field and a spinner - a pair of arrow head icons that adjust the value up or down by one increment when tapped.

  • With no specification the value increment is one.
  • When the specification is a single number it sets the increment to that value, which may be any floating point value, negative or positive.
  • Giving a single value in square brackets ( [] ) sets the maximum value for the spin-box.

EXCEPTION: the spin-box increment specification may NOT be enclosed in square brackets else it will be taken as a maximum value. To set both an increment and a maximum the three valued range form of the specification must be used, which forces the use of a Slider Widget.

NOTE Setting a default greater than the maximum specified will implicitly raise the maximum to the default.

Typing a value into the number field is always possible, but digits typed when the max value would be exceeded will be rejected, as will a minus sign. It is possible to enter a value that the increment setting would normally never reach.

experimental-build customizer example 4
// spin-box with default step size of 1
Spinbox= 5;

// spin-box with step size 0.5
Spinbox= 5.5; // .5

Setting the default to a value that the increment would not normally reach can have side effects that may not be obvious.

Slider Widget

Numeric parameters specified to have a limited range, with an optional step value, are rendered as spin-boxes with a slider bar added to the widget. The specification format for the Spin-Box also applies to the Slider, with the following additions.

The general format of the specification is one to three numbers separated by colons ( ':' ), as for a range value, but it may not be given as a range variable.

  • A single value ( [50] ) sets the maximum.
  • Two values ( [10:50] ) set the minimum and maximum values.
  • The third limit is the increment, given as the second of the three values ( [10,2,50] )

Minimum and Maximum limits are inclusive, thus [1:10] specifies values from 1 to 10 inclusive. If the default value falls between the limits, if given, the slider will be positioned at that value in the range. A default value set outside the range, if given, replaces the relevant limit, min or max, in the operation of the slider and spin-box.

experimental-build customizer example 2
// widget for number with ONLY a max value specification renders as a spin-box
sliderWithMax =34; // [50]

// slider widget limited to values from 10 to 100
sliderWithRange =34; // [10:100]

// a numeric range from zero to 100 in increments of 5
stepSlider=2; //[0:5:100]

// slider bar centered in the range
sliderCentered =0; // [-10.5:0.1:10.045]

The single value format ( [<max>] )is provided for compatibility with parameterized models on Thingiverse.

Checkbox Widget

Boolean values are rendered as check-boxes in the panel.

experimental-build customizer example 3
//description
Variable = true;

This widget is not supported by Thingiverse. You may prefer to use a [0,1] range as OpenSCAD will use zero as false and 1 as true in logical expressions.

Text Widget

This widget accepts a text string as a parameter, with the option to limit the number of characters it can have.

experimental-build configurator example 5
// Text box for string
String="hello";

// Text box for string with length 8
String="length"; //8

NOTE: The text box widget was introduced in version 2021.01 and as of 2025.03.01 is still available

Vector Widget

experimental-build configurator example 6
// vector widget shows from 1 to 4 spin-boxes
Vector1=[34];
Vector2=[12,34];
Vector3=[12,34,45];
Vector4=[12,34,45,23];

When a range is specified for a vector it is applied to all of the vector's elements:

VectorRange3=[12,34,46]; //[1:2:50] // PROBLEM
VectorRange4=[-2,34,-4,24]; //[-10:2:50]

PROBLEM The 3 element vector is highlighted as a problem due to the mismatch between the default values all being even numbers, the minimum being one, and the increment being two. When the file is opened the Customizer Panel will show the defaults, and using the spinner to decrement will correctly operate to give even numbers, down to the minimum, one. Thereafter using it to increment will now give the odd numbers, 3, 5, 7, etc. This can be corrected by typing a correction into the number field, or avoided entirely by setting only values that conform to the increment, as seen in the four element vector example.

Parameter Groups

Related parameters may be grouped using a block comment in this form:

/* [Group Name] */

The strings for the group name may be separated, as shown next, but then the strings are rendered with a dash ( '-' ) between them:

/* [Group] [Name] */

The name text is a taken as a string literal so the case of the letters in it does not matter.

Each group will be shown as a section headed by a title bar with a fold icon and the group name. Sections are open when the file is loaded but may be closed ( folded ) to show only the title bar.

There are three groups predefined by the Panel: un-grouped, Global, and Hidden.

Un-Grouped Parameters

Parameters that are defined outside of any group are shown in a section of the Panel labeled “parameters”. In practice this includes only parameters defined before the first group.

In Thingiverse these parameters are listed with no section header.

[Global]

Parameters in the Global group not shown in their own section, instead they are included in all other groups.

The case of the letters in this group name is Required to be "Global".

[Hidden]

The Hidden group is not shown. Variables that are used as constants, test data, and parameters that should not be visible to most users are best included in this group.

This group is included for compatibility with Thingiverse.

The case of the letters in this group name is Required to be "Hidden".

See also #hidden_parameters

Customizer Panel Example

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

/*[ Sliders ]*/
// numeric slider widget, default increment
slider =34; // [10:100]

//numeric slider widget incrementing by 5
stepSlider=20; //[0:5:100]

/* [Checkbox] */
// boolean widget (hidden follows)
Variable = true;


/* [Hidden] */
xxx = 12;

/*[Spinboxes] */
// spinbox with step size 1 (hidden above)
Spinbox = 5; 

/* [Textbox] */
// Text box for string
String="hello";

/* [Vectorsd] */
// vector of 1 element
Vector1=[12]; //[0:2:50]
// vector of 2 element
Vector2=[12,34]; //[0:2:50]
// vector of 3 element
Vector3=[-20,6,30]; //[-30:2:60]
// vector of 4 element
Vector4=[12,34,46,24]; //[0:2:50]

/* [Hidden] */
debugMode = true;

Saving Parameters for Reuse

It is possible to take snapshots of the current parameter values, called parameter sets, for later reuse. There is always a set named "<design default>" that holds the default values given in the file's Customizer's parameter definitions. The "+" button may be used to add a new set. A pop-up window asks for the new set's name and hitting the OK button saves the file and adds its name to the drop down list. Leaving the name field blank will create the set without a name, which will make it impossible to load back in later. The data is saved in a JSON file ( i.e. filename.json ) that can be loaded with the model file using a command line option.

There can be any number of sets in a .scad file so two command line options are necessary to load a particular set from a.json file: 

* p (lower case p) to give the filename
* P (upper case P) to give the name of the set

Passing a Parameter Set on the Command Line

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

openscad -o <output-file> -p <parameteric-file (JSON File) > -P <NameOfSet> <input-file SCAD file >
  • -o output file for this command - in this example an .stl file
  • -p input JSON data file
  • -P name of the parameter set in the data file to use

The following is the format of the JSON file used to store multiple parameter sets:

{
    "parameterSets":{
              "set-name ":{
                         "parameter-name " :"value ",
                         "parameter-name " :"value "
                        },
             "set-name ":{
                         "parameter-name " :"value ",
                         "parameter-name " :"value "
                        },
    },
    "fileFormatVersion": "1"
}

The following is a sample JSON file with two parameter sets:

{
    "parameterSets":
    {
        "FirstSet": {
            "Labeled_values": "13",
            "Numbers": "18",
            "Spinbox": "35",
            "Vector": "[2, 34, 45, 12, 23, 56]",
            "slider": "2",
            "stepSlider": "12",
            "string": "he"
        },
        "SecondSet": {
            "Labeled_values": "10",
            "Numbers": "8",
            "Spinbox": "5",
            "Vector": "[12, 34, 45, 12, 23, 56]",
            "slider": "12",
            "stepSlider": "2",
            "string": "hello"
        }
    },
    "fileFormatVersion": "1"
}

GUI

Through GUI you can easily apply and save Parameter in JSON file using Present section in Customizer explained below.

The title bar of the Panel has these controls:

  1. Automatic Preview: When checked the model preview is updated when any parameter is changed, else the preview button (or F5) must be used to update the screen.
  2. Show Details: Dropdown selector
    1. Show Details: parameter descriptions are shown below each parameter name.
    2. Inline Details: parameter descriptions are shown next to each parameter name as allowed by the space available, which means descriptions may be cut short. This option saves on vertical space at the cost of possibly incomplete descriptions.
    3. Hide Details: No descriptions are shown. Hovering over the input widget will still pop-up the description.
  3. Reset button: The values of all widgets are set back to the defaults set in the SCAD file.

Just under the title bar are the Preset Controls:

a drop down selector
select one of the parameters sets available in this file
'+' button
add new parameter set
'–' button
delete selected set

Below the Preset Section is the Panel showing the parameter widgets.

Customizer features may be explored using two examples that are provided with OpenSCAD:

  1. Parametric/sign.scad
  2. Parametric/candlStand.scad

Partial Modification Parameter Sets

When a dataset is loaded, only the parameters in the named parameter set are modified. Parameters in the SCAD file that are not in the given set are not set to their defaults. This allows a JSON data file to be applied to modify a model as it currently exists.

Such a modifier JSON file may be created, or modified from an existing file, to define additional parameters or update specific settings.

Hidden Parameters in a Parameter Set

Variables in the Hidden group are stored in the JSON file, but are not retrieved from the JSON file. The operating principle is that only parameters that the user can see and control from the customizer UI modify values when loaded with a model.

Editing a JSON file to move a hidden parameter to another one means that it will have effect when loaded with a model. The model designer can thus have parameters reserved for internal use that will become visible to the user in a future version.

A hidden variable can also be used as a "last saved with" indicator, that can be read by manually viewing the JSON file.

Tips and Tricks

Set Range and Stepping

Parameters that do not have an explicit specification will have appropriate values for numeric range and increment created by the Customizer, which may not meet the designer's intent. For example the customizer treats numbers with zero fractional parts ( 1.0 ) as integers and will generally use one as their increment. The customizer does not handle negative numbers well so negative minimums and increments are best given explicitly as specifications.

Range limits are instructive to a model's user. For instance, a smart phone holder could have its sizes limited smart phone sizes. Extending the model for use as a tablet holder will require the user to modify the SCAD model file which will serve to inform the user about the structure of the design.

Scroll Wheel On Spin-Box

The scroll wheel on your mouse may be used to rapidly change the value of a spinner by clicking on the widget and then rolling the wheel.

Examples

color =

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

echo(cubeColor);

color(cubeColor)
   cube();

color(sphereColor)
   sphere();

Notes

I saved the Thingiverse Customizer documentation, originally here, to the Internet Archive here, just in case.

Category:Book:OpenSCAD User Manual#Customizer%20
Category:Book:OpenSCAD User Manual