OpenSCAD User Manual/WIP

From Wikibooks, open books for an open world
Jump to navigation Jump to 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 feature provides a graphic user interface for editing model parameters. With this feature one do not need to edit the code to change the values of the parameters / variables. Programmers can create templates for a given model, and customize these further to adapt to different needs / users. Sets of parameter values can also be saved, which effectively saves a variant of a particular 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

supported variables[edit]

  • Only variables in the main file are evaluated. Files from includes and use are NOT considered.
  • Only the variables that are on the top of the main file will be evaluated, that is, they must be declared BEFORE any function or module declaration in order to appear in the customizer.
  • If you want to hide some variables from the customizer, those must be put at least after the first declaration of function or module.

Only literals are available as parameters. Examples for literals are:

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

Expression (even trivial examples) like

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

are not supported as parameters.

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:

Drop down box[edit]

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:S, 20:M, 30:L]

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

Slider[edit]

Only numbers are allowed in this one, specify any of the following:

experimental-build customizer example 2
// slider widget for number with max. value
sliderWithMax =34; // [50]

// slider widget for number in range
sliderWithRange =34; // [10:100]

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

// slider widget for number in range
sliderCentered =0; // [-10:0.1:10]

Note that this

// slider widget for number with max. value
sliderWithMax =34; // [50]

is mainly for compatibility with thingiverse

Checkbox[edit]

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

Spinbox[edit]

experimental-build customizer example 4
// spinbox with step size 1
Spinbox= 5;

Textbox[edit]

experimental-build configurator example 5
//Text box for vector with more than 4 elements
Vector6=[12,34,44,43,23,23];

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

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

Special vector[edit]

experimental-build configurator example 6
//Spin box box for vector with less than or equal to 4 elements
Vector2=[12,34];
Vector3=[12,34,45];
Vector4=[12,34,45,23];

You can also set a range for the vector:

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

Creating Tabs[edit]

Parameters can be grouped into tabs. This feature will allows related parameters to be associated into groups. The syntax is very similar the Thingiverse rules for tabs. To create a tab, use a multi-line block comment like this:

/* [Tab Name] */

Also possible, but not recommended:

/* [Tab] [Name] */

Three tabs names have a special functionality;

[Global][edit]

Parameters in the Global tab will always be shown on every tab no matter which tab is selected. No tab will be displayed for “Global” parameters, they will always be shown in all the tabs.

[Hidden][edit]

Parameters in the Hidden tab (with first letter uppercase) will never be displayed. Not even the tab will be shown. This prevents global variables that have not been parameterized for the Thingiverse or OpenSCAD Customizer from showing up in the Customizer interface or widget. Included for compatibility with Thingiverse. You can have multiples segments under the Hidden group. see also #hidden_parameters

parameters[edit]

Parameters that are not under any tab will be displayed under a tab named “parameters”. In Thingiverse, these parameters are listed with no tab.

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. JSON parameter values can be then reused through the command line.

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 after 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 the 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.

hidden parameters[edit]

Variables belonging to the hidden group are stored in the json file, but are NOT retrieved from the json file.

Meaning: If a variable is moved from the hidden group to an other group, it also becomes applicable. This allows a designer to use the hidden group for reserved variables, that become customizable (and assigend with a different default) in a future version, without breaking existing preset.

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

The idea is, that the customizer only modifies variables that the user can see and control from the customizer UI.

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. First, click on the spin box to focus the spin box.

Examples[edit]

color =[edit]

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

echo(cubeColor);

color(cubeColor)
cube();

color(sphereColor)
sphere();

Inputdriver[edit]

Introduction[edit]

The inputdriver is currently in development in a separate development branch, so it is not part of the current development snapshots.

The inputdriver allows a user the use of things like a gamepad or a 3D-Mouse in OpenSCAD.

Currently, the following drivers are in development:

  • HIDAPI - Used on MacOS and Windows - needs the USB IDs / it works on Linux too, but needs additional privileges, so it's not ideal for the user
  • Joystick driver - uses the Linux joystick device (currently fixed /dev/input/js0)
  • SpaceNav driver - using the spacenavd daemon
  • DBus driver - Linux only / not for actual devices but for remote control
  • QGamepad - used for Cross-platform joystick support - This seems to require some additional configuration on Qt level currently, so it needs some more work to make it easy to use

The default axis mapping is for 3D-mices.

How to try it out[edit]

The feature is experimental and not yet offically integrated (although we are getting close). There are separate builds needed from the github branch inputdriver5.

The feature needs to be enabled in the Preferences -> Features panel (check 'input-driver' box) and after restarting OpenSCAD the configuration panels should show up in Preferences.

Linux[edit]

Easiest way to try out would be using one of the Linux AppImages (x86_64, armv7l, aarch64). Those links always points to the latest build for Linux and supports currently the Joystick based driver (which also works with the 3D Mouse, but needs the spacenavd driver to be not running).

With a recent Linux distribution it should be simply

  • Download the AppImage
  • chmod 755 OpenSCAD-Branch-InputDriver-latest-x86_64.AppImage
  • Run with ./OpenSCAD-Branch-InputDriver-latest-x86_64.AppImage

Windows[edit]

From time to time there are snapshots built for Windows. Those can be downloaded from the OpenSCAD file server in the snapshots folder.

MacOS[edit]

There's currently no snapshot builds available, please ask on the forum/mailing list if you would like to try this feature on MacOS.

Joystick and gamepads[edit]

linux[edit]

Almost any controller that your Linux computer recognizes should work

The JoystickInputDriver is using the device /dev/input/js0.

Under Ubuntu Linux, you need the packet joystick for joystick support.

QGamepad can also be used, but is not recommended as the QGamepad Driver makes assumptions about the Gamepad that might not be true.

Windows[edit]

QGamepad works well with XBox 360 controllers

Under Windows, you can use QGamepad as a driver.

3D-Mouse[edit]

Linux[edit]

On Linux, the easiest way with the Space Mouse Wireless is interestingly to go though the Joystick driver which is normally enabled on most systems.

Spacenav[edit]

Spacenav is also supported. http://spacenav.sourceforge.net/ https://wiki.archlinux.org/index.php/3D_Mouse#Open_Source_Drivers

sudo apt-get spacenavd

On debian:

sudo  apt install libspnavd-dev 

(requires restart)

Windows[edit]

OpenSCAD interacts directly with the 3D Mouse using the HIDAPI.

Therefore, the driver from the device manufacturer is not required. If the driver of the device manufacturer is installed, the driver has to be stopped, so that OpenSCAD can claim the device.

There are different ways to stop the driver. In your start menu you should have a folder 3Dconnexion and in there "Stop Driver".

You can also try

"C:\Program Files\3Dconnexion\3DxWare\3DxWinCore64\3DxService.exe" -shutdown

Mac OS[edit]

DBus[edit]

The D-Bus driver can be used for remote controlling OpenSCAD. This is mainly intended for programmers. It can for example be used to write a custom input driver.

Debug and testing[edit]

For debugging and testing, D-Feet can be used. OpenSCAD can be found on the Session Bus under org.openscad.OpenSCAD.

qdbus is NOT recommended, as it has issues with some of the more complex data structures.

Example[edit]

An example for QT/C++ can be found under this page.

Camera System[edit]

Note that OpenSCADs camera behavior and system does not operate in a standard way. Via DBus, you are directly interacting OpenSCADS camera. Note that the camera system and thus this is interface could be refractored at some point.

Actions[edit]

Please note that the actions exposed Via dbus are mostly the ones from the Menu Bar of OpenSCAD. Keep in mind, that the menubar might change at some point and that compatibility with the dbus driver is not of concern.

FAQ[edit]

Which button is which?[edit]

Open the preferences, then go to the button tab then press the button you want to assign. The text next to the relevant ComboBox will be shown in red, bold text.

View is drifting[edit]

If your view is drifting, please recalibrate the neutral position and deadzone of your input device. This can be done within OpenSCAD or with the tools of the operating system.

Where are my settings stored?[edit]

See this page.

Development[edit]