Image (lv_img)¶

Overview¶

Images are the basic object to display from the flash (as arrays) or externally as files. Images can display symbols (LV_SYMBOL_...) too.

Using the Image decoder interface custom image formats can be supported as well.

Parts and Styles¶

The images has only a main part called LV_IMG_PART_MAIN which uses the typical background style propeties to draw a background rectangle and the image properties. The padding values are used to make the background virtually larger. (It won't change the image's real size but the size modification is applied only during drawing)

Usage¶

Image source¶

To provide maximum flexibility, the source of the image can be:

a variable in the code (a C array with the pixels).
a file stored externally (like on an SD card).
a text with Symbols.

To set the source of an image, use lv_img_set_src(img, src).

To generate a pixel array from a PNG, JPG or BMP image, use the Online image converter tool and set the converted image with its pointer: lv_img_set_src(img1, &converted_img_var); To make the variable visible in the C file, you need to declare it with LV_IMG_DECLARE(converted_img_var).

To use external files, you also need to convert the image files using the online converter tool but now you should select the binary Output format. You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Got to the File system to learn more. To set an image sourced from a file, use lv_img_set_src(img, "S:folder1/my_img.bin").

You can set a symbol similarly to Labels. In this case, the image will be rendered as text according to the font specified in the style. It enables to use of light-weighted mono-color "letters" instead of real images. You can set symbol like lv_img_set_src(img1, LV_SYMBOL_OK).

Label as an image¶

Images and labels are sometimes used to convey the same thing. For example, to describe what a button does. Therefore, images and labels are somewhat interchangeable. To handle these images can even display texts by using LV_SYMBOL_DUMMY as the prefix of the text. For example, lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text").

Transparency¶

The internal (variable) and external images support 2 transparency handling methods:

Chrome keying - Pixels with LV_COLOR_TRANSP (lv_conf.h) color will be transparent.
Alpha byte - An alpha byte is added to every pixel.

Palette and Alpha index¶

Besides True color (RGB) color format, the following formats are also supported:

Indexed - Image has a palette.
Alpha indexed - Only alpha values are stored.

These options can be selected in the font converter. To learn more about the color formats, read the Images section.

Recolor¶

The images can be re-colored in run-time to any color according to the brightness of the pixels. It is very useful to show different states (selected, inactive, pressed, etc.) of an image without storing more versions of the same image. This feature can be enabled in the style by setting img.intense between LV_OPA_TRANSP (no recolor, value: 0) and LV_OPA_COVER (full recolor, value: 255). The default value is LV_OPA_TRANSP so this feature is disabled.

Auto-size¶

It is possible to automatically set the size of the image object to the image source's width and height if enabled by the lv_img_set_auto_size(image, true) function. If auto-size is enabled, then when a new file is set, the object size is automatically changed. Later, you can modify the size manually. The auto-size is enabled by default if the image is not a screen.

Mosaic¶

If the object size is greater than the image size in any directions, then the image will be repeated like a mosaic. It's a very useful feature to create a large image from only a very narrow source. For example, you can have a 300 x 1 image with a special gradient and set it as a wallpaper using the mosaic feature.

Offset¶

With lv_img_set_offset_x(img, x_ofs) and lv_img_set_offset_y(img, y_ofs), you can add some offset to the displayed image. It is useful if the object size is smaller than the image source size. Using the offset parameter a Texture atlas or a "running image" effect can be created by Animating the x or y offset.

Transformations¶

Using the lv_img_set_zoom(img, factor) the images will be zoomed. Set factor to 256 or LV_IMG_ZOOM_NONE to disable zooming. A larger value enlarges the images (e.g. 512 double size), a smaller value shrinks it (e.g. 128 half size). Fractional scale works as well. E.g. 281 for 10% enlargement.

To rotate the image use lv_img_set_angle(img, angle). Angle has 0.1 degree precision, so for 45.8° set 458.

By default, the pivot point of the rotation is the center of the image. It can be changed with lv_img_set_pivot(img, pivot_x, pivot_y). 0;0 is the top left corner.

The quality of the transformation can be adjusted with lv_img_set_antialias(img, true/false). With enabled anti-aliasing the transformations has a higher quality but they are slower.

The transformations require the whole image to be available. Therefore indexed images (LV_IMG_CF_INDEXED_...), alpha only images (LV_IMG_CF_ALPHA_...) or images from files can not be transformed. In other words transformations work only on true color images stored as C array, or if a custom Image decoder returns the whole image.

Note that, the real coordinates of image object won't change during transformation. That is lv_obj_get_width/height/x/y() will returned the original, non-zoomed coordinates.

Rotate¶

The images can be rotated with

Events¶

As by default, clicking of the image objects is disabled, only generic non-input device-related events are sent. If you want to catch all of the generic events of an image object, you should enable its clicking by using this: lv_obj_set_click(img, true)

Learn more about Events.

Keys¶

No Keys are processed by the object type.

Learn more about Keys.

Example¶

C¶

Image from variable and symbol¶

#include "../../../lv_examples.h"
#if LV_USE_IMG

/* Find the image here: https://github.com/lvgl/lv_examples/tree/master/assets */
LV_IMG_DECLARE(img_cogwheel_argb);

void lv_ex_img_1(void)
{
    lv_obj_t * img1 = lv_img_create(lv_scr_act(), NULL);
    lv_img_set_src(img1, &img_cogwheel_argb);
    lv_obj_align(img1, NULL, LV_ALIGN_CENTER, 0, -20);

    lv_obj_t * img2 = lv_img_create(lv_scr_act(), NULL);
    lv_img_set_src(img2, LV_SYMBOL_OK "Accept");
    lv_obj_align(img2, img1, LV_ALIGN_OUT_BOTTOM_MID, 0, 20);
}

#endif

Image recoloring¶

#include "../../../lv_examples.h"
#if LV_USE_IMG

#define SLIDER_WIDTH 20

static void create_sliders(void);
static void slider_event_cb(lv_obj_t * slider, lv_event_t event);

static lv_obj_t * red_slider, * green_slider, * blue_slider, * intense_slider;
static lv_obj_t * img1;
LV_IMG_DECLARE(img_cogwheel_argb);

void lv_ex_img_2(void)
{
    /*Create 4 sliders to adjust RGB color and re-color intensity*/
    create_sliders();

    /* Now create the actual image */
    img1 = lv_img_create(lv_scr_act(), NULL);
    lv_img_set_src(img1, &img_cogwheel_argb);
    lv_obj_align(img1, NULL, LV_ALIGN_IN_RIGHT_MID, -20, 0);
}

static void slider_event_cb(lv_obj_t * slider, lv_event_t event)
{
    if(event == LV_EVENT_VALUE_CHANGED) {
        /* Recolor the image based on the sliders' values */
        lv_color_t color  = lv_color_make(lv_slider_get_value(red_slider), lv_slider_get_value(green_slider), lv_slider_get_value(blue_slider));
        lv_opa_t intense = lv_slider_get_value(intense_slider);
        lv_obj_set_style_local_image_recolor_opa(img1, LV_IMG_PART_MAIN, LV_STATE_DEFAULT, intense);
        lv_obj_set_style_local_image_recolor(img1, LV_IMG_PART_MAIN, LV_STATE_DEFAULT, color);
    }
}

static void create_sliders(void)
{
    /* Create a set of RGB sliders */
    /* Use the red one as a base for all the settings */
    red_slider = lv_slider_create(lv_scr_act(), NULL);
    lv_slider_set_range(red_slider, 0, 255);
    lv_obj_set_size(red_slider, SLIDER_WIDTH, 200); /* Be sure it's a vertical slider */
    lv_obj_set_style_local_bg_color(red_slider, LV_SLIDER_PART_INDIC, LV_STATE_DEFAULT, LV_COLOR_RED);
    lv_obj_set_event_cb(red_slider, slider_event_cb);

    /* Copy it for the other three sliders */
    green_slider = lv_slider_create(lv_scr_act(), red_slider);
    lv_obj_set_style_local_bg_color(green_slider, LV_SLIDER_PART_INDIC, LV_STATE_DEFAULT, LV_COLOR_LIME);

    blue_slider = lv_slider_create(lv_scr_act(), red_slider);
    lv_obj_set_style_local_bg_color(blue_slider, LV_SLIDER_PART_INDIC, LV_STATE_DEFAULT, LV_COLOR_BLUE);

    intense_slider = lv_slider_create(lv_scr_act(), red_slider);
    lv_obj_set_style_local_bg_color(intense_slider, LV_SLIDER_PART_INDIC, LV_STATE_DEFAULT, LV_COLOR_GRAY);
    lv_slider_set_value(intense_slider, 255, LV_ANIM_OFF);

    lv_obj_align(red_slider, NULL, LV_ALIGN_IN_LEFT_MID, 20, 0);
    lv_obj_align(green_slider, red_slider, LV_ALIGN_OUT_RIGHT_MID, 20, 0);
    lv_obj_align(blue_slider, green_slider, LV_ALIGN_OUT_RIGHT_MID, 20, 0);
    lv_obj_align(intense_slider, blue_slider, LV_ALIGN_OUT_RIGHT_MID, 20, 0);
}

#endif

MicroPython¶

Image from variable and symbol¶

Click to try in the simulator!

from imagetools import get_png_info, open_png

# Register PNG image decoder
decoder = lv.img.decoder_create()
decoder.info_cb = get_png_info
decoder.open_cb = open_png

with open('img_cogwheel_argb.png','rb') as f:
  png_data = f.read()

png_img_dsc = lv.img_dsc_t({
    'data_size': len(png_data),
    'data': png_data 
})

# Create an image using the decoder

img1 = lv.img(lv.scr_act(),None)
lv.img.cache_set_size(2)
img1.align(lv.scr_act(), lv.ALIGN.CENTER, 0, -50)
img1.set_src(png_img_dsc)

img2 = lv.img(lv.scr_act(), None)
img2.set_src(lv.SYMBOL.OK+"Accept")
img2.align(img1, lv.ALIGN.OUT_BOTTOM_MID, 0, 20)

Image recoloring¶

Click to try in the simulator!

from lv_colors import lv_colors
from imagetools import get_png_info, open_png

SLIDER_WIDTH=15

# Register PNG image decoder
decoder = lv.img.decoder_create()
decoder.info_cb = get_png_info
decoder.open_cb = open_png

with open('img_cogwheel_argb.png','rb') as f:
  png_data = f.read()

png_img_dsc = lv.img_dsc_t({
    'data_size': len(png_data),
    'data': png_data 
})
def slider_event_cb(slider,event):
    if event == lv.EVENT.VALUE_CHANGED:
      # Recolor the image based on the sliders' values 
      color  = lv.color_make(red_slider.get_value(), green_slider.get_value(), blue_slider.get_value())
      intense = intense_slider.get_value()
      img1.set_style_local_image_recolor_opa(lv.img.PART.MAIN, lv.STATE.DEFAULT, intense)
      img1.set_style_local_image_recolor(lv.img.PART.MAIN, lv.STATE.DEFAULT, color)

# Create a set of RGB sliders 
# Use the red one as a base for all the settings 
red_slider = lv.slider(lv.scr_act(), None)
red_slider.set_range(0, 255)
red_slider.set_size(SLIDER_WIDTH, 200)   # Be sure it's a vertical slider
red_slider.set_style_local_bg_color(lv.slider.PART.INDIC, lv.STATE.DEFAULT, LV_COLOR_RED)
red_slider.set_event_cb(slider_event_cb)

# Copy it for the other three sliders 
green_slider = lv.slider(lv.scr_act(), red_slider)
green_slider.set_style_local_bg_color(lv.slider.PART.INDIC, lv.STATE.DEFAULT, lv_colors.LIME)
green_slider.set_event_cb(slider_event_cb)

blue_slider = lv.slider(lv.scr_act(), red_slider)
blue_slider.set_style_local_bg_color(lv.slider.PART.INDIC, lv.STATE.DEFAULT, lv_colors.BLUE)
blue_slider.set_event_cb(slider_event_cb)

intense_slider = lv.slider(lv.scr_act(), red_slider)
intense_slider.set_style_local_bg_color(lv.slider.PART.INDIC, lv.STATE.DEFAULT, lv_colors.GRAY)
intense_slider.set_value(255, lv.ANIM.OFF)
intense_slider.set_event_cb(slider_event_cb)

red_slider.align(None, lv.ALIGN.IN_LEFT_MID, 15, 0)
green_slider.align(red_slider, lv.ALIGN.OUT_RIGHT_MID, 15, 0)
blue_slider.align(green_slider, lv.ALIGN.OUT_RIGHT_MID, 15, 0)
intense_slider.align(blue_slider, lv.ALIGN.OUT_RIGHT_MID, 15, 0)


img1 = lv.img(lv.scr_act(),None)
lv.img.cache_set_size(2)
img1.align(lv.scr_act(), lv.ALIGN.CENTER, 50, -30)
img1.set_src(png_img_dsc)

while True:
    lv.task_handler()
    time.sleep_ms(10)

API¶

Typedefs

typedef uint8_t lv_img_part_t¶

Enums

enum [anonymous]¶

Values:

enumerator LV_IMG_PART_MAIN¶

Functions

lv_obj_t *lv_img_create(lv_obj_t *par, const lv_obj_t *copy)¶

Create an image objects

Parameters

par -- pointer to an object, it will be the parent of the new button
copy -- pointer to a image object, if not NULL then the new object will be copied from it

Returns

pointer to the created image

void lv_img_set_src(lv_obj_t *img, const void *src_img)¶

Set the pixel map to display by the image

Parameters

img -- pointer to an image object
data -- the image data

void lv_img_set_auto_size(lv_obj_t *img, bool autosize_en)¶

Enable the auto size feature. If enabled the object size will be same as the picture size.

Parameters

img -- pointer to an image
en -- true: auto size enable, false: auto size disable

void lv_img_set_offset_x(lv_obj_t *img, lv_coord_t x)¶

Set an offset for the source of an image. so the image will be displayed from the new origin.

Parameters

img -- pointer to an image
x -- the new offset along x axis.

void lv_img_set_offset_y(lv_obj_t *img, lv_coord_t y)¶

Set an offset for the source of an image. so the image will be displayed from the new origin.

Parameters

img -- pointer to an image
y -- the new offset along y axis.

void lv_img_set_pivot(lv_obj_t *img, lv_coord_t pivot_x, lv_coord_t pivot_y)¶

Set the rotation center of the image. The image will be rotated around this point

Parameters

img -- pointer to an image object
pivot_x -- rotation center x of the image
pivot_y -- rotation center y of the image

void lv_img_set_angle(lv_obj_t *img, int16_t angle)¶

Set the rotation angle of the image. The image will be rotated around the set pivot set by lv_img_set_pivot()

Parameters

img -- pointer to an image object
angle -- rotation angle in degree with 0.1 degree resolution (0..3600: clock wise)

void lv_img_set_zoom(lv_obj_t *img, uint16_t zoom)¶

Set the zoom factor of the image.

Parameters

img -- pointer to an image object
zoom -- the zoom factor.
- 256 or LV_ZOOM_IMG_NONE for no zoom
- <256: scale down
- >256 scale up
- 128 half size
- 512 double size

void lv_img_set_antialias(lv_obj_t *img, bool antialias)¶

Enable/disable anti-aliasing for the transformations (rotate, zoom) or not

Parameters

img -- pointer to an image object
antialias -- true: anti-aliased; false: not anti-aliased

const void *lv_img_get_src(lv_obj_t *img)¶

Get the source of the image

Parameters: img -- pointer to an image object
Returns: the image source (symbol, file name or C array)

const char *lv_img_get_file_name(const lv_obj_t *img)¶

Get the name of the file set for an image

Parameters: img -- pointer to an image
Returns: file name

bool lv_img_get_auto_size(const lv_obj_t *img)¶

Get the auto size enable attribute

Parameters: img -- pointer to an image
Returns: true: auto size is enabled, false: auto size is disabled

lv_coord_t lv_img_get_offset_x(lv_obj_t *img)¶

Get the offset.x attribute of the img object.

Parameters: img -- pointer to an image
Returns: offset.x value.

lv_coord_t lv_img_get_offset_y(lv_obj_t *img)¶

Get the offset.y attribute of the img object.

Parameters: img -- pointer to an image
Returns: offset.y value.

uint16_t lv_img_get_angle(lv_obj_t *img)¶

Get the rotation angle of the image.

Parameters: img -- pointer to an image object
Returns: rotation angle in degree (0..359)

void lv_img_get_pivot(lv_obj_t *img, lv_point_t *center)¶

Get the rotation center of the image.

Parameters

img -- pointer to an image object
center -- rotation center of the image

uint16_t lv_img_get_zoom(lv_obj_t *img)¶

Get the zoom factor of the image.

Parameters: img -- pointer to an image object
Returns: zoom factor (256: no zoom)

bool lv_img_get_antialias(lv_obj_t *img)¶

Get whether the transformations (rotate, zoom) are anti-aliased or not

Parameters: img -- pointer to an image object
Returns: true: anti-aliased; false: not anti-aliased

struct lv_img_ext_t¶

Public Members

const void *src¶

lv_point_t offset¶

lv_coord_t w¶

lv_coord_t h¶

uint16_t angle¶

lv_point_t pivot¶

uint16_t zoom¶

uint8_t src_type¶

uint8_t auto_size¶

uint8_t cf¶

uint8_t antialias¶