Algorithm Visualizer

WFC Visualizer

A live, interactive Wave Function Collapse visualizer whose real Python and NumPy engine runs in the browser through Pyodide, so a paintable sample drives an animated overlapping WFC solve with no server and no per-step round-trips.

Python

NumPy

Pyodide

WebAssembly

JavaScript

Live Code

Employer signal

What This Project Shows

This project shows that I can implement a non-trivial constraint-solving algorithm from first principles, then make it genuinely interactive in the browser by running the actual Python engine in WebAssembly instead of porting or faking it.

Problem

What Needed To Be Solved

Wave Function Collapse is usually shown as a finished GIF or buried in a game pipeline, which hides how it works. I wanted a visualizer where you can paint the source sample, change pattern size and symmetry, and step through the solve from the initial all-possible wave — but doing that smoothly over thousands of steps rules out a network round-trip per step, and rewriting the engine in JavaScript would have meant maintaining two implementations.

Approach

How I Built The Solution

I wrote the engine as plain Python and NumPy split into focused modules, then ran that exact code in the browser through Pyodide (CPython compiled to WebAssembly). The web UI keeps a long-lived Pyodide session alive so Play, Pause, and Step operate on real solver state, and the whole thing ships as static files on GitHub Pages with no build step.

Outcome

What It Demonstrates

The WFC Visualizer demonstrates algorithm implementation, NumPy-level data modeling, and the ability to deliver a real Python engine as a fast, server-free interactive web app through WebAssembly.

Technical Signals

Constraint propagation

Wave Function Collapse

NumPy

Pyodide / WebAssembly

Static-site deployment

Python test suite

Implementation Notes

Implemented overlapping WFC in four stages: slide an N×N window to extract unique patterns and weights (with optional D4 symmetry), precompute a `compatible[4, T, T]` overlap-agreement table, collapse the lowest-entropy cell by weighted random choice and propagate the boolean possibility masks, and restart on contradiction.
Kept the engine as a plain Python package — `patterns.py`, `adjacency.py`, `solver.py`, `render.py`, `samples.py` — so the same code runs under CPython locally and under Pyodide in the browser with no fork.
Drove the animation from a persistent Pyodide session: Generate spins up a fresh session and plays, Step 0 creates the same fresh session but stays paused so the initial wave can be inspected, and render maps unresolved cells to their averaged possible-pattern colours.
Covered pattern extraction, adjacency, rendering, and solver behaviour with a pytest suite, and deployed straight from the repo with `.nojekyll` so Jekyll does not drop the `_`-prefixed `wfc/__init__.py` and break the import.

Evidence From Source

Source signal

The `wfc/` package precomputes adjacency into a `compatible[4, T, T]` table so propagation is a lookup, collapses the minimum-entropy cell with weighted random choice, and raises a `Contradiction` that triggers a restart — and the browser build fetches those same `wfc/*.py` files and imports them through Pyodide.

Engineering decision

Running the unmodified Python engine in WebAssembly instead of rewriting it in JavaScript is the key call: it keeps one tested implementation, allows smooth per-step animation without a server, and made the deploy a static GitHub Pages upload.