OpenSCAD 用户手册/用户定义函数和模块
(重定向自 OpenSCAD 用户手册/模块)
用户可以通过定义自己的函数和模块来扩展语言。这允许将脚本的一部分分组以便于重复使用不同的值。选择良好的名称也有助于记录您的脚本。
函数返回的值。
模块执行操作，但不返回值。
OpenSCAD 在编译时计算变量的值，而不是运行时。范围内的最后一个变量赋值适用于该范围内的所有位置。它也适用于其范围内的任何内部范围或子节点。有关更多详细信息，请参阅变量的作用域。将它们视为可覆盖的常量而不是变量可能会有所帮助。
对于函数和模块，OpenSCAD 针对每次使用都复制脚本的相关部分。每个副本都有自己的作用域，其中包含特定于该实例的变量和表达式的固定值。
函数和模块的名称区分大小写，因此test()和TEST()指的是不同的函数/模块。
模块和函数可以在模块定义中定义，它们只能在该模块的作用域内可见。
例如
function parabola(f,x) = ( 1/(4*f) ) * x*x;
module plotParabola(f,wide,steps=1) {
function y(x) = parabola(f,x);
module plot(x,y) {
translate([x,y])
circle(1,$fn=12);
}
xAxis=[-wide/2:steps:wide/2];
for (x=xAxis)
plot(x, y(x));
}
color("red") plotParabola(10, 100, 5);
color("blue") plotParabola(4, 60, 2);
函数 y() 和模块 plot() 无法在全局范围内调用。
函数对值进行操作以计算和返回新值。
- 函数定义
function name ( parameters ) = value ;
- 名称
- 您为此函数提供的名称。一个有意义的名称在以后会有所帮助。当前有效的名称只能由简单字符和下划线 [a-zA-Z0-9_] 组成，并且不允许使用高 ASCII 或 Unicode 字符。
- 参数
- 零个或多个参数。参数可以分配默认值，以便在调用时省略参数时使用。参数名称是本地的，不会与相同名称的外部变量发生冲突。
- 值
- 计算值的表达式。该值可以是向量。
在使用时，函数被视为值，并且本身不以分号 ; 结尾。
// example 1
function func0() = 5;
function func1(x=3) = 2*x+1;
function func2() = [1,2,3,4];
function func3(y=7) = (y==7) ? 5 : 2 ;
function func4(p0,p1,p2,p3) = [p0,p1,p2,p3];
echo(func0()); // 5
a = func1(); // 7
b = func1(5); // 11
echo(func2()); // [1, 2, 3, 4]
echo(func3(2), func3()); // 2, 5
z = func4(func0(), func1(), func2(), func3());
// [5, 7, [1, 2, 3, 4], 5]
translate([0, -4*func0(), 0])
cube([func0(), 2*func0(), func0()]);
// same as translate([0,-20,0]) cube([5,10,5]);
// example 2 creates for() range to give desired no of steps to cover range
function steps(start, no_steps, end) =
[start : (end-start)/(no_steps-1) : end];
echo(steps(10, 3, 5)); // [10 : -2.5 : 5]
for (i = steps(10, 3, 5)) echo(i); // 10 7.5 5
echo(steps(10, 3, 15)); // [10 : 2.5 : 15]
for (i = steps(10, 3, 15)) echo(i); // 10 12.5 15
echo(steps(0, 5, 5)); // [0 : 1.25 : 5]
for (i = steps(0, 5, 5)) echo(i); // 0 1.25 2.5 3.75 5
// example 3 rectangle with top pushed over, keeping same y
function rhomboid(x=1, y=1, angle=90)
= [[0,0],[x,0],
[x+x*cos(angle)/sin(angle),y],
[x*cos(angle)/sin(angle),y]];
echo (v1); v1 = rhomboid(10,10,35); // [[0, 0],
// [10, 0],
// [24.2815, 10],
// [14.2815, 10]]
polygon(v1);
polygon(rhomboid(10,10,35)); // alternate
//performing the same action with a module
module parallelogram(x=1,y=1,angle=90)
{polygon([[0,0],[x,0],
[x+x*cos(angle)/sin(angle),y],
[x*cos(angle)/sin(angle),y]]);};
parallelogram(10,10,35);
您也可以使用let 语句 在函数中创建变量
function get_square_triangle_perimeter(p1, p2) =
let (hypotenuse = sqrt(p1*p1+p2*p2))
p1 + p2 + hypotenuse;
它可用于在递归函数中存储值。有关一般概念的更多信息，请参阅维基百科页面。
递归 函数调用受支持。使用条件运算符 "... ? ... : ... "，可以确保递归终止。
// recursion example: add all integers up to n
function add_up_to(n) = ( n==0 ? 0 : n + add_up_to(n-1) );
有一个内置的递归限制以防止应用程序崩溃（几千个）。如果达到限制，您将收到类似以下错误：ERROR: Recursion detected calling function ... 。
对于所有尾递归 函数调用自身，OpenSCAD 能够在内部消除递归，将其转换为迭代循环。前面的示例代码不是尾调用，因为需要在调用后计算“add”操作。但以下是符合尾递归消除的
// tail-recursion elimination example: add all integers up to n
function add_up_to(n, sum=0) =
n==0 ?
sum :
add_up_to(n-1, sum+n);
echo(sum=add_up_to(100000));
// ECHO: sum = 5.00005e+009
尾递归消除允许更高的递归限制（高达 1000000）。
[注意: 需要版本 2021.01]
函数字面量 是定义函数的表达式，其他名称为 lambda 或闭包。
- 函数字面量
function (x) x + x
函数字面量可以分配给变量，并且像任何值一样传递。调用函数使用带括号的正常函数调用语法。
func = function (x) x * x; echo(func(5)); // ECHO: 25
可以定义返回函数的函数。未绑定变量由词法范围捕获。
a = 1;
selector = function (which)
which == "add"
? function (x) x + x + a
: function (x) x * x + a;
echo(selector("add")); // ECHO: function(x) ((x + x) + a)
echo(selector("add")(5)); // ECHO: 11
echo(selector("mul")); // ECHO: function(x) ((x * x) + a)
echo(selector("mul")(5)); // ECHO: 26
可以覆盖内置函数。请注意，定义首先处理，因此评估确实对两个 echo() 调用返回 true，因为这些是在后续处理步骤中评估的。
| 源代码 | 控制台输出 |
|---|---|
echo (sin(1));
function sin(x) = true;
echo (sin(1));
|
Compiling design (CSG Tree generation)...
ECHO: true
ECHO: true
Compiling design (CSG Products generation)...
|
模块可用于定义对象，或使用 children() 定义操作符。定义后，模块将临时添加到语言中。
- 模块定义
module name ( parameters ) { actions }
- 名称
- 您为此模块提供的名称。尝试选择一个有意义的名称。当前有效的名称只能由简单字符和下划线 [a-zA-Z0-9_] 组成，并且不允许使用高 ASCII 或 Unicode 字符。
- 参数
- 零个或多个参数。参数可以分配默认值，以便在调用时省略参数时使用。参数名称是本地的，不会与相同名称的外部变量发生冲突。
- 操作
- 几乎所有在模块外部有效的语句都可以包含在模块中。这包括函数和其他模块的定义。此类函数和模块只能从封闭模块中调用。
可以分配变量，但它们的作用域仅限于模块的每次使用。OpenSCAD 中没有机制让模块向外部返回值。有关更多详细信息，请参阅变量的作用域。
对象模块使用一个或多个基元，以及相关的运算符，来定义新对象。
在使用中，对象模块是以分号 ';' 结尾的操作。
name ( parameter values );
//example 1
translate([-30,-20,0])
ShowColorBars(Expense);
ColorBreak=[[0,""],
[20,"lime"], // upper limit of color range
[40,"greenyellow"],
[60,"yellow"],
[75,"LightCoral"],
[200,"red"]];
Expense=[16,20,25,85,52,63,45];
module ColorBar(value,period,range){ // 1 color on 1 bar
RangeHi = ColorBreak[range][0];
RangeLo = ColorBreak[range-1][0];
color( ColorBreak[range][1] )
translate([10*period,0,RangeLo])
if (value > RangeHi) cube([5,2,RangeHi-RangeLo]);
else if (value > RangeLo) cube([5,2,value-RangeLo]);
}
module ShowColorBars(values){
for (month = [0:len(values)-1], range = [1:len(ColorBreak)-1])
ColorBar(values[month],month,range);
}
//example 2
module house(roof="flat",paint=[1,0,0]) {
color(paint)
if(roof=="flat") { translate([0,-1,0]) cube(); }
else if(roof=="pitched") {
rotate([90,0,0]) linear_extrude(height=1)
polygon(points=[[0,0],[0,1],[0.5,1.5],[1,1],[1,0]]); }
else if(roof=="domical") {
translate([0,-1,0]){
translate([0.5,0.5,1]) sphere(r=0.5,$fn=20); cube(); }
} }
house();
translate([2,0,0]) house("pitched");
translate([4,0,0]) house("domical",[0,1,0]);
translate([6,0,0]) house(roof="pitched",paint=[0,0,1]);
translate([0,3,0]) house(paint=[0,0,0],roof="pitched");
translate([2,3,0]) house(roof="domical");
translate([4,3,0]) house(paint=[0,0.5,0.5]);
//example 3
element_data = [[0,"","",0], // must be in order
[1,"Hydrogen","H",1.008], // indexed via atomic number
[2,"Helium", "He",4.003] // redundant atomic number to preserve your sanity later
];
Hydrogen = 1;
Helium = 2;
module coaster(atomic_number){
element = element_data[atomic_number][1];
symbol = element_data[atomic_number][2];
atomic_mass = element_data[atomic_number][3];
//rest of script
}
使用 `children()` 允许模块充当应用于该模块实例化内任何或所有对象的运算符。在使用中，运算符模块不会以分号结尾。
name ( parameter values ){scope of operator}
基本上，`children()` 命令用于对由范围聚焦的对象进行修改。
module myModification() { rotate([0,45,0]) children(); }
myModification() // The modification
{ // Begin focus
cylinder(10,4,4); // First child
cube([20,2,2], true); // Second child
} // End focus
对象通过从 0 到 $children-1 的整数索引。OpenSCAD 将 $children 设置为范围内的对象总数。分组到子范围的对象被视为一个子对象。 参见下面关于独立子对象的示例 和 变量作用域。请注意，`children()`、`echo()` 和空块语句（包括 `if` 语句）都被视为 `$children` 对象，即使没有几何体存在（截至 2017.12.23 版本）。
children(); all children children(index); value or variable to select one child children([start : step : end]); select from start to end incremented by step children([start : end]); step defaults to 1 or -1 children([vector]); selection of several children
已弃用的 `child()` 模块
在 2013.06 版本之前，使用的是现已弃用的 `child()` 模块。这可以根据下表转换为新的 `children()`。
| 2013.06 之前 | 2014.03 及之后 |
|---|---|
| child() | children(0) |
| child(x) | children(x) |
| for (a = [0:$children-1]) child(a) | children([0:$children-1]) |
示例
//Use all children
module move(x=0,y=0,z=0,rx=0,ry=0,rz=0)
{ translate([x,y,z])rotate([rx,ry,rz]) children(); }
move(10) cube(10,true);
move(-10) cube(10,true);
move(z=7.07, ry=45)cube(10,true);
move(z=-7.07,ry=45)cube(10,true);
//Use only the first child, multiple times
module lineup(num, space) {
for (i = [0 : num-1])
translate([ space*i, 0, 0 ]) children(0);
}
lineup(5, 65){ sphere(30);cube(35);}
//Separate action for each child
module SeparateChildren(space){
for ( i= [0:1:$children-1]) // step needed in case $children < 2
translate([i*space,0,0]) {children(i);text(str(i));}
}
SeparateChildren(-20){
cube(5); // 0
sphere(5); // 1
translate([0,20,0]){ // 2
cube(5);
sphere(5);
}
cylinder(15); // 3
cube(8,true); // 4
}
translate([0,40,0])color("lightblue")
SeparateChildren(20){cube(3,true);}
//Multiple ranges
module MultiRange(){
color("lightblue") children([0:1]);
color("lightgreen")children([2:$children-2]);
color("lightpink") children($children-1);
}
MultiRange()
{
cube(5); // 0
sphere(5); // 1
translate([0,20,0]){ // 2
cube(5);
sphere(5);
}
cylinder(15); // 3
cube(8,true); // 4
}
更多模块示例
[edit | edit source]- 对象
module arrow(){
cylinder(10);
cube([4,.5,3],true);
cube([.5,4,3],true);
translate([0,0,10]) cylinder(4,2,0,true);
}
module cannon(){
difference(){union()
{sphere(10);cylinder(40,10,8);} cylinder(41,4,4);
} }
module base(){
difference(){
cube([40,30,20],true);
translate([0,0,5]) cube([50,20,15],true);
} }
- 运算符
module aim(elevation,azimuth=0)
{ rotate([0,0,azimuth])
{ rotate([0,90-elevation,0]) children(0);
children([1:1:$children-1]); // step needed in case $children < 2
} }
aim(30,20)arrow();
aim(35,270)cannon();
aim(15){cannon();base();}
module RotaryCluster(radius=30,number=8)
for (azimuth =[0:360/number:359])
rotate([0,0,azimuth])
translate([radius,0,0]) { children();
translate([40,0,30]) text(str(azimuth)); }
RotaryCluster(200,7) color("lightgreen") aim(15){cannon();base();}
rotate([0,0,110]) RotaryCluster(100,4.5) aim(35)cannon();
color("LightBlue")aim(55,30){cannon();base();}
递归模块
[edit | edit source]与函数类似，模块可能包含递归调用。但是，递归模块没有尾递归消除。
以下代码生成一个粗略的树模型。每个树枝本身都是树的修改版本，由递归生成。注意将递归深度（分支）n 保持在 7 以下，因为基元数量和预览时间呈指数增长。
module simple_tree(size, dna, n) {
if (n > 0) {
// trunk
cylinder(r1=size/10, r2=size/12, h=size, $fn=24);
// branches
translate([0,0,size])
for(bd = dna) {
angx = bd[0];
angz = bd[1];
scal = bd[2];
rotate([angx,0,angz])
simple_tree(scal*size, dna, n-1);
}
}
else { // leaves
color("green")
scale([1,1,3])
translate([0,0,size/6])
rotate([90,0,0])
cylinder(r=size/6,h=size/10);
}
}
// dna is a list of branching data bd of the tree:
// bd[0] - inclination of the branch
// bd[1] - Z rotation angle of the branch
// bd[2] - relative scale of the branch
dna = [ [12, 80, 0.85], [55, 0, 0.6],
[62, 125, 0.6], [57, -125, 0.6] ];
simple_tree(50, dna, 5);
在 技巧与窍门 中可以找到另一个递归模块的示例。
覆盖内置模块
[edit | edit source]可以覆盖内置模块。
一个简单但无用的示例是
module sphere(){
square();
}
sphere();
注意，覆盖后无法调用内置的 sphere 模块。
使用此语言功能的更明智方法是使用挤出的 2D 形状覆盖 3D 形状。这允许自定义默认参数并添加额外的参数。