python-maze/README.md

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
• Animated solving with pause/stop controls and adjustable speed

📊 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

1. Clone the repository:

git clone <repository-url>
cd mazer

2. Create virtual environment:

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Generate SEO images:

python generate_images.py

This creates favicons, social media previews, and PWA icons. See GENERATE_IMAGES_INSTRUCTIONS.md for details.

5. Run the application:

python api/app.py

6. Open your browser: Navigate to http://localhost:5000

Docker Setup

1. Build and run with Docker Compose:

cd docker
docker-compose up --build

2. Access the application: Navigate to http://localhost:5000

Usage

Web Interface

The web interface provides 9 main operations:

1. Generate Maze - Create a new maze with selected algorithm and dimensions
2. Visualize - Display the maze on canvas
3. Download Image - Save maze as PNG file
4. Save to File - Persist maze as JSON
5. Load from File - Restore saved maze
6. Solve (DFS) - Find path using Depth-First Search with animated visualization
7. Solve (BFS) - Find shortest path using Breadth-First Search with animated visualization
8. Analyze - Compute maze statistics and metrics
9. Benchmark - Compare algorithm performance

Animation Controls

When solving a maze, you can:

• Pause/Resume - Pause the animation and resume where you left off
• Stop - Stop the animation and show the final result
• Adjust Speed - Use the slider to control animation speed (slow to fast)

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&format=png

# Parameters:
# - solution: true/false (include solution path)
# - solver: dfs/bfs (which algorithm to use)
# - format: png/jpg (image format, defaults to png)

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
• SEO: Comprehensive meta tags, structured data, sitemap, robots.txt

SEO Features

The site is fully optimized for search engines:

• ✅ Comprehensive meta tags (title, description, keywords)
• ✅ Open Graph tags for social media sharing
• ✅ Twitter Card support
• ✅ Schema.org structured data (WebApplication)
• ✅ XML sitemap with image sitemap
• ✅ robots.txt for crawler guidance
• ✅ PWA manifest for mobile app experience
• ✅ Semantic HTML with ARIA roles
• ✅ Mobile-optimized and responsive
• ✅ Fast loading with resource hints

See SEO_OPTIMIZATION.md for complete details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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