From 20fec6461adea46e8e29a837249aba0a8cfb35bc Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Sun, 5 Jul 2020 22:12:30 +0200
Subject: [PATCH] api/_common/LightGrid: make image more efficient

Usually, images are static, so they can be computed in advance instead of during runtime. This makes scripts smaller and much more memory efficient.

For example, now you can say:

HOUSE = 4685823

hub.grid.image(HOUSE)

since 4685823 =
```
0 0 1 0 0
0 1 1 1 0
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
```

We could also choose the binary format to allow for more generic screen sizes. If we allow a bit more space (2 words instead of 1), we could do 1 byte per row to allow screens up to 8x8. Right now, though, we choose 1 word < 31 bits which is a bit more efficient in MicroPython.

We can easily list numerous example in the docs or provide a simple visual calculator.

There is still a matrix method that takes a 2D matrix of intensities for full control during runtime, which is what the image() method was doing initially. This commit renames the old draft to matrix().
---
 pybricks/_common.py | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/pybricks/_common.py b/pybricks/_common.py
index b1f009f..f769682 100644
--- a/pybricks/_common.py
+++ b/pybricks/_common.py
@@ -471,19 +471,39 @@ class LightGrid:
         """
         pass
 
-    def image(self, matrix, clear=True):
-        """Shows an image made up of pixels of a given brightness.
+    def image(self, binary, clear=True):
+        """Shows an image made up of pixels of full brightness, represented by
+        a single number.
+
+        You can use one of the built-in example images or make your own.
+
+        Arguments:
+            binary (int): Binary number representing the image. Each bit is one
+                pixel, where 1 means on and 0 means off. The least significant
+                bit is the last pixel.
+            clear (bool): Whether to turn off all the lights before showing
+                the new image. If you choose ``False``,
+                the given matrix is added to the one already shown.
+        """
+        pass
+
+    def matrix(self, matrix, clear=True):
+        """Shows an image made up of pixels of a given brightness, represented
+        by a matrix of intensity values.
+
+        Compared to :meth:`.image` you can make more refined images, but this
+        method is slower and uses more memory.
 
         Arguments:
             matrix (2D Array): Matrix of intensities (:ref:`brightness`).
             clear (bool): Whether to turn off all the lights before showing
                 the new image. If you choose ``False``,
-                the given matrix is added to one already shown.
+                the given matrix is added to the one already shown.
         """
         pass
 
     def pixel(self, row, column, brightness):
-        """Turns on a pixel at the specified brightness.
+        """Turns on one pixel at the specified brightness.
 
         Arguments:
             row (int): Vertical grid index, starting at 0 from the top.
@@ -509,7 +529,7 @@ class LightGrid:
         """Displays a number on the light grid.
 
         Arguments:
-            number (int): The number to be displayed.
+            number (int): The number to be displayed (0--99).
         """
         pass