OpenSCAD User Manual/WIP

From Wikibooks, open books for an open world
Jump to: navigation, search

Work in Progress[edit]

Overview[edit]

This section contains documentation about ongoing work which is available as experimental features in snapshot versions of OpenSCAD or not yet integrated at all and pending in a branch or pull-request at the OpenSCAD github repository.

Information listed here is mainly intended to help people using and testing the experimental features to provide feedback. It's likely that there are changes to the API and behavior of the features before those are officially released.

NOTE: If the feature mentioned here is already included in the snapshot builds, it's normally also required to enable the feature in the Preferences dialog!

Extensions to the list comprehension syntax[edit]

multiple generator expressions[edit]

The list comprehension syntax is generalized to allow multiple expressions. This allows to easily construct lists from multiple sub lists generated by different list comprehension expressions avoiding concat.

steps = 50;

points = [
	// first expression generating the points in the positive Y quadrant
	for (a = [0 : steps]) [ a, 10 * sin(a * 360 / steps) + 10 ],
	// second expression generating the points in the negative Y quadrant
	for (a = [steps : -1 : 0]) [ a, 10 * cos(a * 360 / steps) - 20 ],
	// additional list of fixed points
	[ 10, -3 ], [ 3, 0 ], [ 10, 3 ]
];

polygon(points);

if/else[edit]

The if-else construct is equivalent to the conditional expression ?: except that it can be combined with filter if. To bind an else expression to a specific if, it's possible to use parenthesis.

// even numbers are halved, positive odd numbers are preserved, negative odd numbers are eliminated
echo( [for(a=[-3:5]) if(a%2==0) [a,a/2] else if( a>0 ) [a,a] ] );
// ECHO: [[-2, -1], [0, 0], [1, 1], [2, 1], [3, 3], [4, 2], [5, 5]];

Note that in the expression above the conditional operator could not substitute if-else. It is possible to express this same filter with the conditional operator but with a more cryptic logic:

// even numbers are halved, positive odd numbers are preserved, negative odd numbers are eliminated
echo( [for(a=[-3:5]) if(a%2==0 || ( a%2!=0 && a>0) ) a%2==0 ? [a,a/2] : [a,a] ]);
// ECHO: [[-2, -1], [0, 0], [1, 1], [2, 1], [3, 3], [4, 2], [5, 5]];

each[edit]

each embeds the values of a list given as argument directly, effectively unwrapping the argument list.

// Without using "each", a nested list is generated
echo([ for (a = [1 : 4]) [ a, a * a ] ]);
// ECHO: [[1, 1], [2, 4], [3, 9], [4, 16]]

// Adding "each" unwraps the inner list, producing a flat list as result
echo([ for (a = [1 : 4]) each [ a, a * a ] ]);
// ECHO: [1, 1, 2, 4, 3, 9, 4, 16]

each unwraps ranges and helps to build more general for lists when combined with multiple generator expressions.

A = [-2, each [1:2:5], each [6:-2:0], -1 ];
echo([for(a=A) 2*a ]);
// ECHO: [-4, 2, 6, 10, 12, 8, 4, 0, -2]

for expression[edit]

The for expression is extended to allow a syntax which looks similar to C. This syntax does not imply a sequential evaluation order of the following expression.

echo( [for (a = 0, b = 1;a < 5;a = a + 1, b = b + 2) [ a, b * b ] ] );
// ECHO: [[0, 1], [1, 9], [2, 25], [3, 49], [4, 81]]

Customizer[edit]

Customizer will provide User Interface to Customize Models interactively instead of modifying them manually. It will make the user able to create the templates for given model which can further be customize to cater to their need of different users and also provide feature to save the set of parameters which define a different model using same template of model.

Activation of Customizer functions[edit]

  • This is experimental functionality, yet distributed in development snapshot since 2017.01.20.
  • In [Edit] menu, select [Preferences] then open tab [Features], tick [Customizer], then close the window when tick is shown.
  • In View menu, you shall now have an option [Hide customizer], than you shall untick

Syntax support for generation of the customization form:[edit]

// variable description
variable name = defaultValue; // possible values

Following is the syntax for how to define different types of widgets in the form:

  1. Drop down box:
    experimental-build configurator example 1
    // combo box for nunber
    Numbers=2; // [0, 1, 2, 3]
    
    // combo box for string
    Strings="foo"; // [foo, bar, baz]
    
    //labeled combo box for numbers
    Labeled_values=10; // [10:L, 20:M, 30:L]
    
    //labeled combo box for string
    Labeled_value="S"; // [S:Small, M:Medium, L:Large]
    
  2. Slider: Only numbers are allowed in this one, specify any of the following:
    experimental-build configurator example 2
    // slider widget for number
    slider =34; // [10:100]
    
    //step slider for number
    stepSlider=2; //[0:5:100]
    
  3. Checkbox:
    //description
    Variable = true;
    
  4. Spinbox:
    // spinbox with step size 1
    Spinbox= 5;
    
  5. Textbox:
    experimental-build configurator example 15
    //Text box for vector with more than 4 elements
    Vector=[12,34,44,43,23,23];
    
    // Text box for string
    String="hello";
    
  6. Special vector:
    //Text box for vector with less than or equal to 4 elements
    Vector2=[12,34,45,23];
    

Creating Tabs:[edit]

Parameters can be grouped into tabs. This feature will allow us to separate similar and related parameters. The syntax for this is also mainly similar to that of Thingiverse syntax for creating the tabs. To create a tab, use a multi-line block comment like this:

/* [Tab Name] */

The following tab names are reserved for special functionality:

[Global]

Parameters in the global tab will always be shown on every tab no matter which tab is selected. Note: there will be no tab for “Global” params, they will just always be shown in all the tabs.

[Hidden]

Parameters in the hidden tab will never be displayed. Not even the tab will be shown. Even though the variables who have not been parameterized using the thingiverse or native syntax will not be displayed in openscad parameter widget but we have implemented this to make our comment like syntax similar as that of thinigverse.

Also the parameters who are under no tab will be displayed under TAB named “parameters”.

OpenSCAD-2017-01-07-experimental-build-configurator-tabs.png
/* [Drop down box:] */
// combo box for nunber
Numbers=2; // [0, 1, 2, 3]

// combo box for string
Strings="foo"; // [foo, bar, baz]

//labeled combo box for numbers
Labeled_values=10; // [10:L, 20:M, 30:XL]

//labeled combo box for string
Labeled_value="S"; // [S:Small, M:Medium, L:Large]

/*[ Slider ]*/
// slider widget for number
slider =34; // [10:100]

//step slider for number
stepSlider=2; //[0:5:100]

/* [Checkbox] */

//description
Variable = true;

/*[Spinbox] */

// spinbox with step size 1
Spinbox = 5; 

/* [Textbox] */

//Text box for vector with more than 4 elements
Vector=[12,34,44,43,23,23];

// Text box for string
String="hello";

/* [Special vector] */
//Text box for vector with less than or equal to 4 elements
Vector2=[12,34,45,23];

Saving Parameters value in JSON file:[edit]

This feature which is unique to openSCAD give user the ability to save the values of all parameters and also we can apply them through the cmd-line and get the output.

Cmdline:[edit]
 openscad --enable=customizer -o model-2.stl -p parameters.json -P model-2 model.scad

openscad --enable=customizer -o <output-file> -p <parameteric-file (JSON File) > -P <NameOfSet> <input-file SCAD file >

  • -p is used to give input JSON file in which parameters are saved.
  • -P is used to give the name of the set of the parameters written in JSON file.

And JSON file is written in the following format:

{
    "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"
}
{
    "parameterSets":{
              "set-name ":{
                         "parameter-name " :"value ",
                         "parameter-name " :"value "
                        },
             "set-name ":{
                         "parameter-name " :"value ",
                         "parameter-name " :"value "
                        },
    },
    "fileFormatVersion": "1"
}
GUI:[edit]

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

In customizer, You will be able to see two checkbox’s which are:

  1. Automatic Preview : If checked preview of model will be automatically updated when you change any parameter in Customizer else you need to click preview button after you update parameter in customizer.
  2. Show Details: If checked the description for parameter will be shown above the input widget for the parameter else It will not be displayed but you still can view the description by hovering the cursor over the input widget.

Then comes Reset button which when clicked resets the values of all input widgets for the parameter to default provided in SCAD file.

Next come Preset section: It consist of three buttons:

combo Box
It is used to select the set of parameters to be used
+ button
  1. It is used to update the set selected in combo Box. On clicking + button values of parameters in set are replaced by new values
  2. If we select “No set selected” in comboBox, then we can use + button to add new set of the parameters
– button
It is used to delete the set selected in combo Box.

and finally below Preset Section is the Place where you can play with the parameters.

You can also refer to  two examples that are Part of OpenSCAD to learn more:

  1. Parametric/sign.scad
  2. Parametric/candlStand.scad
Create manually datasets:[edit]

You can create manually a dataset by modifying the json file according above format and defining your own variables. When a dataset is loaded, only the parameters defined in the dataset are modified, other parameters are NOT set to defaults. This allow to create partial datasets which are only modifiers, not complete dataset.