developing.rst
1 """"""""""""""""" 2 Developing 3 """"""""""""""""" 4 5 Strategy: 6 * read headers to determine file type 7 * keep a pointer to the start of data 8 * read data into the Palette for all colors present 9 * rewind the file pointer back to start of data 10 * read data into the Bitmap 11 * return a bitmap and palette instance 12 13 Shared Bindings 14 =============== 15 16 This library uses interfaces from CircuitPython's `displayio` module (Bitmap and Palette) to load images from disk into memory. 17 18 The Bitmap and Palette objects are related, and together can be used to display the image on a screen for the user. 19 20 21 22 The Palette is a list of colors present in the image. 23 Its constructor takes a single argument: (int) max_colors, representing how many colors will be populated in the palette. 24 25 26 ==================== 27 Palette code example 28 ==================== 29 30 .. code:: python 31 32 palette = Palette(4) # 4 represents that we will define four colors in palette 33 palette[0] = b'\x00\x00\x00\x00' # white 34 palette[1] = b'\xFF\x00\x00\x00' # red 35 palette[2] = b'\x00\xFF\x00\x00' # green 36 palette[3] = b'\x00\x00\xFF\x00' # blue 37 38 39 ==================== 40 Bitmap code example 41 ==================== 42 43 .. code:: python 44 45 bitmap = Bitmap(3, 2, 4) # 3 pixels wide, two pixels tall, 4 colors 46 bitmap[0,0] = 0 # palette color 0 47 bitmap[0,1] = 1 # palette color 1 48 ... 49 50 ============================ 51 Example of Palette and Image 52 ============================ 53 54 The example is 4bit.bmp from the examples/images folder: 55 56 .. image:: ../examples/images/4bit.bmp 57 :height: 17 58 :width: 15 59 :alt: 4bit image 60 61 The Palette object appears like this after loading:: 62 63 Palette: 64 [0] b'\x00\x00\x00\x00' 65 [1] b'\x7f\x00\x00\x00' 66 [2] b'\xff\x00\x00\x00' 67 [3] b'w\x00\xb1\x00' 68 [4] b'\xff\x00\x9d\x00' 69 [5] b'\x00\x00\xff\x00' 70 [6] b'\xff\x00\xfe\x00' 71 [7] b'\xbf\x80\x00\x00' 72 [8] b'zzz\x00' 73 [9] b'\xff\x9e\xa5\x00' 74 [10] b'\x00\x98\xff\x00' 75 [11] b'\x00\xff\x00\x00' 76 [12] b'h\xff\x00\x00' 77 [13] b'\xfb\xff\x9e\x00' 78 [14] b'\x00\xfb\xff\x00' 79 [15] b'\xfb\xfb\xfb\x00' 80 81 This palette has 16 colors. The value in square brackets [] is the color's index in the palette. The byte values are the RGB or RGB + padding of each color. 82 83 The Bitmap is an grid of which palette color to use in each position of the image. 84 85 The corresponding Bitmap to the example above appears like this after loading:: 86 87 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 88 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 89 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 90 11 11 11 5 5 5 15 15 15 5 5 5 2 2 2 91 11 11 11 5 5 5 15 15 15 5 5 5 2 2 2 92 6 6 6 5 5 5 1 1 1 5 5 5 10 10 10 93 6 6 6 5 5 5 1 1 1 5 5 5 10 10 10 94 6 6 6 5 5 5 1 1 1 5 5 5 10 10 10 95 14 14 14 5 5 5 9 9 9 5 5 5 8 8 8 96 14 14 14 5 5 5 9 9 9 5 5 5 8 8 8 97 14 14 14 5 5 5 9 9 9 5 5 5 8 8 8 98 3 3 3 5 5 5 0 0 0 5 5 5 13 13 13 99 3 3 3 5 5 5 0 0 0 5 5 5 13 13 13 100 4 4 4 5 5 5 12 12 12 5 5 5 7 7 7 101 4 4 4 5 5 5 12 12 12 5 5 5 7 7 7 102 4 4 4 5 5 5 12 12 12 5 5 5 7 7 7 103 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 104 105 This grid represents the example image (``15 pixels wide`` and ``17 pixels tall``). 106 The coordinates are arranged in a zero indexed grid, starting in the top left at ``[0,0]``, 107 and continuing down and to the right to a final coordinate of ``[14,16]``. 108 109 110 The value at each position is an integer, representing an entry in the palette object. 111 112 113 114 For example, the Bitmap coordinate ``[0,0]`` has the value (integer) ``5``. 115 116 117 This corresponds to the the Palette object's, ``[5]`` which is ``b'\x00\x00\xff\x00'``. This is a byte string that represents a color.