16 releases (9 breaking)

0.10.0 Feb 21, 2021
0.9.2 Nov 1, 2020
0.9.1 Feb 15, 2020
0.8.1 Mar 3, 2019
0.4.0 Dec 30, 2018
Download history 16/week @ 2020-11-14 52/week @ 2020-11-21 17/week @ 2020-11-28 35/week @ 2020-12-05 12/week @ 2020-12-12 8/week @ 2020-12-19 2/week @ 2020-12-26 28/week @ 2021-01-02 13/week @ 2021-01-09 13/week @ 2021-01-16 19/week @ 2021-01-23 21/week @ 2021-01-30 40/week @ 2021-02-06 61/week @ 2021-02-13 48/week @ 2021-02-20 22/week @ 2021-02-27

99 downloads per month
Used in 3 crates

MIT license


Wave Function Collapse

Version Documentation

Library for generating grids of values which are similar to a specified grid. A typical use case for this is procedurally-generated images, though it generalizes to any grid of values.

Similar is defined as both:

  • strictly locally similar: every small (typically 3x3) pattern in the output image appears somewhere in the input image.
  • loosely globally similar: the distribution of small patterns in the output image is roughly the same as the distribution of small patterns in the input image.

Grids are populated using a constraint solver. For each cell, we store a probability distribution representing how likely that cell is to contain the top-left corner of possible pattern. Initially the probability of each pattern is based on its frequency in the sample image. Then, it repeatedly identifies the cell whose entropy is the lowest, and decides (randomly, weighted by probability distribution) which pattern to assign to the cell. This assignment may remove some candidate patterns from neighbouring cells, so it then updates candidate cells. This process of choosing a cell, assigning it a pattern, and propagating incompatible neighbours continues until either the entire grid is populated with values, or all the candidates are removed from a cell.

Example of Similar Images

Flowers Input -> Flowers Output1 Flowers Output2

For more image examples, see wfc-image.


This shows the process of generating an image based on the sample flowers image above. The colour of each pixel is the average of all colours which could be assigned to it, weighted by probability.

Flowers Animation


~21K SLoC