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) );
存在内置的递归限制以防止应用程序崩溃（几千次）。如果达到限制，您会收到类似以下错误：错误：在调用函数 ... 时检测到递归。
对于所有尾递归 函数，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` 模块。
使用这种语言功能更明智的方法是使用拉伸的二维图形覆盖三维图形。这样可以进一步自定义默认参数，并添加其他参数。