# Basic Shapes Tutorial ## Primitives There are 3 built-in 3D primitive shapes that OpenSCAD provides: `cube()`, `cylinder()`, and `sphere()`. The BOSL2 library extends and provides alternative to these shapes so that they support more features, and more ways to simply reorient them. ### 3D Cubes BOSL2 overrides the built-in `cube()` module. It still can be used as you expect from the built-in: ```openscad-3D include cube(100); ``` ```openscad-3D include cube(100, center=true); ``` ```openscad-3D include cube([50,40,20], center=true); ``` It is also enhanced to allow you to anchor, spin, orient, and attach it. You can use `anchor=` similarly to how you use it with `rect()` or `oval()`, except you can also anchor vertically in 3D, allowing anchoring to faces, edges, and corners: ```openscad-3D include cube([50,40,20], anchor=BOTTOM); ``` ```openscad-3D include cube([50,40,20], anchor=TOP+BACK); ``` ```openscad-3D include cube([50,40,20], anchor=TOP+FRONT+LEFT); ``` You can use `spin=` to rotate around the Z axis **after** anchoring: ```openscad-3D include cube([50,40,20], anchor=FRONT, spin=30); ``` 3D objects also can be given an `orient=` argument as a vector, pointing to where the top of the shape should be rotated towards. ```openscad-3D include cube([50,40,20], orient=UP+BACK+RIGHT); ``` If you use `anchor=`, `spin=`, and `orient=` together, the anchor is performed first, then the spin, then the orient: ```openscad-3D include cube([50,40,20], anchor=FRONT); ``` ```openscad-3D include cube([50,40,20], anchor=FRONT, spin=45); ``` ```openscad-3D include cube([50,40,20], anchor=FRONT, spin=45, orient=UP+FWD+RIGHT); ``` BOSL2 provides a `cuboid()` module that expands on `cube()`, by providing rounding and chamfering of edges. You can use it similarly to `cube()`, except that `cuboid()` centers by default. You can round the edges with the `rounding=` argument: ```openscad-3D include cuboid([100,80,60], rounding=20); ``` Similarly, you can chamfer the edges with the `chamfer=` argument: ```openscad-3D include cuboid([100,80,60], chamfer=10); ``` You can round only some edges, by using the `edges=` arguments. It can be given a few types of arguments. If you gave it a vector pointed at a face, it will only round the edges surrounding that face: ```openscad-3D include cuboid([100,80,60], rounding=20, edges=TOP); ``` ```openscad-3D include cuboid([100,80,60], rounding=20, edges=RIGHT); ``` If you give `edges=` a vector pointing at a corner, it will round all edges that meet at that corner: ```openscad-3D include cuboid([100,80,60], rounding=20, edges=RIGHT+FRONT+TOP); ``` ```openscad-3D include cuboid([100,80,60], rounding=20, edges=LEFT+FRONT+TOP); ``` If you give `edges=` a vector pointing at an edge, it will round only that edge: ```openscad-3D include cuboid([100,80,60], rounding=10, edges=FRONT+TOP); ``` ```openscad-3D include cuboid([100,80,60], rounding=10, edges=RIGHT+FRONT); ``` If you give the string "X", "Y", or "Z", then all edges aligned with the specified axis will be rounded: ```openscad-3D include cuboid([100,80,60], rounding=10, edges="X"); ``` ```openscad-3D include cuboid([100,80,60], rounding=10, edges="Y"); ``` ```openscad-3D include cuboid([100,80,60], rounding=10, edges="Z"); ``` If you give a list of edge specs, then all edges referenced in the list will be rounded: ```openscad-3D include cuboid([100,80,60], rounding=10, edges=[TOP,"Z",BOTTOM+RIGHT]); ``` The default value for `edges=` is `EDGES_ALL`, which is all edges. You can also give an `except_edges=` argument that specifies edges to NOT round: ```openscad-3D include cuboid([100,80,60], rounding=10, except_edges=BOTTOM+RIGHT); ``` You can give the `except_edges=` argument any type of argument that you can give to `edges=`: ```openscad-3D include cuboid([100,80,60], rounding=10, except_edges=[BOTTOM,"Z",TOP+RIGHT]); ``` You can give both `edges=` and `except_edges=`, to simplify edge specs: ```openscad-3D include cuboid([100,80,60], rounding=10, edges=[TOP,FRONT], except_edges=TOP+FRONT); ``` You can specify what edges to chamfer similarly: ```openscad-3D include cuboid([100,80,60], chamfer=10, edges=[TOP,FRONT], except_edges=TOP+FRONT); ``` ### 3D Cylinder BOSL2 overrides the built-in `cylinder()` module. It still can be used as you expect from the built-in: ```openscad-3D include cylinder(r=50,h=50); ``` ```openscad-3D include cylinder(r=50,h=50,center=true); ``` ```openscad-3D include cylinder(d=100,h=50,center=true); ``` ```openscad-3D include cylinder(d1=100,d2=80,h=50,center=true); ``` You can also anchor, spin, orient, and attach like the `cuboid()` module: ```openscad-3D include cylinder(r=50, h=50, anchor=TOP+FRONT); ``` ```openscad-3D include cylinder(r=50, h=50, anchor=BOTTOM+LEFT); ``` ```openscad-3D include cylinder(r=50, h=50, anchor=BOTTOM+LEFT, spin=30); ``` ```openscad-3D include cylinder(r=50, h=50, anchor=BOTTOM, orient=UP+BACK+RIGHT); ``` BOSL2 provides a `cyl()` module that expands on `cylinder()`, by providing rounding and chamfering of edges. You can use it similarly to `cylinder()`, except that `cyl()` centers the cylinder by default. ```openscad-3D include cyl(r=60, l=100); ``` ```openscad-3D include cyl(d=100, l=100); ``` ```openscad-3D include cyl(d=100, l=100, anchor=TOP); ``` You can round the edges with the `rounding=` argument: ```openscad-3D include cyl(d=100, l=100, rounding=20); ``` Similarly, you can chamfer the edges with the `chamfer=` argument: ```openscad-3D include cyl(d=100, l=100, chamfer=10); ``` You can specify rounding and chamfering for each end individually: ```openscad-3D include cyl(d=100, l=100, rounding1=20); ``` ```openscad-3D include cyl(d=100, l=100, rounding2=20); ``` ```openscad-3D include cyl(d=100, l=100, chamfer1=10); ``` ```openscad-3D include cyl(d=100, l=100, chamfer2=10); ``` You can even mix and match rounding and chamfering: ```openscad-3D include cyl(d=100, l=100, rounding1=20, chamfer2=10); ``` ```openscad-3D include cyl(d=100, l=100, rounding2=20, chamfer1=10); ``` ### 3D Spheres BOSL2 overrides the built-in `sphere()` module. It still can be used as you expect from the built-in: ```openscad-3D include sphere(r=50); ``` ```openscad-3D include sphere(d=100); ``` You can anchor, spin, and orient `sphere()`s, much like you can with `cylinder()` and `cube()`: ```openscad-3D include sphere(d=100, anchor=FRONT); ``` ```openscad-3D include sphere(d=100, anchor=FRONT, spin=30); ``` ```openscad-3D include sphere(d=100, anchor=BOTTOM, orient=RIGHT+TOP); ``` BOSL2 also provides `spheroid()`, which enhances `sphere()` with a few features like the `circum=` and `style=` arguments: You can use the `circum=true` argument to force the sphere to circumscribe the ideal sphere, as opposed to the default inscribing: ```openscad-3D include spheroid(d=100, circum=true); ``` The `style=` argument can choose the way that the sphere will be constructed: The "orig" style matches the `sphere()` built-in's construction. ```openscad-3D include spheroid(d=100, style="orig", $fn=20); ``` The "aligned" style will ensure that there is a vertex at each axis extrema, so long as `$fn` is a multiple of 4. ```openscad-3D include spheroid(d=100, style="aligned", $fn=20); ``` The "stagger" style will stagger the triangulation of the vertical rows: ```openscad-3D include spheroid(d=100, style="stagger", $fn=20); ``` The "icosa" style will make for roughly equal-sized triangles for the entire sphere surface, based on subdividing an icosahedron. This style will round the effective `$fn` to a multiple of 5 when constructing the spheroid: ```openscad-3D include spheroid(d=100, style="icosa", $fn=20); ``` The "octa" style will also make for roughly equal-sized triangles for the entire sphere surface, but based on subdividing an octahedron. This is useful in that it guarantees vertices at the axis extrema. This style will round the effective `$fn` to a multiple of 4 when constructing the spheroid: ```openscad-3D include spheroid(d=100, style="octa", $fn=20); ```