From 9026ad732843001e053fb86d964034e2b2ab20e7 Mon Sep 17 00:00:00 2001 From: Dan Anglin Date: Sun, 18 Feb 2024 11:01:36 +0000 Subject: [PATCH] docs: update README.md with project documentation - Update README.md with the project documentation. - Add a gif of the demo. - Add pictures for illustration. --- README.md | 71 ++++++++++++++++++++++-- assets/images/demo.gif | 3 + assets/images/launch_application.png | 3 + assets/images/option_selection.png | 3 + assets/images/running_the_simulation.png | 3 + 5 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 assets/images/demo.gif create mode 100644 assets/images/launch_application.png create mode 100644 assets/images/option_selection.png create mode 100644 assets/images/running_the_simulation.png diff --git a/README.md b/README.md index d1e4edd..30dfc78 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,76 @@ ## Overview -**This project is WIP.** +Maze Solver is an interactive maze simulator developed with Python and Tkinter. +With this application you can randomly generate mazes and watch as different algorithms try to solve them. -The Maze Solver randomly generates a maze and systematically solves it. +### Demo -Built with Python and Tkinter. +![A demo of the Maze Solver application](assets/images/demo.gif) -## Repository mirrors +### Repository mirrors - **GitHub:** https://github.com/dananglin/maze-solver - **Code Flow:** https://codeflow.dananglin.me.uk/apollo/maze-solver + +## Requirements + +To run the application you'll need a recent version of Python 3. This application was built and tested with Python 3.12.2. + +You'll also need to make sure that you have `Tkinter` installed with your Python installation. +You can test this by running the following in your terminal: + +``` +python -m tkinter +``` + +If the module is installed then you should see a new small window appear on your screen. +If its not you'll see an error message starting with `ModuleNotFoundError` and you'll need to install it. +You may find guides online on how to install Tkinter for your operating system. + +## How to run the application + +Clone this repository to your local machine. + +``` +git clone https://github.com/dananglin/maze-solver.git +``` + +Run the application with Python. + +``` +cd maze-solver +python3 main.py +``` + +You should now see the Maze Solver window on your screen. + +![Launching the application](assets/images/launch_application.png) + +Generate a new maze by clicking on the `Generate maze` button and watch the application generate the maze. + +Once the maze is generated choose which searching algorithm you want to see solve the maze. +As of writing `BFS` and `DFS` are available with more along the way. + +Next choose if you want to enable randomness to the algorithm with the `Enable randomness` checkbox. +Randomness is applied when the solver stands before a fork in its path and has to choose from a number of possible directions. + +With randomness enabled it will randomly choose the next direction and with it disabled the next direction is chosen +from something very similar to an ordered list. + +![Selecting options](assets/images/option_selection.png) + +Once you're happy with the options, click on the `Solve the maze` button to start the simulation. + +As the solver traverses through the maze, it leaves a red trail so that you can keep track of its progress. + +When the solver reaches a dead-end it backtracks until it can choose a new path to traverse. +When it backtracks it leaves behind a grey trail. + +![Running the simulation](assets/images/running_the_simulation.png) + +After the solver solves the maze (or fails to do so) you can run the simulation again on the same maze with by pressing the `Solve the maze` button. + +Try running choosing a different algorithm or toggle between randomness before running the simulation again. + +You can also generate a new maze by clicking the `Generate maze` button again. diff --git a/assets/images/demo.gif b/assets/images/demo.gif new file mode 100644 index 0000000..83fa4bf --- /dev/null +++ b/assets/images/demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7b224f4af209de0c6fecc464f7c710c153026ff699a66413bcf97cb06aaad216 +size 2672243 diff --git a/assets/images/launch_application.png b/assets/images/launch_application.png new file mode 100644 index 0000000..9e7f5b2 --- /dev/null +++ b/assets/images/launch_application.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a5d51c1d2b892aec0984eed3392c81335781ed9cf680e32ac72cd3ea75e68a27 +size 19548 diff --git a/assets/images/option_selection.png b/assets/images/option_selection.png new file mode 100644 index 0000000..c0ded8e --- /dev/null +++ b/assets/images/option_selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:07343adafa60fa3f1e5f3c991eaaf37c58f3e768c950f30e048158e13fbaa30f +size 21964 diff --git a/assets/images/running_the_simulation.png b/assets/images/running_the_simulation.png new file mode 100644 index 0000000..f4e36b2 --- /dev/null +++ b/assets/images/running_the_simulation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:48ce944a36fd080e4373c20fc09f2e1b014e3a0409883fd73f5a641dfca86eeb +size 22443