1# Basic Shapes Tutorial
  2
  3<!-- TOC -->
  4
  5## Primitives
  6There are 3 built-in 3D primitive shapes that OpenSCAD provides: `cube()`, `cylinder()`,
  7and `sphere()`.  The BOSL2 library extends and provides alternative to these shapes so
  8that they support more features, and more ways to simply reorient them.
  9
 10
 11### 3D Cubes
 12BOSL2 overrides the built-in `cube()` module.  It still can be used as you expect from the built-in:
 13
 14```openscad-3D
 15include <BOSL2/std.scad>
 16cube(100);
 17```
 18
 19```openscad-3D
 20include <BOSL2/std.scad>
 21cube(100, center=true);
 22```
 23
 24```openscad-3D
 25include <BOSL2/std.scad>
 26cube([50,40,20], center=true);
 27```
 28
 29It is also enhanced to allow you to anchor, spin, orient, and attach it.
 30
 31You can use `anchor=` similarly to how you use it with `rect()` or `oval()`,
 32except you can also anchor vertically in 3D, allowing anchoring to faces, edges,
 33and corners:
 34
 35```openscad-3D
 36include <BOSL2/std.scad>
 37cube([50,40,20], anchor=BOTTOM);
 38```
 39
 40```openscad-3D
 41include <BOSL2/std.scad>
 42cube([50,40,20], anchor=TOP+BACK);
 43```
 44
 45```openscad-3D
 46include <BOSL2/std.scad>
 47cube([50,40,20], anchor=TOP+FRONT+LEFT);
 48```
 49
 50You can use `spin=` to rotate around the Z axis:
 51
 52```openscad-3D
 53include <BOSL2/std.scad>
 54cube([50,40,20], anchor=FRONT, spin=30);
 55```
 56
 573D objects also gain the ability to use an extra trick with `spin=`;
 58if you pass a list of `[X,Y,Z]` rotation angles to `spin=`, it will
 59rotate by the three given axis angles, similar to using `rotate()`:
 60
 61```openscad-3D
 62include <BOSL2/std.scad>
 63cube([50,40,20], anchor=FRONT, spin=[15,0,30]);
 64```
 65
 663D objects also can be given an `orient=` argument as a vector, pointing
 67to where the top of the shape should be rotated towards.
 68
 69```openscad-3D
 70include <BOSL2/std.scad>
 71cube([50,40,20], orient=UP+BACK+RIGHT);
 72```
 73
 74If you use `anchor=`, `spin=`, and `orient=` together, the anchor is performed
 75first, then the spin, then the orient:
 76
 77```openscad-3D
 78include <BOSL2/std.scad>
 79cube([50,40,20], anchor=FRONT);
 80```
 81
 82```openscad-3D
 83include <BOSL2/std.scad>
 84cube([50,40,20], anchor=FRONT, spin=45);
 85```
 86
 87```openscad-3D
 88include <BOSL2/std.scad>
 89cube([50,40,20], anchor=FRONT, spin=45, orient=UP+FWD+RIGHT);
 90```
 91
 92BOSL2 provides a `cuboid()` module that expands on `cube()`, by providing
 93rounding and chamfering of edges.  You can use it similarly to `cube()`,
 94except that `cuboid()` centers by default.
 95
 96You can round the edges with the `rounding=` argument:
 97
 98```openscad-3D
 99include <BOSL2/std.scad>
100cuboid([100,80,60], rounding=20);
101```
102
103Similarly, you can chamfer the edges with the `chamfer=` argument:
104
105```openscad-3D
106include <BOSL2/std.scad>
107cuboid([100,80,60], chamfer=10);
108```
109
110You can round only some edges, by using the `edges=` arguments.  It can be
111given a few types of arguments. If you gave it a vector pointed at a face,
112it will only round the edges surrounding that face:
113
114```openscad-3D
115include <BOSL2/std.scad>
116cuboid([100,80,60], rounding=20, edges=TOP);
117```
118
119```openscad-3D
120include <BOSL2/std.scad>
121cuboid([100,80,60], rounding=20, edges=RIGHT);
122```
123
124If you give `edges=` a vector pointing at a corner, it will round all edges
125that meet at that corner:
126
127```openscad-3D
128include <BOSL2/std.scad>
129cuboid([100,80,60], rounding=20, edges=RIGHT+FRONT+TOP);
130```
131
132```openscad-3D
133include <BOSL2/std.scad>
134cuboid([100,80,60], rounding=20, edges=LEFT+FRONT+TOP);
135```
136
137If you give `edges=` a vector pointing at an edge, it will round only that edge:
138
139```openscad-3D
140include <BOSL2/std.scad>
141cuboid([100,80,60], rounding=10, edges=FRONT+TOP);
142```
143
144```openscad-3D
145include <BOSL2/std.scad>
146cuboid([100,80,60], rounding=10, edges=RIGHT+FRONT);
147```
148
149If you give the string "X", "Y", or "Z", then all edges aligned with the specified
150axis will be rounded:
151
152```openscad-3D
153include <BOSL2/std.scad>
154cuboid([100,80,60], rounding=10, edges="X");
155```
156
157```openscad-3D
158include <BOSL2/std.scad>
159cuboid([100,80,60], rounding=10, edges="Y");
160```
161
162```openscad-3D
163include <BOSL2/std.scad>
164cuboid([100,80,60], rounding=10, edges="Z");
165```
166
167If you give a list of edge specs, then all edges referenced in the list will
168be rounded:
169
170```openscad-3D
171include <BOSL2/std.scad>
172cuboid([100,80,60], rounding=10, edges=[TOP,"Z",BOTTOM+RIGHT]);
173```
174
175The default value for `edges=` is `EDGES_ALL`, which is all edges.  You can also
176give an `except_edges=` argument that specifies edges to NOT round:
177
178```openscad-3D
179include <BOSL2/std.scad>
180cuboid([100,80,60], rounding=10, except_edges=BOTTOM+RIGHT);
181```
182
183You can give the `except_edges=` argument any type of argument that you can
184give to `edges=`:
185
186```openscad-3D
187include <BOSL2/std.scad>
188cuboid([100,80,60], rounding=10, except_edges=[BOTTOM,"Z",TOP+RIGHT]);
189```
190
191You can give both `edges=` and `except_edges=`, to simplify edge specs:
192
193```openscad-3D
194include <BOSL2/std.scad>
195cuboid([100,80,60], rounding=10, edges=[TOP,FRONT], except_edges=TOP+FRONT);
196```
197
198You can specify what edges to chamfer similarly:
199
200```openscad-3D
201include <BOSL2/std.scad>
202cuboid([100,80,60], chamfer=10, edges=[TOP,FRONT], except_edges=TOP+FRONT);
203```
204
205
206### 3D Cylinder
207BOSL2 overrides the built-in `cylinder()` module.  It still can be used as you
208expect from the built-in:
209
210```openscad-3D
211include <BOSL2/std.scad>
212cylinder(r=50,h=50);
213```
214
215```openscad-3D
216include <BOSL2/std.scad>
217cylinder(r=50,h=50,center=true);
218```
219
220```openscad-3D
221include <BOSL2/std.scad>
222cylinder(d=100,h=50,center=true);
223```
224
225```openscad-3D
226include <BOSL2/std.scad>
227cylinder(d1=100,d2=80,h=50,center=true);
228```
229
230You can also anchor, spin, orient, and attach like the `cuboid()` module:
231
232```openscad-3D
233include <BOSL2/std.scad>
234cylinder(r=50, h=50, anchor=TOP+FRONT);
235```
236
237```openscad-3D
238include <BOSL2/std.scad>
239cylinder(r=50, h=50, anchor=BOTTOM+LEFT);
240```
241
242```openscad-3D
243include <BOSL2/std.scad>
244cylinder(r=50, h=50, anchor=BOTTOM+LEFT, spin=30);
245```
246
247```openscad-3D
248include <BOSL2/std.scad>
249cylinder(r=50, h=50, anchor=BOTTOM, orient=UP+BACK+RIGHT);
250```
251
252
253BOSL2 provides a `cyl()` module that expands on `cylinder()`, by providing
254rounding and chamfering of edges.  You can use it similarly to `cylinder()`,
255except that `cyl()` centers the cylinder by default.
256
257```openscad-3D
258include <BOSL2/std.scad>
259cyl(r=60, l=100);
260```
261
262```openscad-3D
263include <BOSL2/std.scad>
264cyl(d=100, l=100);
265```
266
267```openscad-3D
268include <BOSL2/std.scad>
269cyl(d=100, l=100, anchor=TOP);
270```
271
272You can round the edges with the `rounding=` argument:
273
274```openscad-3D
275include <BOSL2/std.scad>
276cyl(d=100, l=100, rounding=20);
277```
278
279Similarly, you can chamfer the edges with the `chamfer=` argument:
280
281```openscad-3D
282include <BOSL2/std.scad>
283cyl(d=100, l=100, chamfer=10);
284```
285
286You can specify rounding and chamfering for each end individually:
287
288```openscad-3D
289include <BOSL2/std.scad>
290cyl(d=100, l=100, rounding1=20);
291```
292
293```openscad-3D
294include <BOSL2/std.scad>
295cyl(d=100, l=100, rounding2=20);
296```
297
298```openscad-3D
299include <BOSL2/std.scad>
300cyl(d=100, l=100, chamfer1=10);
301```
302
303```openscad-3D
304include <BOSL2/std.scad>
305cyl(d=100, l=100, chamfer2=10);
306```
307
308You can even mix and match rounding and chamfering:
309
310```openscad-3D
311include <BOSL2/std.scad>
312cyl(d=100, l=100, rounding1=20, chamfer2=10);
313```
314
315```openscad-3D
316include <BOSL2/std.scad>
317cyl(d=100, l=100, rounding2=20, chamfer1=10);
318```
319
320
321### 3D Spheres
322BOSL2 overrides the built-in `sphere()` module.  It still can be used as you
323expect from the built-in:
324
325```openscad-3D
326include <BOSL2/std.scad>
327sphere(r=50);
328```
329
330```openscad-3D
331include <BOSL2/std.scad>
332sphere(d=100);
333```
334
335You can anchor, spin, and orient `sphere()`s, much like you can with `cylinder()`
336and `cube()`:
337
338```openscad-3D
339include <BOSL2/std.scad>
340sphere(d=100, anchor=FRONT);
341```
342
343```openscad-3D
344include <BOSL2/std.scad>
345sphere(d=100, anchor=FRONT, spin=30);
346```
347
348```openscad-3D
349include <BOSL2/std.scad>
350sphere(d=100, anchor=BOTTOM, orient=RIGHT+TOP);
351```
352
353BOSL2 also provides `spheroid()`, which enhances `sphere()` with a few features
354like the `circum=` and `style=` arguments:
355
356You can use the `circum=true` argument to force the sphere to circumscribe the
357ideal sphere, as opposed to the default inscribing:
358
359```openscad-3D
360include <BOSL2/std.scad>
361spheroid(d=100, circum=true);
362```
363
364The `style=` argument can choose the way that the sphere will be constructed:
365The "orig" style matches the `sphere()` built-in's construction. 
366
367```openscad-3D
368include <BOSL2/std.scad>
369spheroid(d=100, style="orig", $fn=20);
370```
371
372The "aligned" style will ensure that there is a vertex at each axis extrema,
373so long as `$fn` is a multiple of 4.
374
375```openscad-3D
376include <BOSL2/std.scad>
377spheroid(d=100, style="aligned", $fn=20);
378```
379
380The "stagger" style will stagger the triangulation of the vertical rows:
381
382```openscad-3D
383include <BOSL2/std.scad>
384spheroid(d=100, style="stagger", $fn=20);
385```
386
387The "icosa" style will make for roughly equal-sized triangles for the entire
388sphere surface, based on subdividing an icosahedron.  This style will round the
389effective `$fn` to a multiple of 5 when constructing the spheroid:
390
391```openscad-3D
392include <BOSL2/std.scad>
393spheroid(d=100, style="icosa", $fn=20);
394```
395
396The "octa" style will also make for roughly equal-sized triangles for the entire
397sphere surface, but based on subdividing an octahedron.  This is useful in that it
398guarantees vertices at the axis extrema.  This style will round the effective `$fn`
399to a multiple of 4 when constructing the spheroid:
400
401```openscad-3D
402include <BOSL2/std.scad>
403spheroid(d=100, style="octa", $fn=20);
404```
405