diff --git a/README.md b/README.md index 35c58ed..6ec647a 100644 --- a/README.md +++ b/README.md @@ -1,219 +1,155 @@ -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); -} -``` -
+Icon + +# MazeLib + +> **VŠB-TUO** — School project · Programming in C++ + +

+ CI + License + Issues +

+ +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. + +

+ Unsolved maze +     + Solved maze +

+ +## 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: + ```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 . + ``` + +## CLI Usage + +
+General help + +``` +Format: mazelib [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 +``` +
+ +

+ 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 + +This project was created as a school assignment at VŠB-TUO.