# Image (lv_image) (/widgets/image)



<br />

<hr />

Overview [#overview]

Images are Widgets that display images from flash (as arrays) or
from files. Images can also display symbols (`LV_SYMBOL_...`).

Using the [Image decoder interface](/main-modules/images/decoders), custom image formats
can be supported as well.

Parts and Styles [#parts-and-styles]

* <ApiLink name="LV_PART_MAIN" /> A background rectangle that uses the [typical
  background style properties](/common-widget-features/styles/overview), and the image itself uses the image
  style properties.

Usage [#usage]

Image source [#image-source]

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

* a variable in code (a C array containing the pixels).
* a file stored externally (e.g. on an SD card).
* a [Symbol](/main-modules/fonts/overview) as text.

To set the source of an image, use <ApiLink name="lv_image_set_src" display="lv_image_set_src(img, src)" />.

To generate a pixel array from a PNG, JPG or BMP image, use the LVGL Online Image Converter
and set the converted image as the image source with its pointer with
<ApiLink name="lv_image_set_src" display="lv_image_set_src(img1, &converted_img_var)" />.
To make the converted image variable accessible from the C file, declare it with
<ApiLink name="LV_IMAGE_DECLARE" display="LV_IMAGE_DECLARE(converted_img_var)" />.

To use external files, you also need to convert the image files using
the online converter tool, but select the binary output
format. You also need to use LVGL's file system module and register a
driver with some functions for basic file operations.  See
[File system](/main-modules/fs) to learn more.  Then set the translated
image as the image source with <ApiLink name="lv_image_set_src" display="lv_image_set_src(img, &#x22;S:folder1/my_img.bin&#x22;)" />.

You can also set a symbol as an image source similar to a [Labels](/widgets/label). In
this case, the image will be rendered as text according to the *font*
specified in the style. It enables the use of light-weight monochrome
"characters" instead of real images. You can set a symbol as an image source with
<ApiLink name="lv_image_set_src" display="lv_image_set_src(img1, LV_SYMBOL_OK)" />.

Label as an image [#label-as-an-image]

Images and labels are sometimes used to convey the same thing, such as
describing what a button does.  In this context, images and labels
are somewhat interchangeable:  images can display text by
using the macro <ApiLink name="LV_SYMBOL_DUMMY" /> (which equates to a 3-byte C string
containing a special code) as the prefix of the text.  For example,
`lv_image_set_src(img, LV_SYMBOL_DUMMY "Some text")`.

Transparency [#transparency]

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

* **Alpha byte**: An alpha channel is added to every pixel that contains
  its opacity, typically a byte.  It is the 'A' in the various color formats
  that contain an alpha channel, such as ARGB8888, ARGB8565, ARGB1555, etc.
* **Indexed transparent color**:  a specific index in a color palette serves to
  signal transparency for each pixel that uses it.

Palette and Alpha index [#palette-and-alpha-index]

Besides RGB888 and ARGB8888 color formats, the following formats are supported:

* **Indexed**: Image has a color palette, and each pixel is an index into that palette.
* **Alpha indexed**: The values stored at pixel positions are alpha (opacity) values.

These options can be selected in the LVGL Online Image Converter.  Learn more
about color formats in the [Color Formats](/main-modules/images/color_formats) section.

Recolor [#recolor]

A color can be mixed with every pixel of an image with a given
intensity. This can be useful to show different states (checked,
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_recolor_opa` between <ApiLink name="LV_OPA_TRANSP" /> (no recolor, value: 0) and
<ApiLink name="LV_OPA_COVER" /> (full recolor, value: 255). The default value is
<ApiLink name="LV_OPA_TRANSP" /> causing this feature to be disabled.

The color to mix is set by `img_recolor`.

Offset [#offset]

With <ApiLink name="lv_image_set_offset_x" display="lv_image_set_offset_x(img, x_ofs)" /> and
<ApiLink name="lv_image_set_offset_y" display="lv_image_set_offset_y(img, y_ofs)" />, you can add some offset to the
displayed image. Useful if the Widget size is smaller than the image
source size. Using the offset parameter a [Texture atlas](https://en.wikipedia.org/wiki/Texture_atlas)
or a "running image" effect can be created by [Animating](/main-modules/animation) the x or y offset.

Transformations [#transformations]

You can zoom images in or out by using <ApiLink name="lv_image_set_scale" display="lv_image_set_scale(img, factor)" />.
Set `factor` to `256` or <ApiLink name="LV_SCALE_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 scaling works using a value
that is proportionally larger or smaller, e.g. `281` for 10% enlargement.

<ApiLink name="lv_image_set_scale_x" display="lv_image_set_scale_x(img, factor)" /> and
<ApiLink name="lv_image_set_scale_y" display="lv_image_set_scale_y(img, factor)" /> can also be used to
set the horizontal and vertical scaling independently.  They can be different values.

To rotate the image use <ApiLink name="lv_image_set_rotation" display="lv_image_set_rotation(img, angle_x10)" />.
The `angle_x10` argument is an `int32_t` containing the angle (in degrees)
multiplied by 10.  This gives 0.1-degree resolution.  Example:  458 means 45.8°.

By default, the pivot point of the rotation is the center of the image.
This can be changed with <ApiLink name="lv_image_set_pivot" display="lv_image_set_pivot(img, pivot_x, pivot_y)" /> where
the coordinates `(0,0)` represent the top left corner.

The quality of the transformation can be adjusted with
<ApiLink name="lv_image_set_antialias" display="lv_image_set_antialias(img, true)" />. Enabling anti-aliasing
causes the transformations to be of higher quality, but slower.

Transformations require the whole image to be available. Therefore
indexed images (`LV_COLOR_FORMAT_I1/2/4/8_...`) and alpha only images cannot be transformed.
In other words transformations work only on normal (A)RGB or A8 images stored as a
C array, or on images provided by a custom [Image Decoders](/main-modules/images/decoders)
that returns the whole image.

Note that the real coordinates of image Widgets do not change with a
transformation. That is <ApiLink name="lv_obj_get_width" display="lv_obj_get_width/height/x/y" /> will return
the original, non-zoomed coordinates.

**IMPORTANT**:  The transformation of the image is independent of the transformation
properties [coming from styles](/common-widget-features/styles/overview).
The main differences are that pure Image Widget transformations:

* do not transform the children of the Image Widget, and
* the image is transformed directly without creating an intermediate layer (buffer) to snapshot the Widget.

Inner align [#inner-align]

By default the image Widget's width and height are <ApiLink name="LV_SIZE_CONTENT" />,
meaning that the Widget will be sized automatically to the size of its image source.

If the Widget's width or height is set to a different value, the value of the `inner_align`
property (set using <ApiLink name="lv_image_set_inner_align" display="lv_image_set_inner_align(widget, align)" />) governs how
the image source is aligned inside the Widget.

`align` can be any of these values:

* <ApiLink name="LV_IMAGE_ALIGN_DEFAULT" />: Meaning top left
* <ApiLink name="LV_IMAGE_ALIGN_TOP_LEFT" />
* <ApiLink name="LV_IMAGE_ALIGN_TOP_MID" />
* <ApiLink name="LV_IMAGE_ALIGN_TOP_RIGHT" />
* <ApiLink name="LV_IMAGE_ALIGN_BOTTOM_LEFT" />
* <ApiLink name="LV_IMAGE_ALIGN_BOTTOM_MID" />
* <ApiLink name="LV_IMAGE_ALIGN_BOTTOM_RIGHT" />
* <ApiLink name="LV_IMAGE_ALIGN_LEFT_MID" />
* <ApiLink name="LV_IMAGE_ALIGN_RIGHT_MID" />
* <ApiLink name="LV_IMAGE_ALIGN_CENTER" />
* <ApiLink name="LV_IMAGE_ALIGN_STRETCH" />
* <ApiLink name="LV_IMAGE_ALIGN_TILE" />
* <ApiLink name="LV_IMAGE_ALIGN_CONTAIN" />
* <ApiLink name="LV_IMAGE_ALIGN_COVER" />

Any `offset` value is applied after the image source is aligned. For example setting
an offset of `y=-10` with `align` == <ApiLink name="LV_IMAGE_ALIGN_CENTER" /> will
move the image source up 10 pixels from the center of the Widget.

To automatically scale or tile the image, pass one of these `align` values:

* <ApiLink name="LV_IMAGE_ALIGN_STRETCH" /> Set X and Y scale to fill the Widget's area
* <ApiLink name="LV_IMAGE_ALIGN_TILE" /> Tile image to fill Widget's area. Offset is applied to shift the tiling.
* <ApiLink name="LV_IMAGE_ALIGN_CONTAIN" /> The image keeps its aspect ratio, but is resized to the maximum size that fits within the Widget's area.
* <ApiLink name="LV_IMAGE_ALIGN_COVER" /> The image keeps its aspect ratio and fills the Widget's area.

Data binding [#data-binding]

To get familiar with observers, subjects, and data bindings in general visit the
[Observer](/main-modules/observer/observer) page.

This method of subscribing to a pointer Subject affects a Image Widget's source (`src`)
value directly.  Note that this is a one-way binding (Subject ==> Widget) so when
the subject changes, the Image will be updated too.

It supports only pointer subjects.

* <ApiLink name="lv_image_bind_src" display="lv_image_bind_src(img, &subject)" />

Events [#events]

No special events are sent by Image Widgets.  By default, Image Widgets are created
without the LV\_OBJ\_FLAG\_CLICKABLE flag, but you can add it to make an Image Widget
detect and emit LV\_EVENT\_CLICKED events if desired.

<Callout type="info" title="Further Reading">
  Learn more about [Events](/common-widget-features/events) emitted by all Widgets.

  Learn more about [events](/common-widget-features/events).
</Callout>

Keys [#keys]

No *Keys* are processed by Image Widgets.

<Callout type="info" title="Further Reading">
  Learn more about [Keys](/main-modules/indev/keypad).
</Callout>

Examples [#examples]

Image from variable and symbol [#image-from-variable-and-symbol]

<LvglExample name="lv_example_image_1" path="widgets/image/lv_example_image_1" />

Image recoloring [#image-recoloring]

<LvglExample name="lv_example_image_2" path="widgets/image/lv_example_image_2" />

Rotate and zoom [#rotate-and-zoom]

<LvglExample name="lv_example_image_3" path="widgets/image/lv_example_image_3" />

Image offset and styling [#image-offset-and-styling]

<LvglExample name="lv_example_image_4" path="widgets/image/lv_example_image_4" />

API [#api]