图像 (lv_img)

概述

图像是用于从闪存（作为数组）或文件中显示图像的基本对象。图像也可以显示符号（LV_SYMBOL_...）。

通过使用图像解码器接口，还可以支持自定义图像格式。

部件和样式

• LV_PART_MAIN 一个背景矩形，使用典型的背景样式属性，并通过图像样式属性显示图像本身。

用法

图像来源

为了提供最大的灵活性，图像的来源可以是：

• 代码中的变量（一个包含像素的 C 数组）。

• 外部存储的文件（例如在 SD 卡上）。

• 带有符号的文本。

使用 lv_img_set_src(img, src) 设置图像的来源。

要从 PNG、JPG 或 BMP 图像生成像素数组，请使用在线图像转换工具，并通过指针设置转换后的图像：lv_img_set_src(img1, &converted_img_var);
要使变量在 C 文件中可见，需要使用 LV_IMG_DECLARE(converted_img_var) 声明它。

要使用外部文件，也需要使用在线转换工具转换图像文件，但此时应选择二进制输出格式。 还需要使用 LVGL 的文件系统模块并注册一个驱动程序以执行基本文件操作。请访问文件系统了解更多信息。 要设置来自文件的图像，请使用 lv_img_set_src(img, "S:folder1/my_img.bin")。

还可以类似于标签设置符号。在这种情况下，图像将根据样式中指定的字体呈现为文本。这使得可以使用轻量级的单色“字母”代替真实图像。可以像这样设置符号：lv_img_set_src(img1, LV_SYMBOL_OK)。

标签作为图像

图像和标签有时用于传达相同的内容。例如，用于描述按钮的功能。 因此，图像和标签在某种程度上是可以互换的，即图像可以通过使用 LV_SYMBOL_DUMMY 作为文本的前缀来显示文本。例如：lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")。

透明度

内部（变量）和外部图像支持两种透明度处理方法：

• 色键透明 - 像素颜色为 LV_COLOR_CHROMA_KEY（lv_conf.h）的像素将透明。

• Alpha 字节 - 每个像素添加一个 Alpha 字节，表示像素的不透明度。

调色板和 Alpha 索引

除了真彩色（RGB）颜色格式，还支持以下格式：

• 索引 - 图像有一个调色板。

• Alpha 索引 - 仅存储 Alpha 值。

这些选项可以在图像转换器中选择。要了解更多关于颜色格式的信息，请阅读图像部分。

重着色

可以通过给定的强度将一种颜色与图像的每个像素混合。 这对于显示图像的不同状态（选中、禁用、按下等）而无需存储相同图像的多个版本非常有用。 可以通过在样式中将 img_recolor_opa 设置为 LV_OPA_TRANSP（无重着色，值：0）到 LV_OPA_COVER（完全重着色，值：255）之间的值来启用此功能。 默认值为 LV_OPA_TRANSP，因此此功能默认禁用。

混合的颜色通过 img_recolor 设置。

自动调整大小

如果图像对象的宽度或高度设置为 LV_SIZE_CONTENT，对象的大小将根据图像来源的大小自动调整。

马赛克

如果对象的大小在任何方向上大于图像大小，则图像将像马赛克一样重复。 这允许从仅一个非常窄的来源创建一个大图像。 例如，可以使用一个 300 x 5 的图像设置为壁纸，并启用马赛克功能。

偏移

通过 lv_img_set_offset_x(img, x_ofs) 和 lv_img_set_offset_y(img, y_ofs)，可以为显示的图像添加一些偏移。 当对象大小小于图像来源大小时非常有用。 使用偏移参数可以通过动画 x 或 y 偏移创建纹理图集或“运行图像”效果。

变换

使用 lv_img_set_zoom(img, factor) 可以缩放图像。将 factor 设置为 256 或 LV_IMG_ZOOM_NONE 以禁用缩放。 更大的值放大图像（例如 512 双倍大小），更小的值缩小图像（例如 128 半大小）。 也支持分数缩放。例如，281 表示放大 10%。

要旋转图像，请使用 lv_img_set_angle(img, angle)。角度具有 0.1 度的精度，因此对于 45.8° 设置为 458。

transform_zoom 和 transform_angle 样式属性也用于确定最终的缩放和角度。

默认情况下，旋转的枢轴点是图像的中心。可以通过 lv_img_set_pivot(img, pivot_x, pivot_y) 更改。0;0 是左上角。

可以通过 lv_img_set_antialias(img, true/false) 调整变换的质量。启用抗锯齿时，变换质量更高但速度较慢。

变换需要整个图像可用。因此，索引图像（LV_IMG_CF_INDEXED_...）、仅 Alpha 图像（LV_IMG_CF_ALPHA_...）或来自文件的图像无法变换。 换句话说，变换仅适用于存储为 C 数组的真彩色图像，或者如果自定义图像解码器返回整个图像。

注意，图像对象的实际坐标在变换期间不会改变。即 lv_obj_get_width/height/x/y() 将返回原始的、未缩放的坐标。

重要 图像的变换独立于样式带来的变换属性。（参见这里）。主要区别在于纯图像小部件变换：

• 不会变换图像小部件的子对象。

• 图像直接变换，而无需创建中间层（缓冲区）来快照小部件。

尺寸模式

默认情况下，当图像被缩放或旋转时，图像对象的实际坐标不会改变。 较大的内容只是溢出对象的边界。 这也意味着布局不会受到变换的影响。

如果需要对象大小更新为变换后的大小，请设置 lv_img_set_size_mode(img, LV_IMG_SIZE_MODE_REAL)。（之前的模式是默认模式，称为 LV_IMG_SIZE_MODE_VIRTUAL）。 在这种情况下，如果对象的宽度/高度设置为 LV_SIZE_CONTENT，对象的大小将设置为缩放和旋转后的大小。 如果设置了显式大小，则溢出的内容将被裁剪。

圆角图像

可以使用 lv_obj_set_style_radius 为图像设置圆角，并启用 lv_obj_set_style_clip_corner 将内容裁剪为圆角矩形或圆形。 请注意，这会对基于 CPU 的渲染器产生一些负面性能影响。

事件

图像对象不发送特殊事件。

请参阅基础对象的事件。

了解更多关于事件的信息。

按键

此对象类型不处理任何按键。

了解更多关于按键的信息。

示例

Image from variable and symbol

C code  

 GitHub

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


void lv_example_img_1(void)
{
    LV_IMG_DECLARE(img_cogwheel_argb);
    lv_obj_t * img1 = lv_img_create(lv_scr_act());
    lv_img_set_src(img1, &img_cogwheel_argb);
    lv_obj_align(img1, LV_ALIGN_CENTER, 0, -20);
    lv_obj_set_size(img1, 200, 200);

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

#endif

MicroPython code  

 GitHub Simulator

#!/opt/bin/lv_micropython -i
import usys as sys
import lvgl as lv
import display_driver
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

# Create an image from the png file
try:
    with open('../../assets/img_cogwheel_argb.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find img_cogwheel_argb.png")
    sys.exit()

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

img1 = lv.img(lv.scr_act())
img1.set_src(img_cogwheel_argb)
img1.align(lv.ALIGN.CENTER, 0, -20)
img1.set_size(200, 200)

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

---

Image recoloring

C code  

 GitHub

#include "../../lv_examples.h"
#if LV_USE_IMG && LV_USE_SLIDER && LV_BUILD_EXAMPLES

static lv_obj_t * create_slider(lv_color_t color);
static void slider_event_cb(lv_event_t * e);

static lv_obj_t * red_slider, * green_slider, * blue_slider, * intense_slider;
static lv_obj_t * img1;


/**
 * Demonstrate runtime image re-coloring
 */
void lv_example_img_2(void)
{
    /*Create 4 sliders to adjust RGB color and re-color intensity*/
    red_slider = create_slider(lv_palette_main(LV_PALETTE_RED));
    green_slider = create_slider(lv_palette_main(LV_PALETTE_GREEN));
    blue_slider = create_slider(lv_palette_main(LV_PALETTE_BLUE));
    intense_slider = create_slider(lv_palette_main(LV_PALETTE_GREY));

    lv_slider_set_value(red_slider, LV_OPA_20, LV_ANIM_OFF);
    lv_slider_set_value(green_slider, LV_OPA_90, LV_ANIM_OFF);
    lv_slider_set_value(blue_slider, LV_OPA_60, LV_ANIM_OFF);
    lv_slider_set_value(intense_slider, LV_OPA_50, LV_ANIM_OFF);

    lv_obj_align(red_slider, LV_ALIGN_LEFT_MID, 25, 0);
    lv_obj_align_to(green_slider, red_slider, LV_ALIGN_OUT_RIGHT_MID, 25, 0);
    lv_obj_align_to(blue_slider, green_slider, LV_ALIGN_OUT_RIGHT_MID, 25, 0);
    lv_obj_align_to(intense_slider, blue_slider, LV_ALIGN_OUT_RIGHT_MID, 25, 0);

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

    lv_event_send(intense_slider, LV_EVENT_VALUE_CHANGED, NULL);
}

static void slider_event_cb(lv_event_t * e)
{
    LV_UNUSED(e);

    /*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_img_recolor_opa(img1, intense, 0);
    lv_obj_set_style_img_recolor(img1, color, 0);
}

static lv_obj_t * create_slider(lv_color_t color)
{
    lv_obj_t * slider = lv_slider_create(lv_scr_act());
    lv_slider_set_range(slider, 0, 255);
    lv_obj_set_size(slider, 10, 200);
    lv_obj_set_style_bg_color(slider, color, LV_PART_KNOB);
    lv_obj_set_style_bg_color(slider, lv_color_darken(color, LV_OPA_40), LV_PART_INDICATOR);
    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
    return slider;
}

#endif

MicroPython code  

 GitHub Simulator

#!/opt/bin/lv_micropython -i
import usys as sys
import lvgl as lv
import display_driver
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

# Create an image from the png file
try:
    with open('../../assets/img_cogwheel_argb.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find img_cogwheel_argb.png")
    sys.exit()

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

def create_slider(color):
    slider = lv.slider(lv.scr_act())
    slider.set_range(0, 255)
    slider.set_size(10, 200)
    slider.set_style_bg_color(color, lv.PART.KNOB)
    slider.set_style_bg_color(color.color_darken(lv.OPA._40), lv.PART.INDICATOR)
    slider.add_event_cb(slider_event_cb, lv.EVENT.VALUE_CHANGED, None)
    return slider

def slider_event_cb(e):
    # 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_img_recolor_opa(intense, 0)
    img1.set_style_img_recolor(color, 0)

#
# Demonstrate runtime image re-coloring
#
# Create 4 sliders to adjust RGB color and re-color intensity
red_slider = create_slider(lv.palette_main(lv.PALETTE.RED))
green_slider = create_slider(lv.palette_main(lv.PALETTE.GREEN))
blue_slider = create_slider(lv.palette_main(lv.PALETTE.BLUE))
intense_slider = create_slider(lv.palette_main(lv.PALETTE.GREY))

red_slider.set_value(lv.OPA._20, lv.ANIM.OFF)
green_slider.set_value(lv.OPA._90, lv.ANIM.OFF)
blue_slider.set_value(lv.OPA._60, lv.ANIM.OFF)
intense_slider.set_value(lv.OPA._50, lv.ANIM.OFF)

red_slider.align(lv.ALIGN.LEFT_MID, 25, 0)
green_slider.align_to(red_slider, lv.ALIGN.OUT_RIGHT_MID, 25, 0)
blue_slider.align_to(green_slider, lv.ALIGN.OUT_RIGHT_MID, 25, 0)
intense_slider.align_to(blue_slider, lv.ALIGN.OUT_RIGHT_MID, 25, 0)

# Now create the actual image
img1 = lv.img(lv.scr_act())
img1.set_src(img_cogwheel_argb)
img1.align(lv.ALIGN.RIGHT_MID, -20, 0)

lv.event_send(intense_slider, lv.EVENT.VALUE_CHANGED, None)

---

Rotate and zoom

C code  

 GitHub

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

static void set_angle(void * img, int32_t v)
{
    lv_img_set_angle(img, v);
}

static void set_zoom(void * img, int32_t v)
{
    lv_img_set_zoom(img, v);
}


/**
 * Show transformations (zoom and rotation) using a pivot point.
 */
void lv_example_img_3(void)
{
    LV_IMG_DECLARE(img_cogwheel_argb);

    /*Now create the actual image*/
    lv_obj_t * img = lv_img_create(lv_scr_act());
    lv_img_set_src(img, &img_cogwheel_argb);
    lv_obj_align(img, LV_ALIGN_CENTER, 50, 50);
    lv_img_set_pivot(img, 0, 0);    /*Rotate around the top left corner*/

    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_var(&a, img);
    lv_anim_set_exec_cb(&a, set_angle);
    lv_anim_set_values(&a, 0, 3600);
    lv_anim_set_time(&a, 5000);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_start(&a);

    lv_anim_set_exec_cb(&a, set_zoom);
    lv_anim_set_values(&a, 128, 256);
    lv_anim_set_playback_time(&a, 3000);
    lv_anim_start(&a);
}

#endif

MicroPython code  

 GitHub Simulator

#!/opt/bin/lv_micropython -i
import usys as sys
import lvgl as lv
import display_driver
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

# Create an image from the png file
try:
    with open('../../assets/img_cogwheel_argb.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find img_cogwheel_argb.png")
    sys.exit()

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

def set_angle(img, v):
    img.set_angle(v)

def set_zoom(img, v):
    img.set_zoom(v)


#
# Show transformations (zoom and rotation) using a pivot point.
#

# Now create the actual image
img = lv.img(lv.scr_act())
img.set_src(img_cogwheel_argb)
img.align(lv.ALIGN.CENTER, 50, 50)
img.set_pivot(0, 0)               # Rotate around the top left corner

a1 = lv.anim_t()
a1.init()
a1.set_var(img)
a1.set_custom_exec_cb(lambda a,val: set_angle(img,val))
a1.set_values(0, 3600)
a1.set_time(5000)
a1.set_repeat_count(lv.ANIM_REPEAT.INFINITE)
lv.anim_t.start(a1)

a2 = lv.anim_t()
a2.init()
a2.set_var(img)
a2.set_custom_exec_cb(lambda a,val: set_zoom(img,val))
a2.set_values(128, 256)
a2.set_time(5000)
a2.set_playback_time(3000)
a2.set_repeat_count(lv.ANIM_REPEAT.INFINITE)
lv.anim_t.start(a2)

---

Image offset and styling

C code  

 GitHub

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

static void ofs_y_anim(void * img, int32_t v)
{
    lv_img_set_offset_y(img, v);
}

/**
 * Image styling and offset
 */
void lv_example_img_4(void)
{
    LV_IMG_DECLARE(img_skew_strip);

    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_bg_color(&style, lv_palette_main(LV_PALETTE_YELLOW));
    lv_style_set_bg_opa(&style, LV_OPA_COVER);
    lv_style_set_img_recolor_opa(&style, LV_OPA_COVER);
    lv_style_set_img_recolor(&style, lv_color_black());

    lv_obj_t * img = lv_img_create(lv_scr_act());
    lv_obj_add_style(img, &style, 0);
    lv_img_set_src(img, &img_skew_strip);
    lv_obj_set_size(img, 150, 100);
    lv_obj_center(img);

    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_var(&a, img);
    lv_anim_set_exec_cb(&a, ofs_y_anim);
    lv_anim_set_values(&a, 0, 100);
    lv_anim_set_time(&a, 3000);
    lv_anim_set_playback_time(&a, 500);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_start(&a);

}

#endif

MicroPython code  

 GitHub Simulator

from imagetools import get_png_info, open_png

def ofs_y_anim(img, v):
    img.set_offset_y(v)
    # print(img,v)

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

# Create an image from the png file
try:
    with open('../../assets/img_skew_strip.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find img_skew_strip.png")
    sys.exit()

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

#
# Image styling and offset
#

style = lv.style_t()
style.init()
style.set_bg_color(lv.palette_main(lv.PALETTE.YELLOW))
style.set_bg_opa(lv.OPA.COVER)
style.set_img_recolor_opa(lv.OPA.COVER)
style.set_img_recolor(lv.color_black())

img = lv.img(lv.scr_act())
img.add_style(style, 0)
img.set_src(img_skew_strip)
img.set_size(150, 100)
img.center()

a = lv.anim_t()
a.init()
a.set_var(img)
a.set_values(0, 100)
a.set_time(3000)
a.set_playback_time(500)
a.set_repeat_count(lv.ANIM_REPEAT.INFINITE)
a.set_custom_exec_cb(lambda a,val: ofs_y_anim(img,val))
lv.anim_t.start(a)

---

API

Typedefs

typedef uint8_t lv_img_size_mode_t

Enums

Image size mode, when image size and object size is different

Values:

enumerator LV_IMG_SIZE_MODE_VIRTUAL

Zoom doesn't affect the coordinates of the object, however if zoomed in the image is drawn out of the its coordinates. The layout's won't change on zoom

enumerator LV_IMG_SIZE_MODE_REAL

If the object size is set to SIZE_CONTENT, then object size equals zoomed image size. It causes layout recalculation. If the object size is set explicitly, the image will be cropped when zoomed in.

Functions

lv_obj_t *lv_img_create(lv_obj_t *parent)

Create an image object

Parameters

parent -- pointer to an object, it will be the parent of the new image

Returns

pointer to the created image

void lv_img_set_src(lv_obj_t *obj, const void *src)

Set the image data to display on the object

Parameters

• obj -- pointer to an image object

• src_img -- 1) pointer to an lv_img_dsc_t descriptor (converted by LVGL's image converter) (e.g. &my_img) or 2) path to an image file (e.g. "S:/dir/img.bin")or 3) a SYMBOL (e.g. LV_SYMBOL_OK)

void lv_img_set_offset_x(lv_obj_t *obj, lv_coord_t x)

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

Parameters

• obj -- pointer to an image

• x -- the new offset along x axis.

void lv_img_set_offset_y(lv_obj_t *obj, lv_coord_t y)

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

Parameters

• obj -- pointer to an image

• y -- the new offset along y axis.

void lv_img_set_angle(lv_obj_t *obj, 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() Note that indexed and alpha only images can't be transformed.

Parameters

• obj -- pointer to an image object

• angle -- rotation angle in degree with 0.1 degree resolution (0..3600: clock wise)

void lv_img_set_pivot(lv_obj_t *obj, lv_coord_t x, lv_coord_t y)

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

Parameters

• obj -- pointer to an image object

• x -- rotation center x of the image

• y -- rotation center y of the image

void lv_img_set_zoom(lv_obj_t *obj, uint16_t zoom)

void lv_img_set_antialias(lv_obj_t *obj, bool antialias)

Enable/disable anti-aliasing for the transformations (rotate, zoom) or not. The quality is better with anti-aliasing looks better but slower.

Parameters

• obj -- pointer to an image object

• antialias -- true: anti-aliased; false: not anti-aliased

void lv_img_set_size_mode(lv_obj_t *obj, lv_img_size_mode_t mode)

Set the image object size mode.

Parameters

• obj -- pointer to an image object

• mode -- the new size mode.

const void *lv_img_get_src(lv_obj_t *obj)

Get the source of the image

Parameters

obj -- pointer to an image object

Returns

the image source (symbol, file name or ::lv-img_dsc_t for C arrays)

lv_coord_t lv_img_get_offset_x(lv_obj_t *obj)

Get the offset's x attribute of the image object.

Parameters

img -- pointer to an image

Returns

offset X value.

lv_coord_t lv_img_get_offset_y(lv_obj_t *obj)

Get the offset's y attribute of the image object.

Parameters

obj -- pointer to an image

Returns

offset Y value.

uint16_t lv_img_get_angle(lv_obj_t *obj)

Get the rotation angle of the image.

Parameters

obj -- pointer to an image object

Returns

rotation angle in 0.1 degrees (0..3600)

void lv_img_get_pivot(lv_obj_t *obj, lv_point_t *pivot)

Get the pivot (rotation center) of the image.

Parameters

• img -- pointer to an image object

• pivot -- store the rotation center here

uint16_t lv_img_get_zoom(lv_obj_t *obj)

Get the zoom factor of the image.

Parameters

obj -- pointer to an image object

Returns

zoom factor (256: no zoom)

bool lv_img_get_antialias(lv_obj_t *obj)

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

Parameters

obj -- pointer to an image object

Returns

true: anti-aliased; false: not anti-aliased

lv_img_size_mode_t lv_img_get_size_mode(lv_obj_t *obj)

Get the size mode of the image

Parameters

obj -- pointer to an image object

Returns

element of lv_img_size_mode_t

Variables

const lv_obj_class_t lv_img_class

struct lv_img_t

#include <lv_img.h>

Data of image

Public Members

lv_obj_t obj

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 cf

uint8_t antialias

uint8_t obj_size_mode