Added Basics tutorial

This commit is contained in:
Revar Desmera 2020-03-24 23:16:16 -07:00
parent b0b436eb63
commit 7640627300
4 changed files with 569 additions and 3 deletions

View file

@ -15,7 +15,7 @@ done
if [[ "$FILES" != "" ]]; then
PREVIEW_LIBS="$FILES"
else
PREVIEW_LIBS="FractalTree"
PREVIEW_LIBS="Basics FractalTree"
fi
dir="$(basename $PWD)"
@ -30,7 +30,7 @@ rm -f tmp_*.scad
for base in $PREVIEW_LIBS; do
base="$(basename $base .md)"
mkdir -p images/tutorials
rm -f images/tutorials/*.png images/tutorials/*.gif
rm -f images/tutorials/$base_*.png images/tutorials/*.gif
echo "$base.md"
../scripts/tutorial_gen.py ../tutorials/$base.md -o Tutorial-$base.md $FORCED -I images/tutorials/ || exit 1
if [ "$DISPMD" != "" ]; then

213
tutorials/Basic_Shapes.md Normal file
View file

@ -0,0 +1,213 @@
# Basic Shapes Tutorial
## Enhanced Primitives
There are 5 built-in primitive shapes that OpenSCAD provides. The BOSL2
library extends these shapes so that they support more features, and more
ways to simply reorient them.
### Enhanced 2D Square
You can still use `square()` in the familiar ways that OpenSCAD provides:
```openscad-example
square(100, center=false);
```
```openscad-example
square(100, center=true);
```
```openscad-example
square([40,50], center=true);
```
BOSL2's enhanced `square()` also allows you to round the corners:
```openscad-example
square([40,50], center=true, rounding=10);
```
It also supports chamfers:
```openscad-example
square([40,50], center=true, chamfer=10);
```
It even allows you to specify *which* corners get rounded or chamferred:
```openscad-example
square([40,50], center=true, rounding=[0,5,10,15]);
```
```openscad-example
square([40,50], center=true, chamfer=[0,5,10,15]);
```
It will even let you mix rounding and chamferring:
```openscad-example
square([40,50], center=true, rounding=[5,0,10,0], chamfer=[0,5,0,15]);
```
### Anchors and Spin
The `anchor=` argument is an alternative to `center=`, which allows more
alignment options. It takes a vector as a value, pointing roughly towards
the side or corner you want to align to the origin. For example, to align
the center of the back edge to the origin, set the anchor to `[0,1]`:
```openscad-example
square([40,50], anchor=[0,1]);
```
To align the front right corner to the origin:
```openscad-example
square([40,50], anchor=[1,-1]);
```
To center:
```openscad-example
square([40,50], anchor=[0,0]);
```
To make it clearer when giving vectors, there are several standard vector constants defined:
- `LEFT` is a vector towards X-. (`[-1,0,0]`)
- `RIGHT` is a vector towards X+. (`[1,0,0]`)
- `FRONT`, `FORWARD` or `FWD` is a vector towards Y-. (`[0,-1,0]`)
- `BACK` is a vector towards Y+. (`[0,1,0]`)
- `BOTTOM`, `BOT`, `BTM` or `DOWN` is a vector towards Z-. (`[0,0,-1]`) Not used with 2D anchors.
- `TOP`, or `UP` is a vector towards Z+. (`[0,0,1]`) Not used with 2D anchors.
- `CENTER` or `CTR` is a centered vector. (`[0,0,0]`)
Note that even though these are 3D vectors, you can use most of them, (except `UP`/`DOWN`, of course) for anchors in 2D shapes:
```openscad-example
square([40,50], anchor=BACK);
```
```openscad-example
square([40,50], anchor=CENTER);
```
You can add them together to point to corners:
```openscad-example
square([40,50], anchor=FRONT+RIGHT);
```
Finally, the `spin` argument can rotate the shape by a given number of degrees clockwise:
```openscad-example
square([40,50], anchor=CENTER, spin=30);
```
Anchoring or centering is performed before the spin:
```openscad-example
square([40,50], anchor=BACK, spin=30);
```
### Enhanced 2D Circle
The enhanced `circle()` primitive can be used like the OpenSCAD built-in:
```openscad-example
circle(r=50);
```
```openscad-example
circle(d=100);
```
```openscad-example
circle(d=100, $fn=8);
```
Since a circle in OpenSCAD can only be approximated by a regular polygon with
a number of straight sides, this can lead to size and shape inaccuracies. To
counter this, the `realign` and `circum` arguments are also provided.
The `realign` argument, if set `true`, rotates the circle by half the angle between sides:
```openscad-example
circle(d=100, $fn=8, realign=true);
```
The `circum` argument, if true, makes the polygon describing the circle circumscribe the ideal circle instead of inscribing it.
Inscribing the ideal circle:
```openscad-example
difference() {
circle(d=100, $fn=360);
circle(d=100, $fn=6);
}
```
Circumscribing the ideal circle:
```openscad-example
difference() {
circle(d=100, $fn=6, circum=true);
circle(d=100, $fn=360);
}
```
You can also use anchor and spin on enhanced `circle()`:
```openscad-example
circle(r=50, anchor=BACK);
```
```openscad-example
circle(r=50, anchor=FRONT+RIGHT);
```
Using spin on a circle may not make initial sense, until you remember that anchoring is performed before spin:
```openscad-example
circle(r=50, anchor=FRONT, spin=30);
```
### Echanced 3D Cube
You can use enhanced `cube()` like the normal OpenSCAD built-in:
```openscad-example
cube(100);
```
```openscad-example
cube(100, center=true);
```
```openscad-example
cube([50,40,20], center=true);
```
You can use `anchor` similarly to `square()`, except you can anchor vertically
too, in 3D, allowing anchoring to faces, edges, and corners:
```openscad-example
cube([50,40,20], anchor=BOTTOM);
```
```openscad-example
cube([50,40,20], anchor=TOP+BACK);
```
```openscad-example
cube([50,40,20], anchor=TOP+FRONT+LEFT);
```
You can use `spin` as well, to rotate around the Z axis:
```openscad-example
cube([50,40,20], anchor=FRONT, spin=30);
```
3D objects also gain the ability to use an extra trick with `spin`;
if you pass a list of `[X,Y,Z]` rotation angles to `spin`, it will
rotate by the three given axis angles, similar to using `rotate()`:
```openscad-example
cube([50,40,20], anchor=FRONT, spin=[15,0,30]);
```
3D objects also can be given an `orient` argument that is given as a vector,
pointing towards where the top of the shape should be rotated towards.
```openscad-example
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-example
cube([50,40,20], anchor=FRONT, spin=45, orient=UP+FWD+RIGHT);
```
### Echanced 3D Cylinder
You can use the enhanced `cylinder()` as normal for OpenSCAD:
```openscad-example
cylinder(r=50,h=50);
```
```openscad-example
cylinder(r=50,h=50,center=true);
```
```openscad-example
cylinder(d=100,h=50,center=true);
```
```openscad-example
cylinder(d1=100,d2=80,h=50,center=true);
```

353
tutorials/Basics.md Normal file
View file

@ -0,0 +1,353 @@
# BOSL2 Basics Tutorial
<!-- TOC -->
## Transforms
### Translation
The `translate()` command is very simple:
```openscad
#sphere(d=20);
translate([0,0,30]) sphere(d=20);
```
But at a glance, or when the formula to calculate the move is complex, it can be difficult to see
just what axis is being moved along, and in which direction. It's also a bit verbose for such a
frequently used command. For these reasons, BOSL2 provides you with shortcuts for each direction.
These shortcuts are `up()`, `down()`, `fwd()`, `back()`, `left()`, and `right()`:
```openscad
#sphere(d=20);
up(30) sphere(d=20);
```
```openscad
#sphere(d=20);
down(30) sphere(d=20);
```
```openscad
#sphere(d=20);
fwd(30) sphere(d=20);
```
```openscad
#sphere(d=20);
back(30) sphere(d=20);
```
```openscad
#sphere(d=20);
left(30) sphere(d=20);
```
```openscad
#sphere(d=20);
right(30) sphere(d=20);
```
There is also a more generic `move()` command that can work just like `translate()`, or you can
specify the motion on each axis more clearly:
```openscad
#sphere(d=20);
move([30,-10]) sphere(d=20);
```
```openscad
#sphere(d=20);
move(x=30,y=10) sphere(d=20);
```
### Scaling
The `scale()` command is also fairly simple:
```openscad
scale(2) cube(10, center=true);
```
```openscad
scale([1,2,3]) cube(10, center=true);
```
If you want to only change the scaling on one axis, though, BOSL2 provides clearer
commands to do just that; `xscale()`, `yscale()`, and `zscale()`:
```openscad
xscale(2) cube(10, center=true);
```
```openscad
yscale(2) cube(10, center=true);
```
```openscad
zscale(2) cube(10, center=true);
```
### Rotation
The `rotate()` command is fairly straightforward:
```openscad
rotate([0,30,0]) cube(20, center=true);
```
It is also a bit verbose, and can, at a glance, be difficult to tell just how it is rotating.
BOSL2 provides shortcuts for rotating around each axis, for clarity; `xrot()`, `yrot()`, and `zrot()`:
```openscad
xrot(30) cube(20, center=true);
```
```openscad
yrot(30) cube(20, center=true);
```
```openscad
zrot(30) cube(20, center=true);
```
The `rot()` command is a more generic rotation command, and shorter to type than `rotate()`:
```openscad
rot([0,30,15]) cube(20, center=true);
```
All of the rotation shortcuts can take a `cp=` argument, that lets you specify a
centerpoint to rotate around:
```openscad
cp = [0,0,40];
color("blue") move(cp) sphere(d=3);
#cube(20, center=true);
xrot(45, cp=cp) cube(20, center=true);
```
```openscad
cp = [0,0,40];
color("blue") move(cp) sphere(d=3);
#cube(20, center=true);
yrot(45, cp=cp) cube(20, center=true);
```
```openscad
cp = [0,40,0];
color("blue") move(cp) sphere(d=3);
#cube(20, center=true);
zrot(45, cp=cp) cube(20, center=true);
```
You can also do a new trick with it. You can rotate from pointing in one direction, towards another.
You give these directions using vectors:
```openscad
#cylinder(d=10, h=50);
rot(from=[0,0,1], to=[1,0,1]) cylinder(d=10, h=50);
```
There are several direction vectors constants and aliases you can use for clarity:
Constant | Value | Direction
------------------------------ | ------------ | --------------
`CENTER`, `CTR` | `[ 0, 0, 0]` | Centered
`LEFT` | `[-1, 0, 0]` | Towards X-
`RIGHT` | `[ 1, 0, 0]` | Towards X+
`FWD`, `FORWARD`, `FRONT` | `[ 0,-1, 0]` | Towards Y-
`BACK` | `[ 0, 1, 0]` | Towards Y+
`DOWN`, `BOTTOM`, `BOT`, `BTM` | `[ 0, 0,-1]` | Towards Z-
`UP`, `TOP` | `[ 0, 0, 1]` | Towards Z+
`ALLPOS` | `[ 1, 1, 1]` | Towards X+Y+Z+
`ALLNEG` | `[-1,-1,-1]` | Towards X+Y+Z+
This lets you rewrite the above vector rotation more clearly as:
```openscad
#cylinder(d=10, h=50);
rot(from=UP, to=UP+RIGHT) cylinder(d=10, h=50);
```
### Mirroring
The standard `mirror()` command works like this:
```openscad
#yrot(60) cylinder(h=50, d1=20, d2=10);
mirror([1,0,0]) yrot(-60) cylinder(h=50, d1=20, d2=10);
```
BOSL2 provides shortcuts for mirroring across the standard axes; `xflip()`, `yflip()`, and `zflip()`:
```openscad
#yrot(60) cylinder(h=50, d1=20, d2=10);
xflip() yrot(-60) cylinder(h=50, d1=20, d2=10);
```
```openscad
#xrot(60) cylinder(h=50, d1=20, d2=10);
yflip() xrot(60) cylinder(h=50, d1=20, d2=10);
```
```openscad
#cylinder(h=50, d1=20, d2=10);
zflip() cylinder(h=50, d1=20, d2=10);
```
All of the flip commands can offset where the mirroring is performed:
```openscad
#zrot(30) cube(20, center=true);
xflip(x=-20) zrot(30) cube(20, center=true);
color("blue",0.25) left(20) cube([0.1,50,50], center=true);
```
```openscad
#zrot(30) cube(20, center=true);
yflip(y=20) zrot(30) cube(20, center=true);
color("blue",0.25) back(20) cube([40,0.1,40], center=true);
```
```openscad
#xrot(30) cube(20, center=true);
zflip(z=-20) xrot(30) cube(20, center=true);
color("blue",0.25) down(20) cube([40,40,0.1], center=true);
```
### Skewing
One transform that OpenSCAD does not perform natively is skewing.
BOSL2 provides the `skew()` command for that. You give it multipliers
for the skews you want to perform. The arguments used all start with `s`,
followed by the axis you want to skew along, followed by the axis that
the skewing will increase along. For example, to skew along the X axis as
you get farther along the Y axis, use the `sxy=` argument. If you give it
a multiplier of `0.5`, then for each unit further along the Y axis you get,
you will add `0.5` units of skew to the X axis. Giving a negative multiplier
reverses the direction it skews:
```openscad
skew(sxy=0.5) cube(10,center=false);
```
```openscad
skew(sxz=-0.5) cube(10,center=false);
```
```openscad
skew(syx=-0.5) cube(10,center=false);
```
```openscad
skew(syz=0.5) cube(10,center=false);
```
```openscad
skew(szx=-0.5) cube(10,center=false);
```
```openscad
skew(szy=0.5) cube(10,center=false);
```
## Distributors
Distributors are modules that are useful for placing multiple copies of a child
across a line, area, volume, or ring. Many transforms also distributive variation.
Transforms | Related Distributors
----------------------- | ---------------------
`left()`, `right()` | `xcopies()`
`fwd()`, `back()` | `ycopies()`
`down()`, `up()` | `zcopies()`
`move()`, `translate()` | `move_copies()`, `line_of()`, `grid2d()`, `grid3d()`
`xrot()` | `xrot_copies()`
`yrot()` | `yrot_copies()`
`zrot()` | `zrot_copies()`
`rot()`, `rotate()` | `rot_copies()`, `arc_of()`
### Transform Distributors
Using `xcopies()`, you can make a line of evenly spaced copies of a shape
centered along the X axis. To make a line of 5 spheres, spaced every 20
units along the X axis, do:
```openscad
xcopies(20, n=5) sphere(d=10);
```
Note that the first expected argument to `xcopies()` is the spacing argument,
so you do not need to supply the `spacing=` argument name.
Similarly, `ycopies()` makes a line of evenly spaced copies centered along the
Y axis. To make a line of 5 spheres, spaced every 20 units along the Y
axis, do:
```openscad
ycopies(20, n=5) sphere(d=10);
```
And, `zcopies()` makes a line of evenly spaced copies centered along the Z axis.
To make a line of 5 spheres, spaced every 20 units along the Z axis, do:
```openscad
zcopies(20, n=5) sphere(d=10);
```
If you don't give the `n=` argument to `xcopies()`, `ycopies()` or `zcopies()`,
then it defaults to 2 (two) copies:
```openscad
xcopies(20) sphere(d=10);
```
```openscad
ycopies(20) sphere(d=10);
```
```openscad
zcopies(20) sphere(d=10);
```
If you don't know the spacing you want, but instead know how long a line you want
the copies distributed over, you can use the `l=` argument instead of the `spacing=`
argument:
```openscad
xcopies(l=100, n=5) sphere(d=10);
```
```openscad
ycopies(l=100, n=5) sphere(d=10);
```
```openscad
zcopies(l=100, n=5) sphere(d=10);
```
If you don't want the line of copies centered on the origin, you can give a starting
point, `sp=`, and the line of copies will start there. For `xcopies()`, the line of
copies will extend to the right of the starting point.
```openscad
xcopies(20, n=5, sp=[0,0,0]) sphere(d=10);
```
For `ycopies()`, the line of copies will extend to the back of the starting point.
```openscad
ycopies(20, n=5, sp=[0,0,0]) sphere(d=10);
```
For `zcopies()`, the line of copies will extend upwards from the starting point.
```openscad
zcopies(20, n=5, sp=[0,0,0]) sphere(d=10);
```
If you need to distribute copies along an arbitrary line, you can use the
`line_of()` command. You can give both the direction vector and the spacing
of the line of copies with the `spacing=` argument:
```openscad
line_of(spacing=(BACK+RIGHT)*20, n=5) sphere(d=10);
```
With the `p1=` argument, you can specify the starting point of the line:
```openscad
line_of(spacing=(BACK+RIGHT)*20, n=5, p1=[0,0,0]) sphere(d=10);
```
IF you give both `p1=` and `p2=`, you can nail down both the start and endpoints
of the line of copies:
```openscad
line_of(p1=[0,100,0], p2=[100,0,0], n=4)
sphere(d=10);
```
### Rotational Distributors
You can make six copies of a cone, rotated around a center:
```openscad
zrot_copies(n=6) yrot(90) cylinder(h=50,d1=0,d2=20);
```
To Be Completed

View file

@ -8,7 +8,7 @@
//////////////////////////////////////////////////////////////////////
BOSL_VERSION = [2,0,224];
BOSL_VERSION = [2,0,225];
// Section: BOSL Library Version Functions