跳转至内容

OpenSCAD 用户手册/基本实体

来自 Wikibooks，开放世界中的开放书籍

立方体

[编辑 | 编辑源代码]

在第一个卦限中创建立方体或长方体（即“盒子”）。当 center 为 true 时，立方体以原点为中心。如果按此处显示的顺序给出，则参数名称是可选的。

cube(size = [x,y,z], center = true/false);
cube(size =  x ,     center = true/false);
参数:
尺寸
单个值，所有边长都为该长度的立方体
3 值数组 [x,y,z]，尺寸为 x、y 和 z 的长方体。
中心
false（默认），第 1（正）卦限，一个角在 (0,0,0)
true，立方体以 (0,0,0) 为中心
default values:  cube();   yields:  cube(size = [1, 1, 1], center = false);
示例:

equivalent scripts for this example
 cube(size = 18);
 cube(18);
 cube([18,18,18]);
 .
 cube(18,false);
 cube([18,18,18],false);
 cube([18,18,18],center=false);
 cube(size = [18,18,18], center = false);
 cube(center = false,size = [18,18,18] );


equivalent scripts for this example
 cube([18,28,8],true);
 box=[18,28,8];cube(box,true);

球体

[编辑 | 编辑源代码]

在坐标系的原点创建一个球体。r 参数名称是可选的。要使用 d 而不是 r，则必须命名 d。

参数

r
半径。这是球体的半径。球体的分辨率基于球体的尺寸以及 $fa、$fs 和 $fn 变量。有关这些特殊变量的更多信息，请参阅：OpenSCAD_User_Manual/Other_Language_Features
d
直径。这是球体的直径。
$fa
碎片角度（度）
$fs
碎片尺寸（毫米）
$fn
分辨率
 default values:  sphere();   yields:   sphere($fn = 0, $fa = 12, $fs = 2, r = 1);

使用示例 

sphere(r = 1);
sphere(r = 5);
sphere(r = 10);
sphere(d = 2);
sphere(d = 10);
sphere(d = 20);

// this creates a high resolution sphere with a 2mm radius
sphere(2, $fn=100); 

// also creates a 2mm high resolution sphere but this one 
// does not have as many small triangles on the poles of the sphere
sphere(2, $fa=5, $fs=0.1);

Sample OpenSCAD spheres, showing clearly the difference in scale.

圆柱体

[编辑 | 编辑源代码]

创建一个以 z 轴为中心的圆柱体或圆锥体。当 center 为 true 时，它也沿 z 轴垂直居中。

如果按此处显示的顺序给出，则参数名称是可选的。如果命名了一个参数，则所有后续参数也必须命名。

cylinder(h = height, r1 = BottomRadius, r2 = TopRadius, center = true/false);

注释

如果使用了 r、d、d1 或 d2，则第 2 和第 3 个位置参数为 r1 和 r2，它们必须命名。

使用 r1 和 r2 或 d1 和 d2 且任一值为零将形成圆锥形状，非零非等值将产生圆锥的一部分（圆锥台）。r1 和 d1 定义底部的宽度，在 [0,0,0] 处，r2 和 d2 定义顶部的宽度。

参数
h : 圆柱体或圆锥体的高度
r  : 圆柱体的半径。r1 = r2 = r。
r1 : 半径，圆锥体的底部。
r2 : 半径，圆锥体的顶部。
d  : 圆柱体的直径。r1 = r2 = d / 2。 [注意： 需要版本 2014.03]
d1 : 半径，圆锥体的底部。r1 = d1 / 2。 [注意： 需要版本 2014.03]
d2 : 半径，圆锥体的顶部。r2 = d2 / 2。 [注意： 需要版本 2014.03]
中心
false（默认），z 的范围从 0 到 h
true，z 的范围从 -h/2 到 +h/2
$fa : 每个碎片的最小角度（度）。
$fs : 每个碎片的最小周长。
$fn : 360 度中固定的碎片数量。3 或更大的值将覆盖 $fa 和 $fs
$fa、$fs 和 $fn 必须是命名参数。点击此处了解更多详情。
defaults: cylinder();  yields: cylinder($fn = 0, $fa = 12, $fs = 2, h = 1, r1 = 1, r2 = 1, center = false);


equivalent scripts
 cylinder(h=15, r1=9.5, r2=19.5, center=false);
 cylinder(  15,    9.5,    19.5, false);
 cylinder(  15,    9.5,    19.5);
 cylinder(  15,    9.5, d2=39  );
 cylinder(  15, d1=19,  d2=39  );
 cylinder(  15, d1=19,  r2=19.5);


equivalent scripts
 cylinder(h=15, r1=10, r2=0, center=true);
 cylinder(  15,    10,    0,        true);
 cylinder(h=15, d1=20, d2=0, center=true);
  • center = false
    center = false
  • center = true
    center = true
equivalent scripts
 cylinder(h=20, r=10, center=true);
 cylinder(  20,   10, 10,true);
 cylinder(  20, d=20, center=true);
 cylinder(  20,r1=10, d2=20, center=true);
 cylinder(  20,r1=10, d2=2*10, center=true);
使用 $fn

较大的 $fn 值可以创建更平滑、更圆的表面，但会延长渲染时间。一些人在开发过程中使用中等值以加快渲染速度，然后在最终的 F6 渲染中将其更改为更大的值。

但是，使用较小的值可能会产生一些有趣的非圆形物体。此处显示了一些示例

scripts for these examples
 cylinder(20,20,20,$fn=3);
 cylinder(20,20,00,$fn=4);
 cylinder(20,20,10,$fn=4);
尺寸不足的孔

使用 cylinder() 和 difference() 在物体中放置孔会创建尺寸不足的孔。这是因为圆形路径是用内接于圆的正多边形来近似的。多边形的顶点在圆上，但顶点之间的直线在圆内。要使所有孔都大于真实的圆，多边形必须完全位于圆外（外接）。外接孔的模块

script for this example
 poly_n = 6;
 color("blue") translate([0, 0, 0.02]) linear_extrude(0.1) circle(10, $fn=poly_n);
 color("green") translate([0, 0, 0.01]) linear_extrude(0.1) circle(10, $fn=360);
 color("purple") linear_extrude(0.1) circle(10/cos(180/poly_n), $fn=poly_n);

通常，半径为 的多边形到任意边的中点的半径为 。如果仅知道中点半径 （例如，将内六角扳手放入六角形孔中），则多边形半径为 。

多面体

[编辑 | 编辑源代码]

多面体是最通用的 3D 基本实体。它可用于创建任何规则或不规则形状，包括具有凹面和凸面特征的形状。曲线表面由一系列平面表面近似。

polyhedron( points = [ [X0, Y0, Z0], [X1, Y1, Z1], ... ], triangles = [ [P0, P1, P2], ... ], convexity = N);   // before 2014.03
polyhedron( points = [ [X0, Y0, Z0], [X1, Y1, Z1], ... ], faces = [ [P0, P1, P2, P3, ...], ... ], convexity = N);   // 2014.03 & later
参数
点
3D 点或顶点的向量。每个点依次是一个向量 [x,y,z]，表示其坐标。
可以按任何顺序定义点。N 个点按定义的顺序引用，从 0 到 N-1。
三角形 [已弃用： 三角形将在未来的版本中移除。 请改用 面参数]
共同包围实体的面向量。每个面都是一个向量，包含来自点向量的 3 个点的索引（基于 0）。
面 [注意： 需要版本 2014.03]
共同包围实体的面向量。每个面都是一个向量，包含来自点向量的 3 个或更多点的索引（基于 0）。
可以按任何顺序定义面，但每个面的点必须按正确的顺序排列（见下文）。定义足够的面以完全包围实体，并且没有重叠。
如果描述单个面的点不在同一平面上，则该面会根据需要自动分割成三角形。
凸度
整数。凸度参数指定与对象相交的光线可能穿过的最大面数。此参数仅在 OpenCSG 预览模式下正确显示对象时才需要。它对多面体渲染没有影响。对于显示问题，在大多数情况下，将其设置为 10 应该可以正常工作。
 default values: polyhedron(); yields: polyhedron(points = undef, faces = undef, convexity = 1);


在面的列表中，对于每个面，您可以从哪个点开始是任意的，但面的点（通过点列表中的索引引用）必须在从外部向内观察每个面时按顺时针方向排序。背面从背面观看，底部从底部观看，等等。记住此排序要求的另一种方法是使用右手定则。使用您的右手，将拇指向上伸出，并像竖起大拇指一样弯曲手指，将拇指指向面，并按照手指弯曲的方向排序点。在下面的示例中尝试一下。


示例 1 使用多面体生成 cube( [ 10, 7, 5 ] );
立方体的点编号
展开的立方体面


CubePoints = [
  [  0,  0,  0 ],  //0
  [ 10,  0,  0 ],  //1
  [ 10,  7,  0 ],  //2
  [  0,  7,  0 ],  //3
  [  0,  0,  5 ],  //4
  [ 10,  0,  5 ],  //5
  [ 10,  7,  5 ],  //6
  [  0,  7,  5 ]]; //7
  
CubeFaces = [
  [0,1,2,3],  // bottom
  [4,5,1,0],  // front
  [7,6,5,4],  // top
  [5,6,2,1],  // right
  [6,7,3,2],  // back
  [7,4,0,3]]; // left
  
polyhedron( CubePoints, CubeFaces );

equivalent descriptions of the bottom face
  [0,1,2,3],
  [0,1,2,3,0],
  [1,2,3,0],
  [2,3,0,1],
  [3,0,1,2],
  [0,1,2],[2,3,0],   // 2 triangles with no overlap
  [1,2,3],[3,0,1],
  [1,2,3],[0,1,3],
示例 2 方形底座金字塔
一个简单的多面体，方形底座金字塔
polyhedron(
  points=[ [10,10,0],[10,-10,0],[-10,-10,0],[-10,10,0], // the four points at base
           [0,0,10]  ],                                 // the apex point 
  faces=[ [0,1,4],[1,2,4],[2,3,4],[3,0,4],              // each triangle side
              [1,0,3],[2,1,3] ]                         // two triangles for square base
 );
示例 3 三棱柱

注意：此示例中存在错误，一个目光锐利的 CAD 工程师注意到展开的三角形不正确，斜边应为 1,5 和 0,4。正确的展开方式是将它们放在矩形 A 旁边，沿着边 1,2 和 0,3。代码已更正，希望在不久的将来会出现修订后的图像。

一个多面体三棱柱
  module prism(l, w, h){
      polyhedron(//pt 0        1        2        3        4        5
              points=[[0,0,0], [l,0,0], [l,w,0], [0,w,0], [0,w,h], [l,w,h]],
              faces=[[0,1,2,3],[5,4,3,2],[0,4,5,1],[0,3,4],[5,2,1]]
              );
      
      // preview unfolded (do not include in your function
      z = 0.08;
      separation = 2;
      border = .2;
      translate([0,w+separation,0])
          cube([l,w,z]);
      translate([0,w+separation+w+border,0])
          cube([l,h,z]);
      translate([0,w+separation+w+border+h+border,0])
          cube([l,sqrt(w*w+h*h),z]);
      translate([l+border,w+separation,0])
          polyhedron(//pt 0       1       2        3       4       5
                  points=[[0,0,0],[h,w,0],[0,w,0], [0,0,z],[h,w,z],[0,w,z]],
                  faces=[[0,1,2], [3,5,4], [0,3,4,1], [1,4,5,2], [2,5,3,0]]
                  );
      translate([0-border,w+separation,0])
          polyhedron(//pt 0       1         2        3       4         5
                  points=[[0,0,0],[0-h,w,0],[0,w,0], [0,0,z],[0-h,w,z],[0,w,z]],
                  faces=[[1,0,2],[5,3,4],[0,1,4,3],[1,2,5,4],[2,0,3,5]]
                  );
      }
  
  prism(10, 5, 3);

调试多面体

[编辑 | 编辑源代码]

定义多面体时可能出现的错误包括：所有面的顶点顺序不都是顺时针方向（从外部观察 - 底面需要从下方观察），面重叠，以及缺失面或部分面。一般来说，多面体的面也应该满足流形条件

  • 任何多面体的边上都应该恰好有两个面相交。
  • 如果两个面共用一个顶点，则它们应该在围绕该顶点的面-边循环中处于相同的循环中。

第一条规则消除了诸如两个共用一条边的立方体以及非水密模型等多面体；第二条规则排除了诸如两个共用一个顶点的立方体等多面体。

从外部观察时，描述每个面的点必须按照相同的顺时针顺序排列，并提供了一种检测逆时针方向的方法。当使用 F5 时与 F12 结合使用“组合视图”时，逆时针方向的面将以粉红色显示。重新排列错误面的点。旋转物体以查看所有面。可以使用 F10 关闭粉红色视图。

OpenSCAD 允许暂时注释掉部分面的描述，以便仅显示剩余的面。使用 // 注释掉该行的其余部分。使用 /* 和 */ 开始和结束注释块。这可以是行的一部分，也可以扩展到多行。仅查看部分面可以帮助确定单个面的正确点。请注意，不会显示实体，只会显示面。如果使用 F12，则所有面都有一侧为粉红色。注释掉一些面也有助于显示任何内部面。


示例 1 显示仅 2 个面
CubeFaces = [
/* [0,1,2,3],  // bottom
   [4,5,1,0],  // front */
   [7,6,5,4],  // top
/* [5,6,2,1],  // right
   [6,7,3,2],  // back */
   [7,4,0,3]]; // left


定义多面体后，其预览可能看起来是正确的。多面体本身甚至可能渲染得很好。但是，为了确保它是一个有效的流形并且可以生成有效的 STL 文件，请将其与任何立方体联合并渲染（F6）。如果多面体消失了，则表示它不正确。修改所有面的绕序以及上面提到的两条规则。

面顺序错误

[编辑 | 编辑源代码]
示例 4 一个具有面顺序错误的更复杂的多面体

当您从视图菜单中选择“组合视图”并编译（预览 F5）设计（不要编译并渲染！）时，预览会显示突出显示的方向错误的多边形。不幸的是，在 OpenCSG 预览模式下无法进行此突出显示，因为它会干扰 OpenCSG 预览模式的实现方式。）

在下面，您可以看到此类有问题多面体的代码和图片，错误的多边形（面或面的组合）以粉红色显示。

// Bad polyhedron
polyhedron
    (points = [
	       [0, -10, 60], [0, 10, 60], [0, 10, 0], [0, -10, 0], [60, -10, 60], [60, 10, 60], 
	       [10, -10, 50], [10, 10, 50], [10, 10, 30], [10, -10, 30], [30, -10, 50], [30, 10, 50]
	       ], 
     faces = [
		  [0,2,3],   [0,1,2],  [0,4,5],  [0,5,1],   [5,4,2],  [2,4,3],
                  [6,8,9],  [6,7,8],  [6,10,11], [6,11,7], [10,8,11],
		  [10,9,8], [0,3,9],  [9,0,6], [10,6, 0],  [0,4,10],
                  [3,9,10], [3,10,4], [1,7,11],  [1,11,5], [1,7,8],  
                  [1,8,2],  [2,8,11], [2,11,5]
		  ]
     );
具有方向错误的多边形的多面体

正确多面体如下所示

polyhedron
    (points = [
	       [0, -10, 60], [0, 10, 60], [0, 10, 0], [0, -10, 0], [60, -10, 60], [60, 10, 60], 
	       [10, -10, 50], [10, 10, 50], [10, 10, 30], [10, -10, 30], [30, -10, 50], [30, 10, 50]
	       ], 
     faces = [
		  [0,3,2],  [0,2,1],  [4,0,5],  [5,0,1],  [5,2,4],  [4,2,3],
                  [6,8,9],  [6,7,8],  [6,10,11],[6,11,7], [10,8,11],
		  [10,9,8], [3,0,9],  [9,0,6],  [10,6, 0],[0,4,10],
                  [3,9,10], [3,10,4], [1,7,11], [1,11,5], [1,8,7],  
                  [2,8,1],  [8,2,11], [5,11,2]
		  ]
     );
初学者提示

如果您不完全理解“方向”，请尝试识别方向错误的粉红色面，然后反转对点向量的引用的顺序，直到您得到正确的结果。例如，在上例中，第三个三角形（[0,4,5]）是错误的，我们将其修复为[4,0,5]。请记住，面列表是一个循环列表。此外，您可以从“视图菜单”中选择“显示边”，打印屏幕截图并对点和面进行编号。在我们的示例中，点以黑色注释，面以蓝色注释。根据需要旋转物体并从背面复制第二个副本。这样您就可以跟踪。

顺时针技术

方向由顺时针循环索引确定。这意味着如果您从外部观察三角形（在本例中为 [4,0,5]），您将看到路径是围绕面的中心顺时针方向的。绕序 [4,0,5] 是顺时针方向，因此是正确的。绕序 [0,4,5] 是逆时针方向，因此是错误的。同样，[4,0,5] 的任何其他顺时针顺序都有效：[5,4,0] 和 [0,5,4] 也都是正确的。如果您使用顺时针技术，您的面将始终位于外部（在 OpenSCAD 外部，其他程序使用逆时针方向作为外部）。

将其视为“左手规则”

如果您将左手放在面上，手指弯曲的方向与点的顺序相同，则您的拇指应指向外部。如果您的拇指指向内部，则需要反转绕序。

具有方向错误的多边形的多面体

“多面体”的简洁描述

  • 点定义形状中的所有点/顶点。
  • 面是连接点/顶点的多边形列表。

点列表中的每个点都由一个 3 元组 x、y、z 位置规范定义。点列表中的点会自动从零开始编号，以便在面列表中使用（0、1、2、3……等等）。

面列表中的每个面都通过从点列表中选择 3 个或更多点（使用点顺序号）来定义。

例如，faces=[ [0,1,2] ] 定义了一个从第一个点（点从零开始引用）到第二个点，然后到第三点的三角形。

从外部观察任何面时，面必须按顺时针顺序列出所有点。

多面体点列表中的点重复

[编辑 | 编辑源代码]

多面体定义的点列表可能包含重复项。当两个或多个点的坐标相同时，它们被视为同一个多面体顶点。因此，以下多面体

points = [[ 0, 0, 0], [10, 0, 0], [ 0,10, 0],
          [ 0, 0, 0], [10, 0, 0], [ 0,10, 0],
          [ 0,10, 0], [10, 0, 0], [ 0, 0,10],
          [ 0, 0, 0], [ 0, 0,10], [10, 0, 0],
          [ 0, 0, 0], [ 0,10, 0], [ 0, 0,10]];
polyhedron(points, [[0,1,2], [3,4,5], [6,7,8], [9,10,11], [12,13,14]]);

定义与以下相同的四面体

points = [[0,0,0], [0,10,0], [10,0,0], [0,0,10]];
polyhedron(points, [[0,2,1], [0,1,3], [1,2,3], [0,3,2]]);
检索自“https://wikibooks.cn/w/index.php?title=OpenSCAD_User_Manual/Primitive_Solids&oldid=4398793”
华夏公益教科书