Enabled region use with grid2d()

tutorials/Distributors.md

@@ -26,7 +26,7 @@ Transforms              | Related 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
+```openscad-2D
 xcopies(20, n=5) sphere(d=10);
 ```
 Note that the first expected argument to `xcopies()` is the spacing argument,
@@ -35,7 +35,7 @@ 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
+```openscad-2D
 ycopies(20, n=5) sphere(d=10);
 ```
 
@@ -47,11 +47,11 @@ 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
+```openscad-2D
 xcopies(20) sphere(d=10);
 ```
 
-```openscad
+```openscad-2D
 ycopies(20) sphere(d=10);
 ```
 
@@ -62,11 +62,11 @@ 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
+```openscad-2D
 xcopies(l=100, n=5) sphere(d=10);
 ```
 
-```openscad
+```openscad-2D
 ycopies(l=100, n=5) sphere(d=10);
 ```
 
@@ -77,12 +77,12 @@ 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
+```openscad-2D
 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
+```openscad-2D
 ycopies(20, n=5, sp=[0,0,0]) sphere(d=10);
 ```
 
@@ -105,12 +105,76 @@ 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
+```openscad-2D
 line_of(p1=[0,100,0], p2=[100,0,0], n=4)
     sphere(d=10);
 ```
 
-You can also spread copies across a 2D area using the `grid2d()`
+You can also spread copies across a 2D area using the `grid2d()` command:
+```openscad-2D
+grid2d(20, n=6) sphere(d=10);
+```
+
+The spacing can be separately specified for both the X and Y axes, as can the
+count of rows and columns:
+```openscad-2D
+grid2d([20,30], n=[6,4]) sphere(d=10);
+```
+
+Another neat trick of `grid2d()`, is that you can stagger the output:
+```openscad-2D
+grid2d(20, n=[12,6], stagger=true) sphere(d=10);
+```
+
+You can get the alternate stagger pattern if you set `stagger="alt"`:
+```openscad-2D
+grid2d(20, n=[12,6], stagger="alt") sphere(d=10);
+```
+
+By default, if you give a scalar for the spacing value, staggering will give
+you a hexagonal grid, with the spacing being the distance from an item to all
+six of the surrounding items.  If you give the spacing as a 2-item vector,
+then that will force the X and Y spacings between columns and rows instead.
+```openscad-2D
+grid2d([20,20], n=[6,6], stagger=true) sphere(d=10);
+```
+
+You can alternately specify a grid using size and spacing:
+```openscad-2D
+grid2d(20, size=100) sphere(d=10);
+```
+
+```openscad-2D
+grid2d(20, size=[100,80]) sphere(d=10);
+```
+
+```openscad-2D
+grid2d(20, size=[100,80], stagger=true) sphere(d=10);
+```
+
+You can also make grids by spacifying size and column/row count:
+```openscad-2D
+grid2d(n=5, size=100) sphere(d=10);
+```
+
+```openscad-2D
+grid2d(n=[4,5], size=100) sphere(d=10);
+```
+
+```openscad-2D
+grid2d(n=[4,5], size=[100,80]) sphere(d=10);
+```
+
+Finally, the `grid2d()` command will let you give a polygon or region shape to
+fill with items.  Only the items in the grid whose center would be inside the
+polygon or region will be created.  To fill a star shape with items, you
+can do something like:
+```openscad
+poly = [for (i=[0:11]) polar_to_xy(50*(i%2+1), i*360/12-90)];
+grid2d(5, stagger=true, inside=poly) {
+    cylinder(d=4,h=10,spin=90,$fn=6);
+}
+```
 
 
 ### Rotational Distributors