Merge pull request #239 from blind-coder/mapping_wh

add examples for 2D maps

docs/advanced/mapping.md

@@ -46,3 +46,38 @@ It could be formatted any of the three ways demonstrated above.
 {"map":[0, 1, 2, 3, 4, 9, 8, 7, 6, 5, 10, 11, 12, 13, 14,
 19, 18, 17, 16, 15, 20, 21, 22, 23, 24, 29, 28, 27, 26, 25]}
 ```
+
+The following example shows how to create a `ledmap.json` for LEDs arranged in a two-dimensional grid intead of a one-dimensional string.
+
+Here, we have a serpentine of LEDs in 4 columns and 3 rows:
+```json
+{
+  "map": [
+    0, 1,  2,  3,
+    7, 6,  5,  4,
+    8, 9, 10, 11
+  ],
+  "width":  4,
+  "height": 3
+}
+```
+
+![wiring diagram of the 4x3 mapping](mapping/mapping_4x3.png)
+
+A more complex example of 16 LEDs arrange in a double figure `∞` shape. This includes some missing LEDs showing up as `-1`.
+Note that if a `ledmap.json` file exists, the `2d-gaps.json` file will be ignored.
+```json
+{"map":
+  [
+    -1, -1, 14, -1, 12, -1, 10, -1, -1,
+    -1, 15, -1, 13, -1, 11, -1,  9, -1,
+     0, -1, -1, -1, -1, -1, -1, -1,  8,
+    -1,  1, -1,  3, -1,  5, -1,  7, -1,
+    -1, -1,  2, -1,  4, -1,  6, -1, -1
+  ],
+  "width":  9,
+  "height": 5
+}
+```
+
+![wiring diagram of the double ∞ shape mapping](mapping/mapping_infinity_shape.png)