Skip to content

Commit 05c9621

Browse files
Firestone82Firestone82
authored
docs: unify README, setup guide, and description (#1)
1 parent 3930eee commit 05c9621

1 file changed

Lines changed: 155 additions & 219 deletions

File tree

‎README.md‎

Lines changed: 155 additions & 219 deletions
Original file line numberDiff line numberDiff line change
@@ -1,219 +1,155 @@
1-
<img width="15%" src="assets/icon.png" align="right" alt="Icon">
2-
3-
# Project for C++ (Maze Library API/CLI)
4-
5-
<p>
6-
<img alt="Testing" src="https://github.com/Firestone82/MazeLib/actions/workflows/cmake.yml/badge.svg">
7-
<img alt="License" src="https://img.shields.io/github/license/Firestone82/MazeLib">
8-
<img alt="GitHub issues" src="https://img.shields.io/github/issues/Firestone82/MazeLib">
9-
</p>
10-
11-
- Author: Pavel Mikula (MIK0486)
12-
- Took approximately 78 hours
13-
14-
## Project Theme
15-
The project will focus on generating and solving mazes. It will be divided into two parts for processing.
16-
The first part will be more focused on logic, which will be an API/CLI written in C++.
17-
This API or CLI will accept user input data and create and solve mazes based on the parameters.
18-
The second part of the project will focus more on graphics in Python.
19-
The graphical GUI will serve as the interface for the API and will also be used in the URO subject.
20-
21-
## Logical Part of the Project (API/CLI)
22-
This part will operate the following functions:
23-
- Creating a maze using a specified algorithm
24-
- Saving to a file or image
25-
- Solving a maze using a specified algorithm
26-
- Loading input from a file
27-
- Saving to a file or image
28-
- Finding the fastest algorithm for solving a maze
29-
- Outputting a table of results
30-
- Listing all available algorithms
31-
32-
## Graphical Part of the Project (GUI)
33-
The graphical part of the project, written in Python, will use the tkinter library and
34-
libraries from the first part of the project to connect user interfaces with graphics.
35-
The application will send requests to the API and render their outputs on the screen.
36-
37-
## API Architecture
38-
Important classes for work:
39-
- Maze (Class for storing a maze)
40-
- Algorithm (Class for utilizing an algorithm)
41-
- GeneratingAlgorithm (Subclass for generating algorithms)
42-
- SolvingAlgorithm (Subclass for solving algorithms)
43-
- Graph (Class for storing maze content)
44-
- Node (Subclass for storing maze cell)
45-
- Image (Class for exporting maze to an image)
46-
- Interface (Class for storing the interface)
47-
- Method (Class for saving or loading maze)
48-
- Bind (Class for binding methods into python)
49-
50-
## Requirements:
51-
- C++17
52-
- CMake 3.22.1+
53-
- Python 3.9.7+ (for GUI)
54-
55-
## Installation
56-
```shell
57-
# Clone the repository
58-
git clone https://github.com/Firestone82/MazeLib.git
59-
cd MazeLib
60-
61-
# Building as C++ CLI
62-
mkdir build && cd build
63-
64-
# Build the project
65-
cmake .. && make -j
66-
67-
# Build the project
68-
pip install -r ../requirements.txt && pip install ..
69-
```
70-
71-
## Images
72-
Example maze output:
73-
74-
<p align="center">
75-
<img src="assets/maze.png" alt="Not Solved Maze Image">
76-
&nbsp;
77-
&nbsp;
78-
&nbsp;
79-
<img src="assets/mazeSolved.png" alt="Solved Maze Image">
80-
</p>
81-
82-
## CLI Usage
83-
<details open>
84-
<summary>Click to show help CLI</summary>
85-
86-
```
87-
__ __ _ _ _
88-
| \/ | | | (_) |
89-
| \ / | __ _ _______| | _| |__
90-
| |\/| |/ _` |_ / _ \ | | | '_ \
91-
| | | | (_| |/ / __/ |____| | |_) |
92-
|_| |_|\__,_/___\___|______|_|_.__/
93-
Author: Pavel Mikula (MIK0486)
94-
95-
Format: mazelib <cmd> [options]
96-
97-
Commands:
98-
help | Show program help message (this)
99-
version, ver | Show programs version number
100-
generate, gen | Generate maze to file or image
101-
solve | Solve maze from file or image
102-
test | Test algorithms
103-
algorithms, algs, algos | Show available algorithms
104-
105-
Options:
106-
-h, --help | Show this help message and exit | [boolean]
107-
-v, --version | Show programs version number and exit | [boolean]
108-
```
109-
</details>
110-
111-
<details>
112-
<summary>Click to show generate CLI</summary>
113-
114-
```
115-
Command: mazelib generate [options]
116-
117-
Options:
118-
-w, --width | Width of maze REQUIRED | [int]
119-
-h, --height | Height of maze REQUIRED | [int]
120-
-a, --algorithm | Algorithm to generate maze REQUIRED | [string]
121-
-se, --seed | Seed of the maze | [double]
122-
-s, --start | Start position of maze | [int] [int]
123-
-e, --end | End position of maze | [int] [int]
124-
-pw, --pathWidth | Width of the path between walls | [int]
125-
-ww, --wallWidth | Width of wall between paths | [int]
126-
-f, --file | Path to the file, where maze will be saved | [string]
127-
-i, --image | Path to the image, where maze will be saved | [string]
128-
```
129-
</details>
130-
131-
<details>
132-
<summary>Click to show solve CLI</summary>
133-
134-
```
135-
Command: mazelib solve [options]
136-
137-
Options:
138-
-fi, --fileIn | Path to the input file of maze REQUIRED | [string]
139-
-a, --algorithm | Algorithm to solve maze REQUIRED | [string]
140-
-s, --start | Start position of maze | [int] [int]
141-
-e, --end | End position of maze | [int] [int]
142-
-fo, --fileOut | Path to the file, where maze will be saved | [string]
143-
-i, --image | Path to the image, where maze will be saved | [string]
144-
```
145-
</details>
146-
147-
<details>
148-
<summary>Click to show test CLI</summary>
149-
150-
```
151-
Command: mazelib test [options]
152-
153-
Options:
154-
-fi, --fileIn | Path to the file, from which maze will be loaded REQUIRED | [string]
155-
-a, --algorithm | Algorithms to test, separated by commas | [string]
156-
-fo, --fileOut | Path to the file, where maze will be saved | [string]
157-
-t, --table | Output results printed in table |
158-
```
159-
</details>
160-
161-
<details>
162-
<summary>Click to show algorithms CLI</summary>
163-
164-
```
165-
Command: mazelib algorithms
166-
167-
Options:
168-
-o, --order | Order of algorithms | [string]
169-
-t, --type | Type of algorithms | [string]
170-
-d, --description | Hide description of algorithms |
171-
```
172-
</details>
173-
174-
## API Usage
175-
<details open>
176-
<summary>Click to show example </summary>
177-
178-
```cpp
179-
void example() {
180-
181-
// Creation of a maze
182-
MazeBuilder builder = KruskalAlgorithm(time(nullptr)).generate(10, 10);
183-
builder.setPathWidth(30);
184-
builder.setWallWidth(3);
185-
186-
// Building the maze
187-
Maze maze = builder.build();
188-
189-
// Exporting the maze to a file
190-
TextFileSavingMethod().save(maze, "maze.txt");
191-
192-
// Exporting the maze to an image
193-
ImageSavingMethod().save(maze, "maze.png");
194-
195-
// --------------------------------
196-
197-
// Loading a maze from a file
198-
Expected<MazeBuilder> loaded = TextFileLoadingMethod().load("maze.txt");
199-
200-
// Checking for errors
201-
if (loaded.hasError()) {
202-
cout << "Error: " << loaded.error() << endl;
203-
return;
204-
} else {
205-
builder = loaded.value();
206-
maze = builder.build();
207-
}
208-
209-
// Solving the maze
210-
MazePath path = DepthFirstSearchAlgorithm().solve(maze);
211-
212-
// Exporting the maze to a file with the path
213-
TextFileSavingMethod().save(maze, "mazePath.txt", path);
214-
215-
// Exporting the maze to an image with the path
216-
ImageSavingMethod().save(maze, "mazePath.png", path);
217-
}
218-
```
219-
</details>
1+
<img width="15%" src="assets/icon.png" align="right" alt="Icon">
2+
3+
# MazeLib
4+
5+
> **VŠB-TUO** — School project · Programming in C++
6+
7+
<p>
8+
<img alt="CI" src="https://github.com/Firestone82/MazeLib/actions/workflows/cmake.yml/badge.svg">
9+
<img alt="License" src="https://img.shields.io/github/license/Firestone82/MazeLib">
10+
<img alt="Issues" src="https://img.shields.io/github/issues/Firestone82/MazeLib">
11+
</p>
12+
13+
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.
14+
15+
<p align="center">
16+
<img src="assets/maze.png" alt="Unsolved maze" width="45%">
17+
&nbsp;&nbsp;&nbsp;
18+
<img src="assets/mazeSolved.png" alt="Solved maze" width="45%">
19+
</p>
20+
21+
## Features
22+
23+
**Generation algorithms:** Depth-first search (recursive backtracker), Kruskal's
24+
25+
**Solving algorithms:** BFS, DFS, Dijkstra, Lee, Tremaux, Wall-following
26+
27+
**Output:** PNG image export, binary file serialization
28+
29+
**Interfaces:** CLI, C++ API, Python bindings
30+
31+
## Requirements
32+
33+
- C++17 compiler and CMake 3.22.1+
34+
- Python 3.9+ and pip *(for bindings and GUI)*
35+
36+
## Setup
37+
38+
1. Clone the repository:
39+
```bash
40+
git clone https://github.com/Firestone82/MazeLib.git
41+
cd MazeLib
42+
```
43+
44+
2. Build the C++ library and CLI:
45+
```bash
46+
mkdir build && cd build
47+
cmake .. && make -j$(nproc)
48+
cd ..
49+
```
50+
51+
3. *(Optional)* Install Python bindings (required for MazeLib-GUI):
52+
```bash
53+
pip install -r requirements.txt && pip install .
54+
```
55+
56+
## CLI Usage
57+
58+
<details open>
59+
<summary>General help</summary>
60+
61+
```
62+
Format: mazelib <cmd> [options]
63+
64+
Commands:
65+
generate, gen Generate a maze to file or image
66+
solve Solve a maze from file or image
67+
test Benchmark algorithms
68+
algorithms List available algorithms
69+
```
70+
</details>
71+
72+
<details>
73+
<summary>generate</summary>
74+
75+
```
76+
Options:
77+
-w, --width Width of maze REQUIRED
78+
-h, --height Height of maze REQUIRED
79+
-a, --algorithm Generation algorithm REQUIRED
80+
-se, --seed Seed for reproducible mazes
81+
-s, --start Start position [int] [int]
82+
-e, --end End position [int] [int]
83+
-pw, --pathWidth Path width between walls
84+
-ww, --wallWidth Wall width between paths
85+
-f, --file Output file path
86+
-i, --image Output image path
87+
```
88+
</details>
89+
90+
<details>
91+
<summary>solve</summary>
92+
93+
```
94+
Options:
95+
-fi, --fileIn Input maze file path REQUIRED
96+
-a, --algorithm Solving algorithm REQUIRED
97+
-s, --start Start position
98+
-e, --end End position
99+
-fo, --fileOut Output file path
100+
-i, --image Output image path
101+
```
102+
</details>
103+
104+
<details>
105+
<summary>test</summary>
106+
107+
```
108+
Options:
109+
-fi, --fileIn Maze file to benchmark REQUIRED
110+
-a, --algorithm Algorithms to test (comma-sep)
111+
-fo, --fileOut Output file path
112+
-t, --table Print results as table
113+
```
114+
</details>
115+
116+
<p align="center">
117+
<img src="assets/generate.png" alt="generate command" width="48%">
118+
&nbsp;
119+
<img src="assets/solve.png" alt="solve command" width="48%">
120+
</p>
121+
<p align="center">
122+
<img src="assets/test.png" alt="test command" width="48%">
123+
&nbsp;
124+
<img src="assets/algos.png" alt="algorithms command" width="48%">
125+
</p>
126+
127+
## API Usage
128+
129+
```cpp
130+
// Generate a maze
131+
MazeBuilder builder = KruskalAlgorithm(time(nullptr)).generate(10, 10);
132+
builder.setPathWidth(30);
133+
builder.setWallWidth(3);
134+
Maze maze = builder.build();
135+
136+
// Export to file and image
137+
TextFileSavingMethod().save(maze, "maze.txt");
138+
ImageSavingMethod().save(maze, "maze.png");
139+
140+
// Load a saved maze
141+
Expected<MazeBuilder> loaded = TextFileLoadingMethod().load("maze.txt");
142+
if (loaded.hasError()) {
143+
cout << "Error: " << loaded.error() << endl;
144+
return;
145+
}
146+
maze = loaded.value().build();
147+
148+
// Solve and export with path
149+
MazePath path = DepthFirstSearchAlgorithm().solve(maze);
150+
ImageSavingMethod().save(maze, "mazePath.png", path);
151+
```
152+
153+
## License
154+
155+
This project was created as a school assignment at VŠB-TUO.

0 commit comments

Comments
 (0)