Version 0.2.0 (#2)

* Prepare version 0.2.0 branch * Updated 1-dimensional examples * Added 2-dimensional euclidean API * Added 2-dimensional toroidal API * Updated README.md
irzinfante · Jun 17, 2023 · 02f4a12 · 02f4a12
1 parent fbba649
commit 02f4a12
Show file tree

Hide file tree

Showing 75 changed files with 1,240 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ To use the ```wfc4j``` library in your Java project, you can include the library
 <dependency>
     <groupId>eu.irzinfante</groupId>
     <artifactId>wfc4j</artifactId>
-    <version>0.1.1</version>
+    <version>0.2.0</version>
 </dependency>
 ```
 
@@ -24,6 +24,9 @@ Here are some examples that demonstrate the usage of the different API of the li
 - 1-dimensional:
     - [Euclidean (linear grid)](examples/1-dimensional-euclidean.md)
     - [Toroidal (cyclic grid)](examples/1-dimensional-toroidal.md)
+- 2-dimensional:
+    - [Euclidean (planar grid)](examples/2-dimensional-euclidean.md)
+    - [Toroidal (toroidal grid)](examples/2-dimensional-toroidal.md)
 
 ## Contributing
 

diff --git a/assets/1-dimensional-euclidean/result1.png b/assets/1-dimensional-euclidean/result1.png
diff --git a/assets/1-dimensional-euclidean/result2.png b/assets/1-dimensional-euclidean/result2.png
diff --git a/assets/1-dimensional-euclidean/result3.png b/assets/1-dimensional-euclidean/result3.png
diff --git a/assets/1-dimensional-toroidal/result1.png b/assets/1-dimensional-toroidal/result1.png
diff --git a/assets/1-dimensional-toroidal/result2.png b/assets/1-dimensional-toroidal/result2.png
diff --git a/assets/2-dimensional-euclidean/NE.png b/assets/2-dimensional-euclidean/NE.png
diff --git a/assets/2-dimensional-euclidean/NW.png b/assets/2-dimensional-euclidean/NW.png
diff --git a/assets/2-dimensional-euclidean/SE.png b/assets/2-dimensional-euclidean/SE.png
diff --git a/assets/2-dimensional-euclidean/SW.png b/assets/2-dimensional-euclidean/SW.png
diff --git a/assets/2-dimensional-euclidean/result1.png b/assets/2-dimensional-euclidean/result1.png
diff --git a/assets/2-dimensional-euclidean/result2.png b/assets/2-dimensional-euclidean/result2.png
diff --git a/assets/2-dimensional-toroidal/BTBT.png b/assets/2-dimensional-toroidal/BTBT.png
diff --git a/assets/2-dimensional-toroidal/BTLB.png b/assets/2-dimensional-toroidal/BTLB.png
diff --git a/assets/2-dimensional-toroidal/BTLR.png b/assets/2-dimensional-toroidal/BTLR.png
diff --git a/assets/2-dimensional-toroidal/BTLT.png b/assets/2-dimensional-toroidal/BTLT.png
diff --git a/assets/2-dimensional-toroidal/BTRB.png b/assets/2-dimensional-toroidal/BTRB.png
diff --git a/assets/2-dimensional-toroidal/BTRT.png b/assets/2-dimensional-toroidal/BTRT.png
diff --git a/assets/2-dimensional-toroidal/BT__.png b/assets/2-dimensional-toroidal/BT__.png
diff --git a/assets/2-dimensional-toroidal/LBBT.png b/assets/2-dimensional-toroidal/LBBT.png
diff --git a/assets/2-dimensional-toroidal/LBLB.png b/assets/2-dimensional-toroidal/LBLB.png
diff --git a/assets/2-dimensional-toroidal/LBLR.png b/assets/2-dimensional-toroidal/LBLR.png
diff --git a/assets/2-dimensional-toroidal/LBLT.png b/assets/2-dimensional-toroidal/LBLT.png
diff --git a/assets/2-dimensional-toroidal/LBRB.png b/assets/2-dimensional-toroidal/LBRB.png
diff --git a/assets/2-dimensional-toroidal/LBRT.png b/assets/2-dimensional-toroidal/LBRT.png
diff --git a/assets/2-dimensional-toroidal/LB__.png b/assets/2-dimensional-toroidal/LB__.png
diff --git a/assets/2-dimensional-toroidal/LRBT.png b/assets/2-dimensional-toroidal/LRBT.png
diff --git a/assets/2-dimensional-toroidal/LRLB.png b/assets/2-dimensional-toroidal/LRLB.png
diff --git a/assets/2-dimensional-toroidal/LRLR.png b/assets/2-dimensional-toroidal/LRLR.png
diff --git a/assets/2-dimensional-toroidal/LRLT.png b/assets/2-dimensional-toroidal/LRLT.png
diff --git a/assets/2-dimensional-toroidal/LRRB.png b/assets/2-dimensional-toroidal/LRRB.png
diff --git a/assets/2-dimensional-toroidal/LRRT.png b/assets/2-dimensional-toroidal/LRRT.png
diff --git a/assets/2-dimensional-toroidal/LR__.png b/assets/2-dimensional-toroidal/LR__.png
diff --git a/assets/2-dimensional-toroidal/LTBT.png b/assets/2-dimensional-toroidal/LTBT.png
diff --git a/assets/2-dimensional-toroidal/LTLB.png b/assets/2-dimensional-toroidal/LTLB.png
diff --git a/assets/2-dimensional-toroidal/LTLR.png b/assets/2-dimensional-toroidal/LTLR.png
diff --git a/assets/2-dimensional-toroidal/LTLT.png b/assets/2-dimensional-toroidal/LTLT.png
diff --git a/assets/2-dimensional-toroidal/LTRB.png b/assets/2-dimensional-toroidal/LTRB.png
diff --git a/assets/2-dimensional-toroidal/LTRT.png b/assets/2-dimensional-toroidal/LTRT.png
diff --git a/assets/2-dimensional-toroidal/LT__.png b/assets/2-dimensional-toroidal/LT__.png
diff --git a/assets/2-dimensional-toroidal/RBBT.png b/assets/2-dimensional-toroidal/RBBT.png
diff --git a/assets/2-dimensional-toroidal/RBLB.png b/assets/2-dimensional-toroidal/RBLB.png
diff --git a/assets/2-dimensional-toroidal/RBLR.png b/assets/2-dimensional-toroidal/RBLR.png
diff --git a/assets/2-dimensional-toroidal/RBLT.png b/assets/2-dimensional-toroidal/RBLT.png
diff --git a/assets/2-dimensional-toroidal/RBRB.png b/assets/2-dimensional-toroidal/RBRB.png
diff --git a/assets/2-dimensional-toroidal/RBRT.png b/assets/2-dimensional-toroidal/RBRT.png
diff --git a/assets/2-dimensional-toroidal/RB__.png b/assets/2-dimensional-toroidal/RB__.png
diff --git a/assets/2-dimensional-toroidal/RTBT.png b/assets/2-dimensional-toroidal/RTBT.png
diff --git a/assets/2-dimensional-toroidal/RTLB.png b/assets/2-dimensional-toroidal/RTLB.png
diff --git a/assets/2-dimensional-toroidal/RTLR.png b/assets/2-dimensional-toroidal/RTLR.png
diff --git a/assets/2-dimensional-toroidal/RTLT.png b/assets/2-dimensional-toroidal/RTLT.png
diff --git a/assets/2-dimensional-toroidal/RTRB.png b/assets/2-dimensional-toroidal/RTRB.png
diff --git a/assets/2-dimensional-toroidal/RTRT.png b/assets/2-dimensional-toroidal/RTRT.png
diff --git a/assets/2-dimensional-toroidal/RT__.png b/assets/2-dimensional-toroidal/RT__.png
diff --git a/assets/2-dimensional-toroidal/__BT.png b/assets/2-dimensional-toroidal/__BT.png
diff --git a/assets/2-dimensional-toroidal/__LB.png b/assets/2-dimensional-toroidal/__LB.png
diff --git a/assets/2-dimensional-toroidal/__LR.png b/assets/2-dimensional-toroidal/__LR.png
diff --git a/assets/2-dimensional-toroidal/__LT.png b/assets/2-dimensional-toroidal/__LT.png
diff --git a/assets/2-dimensional-toroidal/__RB.png b/assets/2-dimensional-toroidal/__RB.png
diff --git a/assets/2-dimensional-toroidal/__RT.png b/assets/2-dimensional-toroidal/__RT.png
diff --git a/assets/2-dimensional-toroidal/result.png b/assets/2-dimensional-toroidal/result.png
diff --git a/examples/1-dimensional-euclidean.md b/examples/1-dimensional-euclidean.md
@@ -83,7 +83,7 @@ We will perform 3 executions of the `generate` function in order:
   System.out.println(WFCUtils.WFC1DToString(result));
   ```
 
-  <img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/B.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/B.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/R.png">
+  <img src="../assets/1-dimensional-euclidean/result1.png">
 
 - In the second one we will impose some constraint on the left end:
 
@@ -98,7 +98,7 @@ We will perform 3 executions of the `generate` function in order:
   System.out.println(WFCUtils.WFC1DToString(result));
   ```
 
-  <img src="../assets/1-dimensional-euclidean/L.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/B.png"><img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/B.png"><img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/A'.png">
+  <img src="../assets/1-dimensional-euclidean/result2.png">
 
 - In the third one we will impose constraints in both ends:
 
@@ -111,6 +111,4 @@ We will perform 3 executions of the `generate` function in order:
   System.out.println(WFCUtils.WFC1DToString(result));
   ```
 
-  <img src="../assets/1-dimensional-euclidean/L.png"><img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/B'.png"><img src="../assets/1-dimensional-euclidean/B.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/A'.png"><img src="../assets/1-dimensional-euclidean/A.png"><img src="../assets/1-dimensional-euclidean/R'.png">
-
-Following this examples, and designing other tiles and adjacencies, one can play with wfc4j library to generate very diverse braids (topology). For more information about braids you can follow this [link (Braid - Wolfram MathWorld)](https://mathworld.wolfram.com/Braid.html) and DYOR.
+  <img src="../assets/1-dimensional-euclidean/result3.png">
diff --git a/examples/1-dimensional-toroidal.md b/examples/1-dimensional-toroidal.md
@@ -75,7 +75,7 @@ We will perform 2 executions of the `generate` function in order:
   System.out.println(WFCUtils.WFC1DToString(result));
   ```
 
-  <img src="../assets/1-dimensional-toroidal/BA.png"><img src="../assets/1-dimensional-toroidal/AA.png"><img src="../assets/1-dimensional-toroidal/AB.png"><img src="../assets/1-dimensional-toroidal/BA.png"><img src="../assets/1-dimensional-toroidal/AB.png"><img src="../assets/1-dimensional-toroidal/BA.png"><img src="../assets/1-dimensional-toroidal/AB.png">
+  <img src="../assets/1-dimensional-toroidal/result1.png">
 
 - In the second one we will impose some constraint on the fifth cell:
 
@@ -90,6 +90,4 @@ We will perform 2 executions of the `generate` function in order:
   System.out.println(WFCUtils.WFC1DToString(result));
   ```
 
-  <img src="../assets/1-dimensional-toroidal/AA.png"><img src="../assets/1-dimensional-toroidal/AB.png"><img src="../assets/1-dimensional-toroidal/BB.png"><img src="../assets/1-dimensional-toroidal/BB.png"><img src="../assets/1-dimensional-toroidal/BB.png"><img src="../assets/1-dimensional-toroidal/BB.png"><img src="../assets/1-dimensional-toroidal/BA.png">
-
-Following this examples, and designing other tiles and adjacencies, one can play with wfc4j library to generate very diverse types of rings, bands, bracelets, etc.
+  <img src="../assets/1-dimensional-toroidal/result2.png">
diff --git a/examples/2-dimensional-euclidean.md b/examples/2-dimensional-euclidean.md
@@ -0,0 +1,98 @@
+# 2-dimensional euclidean grid example
+
+Let's see how to use the wfc4j library to generate a planar pattern. These are the tiles we have available:
+
+| NE  | NW  | SE  | SW  |
+|:---:|:---:|:---:|:---:|
+|<img src="../assets/2-dimensional-euclidean/NE.png">|<img src="../assets/2-dimensional-euclidean/NW.png">|<img src="../assets/2-dimensional-euclidean/SE.png">|<img src="../assets/2-dimensional-euclidean/SW.png">|
+
+```java
+import java.util.HashSet;
+import eu.irzinfante.wfc4j.model.Tile;
+
+Tile<String> NE = new Tile<>("NE"), NW = new Tile<>("NW"), SE = new Tile<>("SE"), SW = new Tile<>("SW");
+
+var tileSet = new HashSet<Tile<String>>();
+tileSet.add(NE); tileSet.add(NW); tileSet.add(SE); tileSet.add(SW);
+```
+
+So, the logical adjacencies between tiles are the following:
+
+
+| Tile | Left adjacent tiles   | Right adjacent tiles   | Bottom adjacent tiles  | Top adjacent tiles     |
+|:----:|:---------------------:|:----------------------:|:----------------------:|:----------------------:|
+|<img src="../assets/2-dimensional-euclidean/NE.png">|<img src="../assets/2-dimensional-euclidean/NW.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/NW.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/SE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/SE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|
+|<img src="../assets/2-dimensional-euclidean/NW.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SE.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SE.png">|<img src="../assets/2-dimensional-euclidean/SE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/SE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|
+|<img src="../assets/2-dimensional-euclidean/SE.png">|<img src="../assets/2-dimensional-euclidean/NW.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/NW.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/NW.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/NW.png">|
+|<img src="../assets/2-dimensional-euclidean/SW.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SE.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/SE.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/NW.png">|<img src="../assets/2-dimensional-euclidean/NE.png"> $~~~~$ <img src="../assets/2-dimensional-euclidean/NW.png">|
+
+```java
+import eu.irzinfante.wfc4j.model.TileMap2D;
+import eu.irzinfante.wfc4j.enums.Side2D;
+
+var adjacentNWSW = new HashSet<Tile<String>>();
+adjacentNWSW.add(NW); adjacentNWSW.add(SW);
+
+var adjacentSESW = new HashSet<Tile<String>>();
+adjacentSESW.add(SE); adjacentSESW.add(SW);
+
+var adjacentNESE = new HashSet<Tile<String>>();
+adjacentNESE.add(NE); adjacentNESE.add(SE);
+
+var adjacentNENW = new HashSet<Tile<String>>();
+adjacentNENW.add(NE); adjacentNENW.add(NW);
+
+var tileMap = new TileMap2D<>(tileSet);
+
+tileMap.setAdjacents(NE, Side2D.Left, adjacentNWSW);	tileMap.setAdjacents(NE, Side2D.Right, adjacentNWSW);
+tileMap.setAdjacents(NE, Side2D.Bottom, adjacentSESW);	tileMap.setAdjacents(NE, Side2D.Top, adjacentSESW);
+
+tileMap.setAdjacents(NW, Side2D.Left, adjacentNESE);	tileMap.setAdjacents(NW, Side2D.Right, adjacentNESE);
+tileMap.setAdjacents(NW, Side2D.Bottom, adjacentSESW);	tileMap.setAdjacents(NW, Side2D.Top, adjacentSESW);
+
+tileMap.setAdjacents(SE, Side2D.Left, adjacentNWSW);	tileMap.setAdjacents(SE, Side2D.Right, adjacentNWSW);
+tileMap.setAdjacents(SE, Side2D.Bottom, adjacentNENW);	tileMap.setAdjacents(SE, Side2D.Top, adjacentNENW);
+
+tileMap.setAdjacents(SW, Side2D.Left, adjacentNESE);	tileMap.setAdjacents(SW, Side2D.Right, adjacentNESE);
+tileMap.setAdjacents(SW, Side2D.Bottom, adjacentNENW);	tileMap.setAdjacents(SW, Side2D.Top, adjacentNENW);
+```
+
+Now we can instantiate the API class with an 8 by 6 grid:
+
+```java
+import eu.irzinfante.wfc4j.api.WaveFunctionCollapseEuclidean2D;
+
+int gridSizeX = 8, gridSizeY = 6;
+var WFC = new WaveFunctionCollapseEuclidean2D<String>(tileMap, gridSizeX, gridSizeY, 148576907989080L);
+```
+
+We will perform 2 executions of the `generate` function in order:
+
+- For the first one we won't impose any restriction:
+
+  ```java
+  import eu.irzinfante.wfc4j.util.WFCUtils;
+
+  WFC.clear();
+  var result = WFC.generate();
+
+  System.out.println(WFCUtils.WFC2DToString(result));
+  ```
+
+  <img src="../assets/2-dimensional-euclidean/result1.png">
+
+- For the second one we will impose some constraint on the center of the grid:
+
+  ```java
+  import java.util.Arrays;
+  import eu.irzinfante.wfc4j.model.Cell2D;
+
+  WFC.clear();
+  WFC.setCellConstraint(new Cell2D<>(new HashSet<>(Arrays.asList(SE)), 4, 3));
+  WFC.setCellConstraint(new Cell2D<>(new HashSet<>(Arrays.asList(NW)), 5, 4));
+  result = WFC.generate();
+
+  System.out.println(WFCUtils.WFC2DToString(result));
+  ```
+
+  <img src="../assets/2-dimensional-euclidean/result2.png">
diff --git a/examples/2-dimensional-toroidal.md b/examples/2-dimensional-toroidal.md
@@ -0,0 +1,124 @@
+# 2-dimensional toroidal grid example
+
+In this example we will see how to use the wfc4j library to generate a 2D toroidal pattern with programmatically constructed tiles. Each tile will be the combination of two components.
+
+- First component:
+
+| LR__ | LB__ | LT__ | RB__ | RT__ | BT__ |
+|:----:|:----:|:----:|:----:|:----:|:----:|
+|<img src="../assets/2-dimensional-toroidal/LR__.png">|<img src="../assets/2-dimensional-toroidal/LB__.png">|<img src="../assets/2-dimensional-toroidal/LT__.png">|<img src="../assets/2-dimensional-toroidal/RB__.png">|<img src="../assets/2-dimensional-toroidal/RT__.png">|<img src="../assets/2-dimensional-toroidal/BT__.png">|
+
+- Second component:
+
+| __LR | __LB | __LT | __RB | __RT | __BT |
+|:----:|:----:|:----:|:----:|:----:|:----:|
+|<img src="../assets/2-dimensional-toroidal/__LR.png">|<img src="../assets/2-dimensional-toroidal/__LB.png">|<img src="../assets/2-dimensional-toroidal/__LT.png">|<img src="../assets/2-dimensional-toroidal/__RB.png">|<img src="../assets/2-dimensional-toroidal/__RT.png">|<img src="../assets/2-dimensional-toroidal/__BT.png">|
+
+And therefore the adjacency of the tiles will be based on how the two components of each tile fit together with the components of the adjacent tiles. In our example this is computed like this:
+
+```java
+import eu.irzinfante.wfc4j.enums.Side2D;
+import eu.irzinfante.wfc4j.exceptions.DimensionException;
+import eu.irzinfante.wfc4j.exceptions.TileException;
+import eu.irzinfante.wfc4j.model.Tile;
+import eu.irzinfante.wfc4j.model.TileMap2D;
+
+final String LR = "LR", LB = "LB", LT = "LT", RB = "RB", RT = "RT",   BT = "BT";
+final var components = new String[] {LR, LB, LT, RB, RT, BT};
+
+var tileSet = new HashSet<Tile<String>>();
+for(var first : components) {
+	for(var second : components) {
+		tileSet.add(new Tile<>(first + second));
+	}
+}
+
+var tileMap = new TileMap2D<>(tileSet);
+
+for(var tile : tileSet) {
+	var tileFirstLeft = tile.getValue().substring(0, 2).contains("L");
+	var tileSecondLeft = tile.getValue().substring(2, 4).contains("L");
+	var leftAdjacents = new HashSet<Tile<String>>();
+
+	var tileFirstRight = tile.getValue().substring(0, 2).contains("R");
+	var tileSecondRight = tile.getValue().substring(2, 4).contains("R");
+	var rightAdjacents = new HashSet<Tile<String>>();
+
+	var tileFirstBottom = tile.getValue().substring(0, 2).contains("B");
+	var tileSecondBottom = tile.getValue().substring(2, 4).contains("B");
+	var bottomAdjacents = new HashSet<Tile<String>>();
+
+	var tileFirstTop = tile.getValue().substring(0, 2).contains("T");
+	var tileSecondTop = tile.getValue().substring(2, 4).contains("T");
+	var topAdjacents = new HashSet<Tile<String>>();
+
+	for(var adjacent : tileSet) {
+		var adjacentFirstLeft = adjacent.getValue().substring(0, 2).contains("L");
+		var adjacentSecondLeft = adjacent.getValue().substring(2, 4).contains("L");
+		if( (tileFirstRight && adjacentFirstLeft && tileSecondRight && adjacentSecondLeft) ||
+			(tileFirstRight && adjacentFirstLeft && !tileSecondRight && !adjacentSecondLeft) ||
+			(!tileFirstRight && !adjacentFirstLeft && tileSecondRight && adjacentSecondLeft) ||
+			(!tileFirstRight && !adjacentFirstLeft && !tileSecondRight && !adjacentSecondLeft)
+		) {
+			rightAdjacents.add(adjacent);
+		}
+
+		var adjacentFirstRight = adjacent.getValue().substring(0, 2).contains("R");
+		var adjacentSecondRight = adjacent.getValue().substring(2, 4).contains("R");
+		if( (tileFirstLeft && adjacentFirstRight && tileSecondLeft && adjacentSecondRight) ||
+			(tileFirstLeft && adjacentFirstRight && !tileSecondLeft && !adjacentSecondRight) ||
+			(!tileFirstLeft && !adjacentFirstRight && tileSecondLeft && adjacentSecondRight) ||
+			(!tileFirstLeft && !adjacentFirstRight && !tileSecondLeft && !adjacentSecondRight)
+		) {
+			leftAdjacents.add(adjacent);
+		}
+
+		var adjacentFirstTop = adjacent.getValue().substring(0, 2).contains("T");
+		var adjacentSecondTop = adjacent.getValue().substring(2, 4).contains("T");
+		if( (tileFirstBottom && adjacentFirstTop && tileSecondBottom && adjacentSecondTop) ||
+			(tileFirstBottom && adjacentFirstTop && !tileSecondBottom && !adjacentSecondTop) ||
+			(!tileFirstBottom && !adjacentFirstTop && tileSecondBottom && adjacentSecondTop) ||
+			(!tileFirstBottom && !adjacentFirstTop && !tileSecondBottom && !adjacentSecondTop)
+		) {
+			bottomAdjacents.add(adjacent);
+		}
+
+		var adjacentFirstBottom = adjacent.getValue().substring(0, 2).contains("B");
+		var adjacentSecondBottom = adjacent.getValue().substring(2, 4).contains("B");
+		if( (tileFirstTop && adjacentFirstBottom && tileSecondTop && adjacentSecondBottom) ||
+			(tileFirstTop && adjacentFirstBottom && !tileSecondTop && !adjacentSecondBottom) ||
+			(!tileFirstTop && !adjacentFirstBottom && tileSecondTop && adjacentSecondBottom) ||
+			(!tileFirstTop && !adjacentFirstBottom && !tileSecondTop && !adjacentSecondBottom)
+		) {
+			topAdjacents.add(adjacent);
+		}
+	}
+
+	tileMap.setAdjacents(tile, Side2D.Left, leftAdjacents);
+	tileMap.setAdjacents(tile, Side2D.Right, rightAdjacents);
+	tileMap.setAdjacents(tile, Side2D.Bottom, bottomAdjacents);
+	tileMap.setAdjacents(tile, Side2D.Top, topAdjacents);
+}
+```
+
+> Please, take your time on understanding the code above.
+
+Now we can instantiate the API class with an 6 by 6 grid:
+
+```java
+import eu.irzinfante.wfc4j.api.WaveFunctionCollapseToroidal2D;
+
+int gridSizeX = 6, gridSizeY = 6;
+var WFC = new WaveFunctionCollapseToroidal2D<String>(tileMap, gridSizeX, gridSizeY, 103478937644546L);
+```
+
+Finally we will perform the excution of the `generate` function:
+
+```java
+import eu.irzinfante.wfc4j.util.WFCUtils;
+
+var result = WFC.generate();
+System.out.println(WFCUtils.WFC2DToString(result));
+```
+
+<img src="../assets/2-dimensional-toroidal/result.png">
diff --git a/pom.xml b/pom.xml
@@ -3,7 +3,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>eu.irzinfante</groupId>
 	<artifactId>wfc4j</artifactId>
-	<version>0.1.1</version>
+	<version>0.2.0</version>
 	<packaging>jar</packaging>
 
 	<properties>