Adds support for RLE compression to BMPs

Fixes #20

RLE compression is allowed on 4-bit and 8-bit BMP images. This commit adds
handling for compression levels 1 and 2.

It adds 2 tiny test files for the 4-bit and 8-bit depths, since the
algorithm differs slightly between them. It also includes a version
of the color_wheel.bmp encoded with 8-bit RLE. I cut the image in half
horizontally so that it would load on the PyGamer, which couldn't
allocate the full Bitmap (presumably due to heap fragmentation).

Author: fionawhim

adafruit_imageload/bmp/__init__.py

@@ -51,14 +51,19 @@ def load(file, *, bitmap=None, palette=None):
     height = int.from_bytes(file.read(4), 'little')
     file.seek(0x1c) # Number of bits per pixel
     color_depth = int.from_bytes(file.read(2), 'little')
+    file.seek(0x1e) # Compression type
+    compression = int.from_bytes(file.read(2), 'little')
     file.seek(0x2e) # Number of colors in the color palette
     colors = int.from_bytes(file.read(4), 'little')
 
     if colors == 0 and color_depth >= 16:
         raise NotImplementedError("True color BMP unsupported")
 
+    if compression > 2:
+        raise NotImplementedError("bitmask compression unsupported")
+
     if colors == 0:
         colors = 2 ** color_depth
     from . import indexed
-    return indexed.load(file, width, height, data_start, colors, color_depth, bitmap=bitmap,
+    return indexed.load(file, width, height, data_start, colors, color_depth, compression, bitmap=bitmap,
                         palette=palette)

adafruit_imageload/bmp/indexed.py

@@ -32,15 +32,16 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_ImageLoad.git"
 
-def load(file, width, height, data_start, colors, color_depth, *, bitmap=None, palette=None):
+def load(file, width, height, data_start, colors, color_depth, compression, *, bitmap=None, palette=None):
     """Loads indexed bitmap data into bitmap and palette objects.
 
        :param file file: The open bmp file
        :param int width: Image width in pixels
        :param int height: Image height in pixels
        :param int data_start: Byte location where the data starts (after headers)
        :param int colors: Number of distinct colors in the image
-       :param int color_depth: Number of bits used to store a value"""
+       :param int color_depth: Number of bits used to store a value
+       :param int compression: 0 - none, 1 - 8bit RLE, 2 - 4bit RLE"""
     # pylint: disable=too-many-arguments,too-many-locals
     if palette:
         palette = palette(colors)
@@ -70,7 +71,6 @@ def load(file, width, height, data_start, colors, color_depth, *, bitmap=None, p
         if line_size % 4 != 0:
             line_size += (4 - line_size % 4)
 
-        chunk = bytearray(line_size)
         mask = (1 << minimum_color_depth) - 1
         if height > 0:
             range1 = height - 1
@@ -80,14 +80,138 @@ def load(file, width, height, data_start, colors, color_depth, *, bitmap=None, p
             range1 = 0
             range2 = abs(height)
             range3 = 1
-        for y in range(range1, range2, range3):
-            file.readinto(chunk)
-            pixels_per_byte = 8 // color_depth
-            offset = y * width
-
-            for x in range(width):
-                i = x // pixels_per_byte
-                pixel = (chunk[i] >> (8 - color_depth*(x % pixels_per_byte + 1))) & mask
-                bitmap[offset + x] = pixel
+
+        if compression == 0:
+            chunk = bytearray(line_size)
+            for y in range(range1, range2, range3):
+                file.readinto(chunk)
+                pixels_per_byte = 8 // color_depth
+                offset = y * width
+
+                for x in range(width):
+                    i = x // pixels_per_byte
+                    pixel = (chunk[i] >> (8 - color_depth*(x % pixels_per_byte + 1))) & mask
+                    bitmap[offset + x] = pixel
+        elif compression == 1 or compression == 2:
+            # RLE algorithm, either 8-bit (1) or 4-bit (2)
+            #
+            # Ref: http://www.fileformat.info/format/bmp/egff.htm
+
+            is_4bit = compression == 2
+
+            # This will store the 2-byte run commands, which are either an
+            # amount to repeat and a value to repeat, or a 0x00 and command
+            # marker.
+            run_buf = bytearray(2)
+
+            # We need to be prepared to load up to 256 pixels of literal image
+            # data. (0xFF is max literal length, but odd literal runs are padded
+            # up to an even byte count, so we need space for 256 in the case of
+            # 8-bit.) 4-bit images can get away with half that.
+            literal_buf = bytearray(128 if is_4bit else 256)
+
+            # We iterate with numbers rather than a range because the "delta"
+            # command can cause us to jump forward arbitrarily in the output
+            # image.
+            #
+            # In theory RLE images are only stored in bottom-up scan line order,
+            # but we support either.
+            y = range1
+            x = 0
+
+            while y * range3 < range2 * range3:
+                offset = y * width + x
+
+                # We keep track of how much space is left in our row so that we
+                # can avoid writing extra data outside of the Bitmap. While the
+                # reference above seems to say that the "end run" command is
+                # optional and that image data should wrap from one scan line to
+                # the next, in practice (looking at the output of ImageMagick
+                # and GIMP, and what Preview renders) the bitmap part of the
+                # image can contain data that goes beyond the image’s stated
+                # width that should just be ignored. For example, the 8bit RLE
+                # file is 15px wide but has data for 16px.
+                width_remaining = width - x
+
+                file.readinto(run_buf)
+
+                if run_buf[0] == 0:
+                    # A repeat length of "0" is a special command. The next byte
+                    # tells us what needs to happen.
+                    if run_buf[1] == 0:
+                        # end of the current scan line
+                        y = y + range3
+                        x = 0
+                    elif run_buf[1] == 1:
+                        # end of image
+                        break
+                    elif run_buf[1] == 2:
+                        # delta command jumps us ahead in the bitmap output by
+                        # the x, y amounts stored in the next 2 bytes.
+                        file.readinto(run_buf)
+
+                        x = x + run_buf[0]
+                        y = y + run_buf[1] * range3
+                    else:
+                        # command values of 3 or more indicate that many pixels
+                        # of literal (uncompressed) image data. For 8-bit mode,
+                        # this is raw bytes, but 4-bit mode counts in nibbles.
+                        literal_length_px = run_buf[1]
+
+                        # Inverting the value here to get round-up integer division 
+                        read_length_bytes = -(-literal_length_px // 2) if is_4bit else literal_length_px
+
+                        # If the run has an odd length then there’s a 1-byte padding
+                        # we need to consume but not write into the output
+                        if read_length_bytes % 2 == 1:
+                            read_length_bytes += 1
+
+                        # We use memoryview to artificially limit the length of
+                        # literal_buf so that readinto only reads the amount
+                        # that we want.
+                        literal_buf_mem = memoryview(literal_buf)
+                        file.readinto(literal_buf_mem[0:read_length_bytes])
+
+                        if is_4bit:
+                            for i in range(0, min(literal_length_px, width_remaining)):
+                                # Expanding the two nibbles of the 4-bit data
+                                # into two bytes for our output bitmap.
+                                if i % 2 == 0:
+                                    bitmap[offset + i] = literal_buf[i // 2] >> 4
+                                else: 
+                                    bitmap[offset + i] = literal_buf[i // 2] & 0x0F
+                        else:
+                            # 8-bit values are just a raw copy (limited by
+                            # what’s left in the row so we don’t overflow out of
+                            # the buffer)
+                            for i in range(0, min(literal_length_px, width_remaining)):
+                                bitmap[offset + i] = literal_buf[i]
+
+                        x = x + literal_length_px
+                else:
+                    # first byte was not 0, which means it tells us how much to
+                    # repeat the next byte into the output
+                    run_length_px = run_buf[0]
+
+                    if is_4bit:
+                        # In 4 bit mode, we repeat the *two* values that are
+                        # packed into the next byte. The repeat amount is based
+                        # on pixels, not bytes, though, so if we were to repeat
+                        # 0xab 3 times, the output pixel values would be: 0x0a
+                        # 0x0b 0x0a (notice how it ends at 0x0a) rather than
+                        # 0x0a 0x0b 0x0a 0x0b 0x0a 0x0b
+                        run_values = [
+                            run_buf[1] >> 4,
+                            run_buf[1] & 0x0F
+                        ]
+                        for i in range(0, min(run_length_px, width_remaining)):
+                            bitmap[offset + i] = run_values[i % 2]
+                    else:
+                        run_value = run_buf[1]
+                        for i in range(0, min(run_length_px, width_remaining)):
+                            bitmap[offset + i] = run_value
+
+
+                    x = x + run_length_px
 
     return bitmap, palette