mirror of
https://github.com/BelfrySCAD/BOSL2.git
synced 2025-01-01 09:49:45 +00:00
351 lines
9.3 KiB
Markdown
351 lines
9.3 KiB
Markdown
# BOSL2 Transforms Tutorial
|
|
|
|
<!-- TOC -->
|
|
|
|
## 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+
|
|
`ALLNEG` | `[-1,-1,-1]` | Towards X-Y-Z-
|
|
`ALLPOS` | `[ 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
|
|
|
|
|