add docs

README.md

@@ -382,6 +382,11 @@ These examples incubate dotSCAD and dotSCAD refactors these examples. See [examp
 **util/sort**(lt[, by, idx]) | use [`util/sorted`](https://openhome.cc/eGossip/OpenSCAD/lib3x-sorted.html) instead.
 **util/has**(lt, elem[, sorted]) | use [`util/contains`](https://openhome.cc/eGossip/OpenSCAD/lib3x-contains.html) instead.
 **util/bsearch**(sorted, target) | use [`util/binary_search`](https://openhome.cc/eGossip/OpenSCAD/lib3x-binary_search.html) instead.
+**maze/mz_square_cells**(rows, columns[, start, ...]) | use [maze/mz_square](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_square.html).
+**maze/mz_square_walls**(cells, rows, columns, cell_width, ...) | use [maze/mz_squarewalls](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_squarewalls.html) instead.
+**maze/mz_hex_walls**(cells, rows, columns, cell_radius, ...) | use [maze/mz_hexwalls](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_hexwalls.html) instead.
+**maze/mz_theta_cells**(rows, beginning_number[, start, seed]) | use [maze/mz_theta](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_theta.html) instead.
+
 
 ## Util
 
@@ -391,4 +396,14 @@ These examples incubate dotSCAD and dotSCAD refactors these examples. See [examp
 [**util/contains**(lt, elem)](https://openhome.cc/eGossip/OpenSCAD/lib3x-contains.html) | return `true` if `lt` contains `elem`.
 [**util/binary_search**(sorted, target[, lo, hi])](https://openhome.cc/eGossip/OpenSCAD/lib3x-binary_search.html) | search a value in a sorted list.
 
+
+## Maze
+
+ Signature | Description
+--|--
+[**maze/mz_square**([rows, columns, start, init_cells, x_wrapping, y_wrapping, seed])](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_square.html) | return cell data of a square maze.
+[**maze/mz_squarewalls**(cells, cell_width[, left_border, bottom_border])](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_squarewalls.html) | a helper for creating square wall data from maze cells.
+[**maze/mz_hexwalls**(cells, cell_radius[, left_border, bottom_border])](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_hexwalls.html) | a helper for creating hex wall data from maze cells.
+[**maze/mz_theta**(rings, beginning_number[, start, seed])](https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_theta.html) | return cell data of a theta maze.
+
 ----

docs/lib3x-mz_hexwalls.md

@@ -0,0 +1,33 @@
+# mz_hexwalls
+
+It's a helper for creating wall data from maze cells. You can transform wall points for creating different types of mazes.
+
+**Since:** 3.3
+
+## Parameters
+
+- `cells` : Maze cells.
+- `cell_radius` : The radius of a cell.
+- `left_border` : Default to `true`. Create the leftmost border of the maze.
+- `bottom_border` : Default to `true`. Create the bottommost border of the maze.
+
+## Examples
+    
+	use <maze/mz_square.scad>;
+	use <maze/mz_hexwalls.scad>;
+	use <polyline_join.scad>;
+
+	rows = 10;
+	columns = 12;
+	cell_width = 5;
+	wall_thickness = 2;
+
+	cells = mz_square(rows, columns);
+	walls = mz_hexwalls(cells, cell_width);
+
+	for(wall = walls) {
+		polyline_join(wall) 
+		    circle(wall_thickness, $fn = 24);
+	}
+	
+![mz_hexwalls](images/lib3x-mz_hexwalls-1.JPG)

docs/lib3x-mz_square.md

@@ -0,0 +1,61 @@
+# mz_square
+
+This function returns cell data of a square maze. The data is a 2-dimension list of cells. A cell has the data structure `[x, y, type]`. `x` and `y` are 0-based. `x` means the x-th column and `y` means y-th row for a cell. The value of `type` can be `0`, `1`, `2`, `3` or `4`. Setting them to constants is convenient.
+
+	NO_WALL = 0;          // the cell has no wall
+	TOP_WALL = 1;         // the cell has a top wall
+	RIGHT_WALL = 2;       // the cell has a right wall
+	TOP_RIGHT_WALL = 3;   // the cell has a top wall and a right wall
+	MASK = 4;             // the cell is masked.
+
+The cell data is seperated from views. You can use cell data to construct [different types of mazes](https://www.thingiverse.com/justinsdk/collections/maze-generator).
+
+**Since:** 3.3
+
+## Parameters
+
+- `rows` : The number of rows.
+- `columns` : The number of columns.
+- `start` : The start point to travel the maze. Default to `[0, 0]`.
+- `init_cells` : You can define your own initial cell data, a 2-dimension list of `[x, y, type, visited]`. `visited` means the cell is visited or not. A visited cell won't be visited when traveling the maze. If you don't provide `init_cells`, `mz_square` will generate one automatically. If you provide `init_cells`, `rows` and `columns` will be ignored.
+- `x_wrapping` : Default to `false`. If you want to wrap the maze in the x direction, set it to `true`. The last column of cells will be adjacent to the first column of cells.
+- `y_wrapping` : Default to `false`. If you want to wrap the maze in the y direction, set it to `true`. The last row of cells will be adjacent to the first row of cells.
+- `seed` : The maze is traveling randomly. Use `seed` to initialize the pseudorandom number generator.
+
+## Examples
+    
+	use <maze/mz_square.scad>;
+	use <line2d.scad>;
+
+	rows = 10;
+	columns = 10;
+	cell_width = 5;
+	wall_thickness = 2;
+
+	NO_WALL = 0;       
+	TOP_WALL = 1;    
+	RIGHT_WALL = 2;    
+	TOP_RIGHT_WALL = 3; 
+	MASK = 4;
+
+	cells = mz_square(rows, columns);
+
+	for(row = cells, cell = row) {
+		type = cell[2];
+		
+		translate([cell.x, cell.y] * cell_width) {
+			if(type == TOP_WALL || type == TOP_RIGHT_WALL) {
+				line2d([0, cell_width], [cell_width, cell_width], wall_thickness);
+			}
+			
+			if(type == RIGHT_WALL || type == TOP_RIGHT_WALL) {
+				line2d([cell_width, cell_width], [cell_width, 0], wall_thickness);
+			}	
+		}
+	}
+
+	line2d([0, 0], [cell_width * columns, 0], wall_thickness);
+	line2d([0, 0], [0, cell_width * rows], wall_thickness);
+
+![mz_square](images/lib3x-mz_square-1.JPG)
+

docs/lib3x-mz_squarewalls.md

@@ -0,0 +1,32 @@
+# mz_squarewalls
+
+It's a helper for creating wall data from maze cells. You can transform wall points for creating different types of mazes.
+
+**Since:** 3.3
+
+## Parameters
+
+- `cells` : Maze cells.
+- `cell_width` : The width of a cell.
+- `left_border` : Default to `true`. Create the leftmost border of the maze.
+- `bottom_border` : Default to `true`. Create the bottommost border of the maze.
+
+## Examples
+    
+	use <maze/mz_square.scad>;
+	use <maze/mz_squarewalls.scad>;
+	use <polyline2d.scad>;
+
+	rows = 10;
+	columns = 10;
+	cell_width = 5;
+	wall_thickness = 2;
+
+	cells = mz_square(rows, columns);
+	walls = mz_squarewalls(cells, cell_width);
+
+	for(wall = walls) {
+		polyline2d(wall, wall_thickness, joinStyle = "JOIN_MITER");
+	}
+	
+![mz_squarewalls](images/lib3x-mz_squarewalls-1.JPG)

docs/lib3x-mz_theta.md

@@ -0,0 +1,80 @@
+# mz_theta
+
+This function returns cell data of a theta maze. The data is a two-dimensional list with different row lengths. A cell has the data structure `[ri, ci, type]`. `ri` and `ci` are 0-based. `ri` means the ri-th ring and `ci` means the ci-th (counter-clockwise) cell of the ring. 
+
+![mz_theta](images/lib3x-mz_theta-1.JPG)
+
+The value of `type` is the wall type of the cell. It can be `0`, `1`, `2` or `3`. Setting them to constants is convenient.
+
+	NO_WALL = 0;           // the cell has no wall
+	INWARD_WALL = 1;       // the cell has an inward wall
+	CCW_WALL = 2;          // the cell has a counter-clockwise wall
+	INWARD_CCW_WALL = 3;   // the cell has an inward wall and a clockwise wall
+
+![mz_theta](images/lib3x-mz_theta-2.JPG)
+
+**Since:** 3.3
+
+## Parameters
+
+- `rings` : The number of rings.
+- `beginning_number` : The number of cells in the first row.
+- `start` : The start point to travel the maze. Default to `[0, 0]`.
+- `seed` : The maze is traveling randomly. Use `seed` to initialize the pseudorandom number generator.
+
+## Examples
+    
+	use <maze/mz_theta.scad>;
+	use <polyline_join.scad>;
+
+	rings = 8;
+	beginning_number = 8;
+	cell_width = 10;
+	wall_thickness = 2;
+
+	NO_WALL = 0;           
+	INWARD_WALL = 1;      
+	CCW_WALL = 2;         
+	INWARD_CCW_WALL = 3;   
+
+	function vt_from_angle(theta, r) = [r * cos(theta), r * sin(theta)];
+
+	maze = mz_theta(rings, beginning_number);
+
+	// draw cell walls
+	for(ring = maze, cell = ring) {		
+		ri = cell[0];
+		ci = cell[1];
+		type = cell[2];
+		thetaStep = 360 / len(maze[ri]);
+		innerR = (ri + 1) * cell_width;
+		outerR = (ri + 2) * cell_width;
+		theta1 = thetaStep * ci;
+		theta2 = thetaStep * (ci + 1);
+		
+		innerVt1 = vt_from_angle(theta1, innerR);
+		innerVt2 = vt_from_angle(theta2, innerR);
+		outerVt2 = vt_from_angle(theta2, outerR);
+		
+		if(type == INWARD_WALL || type == INWARD_CCW_WALL) {
+			polyline_join([innerVt1, innerVt2])
+				circle(wall_thickness / 2);
+		}
+
+		if(type == CCW_WALL || type == INWARD_CCW_WALL) {
+			polyline_join([innerVt2, outerVt2])
+				circle(wall_thickness / 2);
+		}
+	}
+
+    // outmost walls
+	thetaStep = 360 / len(maze[rings - 1]);
+	r = cell_width * (rings + 1);
+	for(theta = [0:thetaStep:360 - thetaStep]) {
+		vt1 = vt_from_angle(theta, r);
+		vt2 = vt_from_angle(theta + thetaStep, r);
+		polyline_join([vt1, vt2])
+			circle(wall_thickness / 2);
+	} 
+
+![mz_theta](images/lib3x-mz_theta-3.JPG)

src/experimental/note.md

@@ -9,6 +9,8 @@ new:
 - mz_squarewalls, mz_hexwalls
 - mz_hamiltonian supports init_cells
 
+   update doc mz_square_initialize
+   
 - surface/sf_cylinder?
 - noise/worley_sphere?
 - voronoi/vrn_sphere?

src/maze/mz_hexwalls.scad

@@ -1,7 +1,7 @@
 /**
 * mz_hexwalls.scad
 *
-* @copyright Justin Lin, 2020
+* @copyright Justin Lin, 2022
 * @license https://opensource.org/licenses/lgpl-3.0.html
 *
 * @see https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_hexwalls.html

src/maze/mz_square.scad

@@ -1,7 +1,7 @@
 /**
 * mz_square.scad
 *
-* @copyright Justin Lin, 2020
+* @copyright Justin Lin, 2022
 * @license https://opensource.org/licenses/lgpl-3.0.html
 *
 * @see https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_square.html

src/maze/mz_squarewalls.scad

@@ -1,7 +1,7 @@
 /**
 * mz_squarewalls.scad
 *
-* @copyright Justin Lin, 2020
+* @copyright Justin Lin, 2022
 * @license https://opensource.org/licenses/lgpl-3.0.html
 *
 * @see https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_squarewalls.html

src/maze/mz_theta.scad

@@ -1,10 +1,10 @@
 /**
-* mz_theta_cells.scad
+* mz_theta.scad
 *
-* @copyright Justin Lin, 2020
+* @copyright Justin Lin, 2022
 * @license https://opensource.org/licenses/lgpl-3.0.html
 *
-* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_theta_cells.html
+* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-mz_theta.html
 *
 **/