displayio/tilegrid.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2020 Melissa LeBlanc-Williams for Adafruit Industries
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a copy
   6 # of this software and associated documentation files (the "Software"), to deal
   7 # in the Software without restriction, including without limitation the rights
   8 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 # copies of the Software, and to permit persons to whom the Software is
  10 # furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included in
  13 # all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21 # THE SOFTWARE.
  22
  23 """
  24 `displayio.tilegrid`
  25 ================================================================================
  26
  27 displayio for Blinka
  28
  29 **Software and Dependencies:**
  30
  31 * Adafruit Blinka:
  32   https://github.com/adafruit/Adafruit_Blinka/releases
  33
  34 * Author(s): Melissa LeBlanc-Williams
  35
  36 """
  37
  38 from recordclass import recordclass
  39 from PIL import Image
  40 from displayio.bitmap import Bitmap
  41 from displayio.colorconverter import ColorConverter
  42 from displayio.ondiskbitmap import OnDiskBitmap
  43 from displayio.shape import Shape
  44 from displayio.palette import Palette
  45
  46 __version__ = "0.0.0-auto.0"
  47 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  48
  49 Rectangle = recordclass("Rectangle", "x1 y1 x2 y2")
  50 Transform = recordclass("Transform", "x y dx dy scale transpose_xy mirror_x mirror_y")
  51
  52 # pylint: disable=too-many-instance-attributes
  53 class TileGrid:
  54     """Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple
  55     grids can share bitmaps and pixel shaders.
  56
  57     A single tile grid is also known as a Sprite.
  58     """
  59
  60     def __init__(
  61         self,
  62         bitmap,
  63         *,
  64         pixel_shader,
  65         width=1,
  66         height=1,
  67         tile_width=None,
  68         tile_height=None,
  69         default_tile=0,
  70         x=0,
  71         y=0
  72     ):
  73         """Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is
  74         used to convert the value and its location to a display native pixel color. This may
  75         be a simple color palette lookup, a gradient, a pattern or a color transformer.
  76
  77         tile_width and tile_height match the height of the bitmap by default.
  78         """
  79         if not isinstance(bitmap, (Bitmap, OnDiskBitmap, Shape)):
  80             raise ValueError("Unsupported Bitmap type")
  81         self._bitmap = bitmap
  82         bitmap_width = bitmap.width
  83         bitmap_height = bitmap.height
  84
  85         if pixel_shader is not None and not isinstance(
  86             pixel_shader, (ColorConverter, Palette)
  87         ):
  88             raise ValueError("Unsupported Pixel Shader type")
  89         self._pixel_shader = pixel_shader
  90         if isinstance(self._pixel_shader, ColorConverter):
  91             self._pixel_shader._rgba = True  # pylint: disable=protected-access
  92         self._hidden = False
  93         self._x = x
  94         self._y = y
  95         self._width = width  # Number of Tiles Wide
  96         self._height = height  # Number of Tiles High
  97         self._transpose_xy = False
  98         self._flip_x = False
  99         self._flip_y = False
 100         self._top_left_x = 0
 101         self._top_left_y = 0
 102         if tile_width is None or tile_width == 0:
 103             tile_width = bitmap_width
 104         if tile_height is None or tile_width == 0:
 105             tile_height = bitmap_height
 106         if tile_width < 1:
 107             tile_width = 1
 108         if tile_height < 1:
 109             tile_height = 1
 110         if bitmap_width % tile_width != 0:
 111             raise ValueError("Tile width must exactly divide bitmap width")
 112         self._tile_width = tile_width
 113         if bitmap_height % tile_height != 0:
 114             raise ValueError("Tile height must exactly divide bitmap height")
 115         self._tile_height = tile_height
 116         if not 0 <= default_tile <= 255:
 117             raise ValueError("Default Tile is out of range")
 118         self._pixel_width = width * tile_width
 119         self._pixel_height = height * tile_height
 120         self._tiles = (self._width * self._height) * [default_tile]
 121         self.in_group = False
 122         self._absolute_transform = Transform(0, 0, 1, 1, 1, False, False, False)
 123         self._current_area = Rectangle(0, 0, self._pixel_width, self._pixel_height)
 124         self._moved = False
 125
 126     def update_transform(self, absolute_transform):
 127         """Update the parent transform and child transforms"""
 128         self._absolute_transform = absolute_transform
 129         if self._absolute_transform is not None:
 130             self._update_current_x()
 131             self._update_current_y()
 132
 133     def _update_current_x(self):
 134         if self._transpose_xy:
 135             width = self._pixel_height
 136         else:
 137             width = self._pixel_width
 138         if self._absolute_transform.transpose_xy:
 139             self._current_area.y1 = (
 140                 self._absolute_transform.y + self._absolute_transform.dy * self._x
 141             )
 142             self._current_area.y2 = (
 143                 self._absolute_transform.y
 144                 + self._absolute_transform.dy * (self._x + width)
 145             )
 146             if self._current_area.y2 < self._current_area.y1:
 147                 self._current_area.y1, self._current_area.y2 = (
 148                     self._current_area.y2,
 149                     self._current_area.y1,
 150                 )
 151         else:
 152             self._current_area.x1 = (
 153                 self._absolute_transform.x + self._absolute_transform.dx * self._x
 154             )
 155             self._current_area.x2 = (
 156                 self._absolute_transform.x
 157                 + self._absolute_transform.dx * (self._x + width)
 158             )
 159             if self._current_area.x2 < self._current_area.x1:
 160                 self._current_area.x1, self._current_area.x2 = (
 161                     self._current_area.x2,
 162                     self._current_area.x1,
 163                 )
 164
 165     def _update_current_y(self):
 166         if self._transpose_xy:
 167             height = self._pixel_width
 168         else:
 169             height = self._pixel_height
 170         if self._absolute_transform.transpose_xy:
 171             self._current_area.x1 = (
 172                 self._absolute_transform.x + self._absolute_transform.dx * self._y
 173             )
 174             self._current_area.x2 = (
 175                 self._absolute_transform.x
 176                 + self._absolute_transform.dx * (self._y + height)
 177             )
 178             if self._current_area.x2 < self._current_area.x1:
 179                 self._current_area.x1, self._current_area.x2 = (
 180                     self._current_area.x2,
 181                     self._current_area.x1,
 182                 )
 183         else:
 184             self._current_area.y1 = (
 185                 self._absolute_transform.y + self._absolute_transform.dy * self._y
 186             )
 187             self._current_area.y2 = (
 188                 self._absolute_transform.y
 189                 + self._absolute_transform.dy * (self._y + height)
 190             )
 191             if self._current_area.y2 < self._current_area.y1:
 192                 self._current_area.y1, self._current_area.y2 = (
 193                     self._current_area.y2,
 194                     self._current_area.y1,
 195                 )
 196
 197     def _shade(self, pixel_value):
 198         if isinstance(self._pixel_shader, Palette):
 199             return self._pixel_shader[pixel_value]["rgba"]
 200         if isinstance(self._pixel_shader, ColorConverter):
 201             return self._pixel_shader.convert(pixel_value)
 202         return pixel_value
 203
 204     def _apply_palette(self, image):
 205         image.putpalette(
 206             self._pixel_shader._get_palette()  # pylint: disable=protected-access
 207         )
 208
 209     def _add_alpha(self, image):
 210         alpha = self._bitmap._image.copy().convert(  # pylint: disable=protected-access
 211             "P"
 212         )
 213         alpha.putpalette(
 214             self._pixel_shader._get_alpha_palette()  # pylint: disable=protected-access
 215         )
 216         image.putalpha(alpha.convert("L"))
 217
 218     # pylint: disable=too-many-locals,too-many-branches,too-many-statements
 219     def _fill_area(self, buffer):
 220         """Draw onto the image"""
 221         if self._hidden:
 222             return
 223
 224         if self._bitmap.width <= 0 or self._bitmap.height <= 0:
 225             return
 226
 227         # Copy class variables to local variables in case something changes
 228         x = self._x
 229         y = self._y
 230         width = self._width
 231         height = self._height
 232         tile_width = self._tile_width
 233         tile_height = self._tile_height
 234         bitmap_width = self._bitmap.width
 235         pixel_width = self._pixel_width
 236         pixel_height = self._pixel_height
 237         tiles = self._tiles
 238         absolute_transform = self._absolute_transform
 239         pixel_shader = self._pixel_shader
 240         bitmap = self._bitmap
 241         tiles = self._tiles
 242
 243         tile_count_x = bitmap_width // tile_width
 244
 245         image = Image.new(
 246             "RGBA",
 247             (width * tile_width, height * tile_height),
 248             (0, 0, 0, 0),
 249         )
 250
 251         for tile_x in range(width):
 252             for tile_y in range(height):
 253                 tile_index = tiles[tile_y * width + tile_x]
 254                 tile_index_x = tile_index % tile_count_x
 255                 tile_index_y = tile_index // tile_count_x
 256                 tile_image = bitmap._image  # pylint: disable=protected-access
 257                 if isinstance(pixel_shader, Palette):
 258                     tile_image = tile_image.copy().convert("P")
 259                     self._apply_palette(tile_image)
 260                     tile_image = tile_image.convert("RGBA")
 261                     self._add_alpha(tile_image)
 262                 elif isinstance(pixel_shader, ColorConverter):
 263                     # This will be needed for eInks, grayscale, and monochrome displays
 264                     pass
 265                 image.alpha_composite(
 266                     tile_image,
 267                     dest=(tile_x * tile_width, tile_y * tile_height),
 268                     source=(
 269                         tile_index_x * tile_width,
 270                         tile_index_y * tile_height,
 271                     ),
 272                 )
 273
 274         if absolute_transform is not None:
 275             if absolute_transform.scale > 1:
 276                 image = image.resize(
 277                     (
 278                         int(pixel_width * absolute_transform.scale),
 279                         int(
 280                             pixel_height * absolute_transform.scale,
 281                         ),
 282                     ),
 283                     resample=Image.NEAREST,
 284                 )
 285             if absolute_transform.mirror_x:
 286                 image = image.transpose(Image.FLIP_LEFT_RIGHT)
 287             if absolute_transform.mirror_y:
 288                 image = image.transpose(Image.FLIP_TOP_BOTTOM)
 289             if absolute_transform.transpose_xy:
 290                 image = image.transpose(Image.TRANSPOSE)
 291             x *= absolute_transform.dx
 292             y *= absolute_transform.dy
 293             x += absolute_transform.x
 294             y += absolute_transform.y
 295
 296         source_x = source_y = 0
 297         if x < 0:
 298             source_x = round(0 - x)
 299             x = 0
 300         if y < 0:
 301             source_y = round(0 - y)
 302             y = 0
 303
 304         x = round(x)
 305         y = round(y)
 306
 307         if (
 308             x <= buffer.width
 309             and y <= buffer.height
 310             and source_x <= image.width
 311             and source_y <= image.height
 312         ):
 313             buffer.alpha_composite(image, (x, y), source=(source_x, source_y))
 314
 315     # pylint: enable=too-many-locals,too-many-branches
 316
 317     @property
 318     def hidden(self):
 319         """True when the TileGrid is hidden. This may be False even
 320         when a part of a hidden Group."""
 321         return self._hidden
 322
 323     @hidden.setter
 324     def hidden(self, value):
 325         if not isinstance(value, (bool, int)):
 326             raise ValueError("Expecting a boolean or integer value")
 327         self._hidden = bool(value)
 328
 329     @property
 330     def x(self):
 331         """X position of the left edge in the parent."""
 332         return self._x
 333
 334     @x.setter
 335     def x(self, value):
 336         if not isinstance(value, int):
 337             raise TypeError("X should be a integer type")
 338         if self._x != value:
 339             self._x = value
 340             self._update_current_x()
 341
 342     @property
 343     def y(self):
 344         """Y position of the top edge in the parent."""
 345         return self._y
 346
 347     @y.setter
 348     def y(self, value):
 349         if not isinstance(value, int):
 350             raise TypeError("Y should be a integer type")
 351         if self._y != value:
 352             self._y = value
 353             self._update_current_y()
 354
 355     @property
 356     def flip_x(self):
 357         """If true, the left edge rendered will be the right edge of the right-most tile."""
 358         return self._flip_x
 359
 360     @flip_x.setter
 361     def flip_x(self, value):
 362         if not isinstance(value, bool):
 363             raise TypeError("Flip X should be a boolean type")
 364         if self._flip_x != value:
 365             self._flip_x = value
 366
 367     @property
 368     def flip_y(self):
 369         """If true, the top edge rendered will be the bottom edge of the bottom-most tile."""
 370         return self._flip_y
 371
 372     @flip_y.setter
 373     def flip_y(self, value):
 374         if not isinstance(value, bool):
 375             raise TypeError("Flip Y should be a boolean type")
 376         if self._flip_y != value:
 377             self._flip_y = value
 378
 379     @property
 380     def transpose_xy(self):
 381         """If true, the TileGrid’s axis will be swapped. When combined with mirroring, any 90
 382         degree rotation can be achieved along with the corresponding mirrored version.
 383         """
 384         return self._transpose_xy
 385
 386     @transpose_xy.setter
 387     def transpose_xy(self, value):
 388         if not isinstance(value, bool):
 389             raise TypeError("Transpose XY should be a boolean type")
 390         if self._transpose_xy != value:
 391             self._transpose_xy = value
 392             self._update_current_x()
 393             self._update_current_y()
 394
 395     @property
 396     def pixel_shader(self):
 397         """The pixel shader of the tilegrid."""
 398         return self._pixel_shader
 399
 400     def __getitem__(self, index):
 401         """Returns the tile index at the given index. The index can either be
 402         an x,y tuple or an int equal to ``y * width + x``'.
 403         """
 404         if isinstance(index, (tuple, list)):
 405             x = index[0]
 406             y = index[1]
 407             index = y * self._width + x
 408         elif isinstance(index, int):
 409             x = index % self._width
 410             y = index // self._width
 411         if x > self._width or y > self._height or index >= len(self._tiles):
 412             raise ValueError("Tile index out of bounds")
 413         return self._tiles[index]
 414
 415     def __setitem__(self, index, value):
 416         """Sets the tile index at the given index. The index can either be
 417         an x,y tuple or an int equal to ``y * width + x``.
 418         """
 419         if isinstance(index, (tuple, list)):
 420             x = index[0]
 421             y = index[1]
 422             index = y * self._width + x
 423         elif isinstance(index, int):
 424             x = index % self._width
 425             y = index // self._width
 426         if x > self._width or y > self._height or index >= len(self._tiles):
 427             raise ValueError("Tile index out of bounds")
 428         if not 0 <= value <= 255:
 429             raise ValueError("Tile value out of bounds")
 430         self._tiles[index] = value
 431
 432
 433 # pylint: enable=too-many-instance-attributes