From 07ce2a7dde9976ab66bffb038e81a088fd8be6c3 Mon Sep 17 00:00:00 2001 From: guillempages Date: Tue, 6 Aug 2024 13:08:13 +0200 Subject: [PATCH] Add online_image documentation (#2076) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/display/index.rst | 1 + components/image.rst | 3 +- components/online_image.rst | 152 ++++++++++++++++++++++++++++++++++ images/image-sync-outline.svg | 1 + index.rst | 1 + 5 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 components/online_image.rst create mode 100644 images/image-sync-outline.svg diff --git a/components/display/index.rst b/components/display/index.rst index dc305ca4f..7b4512f6f 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -610,6 +610,7 @@ See Also - :ref:`QR Code Component ` - :ref:`Image Component ` - :ref:`Animation Component ` +- :ref:`Online Image ` - :ghedit:`Edit` .. toctree:: diff --git a/components/image.rst b/components/image.rst index c9962db99..2a27138ae 100644 --- a/components/image.rst +++ b/components/image.rst @@ -9,6 +9,8 @@ Images Use this component to store graphical images on the device, you can then draw the images on compatible displays. +For showing images downloaded at runtime, take a look at the :ref:`Online Image ` component. + .. code-block:: yaml image: @@ -121,4 +123,3 @@ 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. - diff --git a/components/online_image.rst b/components/online_image.rst new file mode 100644 index 000000000..7ac693fd5 --- /dev/null +++ b/components/online_image.rst @@ -0,0 +1,152 @@ +.. _online_image: + +Online Image Component +====================== + +.. seo:: + :description: Instructions for displaying images downloaded at runtime in ESPHome. + :image: image-sync-outline.svg + +With this component you can define images that will be downloaded, decoded and drawn at runtime. + +.. note:: + + Currently only images in PNG format are supported. + +.. warning:: + + This component requires a fair amount of RAM; both for downloading the image, and for storing the decoded image. It might work on devices without PSRAM, but there is no guarantee. + +This component has a dependency to :doc:`/components/http_request`; the configuration options you set to the ``http_request`` component will also apply here. + +.. code-block:: yaml + + online_image: + - url: "https://example.com/example.png" + format: png + id: my_online_image + +Configuration variables +----------------------- + +- **url** (**Required**, url): The URL where the image will be downloaded from. +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later + in your display code. +- **format** (**Required**): The format that the image is encoded with. + + - ``PNG``: The image on the server is encoded in PNG format. +- **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``. + + - ``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. + - ``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. +- **use_transparency** (*Optional*, boolean): 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``. +- **update_interval** (*Optional*, int): Redownload the image when the specified time has elapsed. Defaults to ``never`` (i.e. the update component action needs to be called manually). + +Automations +----------- + +- **on_download_finished** (*Optional*, :ref:`Automation `): An automation to perform when the image has been successfully downloaded. + +A good example for that is to update the display component after the download succeeded. + +- **on_error** (*Optional*, :ref:`Automation `): An automation to perform when an error happened during download or decode. + +Actions +------- + +**online_image.set_url**: Change the URL where the image is downloaded from. The image needs to be manually updated afterwards. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The image to update the URL for. +- **url** (**Required**, url): The new URL to download the image from. + +.. code-block:: yaml + + on_...: + - online_image.set_url: + id: my_online_image + url: "https://www.example.com/new_image.png" + - component.update: my_online_image + +**online_image.release**: Release the memory currently used by an image. Can be used if different display pages need different images, to avoid wasting memory on an image that is currently not being displayed. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The image to update the URL for. + +.. code-block:: yaml + + on_...: + - online_image.release: my_online_image + +Examples +-------- + +.. code-block:: yaml + + online_image: + - url: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png" + format: png + id: my_online_image + on_download_finished: + component.update: my_display + +And then later in code: + +.. code-block:: yaml + + display: + - platform: ... + id: my_display + # ... + lambda: |- + // Draw the image my_online_image at position [x=0,y=0] + it.image(0, 0, id(my_online_image)); + +For monochrome displays the ``image`` method accepts two additional color parameters which can +be supplied to specify the color used to draw bright and dark pixels respectively. +In this case the image will be internally converted to a grayscale image and then to monochrome +based on an internally defined threshold. + +.. code-block:: yaml + + display: + - platform: ... + id: my_display + # ... + lambda: |- + // Draw the image my_image at position [x=0,y=0] + // with front color "OFF" and back color "ON" + it.image(0, 0, id(my_online_image), COLOR_OFF, COLOR_ON); + +By default ``online_image`` is configured to not automatically update/download the image; in order to do the initial download, you can either: + - Add a ``component.update `` in the ``on_connect:`` action on the :doc:`/components/wifi` component. + - Explicitly set an ``update_interval``. + - Call ``component.update `` in an :doc:`/components/interval` block. + - Call ``component.update `` where you need the image to be downloaded/updated. + +.. code-block:: yaml + + wifi: + on_connect: + - component.update: my_online_image + +See Also +-------- + +- :apiref:`online_image/online_image.h` +- :doc:`Image Component ` +- :doc:`Animation Component ` +- :ghedit:`Edit` diff --git a/images/image-sync-outline.svg b/images/image-sync-outline.svg new file mode 100644 index 000000000..7415eee7a --- /dev/null +++ b/images/image-sync-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 54c49ec68..48e810f7e 100644 --- a/index.rst +++ b/index.rst @@ -823,6 +823,7 @@ Display Components QR Code, components/qr_code, qr-code.svg, dark-invert Image, components/image, image-outline.svg, dark-invert Animation, components/animation, image-multiple-outline.svg, dark-invert + Online Image, components/online_image, image-sync-outline.svg, dark-invert Display Menu Core, components/display_menu/index, folder-open.svg, dark-invert Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.png LCD Menu, components/display_menu/lcd_menu, lcd_menu.png