Spaces:
Sleeping
Sleeping
File size: 4,961 Bytes
e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 e0a5254 737fab6 7bfe358 e0a5254 737fab6 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 |
# Maze Maker
Generate, solve, and render mazes in Python.
## Features
- Rectangular mazes (recursive or iterative DFS)
- Triangular mazes
- Hexagonal mazes (axial coordinates)
- Shortest-path solving with BFS
- Image rendering with Pillow
- CLI and Python API support
- Deterministic generation via --seed / seed parameter (non‑zero)
## Installation
Requirements:
- Python 3.8+
- Pillow>=9.0
Install from source:
```sh
git clone https://github.com/Oncorporation/maze_maker.git
cd maze_maker
python -m pip install --upgrade pip
pip install -r requirements.txt
```
Optional editable install:
```sh
pip install -e .
```
## Usage
CLI:
```sh
python -m mazlib.cli --help
python -m mazlib.cli -s rect -z 31x21 -c 20 -O out --show-solution
```
Python API:
```python
from mazlib.cli import run_maze
# non-deterministic (seed=0 uses system randomness)
maze, path = run_maze(shape="rect", size=(31, 21), cell=20, draw=True)
# deterministic: pass a non-zero seed
maze, path = run_maze(shape="rect", size=(31, 21), cell=20, draw=True, seed=42)
```
### `run_maze` parameters
`run_maze(shape='rect', size=(30,20), cell=20, use_iterative=False, draw=True, output=None, show_solution=True, show_doors=False, seed=0)`
- `shape` (`str`): maze shape.
- Canonical values: `rect`, `tri`, `hex`
- Also accepted by `run_maze`: `rectangle`, `grid`, `triangle`, `triangular`, `hexagon`, `hexagonal`
- `size` (`tuple|int`):
- Rect/Tri: `(width, height)` or single `int` (square)
- Hex: `int` radius
- `cell` (`int`): cell size in pixels (`cell_size` for hex drawing internally).
- `use_iterative` (`bool`): use iterative generator variant.
- `draw` (`bool`): when `True`, render maze image.
- `output` (`str|None`): output image path. If `None`, no file is saved and the image is shown (when drawing).
- `show_solution` (`bool`): when `True`, include the solved path overlay in rendering.
- `show_doors` (`bool`): draw light outline guides/cell boundaries.
- `seed` (`int`): optional random seed. Non-zero seeds produce deterministic mazes; `0` (default) uses system randomness.
Return value:
- `(maze, path)`
- `maze`: list of lists (rect) or dict (tri/hex)
- `path`: list of coordinates for the solution path
Notes on determinism and seeding
- Passing a non-zero `seed` to `run_maze` or the individual generators (`generate_maze`,
`generate_maze_iterative`, `generate_hex_maze_iterative`, `generate_tri_maze`, etc.)
uses a private Random instance seeded with that value. That makes generation deterministic
and repeatable across runs when the same seed is used.
### Valid shapes in CLI vs API
- CLI `--shape` accepted values: `rect`, `tri`, `hex`
- Python `run_maze(shape=...)` accepts the aliases listed above
### Image file naming with `mazlib.cli`
`run_maze` supports two output modes from the CLI:
- `-o/--output`: use an exact filename you provide.
- `-O/--out-dir`: auto-generate a filename in the given directory.
Auto-generated filename patterns (when using `-O`):
- Rectangular: `maze_rect_<width>x<height>_<YYYYMMDD_HHMMSS>.png`
- Triangular: `maze_tri_<width>x<height>_<YYYYMMDD_HHMMSS>.png`
- Hexagonal: `maze_hex_r<radius>_<YYYYMMDD_HHMMSS>.png`
When a non-zero `--seed` is provided to the CLI, the seed is appended to the
auto-generated filename as `_s<seed>` (for example `maze_rect_31x21_20230101_123000_s42.png`) so
deterministic outputs are easy to correlate with their seed.
Examples:
```sh
# Explicit filename
python -m mazlib.cli -s rect -z 31x21 -o my_custom_maze.png
# Auto-generated filename in ./out with deterministic seed appended
python -m mazlib.cli -s rect -z 31x21 -O out --seed 42
```
### Drawing customization and colors
The CLI exposes options to control drawing appearance and colors. Use `--show-doors` to draw thin outlines for cell/hex/triangle doors. You can override individual colors with these flags:
- `--color-wall` (default: `black`)
- `--color-floor` (default: `white`)
- `--color-start` (default: `green`)
- `--color-door` (default: `#B0B0B0`)
- `--color-path` (default: `red`)
Example (custom colors):
```sh
python -m mazlib.cli -s rect -z 31x21 -O out --show-doors --color-wall navy --color-start lime --color-path orange
```
Programmatic API users can pass a color_dict to `run_maze` or to the draw functions:
```python
colors = {'wall':'navy', 'floor':'#f8f8f8', 'start':'lime', 'door':'#cccccc', 'path':'orange'}
maze, path = run_maze(shape='rect', size=(31,21), draw=True, seed=42, color_dict=colors)
```
### Drawing notes
- The triangular maze drawing now reliably marks the starting triangle in green
(same visual cue used by rectangular and hex drawing functions).
## Git Submodule (quick reference)
Add:
```sh
git submodule add https://github.com/Oncorporation/maze_maker.git submodules/maze_maker
```
Clone with submodules:
```sh
git clone --recurse-submodules <parent-repo-url>
```
Update after clone:
```sh
git submodule update --init --recursive
```
|