Enabled region use with grid2d()

distributors.scad

@@ -400,18 +400,18 @@ module zdistribute(spacing=10, sizes=undef, l=undef)
 //   Makes a square or hexagonal grid of copies of children.
 //
 // Usage:
-//   grid2d(spacing, size, [stagger], [scale], [in_poly]) ...
+//   grid2d(spacing, size, [stagger], [scale], [inside]) ...
-//   grid2d(n, size, [stagger], [scale], [in_poly]) ...
+//   grid2d(n, size, [stagger], [scale], [inside]) ...
-//   grid2d(spacing, n, [stagger], [scale], [in_poly]) ...
+//   grid2d(spacing, n, [stagger], [scale], [inside]) ...
-//   grid2d(spacing, in_poly, [stagger], [scale]) ...
+//   grid2d(spacing, inside, [stagger], [scale]) ...
-//   grid2d(n, in_poly, [stagger], [scale]) ...
+//   grid2d(n, inside, [stagger], [scale]) ...
 //
 // Arguments:
 //   size = The [X,Y] size to spread the copies over.
 //   spacing = Distance between copies in [X,Y] or scalar distance.
 //   n = How many columns and rows of copies to make.  Can be given as `[COLS,ROWS]`, or just as a scalar that specifies both.  If staggered, count both staggered and unstaggered columns and rows.  Default: 2 (3 if staggered)
 //   stagger = If true, make a staggered (hexagonal) grid.  If false, make square grid.  If `"alt"`, makes alternate staggered pattern.  Default: false
-//   in_poly = If given a list of polygon points, only creates copies whose center would be inside the polygon.  Polygon can be concave and/or self crossing.
+//   inside = If given a list of polygon points, or a region, only creates copies whose center would be inside the polygon or region.  Polygon can be concave and/or self crossing.
 //
 // Side Effects:
 //   `$pos` is set to the relative centerpoint of each child copy, and can be used to modify each child individually.
@@ -427,7 +427,7 @@ module zdistribute(spacing=10, sizes=undef, l=undef)
 //
 // Example:
 //   poly = [[-25,-25], [25,25], [-25,25], [25,-25]];
-//   grid2d(spacing=5, stagger=true, in_poly=poly)
+//   grid2d(spacing=5, stagger=true, inside=poly)
 //      zrot(180/6) cylinder(d=5, h=1, $fn=6);
 //   %polygon(poly);
 //
@@ -440,7 +440,7 @@ module zdistribute(spacing=10, sizes=undef, l=undef)
 //   // Makes a grid of hexagon pillars whose tops are all
 //   // angled to reflect light at [0,0,50], if they were shiny.
 //   hexregion = circle(r=50.01,$fn=6);
-//   grid2d(spacing=10, stagger=true, in_poly=hexregion) union() {
+//   grid2d(spacing=10, stagger=true, inside=hexregion) union() {
 //       // Note: The union() is needed or else $pos will be
 //       //   inexplicably unreadable.
 //       ref_v = (unit([0,0,50]-point3d($pos)) + UP)/2;
@@ -448,10 +448,13 @@ module zdistribute(spacing=10, sizes=undef, l=undef)
 //           zrot(180/6)
 //               cylinder(h=20, d=10/cos(180/6)+0.01, $fn=6);
 //   }
-module grid2d(spacing, n, size, stagger=false, in_poly=undef)
+module grid2d(spacing, n, size, stagger=false, inside=undef)
 {
 	assert(in_list(stagger, [false, true, "alt"]));
-	bounds = is_undef(in_poly)? undef : pointlist_bounds(in_poly);
+	bounds = is_undef(inside)? undef :
+		is_path(inside)? pointlist_bounds(inside) :
+		assert(is_region(inside))
+		pointlist_bounds(flatten(inside));
 	size = is_num(size)? [size, size] :
 		is_vector(size)? assert(len(size)==2) size :
 		bounds!=undef? [
@@ -477,7 +480,11 @@ module grid2d(spacing, n, size, stagger=false, in_poly=undef)
 		for (row = [0:1:n.y-1]) {
 			for (col = [0:1:n.x-1]) {
 				pos = vmul([col,row],spacing) - offset;
-				if (is_undef(in_poly) || point_in_polygon(pos, in_poly)>=0) {
+				if (
+					is_undef(inside) ||
+					(is_path(inside) && point_in_polygon(pos, inside)>=0) ||
+					(is_region(inside) && point_in_region(pos, inside)>=0)
+				) {
 					$col = col;
 					$row = row;
 					$pos = pos;
@@ -496,7 +503,11 @@ module grid2d(spacing, n, size, stagger=false, in_poly=undef)
 				for (col = [0:1:rowcols-1]) {
 					rowdx = (row%2 != staggermod)? spacing.x : 0;
 					pos = vmul([2*col,row],spacing) + [rowdx,0] - offset;
-					if (is_undef(in_poly) || point_in_polygon(pos, in_poly)>=0) {
+					if (
+						is_undef(inside) ||
+						(is_path(inside) && point_in_polygon(pos, inside)>=0) ||
+						(is_region(inside) && point_in_region(pos, inside)>=0)
+					) {
 						$col = col * 2 + ((row%2!=staggermod)? 1 : 0);
 						$row = row;
 						$pos = pos;

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

version.scad

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