Skip to content

VISUALIZER.md

Latest commit

 

History

History
231 lines (166 loc) · 6.33 KB

VISUALIZER.md

File metadata and controls

231 lines (166 loc) · 6.33 KB

🎨 Maze Visualizer Guide

Overview

The maze visualizer is an interactive web-based tool for visually inspecting and validating generated mazes. It makes it easy to spot-check the quality and correctness of generated datasets.

Quick Start

# After generating mazes
bun run visualize

# Or manually open
open visualizer.html

The visualizer will open in your default web browser and automatically load data/benchmark_maps.json.

Features

1. Visual Grid Display

Each maze is rendered as a colorful grid:

  • 🟦 Blue (P) - Player start position
  • 🟥 Red (D) - Destination/goal
  • ⬛ Dark gray (#) - Walls (impassable)
  • ⬜ Light gray (.) - Walkable tiles
  • 🟧 Orange - Optimal path (when shown)

2. Path Visualization Controls

  • Show/Hide Path - Toggle the optimal path overlay
  • Step - Advance through the path one move at a time
  • Reset - Clear the step-by-step visualization
  • Path is displayed both on the grid and as a sequence below

3. Filtering

Filter mazes by:

  • Algorithm: Recursive Backtracker, Prim's, Cellular Automata, or All
  • Size: 5x5, 10x10, 20x20, or All

Filters update the available maze pool instantly.

4. Navigation

Multiple ways to move between mazes:

  • Previous/Next buttons - Sequential navigation
  • Keyboard arrows (←/→) - Quick keyboard navigation
  • Random button (🎲) - Jump to a random maze
  • Displays "Map X / Y" to show progress

5. Information Panel

Each maze displays:

  • Map ID - Unique identifier (e.g., rb_5x5_bm_001)
  • Algorithm - Which generator created it (color-coded badge)
  • Size - Grid dimensions (inner size)
  • Path Length - Number of steps in optimal solution
  • Current Map - Position in filtered results

Keyboard Shortcuts

Key Action
→ Next maze
← Previous maze
Space Toggle path visibility

Use Cases

Spot-Checking Generation Quality

  1. Generate dataset: bun run generate
  2. Open visualizer: bun run visualize
  3. Use filters to check each algorithm
  4. Click through several maps of each size
  5. Verify paths make sense visually

Comparing Algorithms

  1. Set size filter (e.g., "10x10")
  2. Set algorithm to "Recursive Backtracker"
  3. Look at a few maps, note the structure
  4. Switch to "Prim's Algorithm"
  5. Compare the different maze structures
  6. Switch to "Cellular Automata" to see organic layouts

Validating Specific Maps

  1. If you notice an issue with a specific map ID
  2. Open the visualizer
  3. Use Previous/Next to find that specific ID
  4. Show the path to verify it's correct
  5. Step through the path to ensure each move is valid

Path Verification

  1. Select a maze
  2. Click "Show Path" to see the complete optimal route
  3. Click "Step" repeatedly to trace the path move-by-move
  4. Verify the path connects P to D
  5. Check that the path doesn't pass through walls
  6. Confirm path length matches the step count

Technical Details

Implementation

  • Pure client-side - No server required
  • Single HTML file - Fully self-contained with embedded CSS/JS
  • Responsive design - Works on desktop, tablet, and mobile
  • Fetch API - Loads data/benchmark_maps.json asynchronously

Browser Compatibility

Works in all modern browsers:

  • Chrome/Edge (recommended)
  • Firefox
  • Safari
  • Opera

Requires ES6+ support (all browsers from ~2017+).

Performance

  • Loads all 90 benchmark maps instantly
  • Smooth navigation even on large 20x20 mazes
  • Path visualization updates in real-time
  • Filters apply instantly without reloading

Troubleshooting

"Could not load maze data"

Problem: Visualizer can't find the benchmark data file.

Solution:

  1. Make sure you've generated data: bun run generate
  2. Check that data/benchmark_maps.json exists
  3. Open visualizer from the project root directory

Maze looks squished on mobile

Problem: Large mazes (20x20) might be hard to see on small screens.

Solution:

  • Use landscape orientation
  • Pinch to zoom on mobile browsers
  • The visualizer automatically scales cells for smaller screens

No mazes after filtering

Problem: Filter combination returns no results.

Solution:

  • Check that you have generated maps for that combination
  • Try "All Algorithms" and "All Sizes" to see all available maps
  • Verify the benchmark_maps.json contains data

Extending the Visualizer

Adding Fine-tuning Dataset Support

To also visualize the 900 fine-tuning maps:

  1. Modify the fetch call to load finetuning_dataset.jsonl
  2. Parse JSONL format (one JSON per line)
  3. Convert the format to match the benchmark structure
  4. Merge with or switch between datasets

Adding More Visualizations

The visualizer can be extended with:

  • Heatmap - Show which cells are visited most often
  • Statistics dashboard - Path length distribution, wall density
  • Comparison view - Side-by-side algorithm comparison
  • Animation - Animate the A* pathfinding process
  • Export - Save maze as image (PNG/SVG)

Customizing Colors

Edit the CSS variables in <style> section:

.cell-wall { background: #2c3e50; }      /* Walls */
.cell-empty { background: #ecf0f1; }     /* Empty */
.cell-start { background: #3498db; }     /* Start (P) */
.cell-destination { background: #e74c3c; } /* Goal (D) */
.cell-path { background: #f39c12; }      /* Path */

Tips for Validation

✅ Good maze characteristics:

  • Clear path from P to D
  • No isolated areas (all walkable cells connected)
  • Appropriate wall density for algorithm type
  • P and D are well-separated
  • Path doesn't pass through walls

❌ Red flags to check for:

  • P or D placed on walls
  • No visible path between P and D
  • Extremely short paths (might indicate poor placement)
  • Isolated walkable areas not connected to main maze
  • All walls or all empty (generation failure)

Examples

Recursive Backtracker Characteristics

  • Long winding corridors
  • Many dead ends
  • High path complexity
  • ~60-70% walls

Prim's Algorithm Characteristics

  • Blocky room-like areas
  • More open spaces
  • Interconnected chambers
  • ~60-70% walls

Cellular Automata Characteristics

  • Organic, irregular shapes
  • Large open caverns
  • Scattered obstacles
  • ~40-50% walls (more open)

Need help? Check the main README.md or review CLAUDE.md for implementation details.