OpenSCAD 用户手册/自定义器
[注意： 需要版本 2019.05]
自定义器功能为编辑模型参数提供了图形用户界面。使用此功能，无需编辑代码即可更改参数/变量的值。程序员可以为给定模型创建模板，并进一步自定义这些模板以适应不同的需求/用户。还可以保存一组参数值，这实际上保存了特定模型的一个变体。
如果未显示自定义器面板，请使用菜单切换窗口 > 隐藏自定义器使其可见。
自定义器显示满足以下条件的所有变量
- 变量在主文件中分配。自定义器不会显示通过include和use引入的文件中的变量（尽管使用include，它们仍然可以在调用脚本中引用）。
- 变量具有简单的文字值 - 字符串、数字或布尔值 - 或最多四个数字文字的列表。
- 变量未在“隐藏”部分中分配，如仅包含注释/* [Hidden] */的行所定义（详细信息如下）。
- 赋值语句必须出现在第一个{语法元素之前。例如，一些脚本在顶部包含一个空模块，仅用于此目的
module __Customizer_Limit__ () {} // Hide following assignments from Customizer.
debug_mode = false;
因为它出现在{之后，所以自定义器不会显示变量debug_mode。这是一种过时的结束可自定义参数列表的方法 - 注释/* [Hidden] */现在被认为是最佳实践。
注意：可以输入不包含{字符的模块或函数，这不会阻止自定义器显示后续变量。
module does_not_stop_customizer () echo("Some text");
shown_by_customizer = true; // still displayed by Customizer
如上所述，只有简单的文字和最多四个数字的数组可用作参数。文字示例如下
a = "Text"; b = 123; c = 456.789; d = [1,2,3,4];
表达式（即使是简单的示例）如
e = str("String"," ","concat");
f = 12 + 0.5;
不支持作为参数。
// variable description
variable name = defaultValue; // possible values
描述注释必须调整到源文件的左列，没有空格。
以下是如何在表单中定义不同类型小部件的语法
// 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 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兼容
Thingiverse 不支持。
//description
Variable = true;
// spinbox with step size 1
Spinbox= 5;
// spinbox with step size 0.5
Spinbox= 5.5; // .5
注意：文本框示例仅在 2021.01 版本中有效，在未来版本中可能无效！
// 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]
一些理想的自定义约束当前不支持。
- 多行文本框。
- 直接可编辑的（非旋钮框）数值
SerialNumber = 0; //[::non-negative integer]
Offset = 10.0; //[::float]
参数可以分组到选项卡中。此功能允许将相关参数关联到组中。语法与 Thingiverse 选项卡规则非常相似。要创建选项卡，请使用如下所示的多行块注释
/* [Tab Name] */
也可以，但不推荐
/* [Tab] [Name] */
三个选项卡名称具有特殊功能；
全局选项卡中的参数始终显示在每个选项卡上，无论选择哪个选项卡。全局参数不显示任何选项卡；它们出现在所有选项卡中。
隐藏选项卡中的参数（首字母大写）永远不会显示。甚至不显示选项卡。这可以防止 Thingiverse 或 OpenSCAD 自定义器未参数化的全局变量出现在自定义器界面或小部件中。包含是为了与 Thingiverse 兼容。
您可以在隐藏组下有多个段。另请参阅 #hidden_parameters
不在任何选项卡下的参数将在名为“参数”的选项卡下显示。在 Thingiverse 中，这些参数列出时没有选项卡。
/* [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 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]
/* [Hidden] */
debugMode = true;
此功能允许用户保存所有参数的值。然后可以通过命令行重用JSON参数值。
openscad -o model-2.stl -p parameters.json -P model-2 model.scad
openscad -o <output-file> -p <parameteric-file (JSON File) > -P <NameOfSet> <input-file SCAD file >
- -p 用于指定保存参数的输入JSON文件。
- -P 用于指定JSON文件中写入的参数集的名称。
JSON文件以以下格式编写
{
"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，您可以使用下面解释的自定义器中的预设部分轻松应用和保存JSON文件中的参数。
在自定义器中，第一行选项如下
- 自动预览：如果选中，则在您更改自定义器中的任何参数时，模型的预览会自动更新，否则您必须在更新自定义器中的参数后单击预览按钮或按F5。
- 显示详细信息
- 显示详细信息：如果选择，则参数的描述将显示在参数名称下方。
- 内联详细信息：如果选择，则参数的描述将显示在参数名称旁边。较长的描述会被截断。此选项是在垂直空间使用和保留部分描述之间的折衷方案。
- 隐藏详细信息：详细信息被抑制，但您仍然可以通过将光标悬停在输入小部件上查看描述。
- 重置按钮：单击时，它会将所有参数的输入小部件的值重置为SCAD文件中提供的默认值。
接下来是预设部分：它包含四个按钮
- 组合框
- 用于选择要使用的参数集。
- + 按钮
- 添加新的参数集。
- - 按钮
- 用于删除组合框中选择的集。
- 保存预设按钮
- 保存/覆盖当前预设。
最后，在预设部分下方是您可以操作参数的地方。
您还可以参考OpenSCAD中包含的两个示例以了解更多信息
- Parametric/sign.scad
- Parametric/candlStand.scad
您可以通过修改JSON文件以符合上述格式并定义自己的变量来手动创建数据集。加载数据集时，**仅**修改数据集中定义的参数，其他参数**不会**设置为默认值。这允许创建由修饰符组成的部分数据集，而不是完整的数据集。
属于隐藏组的变量存储在JSON文件中，但**不会**从JSON文件中检索。
含义：如果将变量从隐藏组移动到其他组，它也将变得适用。这允许设计人员将隐藏组用于保留变量，这些变量在未来版本中可以自定义（并分配不同的默认值），而不会破坏现有预设。
隐藏变量也可以用作“上次保存的”指示器，可以通过手动查看JSON文件来读取。
其思想是，自定义器仅修改用户可以从自定义器UI中看到和控制的变量。
自定义器尝试猜测合适的范围和步长，但可能会根据您的设计意图给出不一致的结果。例如，自定义器也将像0.0、1.0、2.0等数字视为整数。自定义器也不知道负数是否有意义。因此，建议以注释的形式提供范围和步长。请记住，如有疑问，用户始终可以修改SCAD文件。
不要犹豫限制范围。例如，在智能手机支架的设计中，将尺寸限制在合理的智能手机尺寸范围内。如果有人想将您的智能手机支架用作平板电脑支架，他始终可以直接编辑SCAD文件本身。此操作还会让用户意识到，该设计并非旨在用作平板电脑支架，并且他或她可能需要例如修改支撑结构。
旋转框上的按钮很小，但您可以使用鼠标上的滚轮舒适地更改值。首先，单击旋转框以聚焦旋转框。
cubeColor = [1,0.5,0]; //[0:0.1:1] sphereColor = "blue"; // [red, green, blue] echo(cubeColor); color(cubeColor) cube(); color(sphereColor) sphere();