modules/mazlib/README.md

# 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
```