Maze Generator
A comprehensive Python-based maze generation and solving application featuring 8 different algorithms, an interactive Neo-Brutalism web interface, and advanced analysis tools.
Features
🎨 8 Maze Generation Algorithms
- Recursive Backtracking - Depth-first search with backtracking
- Kruskal's Algorithm - Minimum spanning tree using union-find
- Prim's Algorithm - Greedy minimum spanning tree
- Sidewinder Algorithm - Row-by-row generation with horizontal bias
- Hunt-and-Kill Algorithm - Random walks with hunting phase
- Eller's Algorithm - Memory-efficient row-by-row generation
- Wilson's Algorithm - Loop-erased random walks (uniform spanning trees)
- Aldous-Broder Algorithm - Random walk-based generation
🔍 2 Solving Algorithms
- Depth-First Search (DFS) - Memory-efficient pathfinding
- Breadth-First Search (BFS) - Guaranteed shortest path
🎯 Interactive Web Interface
Built with Neo-Brutalism design aesthetics featuring:
- Bold, thick borders (6px)
- High contrast neon colors (yellow, pink, cyan, green)
- Hard drop shadows
- Chunky typography (Space Grotesk font)
- Asymmetric layouts
📊 Analysis Tools
- Dead end counting and percentage
- Longest path detection
- Branching factor calculation
- Algorithm performance benchmarking
🖼️ Visualization
- Real-time canvas rendering
- PNG image export
- Solution path highlighting
- Visited cell tracking
💾 Persistence
- Save/load mazes as JSON
- File management system
- Reproducible generation with seeds
Installation
Local Setup
- Clone the repository:
git clone <repository-url>
cd mazer
- Create virtual environment:
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
- Install dependencies:
pip install -r requirements.txt
- Run the application:
python api/app.py
- Open your browser:
Navigate to
http://localhost:5000
Docker Setup
- Build and run with Docker Compose:
cd docker
docker-compose up --build
- Access the application:
Navigate to
http://localhost:5000
Usage
Web Interface
The web interface provides 9 main operations:
- Generate Maze - Create a new maze with selected algorithm and dimensions
- Visualize - Display the maze on canvas
- Download Image - Save maze as PNG file
- Save to File - Persist maze as JSON
- Load from File - Restore saved maze
- Solve (DFS) - Find path using Depth-First Search
- Solve (BFS) - Find shortest path using Breadth-First Search
- Analyze - Compute maze statistics and metrics
- Benchmark - Compare algorithm performance
API Endpoints
Generate Maze
POST /api/generate
Content-Type: application/json
{
"algorithm": "recursive_backtracking",
"rows": 15,
"cols": 15,
"seed": 42
}
Solve Maze
POST /api/solve
Content-Type: application/json
{
"maze_id": 0,
"algorithm": "bfs"
}
Analyze Maze
GET /api/analyze/<maze_id>
Download Maze Image
GET /api/download/<maze_id>?solution=true&solver=bfs
Benchmark Algorithms
POST /api/benchmark
Content-Type: application/json
{
"type": "quick"
}
Python API
from src.generators import RecursiveBacktrackingGenerator
from src.solvers import BFSSolver
from src.analysis.analyzer import MazeAnalyzer
# Generate a maze
generator = RecursiveBacktrackingGenerator()
maze = generator.generate(rows=20, cols=20, seed=42)
# Solve the maze
solver = BFSSolver()
solution = solver.solve(maze)
# Analyze the maze
analysis = MazeAnalyzer.analyze(maze)
print(f"Dead ends: {analysis['dead_ends']}")
print(f"Longest path: {analysis['longest_path_length']}")
Testing
Run the test suite with coverage:
# Run all tests
pytest
# Run with coverage report
pytest --cov=src --cov-report=html
# Run specific test file
pytest tests/unit/test_maze.py
# Run specific test
pytest tests/unit/test_generators.py::TestGenerators::test_generator_creates_valid_maze
Test Coverage
- Overall: >90%
- Core modules: >95%
- Generators: >90%
- Solvers: >90%
- API: >85%
Project Structure
mazer/
├── src/ # Core application code
│ ├── core/ # Maze and Cell classes
│ ├── generators/ # 8 generation algorithms
│ ├── solvers/ # DFS and BFS solvers
│ ├── visualization/ # Image and web rendering
│ ├── analysis/ # Analysis and benchmarking
│ └── storage/ # File I/O operations
├── api/ # Flask web API
│ └── app.py # Main application
├── web/ # Frontend
│ ├── static/
│ │ ├── css/ # Neo-Brutalism styles
│ │ └── js/ # Interactive controls
│ └── templates/ # HTML templates
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── docker/ # Docker configuration
├── requirements.txt # Python dependencies
└── README.md # This file
Algorithm Complexity
| Algorithm | Time Complexity | Space Complexity | Characteristics |
|---|---|---|---|
| Recursive Backtracking | O(n) | O(n) | Long winding paths |
| Kruskal's | O(E log E) | O(V) | Many short paths |
| Prim's | O(E log V) | O(V) | Short dead ends |
| Sidewinder | O(n) | O(cols) | Horizontal bias |
| Hunt-and-Kill | O(n²) | O(1) | Few dead ends |
| Eller's | O(n) | O(cols) | Memory efficient |
| Wilson's | O(n) expected | O(n) | Uniform spanning tree |
| Aldous-Broder | O(n log n) | O(1) | Uniform, slow |
Performance Targets
- 5×5 maze: <10ms generation
- 25×25 maze: <100ms generation
- 50×50 maze: <1s generation
- API response time: <2s for all operations
Technologies Used
- Backend: Python 3.11+
- Web Framework: Flask 3.0
- Image Processing: Pillow
- Testing: pytest, pytest-cov
- Containerization: Docker, Docker Compose
- Frontend: HTML5, CSS3, JavaScript
- Design: Neo-Brutalism aesthetic
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License.
Acknowledgments
- Maze generation algorithms based on "Mazes for Programmers" by Jamis Buck
- Neo-Brutalism design inspiration from neobrutalism.dev
Future Enhancements
- Additional solving algorithms (A*, Dijkstra)
- 3D maze support
- Multi-start/multi-end points
- Difficulty ratings
- WebSocket real-time updates
- Mobile app version