From 543829ae7716ecb7f9af0e7f6a4d62590d8dfc90 Mon Sep 17 00:00:00 2001 From: Pavel Mikula <57676764+Firestone82@users.noreply.github.com> Date: Sat, 20 Jun 2026 10:48:29 +0200 Subject: [PATCH 1/2] docs: unify README format, setup guide, and description --- README.md | 288 +++++++++++++----------------------------------------- 1 file changed, 69 insertions(+), 219 deletions(-) diff --git a/README.md b/README.md index 35c58ed..d669544 100644 --- a/README.md +++ b/README.md @@ -1,219 +1,69 @@ -Icon - -# Project for C++ (Maze Library API/CLI) - -

- Testing - License - GitHub issues -

- -- Author: Pavel Mikula (MIK0486) -- Took approximately 78 hours - -## Project Theme -The project will focus on generating and solving mazes. It will be divided into two parts for processing. -The first part will be more focused on logic, which will be an API/CLI written in C++. -This API or CLI will accept user input data and create and solve mazes based on the parameters. -The second part of the project will focus more on graphics in Python. -The graphical GUI will serve as the interface for the API and will also be used in the URO subject. - -## Logical Part of the Project (API/CLI) -This part will operate the following functions: - - Creating a maze using a specified algorithm - - Saving to a file or image - - Solving a maze using a specified algorithm - - Loading input from a file - - Saving to a file or image - - Finding the fastest algorithm for solving a maze - - Outputting a table of results - - Listing all available algorithms - -## Graphical Part of the Project (GUI) -The graphical part of the project, written in Python, will use the tkinter library and -libraries from the first part of the project to connect user interfaces with graphics. -The application will send requests to the API and render their outputs on the screen. - -## API Architecture -Important classes for work: - - Maze (Class for storing a maze) - - Algorithm (Class for utilizing an algorithm) - - GeneratingAlgorithm (Subclass for generating algorithms) - - SolvingAlgorithm (Subclass for solving algorithms) - - Graph (Class for storing maze content) - - Node (Subclass for storing maze cell) - - Image (Class for exporting maze to an image) - - Interface (Class for storing the interface) - - Method (Class for saving or loading maze) - - Bind (Class for binding methods into python) - -## Requirements: -- C++17 -- CMake 3.22.1+ -- Python 3.9.7+ (for GUI) - -## Installation -```shell -# Clone the repository -git clone https://github.com/Firestone82/MazeLib.git -cd MazeLib - -# Building as C++ CLI -mkdir build && cd build - -# Build the project -cmake .. && make -j - -# Build the project -pip install -r ../requirements.txt && pip install .. -``` - -## Images -Example maze output: - -

- Not Solved Maze Image -   -   -   - Solved Maze Image -

- -## CLI Usage -
-Click to show help CLI - -``` - __ __ _ _ _ -| \/ | | | (_) | -| \ / | __ _ _______| | _| |__ -| |\/| |/ _` |_ / _ \ | | | '_ \ -| | | | (_| |/ / __/ |____| | |_) | -|_| |_|\__,_/___\___|______|_|_.__/ -Author: Pavel Mikula (MIK0486) - -Format: mazelib [options] - -Commands: - help | Show program help message (this) - version, ver | Show programs version number - generate, gen | Generate maze to file or image - solve | Solve maze from file or image - test | Test algorithms - algorithms, algs, algos | Show available algorithms - -Options: - -h, --help | Show this help message and exit | [boolean] - -v, --version | Show programs version number and exit | [boolean] -``` -
- -
-Click to show generate CLI - -``` -Command: mazelib generate [options] - -Options: - -w, --width | Width of maze REQUIRED | [int] - -h, --height | Height of maze REQUIRED | [int] - -a, --algorithm | Algorithm to generate maze REQUIRED | [string] - -se, --seed | Seed of the maze | [double] - -s, --start | Start position of maze | [int] [int] - -e, --end | End position of maze | [int] [int] - -pw, --pathWidth | Width of the path between walls | [int] - -ww, --wallWidth | Width of wall between paths | [int] - -f, --file | Path to the file, where maze will be saved | [string] - -i, --image | Path to the image, where maze will be saved | [string] -``` -
- -
-Click to show solve CLI - -``` -Command: mazelib solve [options] - -Options: - -fi, --fileIn | Path to the input file of maze REQUIRED | [string] - -a, --algorithm | Algorithm to solve maze REQUIRED | [string] - -s, --start | Start position of maze | [int] [int] - -e, --end | End position of maze | [int] [int] - -fo, --fileOut | Path to the file, where maze will be saved | [string] - -i, --image | Path to the image, where maze will be saved | [string] -``` -
- -
-Click to show test CLI - -``` -Command: mazelib test [options] - -Options: - -fi, --fileIn | Path to the file, from which maze will be loaded REQUIRED | [string] - -a, --algorithm | Algorithms to test, separated by commas | [string] - -fo, --fileOut | Path to the file, where maze will be saved | [string] - -t, --table | Output results printed in table | -``` -
- -
-Click to show algorithms CLI - -``` -Command: mazelib algorithms - -Options: - -o, --order | Order of algorithms | [string] - -t, --type | Type of algorithms | [string] - -d, --description | Hide description of algorithms | -``` -
- -## API Usage -
-Click to show example - -```cpp -void example() { - - // Creation of a maze - MazeBuilder builder = KruskalAlgorithm(time(nullptr)).generate(10, 10); - builder.setPathWidth(30); - builder.setWallWidth(3); - - // Building the maze - Maze maze = builder.build(); - - // Exporting the maze to a file - TextFileSavingMethod().save(maze, "maze.txt"); - - // Exporting the maze to an image - ImageSavingMethod().save(maze, "maze.png"); - - // -------------------------------- - - // Loading a maze from a file - Expected loaded = TextFileLoadingMethod().load("maze.txt"); - - // Checking for errors - if (loaded.hasError()) { - cout << "Error: " << loaded.error() << endl; - return; - } else { - builder = loaded.value(); - maze = builder.build(); - } - - // Solving the maze - MazePath path = DepthFirstSearchAlgorithm().solve(maze); - - // Exporting the maze to a file with the path - TextFileSavingMethod().save(maze, "mazePath.txt", path); - - // Exporting the maze to an image with the path - ImageSavingMethod().save(maze, "mazePath.png", path); -} -``` -
+# MazeLib + +> **VŠB-TUO** — School project · Programming in C++ + +![C++](https://img.shields.io/badge/C%2B%2B-17-blue) ![Python](https://img.shields.io/badge/Python-3.9%2B-yellow) ![CMake](https://img.shields.io/badge/CMake-3.22%2B-blue) + +## About + +A C++ maze generation and solving library with a command-line interface, programmatic API, and Python bindings. Mazes can be exported as PNG images or serialized to disk for later use. The Python bindings power the companion [MazeLib-GUI](https://github.com/Firestone82/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 Python bindings and GUI)* + +## Setup + +1. Clone the repository: + ```bash + git clone https://github.com/Firestone82/MazeLib.git + cd MazeLib + ``` + +2. Build the C++ library and CLI: + ```bash + mkdir build && cd build + cmake .. + make -j$(nproc) + cd .. + ``` + +3. *(Optional)* Install Python bindings (required for MazeLib-GUI): + ```bash + pip install -r requirements.txt + pip install . + ``` + +## Usage + +```bash +# Generate a 20×20 maze and save it +./build/mazelib generate --width 20 --height 20 --algorithm dfs --output maze.dat + +# Solve a saved maze +./build/mazelib solve --file maze.dat --algorithm dijkstra + +# Export a maze as a PNG image +./build/mazelib generate --width 30 --height 30 --algorithm kruskal --image maze.png + +# Benchmark all algorithms on a 50×50 maze +./build/mazelib test --width 50 --height 50 + +# List available algorithms +./build/mazelib list +``` + +## License + +This project was created as a school assignment at VŠB-TUO. From d604059df75687ca0dc709cca8c634e3c410b2a4 Mon Sep 17 00:00:00 2001 From: Pavel Mikula <57676764+Firestone82@users.noreply.github.com> Date: Sat, 20 Jun 2026 11:14:39 +0200 Subject: [PATCH 2/2] docs: unify README format, setup guide, and description --- README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 106 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d669544..6ec647a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,22 @@ +Icon + # MazeLib > **VŠB-TUO** — School project · Programming in C++ -![C++](https://img.shields.io/badge/C%2B%2B-17-blue) ![Python](https://img.shields.io/badge/Python-3.9%2B-yellow) ![CMake](https://img.shields.io/badge/CMake-3.22%2B-blue) +

+ CI + License + Issues +

-## About +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](https://github.com/Firestone82/MazeLib-GUI) tkinter application. -A C++ maze generation and solving library with a command-line interface, programmatic API, and Python bindings. Mazes can be exported as PNG images or serialized to disk for later use. The Python bindings power the companion [MazeLib-GUI](https://github.com/Firestone82/MazeLib-GUI) tkinter application. +

+ Unsolved maze +     + Solved maze +

## Features @@ -21,7 +31,7 @@ A C++ maze generation and solving library with a command-line interface, program ## Requirements - C++17 compiler and CMake 3.22.1+ -- Python 3.9+ and pip *(for Python bindings and GUI)* +- Python 3.9+ and pip *(for bindings and GUI)* ## Setup @@ -34,34 +44,110 @@ A C++ maze generation and solving library with a command-line interface, program 2. Build the C++ library and CLI: ```bash mkdir build && cd build - cmake .. - make -j$(nproc) + cmake .. && make -j$(nproc) cd .. ``` 3. *(Optional)* Install Python bindings (required for MazeLib-GUI): ```bash - pip install -r requirements.txt - pip install . + pip install -r requirements.txt && pip install . ``` -## Usage +## CLI Usage + +
+General help -```bash -# Generate a 20×20 maze and save it -./build/mazelib generate --width 20 --height 20 --algorithm dfs --output maze.dat +``` +Format: mazelib [options] -# Solve a saved maze -./build/mazelib solve --file maze.dat --algorithm dijkstra +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 +``` +
-# Export a maze as a PNG image -./build/mazelib generate --width 30 --height 30 --algorithm kruskal --image maze.png +
+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 +``` +
-# Benchmark all algorithms on a 50×50 maze -./build/mazelib test --width 50 --height 50 +
+solve -# List available algorithms -./build/mazelib list +``` +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 +``` +
+ +

+ generate command +   + solve command +

+

+ test command +   + algorithms command +

+ +## API Usage + +```cpp +// 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 image +TextFileSavingMethod().save(maze, "maze.txt"); +ImageSavingMethod().save(maze, "maze.png"); + +// Load a saved maze +Expected 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