Document image changes (#4506)

Author: clydebarrow

components/animation.rst

@@ -12,6 +12,7 @@ It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_
       - file: "animation.gif"
         id: my_animation
         resize: 100x100
+        type: RGB565
 
 The animation can be rendered just like the image component with the ``image()`` function of the display component.
 
@@ -50,18 +51,15 @@ Configuration variables:
   in your display code.
 - **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT``
   and preserve the aspect ratio.
-- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``.
+- **type** (**Required**): Specifies how to encode image internally. See the :ref:`image component <display-image>` for more information.
 
   - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
-    per pixel, 8 pixels per byte.
-  - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
-    will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
+    per pixel, 8 pixels per byte. Only ``chroma_key`` transparency is available.
   - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
-  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
-  - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
-  - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
+  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel, 3 with an alpha channel.
+  - ``RGB``: Full RGB color stored. Uses 3 bytes per pixel, 4 with an alpha channel.
 
-- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
+- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account. The possible values are ``opaque`` (default), ``chroma_key`` and ``alpha_channel``. See discussion on transparency in the :ref:`image component <display-image>`.
 - **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over.
 
   - **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation.
@@ -83,4 +81,3 @@ Actions:
 
   - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
   - **frame** (**Required**, int): The frame index to show next.
-

components/image.rst

@@ -15,6 +15,7 @@ For showing images downloaded at runtime, take a look at the :ref:`Online Image
 
     image:
       - file: "image.png"
+        type: binary
         id: my_image
         resize: 100x100
 
@@ -23,12 +24,15 @@ For showing images downloaded at runtime, take a look at the :ref:`Online Image
     image:
       - file: mdi:alert-outline
         id: alert
+        type: grayscale
+        use_transparency: alpha_channel
         resize: 80x80
 
 .. code-block:: yaml
 
     image:
       - file: https://esphome.io/_images/logo.png
+        type: rgb565
         id: esphome_logo
         resize: 200x162
 
@@ -46,36 +50,70 @@ Configuration variables:
   in your display code.
 - **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT``
   and preserve the aspect ratio.
-- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local and remote images and ``TRANSPARENT_BINARY`` for MDIs.
+- **type** (**Required**): Specifies how to encode image internally.
 
   - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
-    per pixel, 8 pixels per byte.
-  - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
-    will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
+    per pixel, 8 pixels per byte. Only ``chroma_key`` transparency is available.
   - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
-  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
-  - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
-  - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
+  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel, 3 with an alpha channel.
+  - ``RGB``: Full RGB color stored. Uses 3 bytes per pixel, 4 with an alpha channel.
 
-- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
+- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account. The possible values are ``opaque`` (default), ``chroma_key`` and ``alpha_channel``. See discussion on transparency below.
 
 - **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here <https://pillow.readthedocs.io/en/stable/reference/Image.html?highlight=Dither#PIL.Image.Image.convert>`__ and `here <https://en.wikipedia.org/wiki/Dither>`__.
 
-  - ``NONE``: Every pixel convert to its nearest color.
+  - ``NONE``: Every pixel converts to its nearest color.
   - ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels.
 
 .. note::
 
     To use images you will need to have the python ``pillow`` package installed.
     Additionally, if you want to use SVG images (including MDI images), you will
-    additionally need to have the python ``cairosvg`` package installed.
+    additionally need to have the python ``cairosvg`` package installed. These are automatically installed when
+    setting up ESPHome via the usual methods.
 
-    If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed.
+Grouping images by type
+-----------------------
 
-    Use ``pip install "esphome[displays]"`` to install these optional dependencies with
-    the versions that ESPHome requires.
+You can group images by type to make it easier to manage them. This is useful when you have a lot of images to be encoded in the same way, and avoids having to repeat the same type for each image. The type name is used as the key for the group. For example:
 
-And then later in code:
+.. code-block:: yaml
+
+    image:
+      grayscale:
+        - file: "image1.png"
+          id: image1
+        - file: "image2.png"
+          id: image2
+        - file: "image3.png"
+          id: image3
+
+      rgb565:
+        - file: "image4.png"
+          id: image4
+        - file: "image5.png"
+          id: image5
+
+In addition, the default transparency type can be set within a type group by using the transparency type as a key.
+
+.. code-block:: yaml
+
+    image:
+      rgb565:
+        alpha_channel:
+        - file: "image1.png"
+          id: image1
+        - file: "image2.png"
+          id: image2
+        opaque:
+        - file: "image2.png"
+
+Displaying Images
+-----------------
+
+Images may be used in LVGL configurations wherever an image is required. See the :doc:`LVGL </components/lvgl/index>` documentation for more information.
+
+To display an image directly on an ESPHome display, you can use the ``image`` method in the display lambda.
 
 .. code-block:: yaml
 
@@ -123,3 +161,12 @@ be supplied to modify the color used to represent the on and off bits respective
 
 You can also use this to invert images in two color displays, use ``COLOR_OFF`` then ``COLOR_ON``
 as the additional parameters.
+
+Transparency options
+--------------------
+
+By default transparency is not used. If ``use_transparency: chroma_key`` is set then a specific colour (0, 1, 0) will be used to replace any transparent or partially transparent portions of the image. This will not be drawn when rendering the image, allowing the background to be visible.
+
+If ``use_transparency: alpha_channel`` is set, then each pixel of the image will be assigned an additional byte with a transparency value. This is useful mainly when using :doc:`LVGL </components/lvgl/index>` as the ``alpha_channel`` transparency will enable smooth blending of transparent images with the background.
+When using the display lambda image drawing functions these will draw or not draw the pixel, no blending with the background will be done.
+The ``BINARY`` format only permits ``chroma_key`` transparency, which effectively turns the image into an alpha mask with one bit per pixel. GRAYSCALE images with transparency store the alpha channel only, and remain 1 byte per pixel.

components/lvgl/widgets.rst

@@ -804,7 +804,7 @@ Images are the basic widgets used to display images.
 
 .. note::
 
-    Currently ``RGB565`` type images are supported, with transparency using the optional parameter ``use_transparency`` set to ``true``. See :ref:`display-image` for how to load an image for rendering in ESPHome.
+    Currently ``RGB565`` type images are supported, with transparency using the optional parameter ``use_transparency`` set. See :ref:`display-image` for how to load an image for rendering in ESPHome.
 
 .. tip::
 

cookbook/lvgl.rst

@@ -1190,7 +1190,7 @@ To display a boot image with a spinner animation which disappears automatically
         id: boot_logo
         resize: 200x200
         type: RGB565
-        use_transparency: true
+        use_transparency: alpha_channel
 
     lvgl:
       ...