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 customizer example 1
    // combo box for number
    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 customizer example 2
    // slider widget for number
    slider =34; // [10:100]
    
    //step slider for number
    stepSlider=2; //[0:5:100]
    
  3. Checkbox:
    experimental-build customizer example 3
    //description
    Variable = true;
    
  4. Spinbox:
    experimental-build customizer example 4
    // spinbox with step size 1
    Spinbox= 5;
    
  5. Textbox:
    experimental-build configurator example 5
    //Text box for vector with more than 4 elements
    Vector=[12,34,44,43,23,23];
    
    // Text box for string
    String="hello";
    
    // Text box for string with length 8
    String="length"; //8
    
  6. Special vector:
    experimental-build configurator example 6
    //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”.

Example showcasing most features[edit]

OpenSCAD-2017-11-05-experimental-build-costumizer-tabs.png
/* [Drop down box:] */
// combo box for number
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
Vector6=[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
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]

Saving Parameters value in JSON file[edit]

This feature, which is unique to openSCAD, gives the 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, the first line of options is as follows:

  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 or press F5 kafter you update parameter in customizer.
  2. Show Details:
    1. Show Details: If chosen, the description for the parameter will be shown below the parameter name.
    2. Inline Details: If chosen, the description for the parameter will be shown right next to the parameter name. Long descriptions get clipped, speak not fully shown. This option is a compromise between vertical space usage and still having part of the description.
    3. Hide Details: It will not be displayed but you still can view the description by hovering the cursor over the input widget.
  3. Reset button which when clicked resets the values of all input widgets for the parameter to default provided in SCAD file.

Next comes Preset section: It consist of four buttons:

combo Box
It is used to select the set of parameters to be used
+ button
add new set of the parameters
– button
It is used to delete the set selected in combo Box.
save preset button
save/overwrite the current preset

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.

Tips and Tricks[edit]

Set Range and Stepping[edit]

The customizer tries to guess an appropriate range and stepping. However it can/will be inconsistent, as the customizer does not know your design intent. For example, the customizer also treats numbers like 0.0, 1.0, 2.0 etc. as integers. The customizer also does not know whether or not negative numbers make sense. It is therefor highly recommended to always supply range and step as comments. Keep in mind, that if in doubt, the user can always modify the scad file.

Do not hesitate to limit the range. For instance, in the design of a smart phone holder, limit the size to reasonable smart phone sizes. If someone wants to use your smart phone holder as a tablet holder, he always can directly edit the SCAD file itself. This act also makes the user aware, that the design was not meant as a tablet holder and that he or she might need for example to modify the support structure

Scroll Wheel[edit]

The buttons on the spinboxes are small, but you can use the scroll wheel on your mouse to change the value comfortably.