OpenSCAD用戶手冊/定製功能

定製器

[請注意: 需要使用版本 2019.05]

定製器（customizer）功能為編輯模型參數提供了圖形用戶接口。使用此特性，便無需編輯代碼來修改參數/變量的值。程式設計師可以為指定的模型創建模板，並通過定製它們來進一步適配不同的需求/用戶。另外，也可以保存一系列參數值，藉此可高效地保存特定模型的變體。

激活定製器功能

在[Edit]菜單裏，選擇[Preferences]再打開[Features]選項卡，選中[Customizer]，最後關閉此窗口。
在View菜單裏，您將看到一個[Hide customizer]選項，將其反選。

支持的變量

僅支持主文件里所計算的變量。主文件里包括的文件並不在支持的範圍內。

只計算主文件里頂層的變量，即，為了讓它們在定製器中可見，就必須將它們聲明在任意函數與模塊之前。

如果您希望令某些變量在不出現在定製器中，至少將其置於第一個函數或模塊的定義之後即可。

只有字面量才可用作參數。以下是有效的字面量示例：

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

像下面那樣的表達式（甚至那些常見的尋常示例）

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

都不可作為定製器里的參數。

生成定製表單的語法支持

// 变量描述
variable name = defaultValue; // 可能的取值

以下為定義定製器中不同類型組件的語法：

下拉組合框

// 用于选择数值的组合框
Numbers=2; // 可选值：[0, 1, 2, 3]

// 用于选择字符串的组合框
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 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]

請注意，此句

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

主要用於兼容Thingiverse

複選框

實驗性地構建定製器示例3

// 描述
Variable = true;

數字調整框

實驗性地構建定製器示例4

// 步长为1的数字调整框
Spinbox= 5;

文本框

// 用于具有4个以上元素的向量的文本框
Vector6=[12,34,44,43,23,23];

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

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

特殊向量

//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];

您也可以為向量設定一個範圍

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

Creating Tabs

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] */

雖然可以，但並不建議這樣寫：

/* [Tab] [Name] */

Three tabs names have a special functionality;

[Global]

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]

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

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

展示大多特性的示例

/* [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]

在JSON文件中保存參數值

此功能是openSCAD中唯一一種能令用戶保存所有參數值的方式。通過命令行即可復用這些JSON參數值。

命令行

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

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:

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.
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.
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:

Parametric/sign.scad
Parametric/candlStand.scad

manually create datasets

You can manually create 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 one to create partial datasets which are only modifiers, not complete dataset.

hidden parameters

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

Set Range and Stepping

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

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.

示例

color =

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

echo(cubeColor);

color(cubeColor)
cube();

color(sphereColor)
sphere();