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:

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:

pip install -e .

Usage

CLI:

python -m mazlib.cli --help
python -m mazlib.cli -s rect -z 31x21 -c 20 -O out --show-solution

Python API:

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:

# 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):

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:

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:

git submodule add https://github.com/Oncorporation/maze_maker.git submodules/maze_maker

Clone with submodules:

git clone --recurse-submodules <parent-repo-url>

Update after clone:

git submodule update --init --recursive