Skip to content
Get started

Images

Use the image component to define images that can be drawn on compatible displays or used with LVGL widgets.

image is a platform component: each entry in the image: list selects a platform which determines where the image data comes from:

  • file: Static images embedded into the firmware at compile time, from a local file, a URL or a Material Design Icon.
  • animation: Multi-frame (animated) images embedded into the firmware at compile time.
  • online_image: Images downloaded, decoded and drawn at runtime.
  • sendspin: Album and artist artwork streamed from a Sendspin group and decoded at runtime.
# Example configuration entry
image:
  - platform: file
    file: "image.png"
    type: BINARY
    id: my_image
    resize: 100x100

Displaying Images

Section titled “Displaying Images”

Images may be used in LVGL configurations wherever an image is required. See the LVGL documentation for more information.

To display an image directly on an ESPHome display, you can use the image method in the display lambda.

display:
  - platform: ...
    # ...
    lambda: |-
      // Draw the image my_image at position [x=0,y=0]
      it.image(0, 0, id(my_image));

By default, ESPHome will align the image at the top left. That means if you enter the coordinates [0,10] for your image, the top left of the image will be at [0,10]. If you want to draw some image at the right side of the display, it is however sometimes useful to choose a different image alignment. When you enter [0,10] you’re really telling ESPHome that it should position the anchor point of the image at [0,10]. When using a different alignment, like TOP_RIGHT, the image will be positioned left of the anchor pointed, so that, as the name implies, the anchor point is a the top right corner of the image.

display:
  - platform: ...
    # ...
    lambda: |-
      // Aligned on left by default
      it.image(0, 0, id(my_image));


      // Aligned on right edge
      it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT);

For binary images the image method accepts two additional color parameters which can be supplied to modify the color used to represent the on and off bits respectively. e.g.

display:
  - platform: ...
    # ...
    lambda: |-
      // Draw the image my_image at position [x=0,y=0]
      // with front color red and back color blue
      it.image(0, 0, id(my_image), id(red), id(blue));


      // Aligned on right edge
      it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue));

You can also use this to invert images in two color displays, use COLOR_OFF then COLOR_ON as the additional parameters.

Setting Defaults

Section titled “Setting Defaults”

If you have several images that share most of their options (type, transparency, resize, …), a platform entry can use defaults: together with files: instead of repeating those options on every image:

image:
  - platform: file
    defaults:
      type: RGB565
      transparency: opaque
      resize: 100x100
    files:
      - id: image_one
        file: "image1.png"
      - id: image_two
        file: "image2.png"
        type: GRAYSCALE # overrides the default type for this image only

Each entry in files: is merged with defaults:, with the entry’s own options taking priority. defaults: can only be used together with files:. This works the same way for every image platform (file, animation and online_image) — just replace the entries in files: with the options normally used for that platform.

  • defaults (Optional, mapping): Options merged into every entry in files:.
  • files (Required, list): A list of images, each using the normal configuration variables of the selected platform.

Transparency Options

Section titled “Transparency Options”

The transparency option controls how the alpha channel of the input image is handled. Possible values are:

  • opaque (default): Transparency is not used; the image is drawn fully opaque.
  • chroma_key: A specific colour is used to represent any transparent or partially transparent portions of the image. Pixels of that colour will not be drawn when rendering the image, allowing the background to be visible.
  • alpha_channel: Each pixel of the image is assigned an additional byte with a transparency value. This is useful mainly when using LVGL, as alpha_channel transparency enables smooth blending of transparent images with the background. This choice is not available for binary images. When using the display lambda image drawing functions, these will only draw or not draw the pixel; no blending with the background will be done.

The BINARY format with chroma_key transparency 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.

See Also

Section titled “See Also”