MazeLib

VŠB-TUO — School project · Programming in C++

A C++ maze generation and solving library with a CLI, programmatic API, and Python bindings. Mazes can be exported as PNG images or serialized to disk. Powers the companion MazeLib-GUI tkinter application.

Features

Generation algorithms: Depth-first search (recursive backtracker), Kruskal's

Solving algorithms: BFS, DFS, Dijkstra, Lee, Tremaux, Wall-following

Output: PNG image export, binary file serialization

Interfaces: CLI, C++ API, Python bindings

Requirements

• C++17 compiler and CMake 3.22.1+
• Python 3.9+ and pip (for bindings and GUI)

Setup

1. Clone the repository:

   git clone https://github.com/Firestone82/MazeLib.git
   cd MazeLib

2. Build the C++ library and CLI:

   mkdir build &&cd build
   cmake .. && make -j$(nproc)cd ..

3. (Optional) Install Python bindings (required for MazeLib-GUI):

   pip install -r requirements.txt && pip install .

CLI Usage

General help

Format: mazelib <cmd> [options]
Commands:
generate, gen Generate a maze to file or image
solve Solve a maze from file or image
test Benchmark algorithms
algorithms List available algorithms

generate

Options:
-w, --width Width of maze REQUIRED
-h, --height Height of maze REQUIRED
-a, --algorithm Generation algorithm REQUIRED
-se, --seed Seed for reproducible mazes
-s, --start Start position [int] [int]
-e, --end End position [int] [int]
-pw, --pathWidth Path width between walls
-ww, --wallWidth Wall width between paths
-f, --file Output file path
-i, --image Output image path

solve

Options:
-fi, --fileIn Input maze file path REQUIRED
-a, --algorithm Solving algorithm REQUIRED
-s, --start Start position
-e, --end End position
-fo, --fileOut Output file path
-i, --image Output image path

test

Options:
-fi, --fileIn Maze file to benchmark REQUIRED
-a, --algorithm Algorithms to test (comma-sep)
-fo, --fileOut Output file path
-t, --table Print results as table

API Usage

// Generate a maze
MazeBuilder builder = KruskalAlgorithm(time(nullptr)).generate(10, 10);
builder.setPathWidth(30);
builder.setWallWidth(3);
Maze maze = builder.build();
// Export to file and imageTextFileSavingMethod().save(maze, "maze.txt");
ImageSavingMethod().save(maze, "maze.png");
// Load a saved maze
Expected<MazeBuilder> loaded = TextFileLoadingMethod().load("maze.txt");
if (loaded.hasError()) {
cout << "Error: " << loaded.error() << endl;
return;
}
maze = loaded.value().build();
// Solve and export with path
MazePath path = DepthFirstSearchAlgorithm().solve(maze);
ImageSavingMethod().save(maze, "mazePath.png", path);

License

This project was created as a school assignment at VŠB-TUO.