Labs / LVGL / 03 Quick Start Example - Control Section (Based on Web Simulator and LVGL v9.0)

22. Displaying Images and Animated GIFs

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents

The summary table of core APIs for lv.image is as follows:

API nameMeaningInput arguments (count + type + description)Return value (type + description)
set_rotationSet the image rotation angle1, int type (rotation angle, e.g. 90/180/270)None, no return value
get_rotationGet the current image rotation angle0, no input argumentsint type (current rotation angle value)
set_srcSet the image source (file / symbol / binary data)1, str type (image path such as "test.png" or an LVGL built-in symbol)None, no return value
set_offset_xSet the image X-axis offset (horizontal position adjustment)1, int type (offset in pixels; positive shifts right, negative shifts left)None, no return value
get_offset_xGet the current image X-axis offset0, no input argumentsint type (current X-axis offset in pixels)
set_offset_ySet the image Y-axis offset (vertical position adjustment)1, int type (offset in pixels; positive shifts down, negative shifts up)None, no return value
get_offset_yGet the current image Y-axis offset0, no input argumentsint type (current Y-axis offset in pixels)
set_scaleSet the overall image zoom ratio (proportional scaling)1, int type (zoom ratio, 100=100%, 200=200%)None, no return value
get_scaleGet the current overall image zoom ratio0, no input argumentsint type (current overall zoom ratio value)
set_scale_xSet the image X-axis zoom ratio separately (width scaling only)1, int type (X-axis zoom ratio)None, no return value
get_scale_xGet the current image X-axis zoom ratio0, no input argumentsint type (current X-axis zoom ratio value)
set_scale_ySet the image Y-axis zoom ratio separately (height scaling only)1, int type (Y-axis zoom ratio)None, no return value
get_scale_yGet the current image Y-axis zoom ratio0, no input argumentsint type (current Y-axis zoom ratio value)
set_antialiasEnable / disable image anti-aliasing (smooths scaled / rotated edges)1, bool type (True to enable, False to disable)None, no return value
get_antialiasCheck whether image anti-aliasing is enabled0, no input argumentsbool type (True = enabled, False = disabled)
set_blend_modeSet the image blend mode (transparency / overlay effects, etc.)1, lv.blend_mode_t enum (e.g. lv.BLEND_MODE.NORMAL)None, no return value
get_blend_modeGet the current image blend mode0, no input argumentslv.blend_mode_t enum (current blend mode)
set_pivotSet the image rotation pivot point2, int type (x: pivot X coordinate, y: pivot Y coordinate)None, no return value
get_pivotGet the image rotation pivot point1, lv.point_t object (used to receive the pivot coordinates)None, the result is stored in the passed-in lv.point_t object

The summary table of core APIs for lv.image is as follows:

API nameMeaningInput parametersReturn valueTypical exception messages in the SDL environment
set_srcSet the GIF source (file / binary data)Count: 1 Type: str/bytes Description: str = GIF file path (e.g. "anim.gif"); bytes = GIF binary dataCount: 0 Type: None Description: No return value1. Wrong argument count: argument num/types mismatch 2. Wrong type (int passed): Cannot convert 'int' to pointer!
restartRestart GIF playback (play from the beginning)Count: 0 Type: None Description: No arguments neededCount: 0 Type: None Description: No return valuePassing any argument: argument num/types mismatch
pausePause GIF playbackCount: 0 Type: None Description: No arguments neededCount: 0 Type: None Description: No return valuePassing any argument: argument num/types mismatch
resumeResume GIF playback (continue after pause)Count: 0 Type: None Description: No arguments neededCount: 0 Type: None Description: No return valuePassing any argument: argument num/types mismatch

The summary table of LVGL built-in symbols (SYMBOL) is shown below, which organizes the name, meaning, type and typical usage scenarios of LVGL built-in symbols (lv.SYMBOL) by function to adapt to the development requirements of SDL LVGL/MicroPython environment, and all symbol types are int (can be directly passed to interfaces such as lv.image.set_src / button text):

CategorySymbol nameMeaningTypeTypical Use Case
Basic identifiersSYMBOL.BULLETDot / bulletintList item prefix, marker dot
Basic identifiersSYMBOL.LISTListintList menu entry, list view icon
Basic identifiersSYMBOL.OKConfirm / checkmarkintSubmit button, operation success indicator
Basic identifiersSYMBOL.CLOSEClose / crossintClose button, cancel operation, popup close
Basic identifiersSYMBOL.WARNINGWarning / exclamation markintError indication, risky operation reminder
MultimediaSYMBOL.AUDIOAudio / soundintAudio playback entry, sound settings
MultimediaSYMBOL.VIDEOVideointVideo playback entry, video settings
MultimediaSYMBOL.MUTEMuteintMute button, volume off
MultimediaSYMBOL.VOLUME_MIDMedium volumeintVolume adjustment (medium)
MultimediaSYMBOL.VOLUME_MAXMaximum volumeintVolume adjustment (maximum)
MultimediaSYMBOL.PREVPrevious track / previous frameintMedia playback control (previous)
MultimediaSYMBOL.PLAYPlayintPlay button, start animation
MultimediaSYMBOL.PAUSEPauseintPause button, pause animation
MultimediaSYMBOL.STOPStopintStop button, stop playback
MultimediaSYMBOL.NEXTNext track / next frameintMedia playback control (next)
MultimediaSYMBOL.EJECTEject / exitintDisc eject, device exit
MultimediaSYMBOL.SHUFFLEShuffleintMedia shuffle mode
MultimediaSYMBOL.LOOPRepeatintMedia repeat mode
Navigation / directionSYMBOL.LEFTLeft arrowintBack, move left, previous step
Navigation / directionSYMBOL.RIGHTRight arrowintForward, move right, next step
Navigation / directionSYMBOL.UPUp arrowintMove up, scroll up, increase
Navigation / directionSYMBOL.DOWNDown arrowintMove down, scroll down, decrease
Operation / controlSYMBOL.POWERPower supplyintPower on / off button, power status
Operation / controlSYMBOL.SETTINGSSettingsintSettings entry, configuration menu
Operation / controlSYMBOL.HOMEHomeintReturn to home button
Operation / controlSYMBOL.REFRESHRefresh / reloadintRefresh data, reload page
Operation / controlSYMBOL.PLUSPlus signintIncrease, add, create new
Operation / controlSYMBOL.MINUSMinus signintDecrease, delete, remove
Operation / controlSYMBOL.EYE_OPENEye (open)intShow password, show hidden content
Operation / controlSYMBOL.EYE_CLOSEEye (closed)intHide password, hide sensitive content
Operation / controlSYMBOL.CUTCutintText / file cut operation
Operation / controlSYMBOL.COPYCopyintText / file copy operation
Operation / controlSYMBOL.PASTEPasteintText / file paste operation
Operation / controlSYMBOL.SAVESaveintSave file, save configuration
Operation / controlSYMBOL.EDITEditintEdit text, modify content
Operation / controlSYMBOL.BACKSPACEBackspace / deleteintKeyboard backspace, delete character
Operation / controlSYMBOL.NEW_LINENewlineintKeyboard newline, text line break
File / storageSYMBOL.DOWNLOADDownloadintFile download, data import
File / storageSYMBOL.UPLOADUploadintFile upload, data export
File / storageSYMBOL.DRIVEDrive / diskintDisk / drive entry
File / storageSYMBOL.DIRECTORYFolder / directoryintFolder entry, directory browsing
File / storageSYMBOL.FILEFileintFile icon, file list item
File / storageSYMBOL.TRASHRecycle bin / deleteintDelete file, empty recycle bin
File / storageSYMBOL.SD_CARDSD cardintSD card storage, external storage entry
Device / connectionSYMBOL.CALLPhone / callintMake a call, call log
Device / connectionSYMBOL.WIFIWIFIintWIFI status, network settings
Device / connectionSYMBOL.BLUETOOTHBluetoothintBluetooth status, Bluetooth settings
Device / connectionSYMBOL.USBUSBintUSB connection, USB storage
Device / connectionSYMBOL.GPSPositioning / GPSintLocation service, map navigation
Status / promptSYMBOL.BARSProgress bar / bar chartintProgress display, data statistics
Status / promptSYMBOL.ENVELOPEEnvelope / mailintMail notification, message center
Status / promptSYMBOL.CHARGEChargingintDevice charging status, charging prompt
Status / promptSYMBOL.BELLBell / notificationintMessage notification, reminder settings
Status / promptSYMBOL.BATTERY_FULLBattery (full)intBattery full status
Status / promptSYMBOL.BATTERY_3Battery (3/4)intBattery 75% charge status
Status / promptSYMBOL.BATTERY_2Battery (2/4)intBattery 50% charge status
Status / promptSYMBOL.BATTERY_1Battery (1/4)intBattery 25% charge status
Status / promptSYMBOL.BATTERY_EMPTYBattery (empty)intBattery low / dead status
Image / editSYMBOL.IMAGEPicture / imageintImage viewing, gallery entry
Image / editSYMBOL.TINTColor adjustment / coloringintImage color adjustment, color settings
Input / interactionSYMBOL.KEYBOARDKeyboardintVirtual keyboard, input entry
Placeholder / testSYMBOL.DUMMYPlaceholder / testintUI placeholder, function test

LVGL Blend Mode lv.BLEND_MODE Names, descriptions, blending effects and typical use cases of all enumeration values:

Symbol nameMeaningTypeBlend effect descriptionTypical Use Case
BLEND_MODE.NORMALNormal blendintDefault mode, foreground pixels cover background pixels (background shows only in transparent areas), no color overlay / modificationNormal display (icons, text, regular images, buttons)
BLEND_MODE.ADDITIVEAdditive blendintForeground color + background color (brightness adds up, colors get brighter as they mix, white + any color = white)Glow effect (button highlight, notification prompt, light animation, gradient glow)
BLEND_MODE.SUBTRACTIVESubtractive blendintBackground color - foreground color (brightness decreases, colors get darker as they mix, black - any color = black)Shadow effects, mask overlays, vignette processing, reducing local brightness
BLEND_MODE.MULTIPLYMultiplyintForeground color × background color (colors darken, contrast increases, white × any color = original background color)Image overlay, texture blending, dark watermarks, retro filters
BLEND_MODE.DIFFERENCEDifference blendintDifference between the pixel values of the foreground and background colors (colors invert, strong contrast, same color = black)Color inversion effects, difference marking, warning alerts, contrast highlighting

22.1 Basic Display of Images and GIFs

import display_driver
import lvgl as lv
import fs_driver

# Initialize the LVGL environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

fs_drv = lv.fs_drv_t()
fs_driver.fs_register(fs_drv, 'S')

'''Display LVGL built-in symbols'''
# Create image
img_symbol = lv.image(scr)
# Display an LVGL built-in symbol ("AUDIO" icon); for more icons see the "class SYMBOL" section of api.py
img_symbol.set_src(lv.SYMBOL.AUDIO)
#Center it
img_symbol.align(lv.ALIGN.CENTER, 0, 0)

# The code below cannot be displayed in the simulator!!!

# '''Display images from storage'''
# img_symbol2 = lv.image(scr)
# # Display png
# img_symbol2.set_src('S:001.png')
# # Display jpg
# #img_symbol2.set_src('S:001.jpg')
# img_symbol2.align(lv.ALIGN.RIGHT_MID, 0, 0)  # Display on the right

# '''Display gif'''
# img_symbol3 = lv.gif(scr)
# img_symbol3.set_src('S:001.gif')
# img_symbol3.align(lv.ALIGN.LEFT_MID, 0, 0)  # Display on the left

# Load the screen
lv.screen_load(scr)
v1.20.0-1053-g349ae32bf-dirty 2024-09-11 22.1

22.2 Internal Icon Display

The code is as follows:

import display_driver
import lvgl as lv

# Initialize the LVGL environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)  # White background

# ========== 1. Core parameter configuration (adjustable, controls density/size) ==========
ICON_SIZE = 24          # Size of a single icon (width = height; smaller shows more)
ICON_GAP = 8            # Spacing between icons (horizontal/vertical)
SCREEN_PADDING = 8      # Padding at screen edges (keeps icons from touching the edge)

# ========== 2. Get all built-in SYMBOL icons ==========
symbol_list = [
    getattr(lv.SYMBOL, name)
    for name in dir(lv.SYMBOL)
    if not name.startswith("__") and name.isupper()
]
total_icons = len(symbol_list)
print(f"Total icons: {total_icons}")

# ========== 3. Dynamically calculate layout (adapts to any screen size) ==========
# Get actual screen size (automatically adapted in the SDL environment)
screen_w = scr.get_width()
screen_h = scr.get_height()

# Calculate the number of icons that fit per row/column
icons_per_row = (screen_w - 2 * SCREEN_PADDING) // (ICON_SIZE + ICON_GAP)
icons_per_col = (screen_h - 2 * SCREEN_PADDING) // (ICON_SIZE + ICON_GAP)
max_icons_per_screen = icons_per_row * icons_per_col
print(f"Screen size: {screen_w}x{screen_h}")
print(f"Icons per row: {icons_per_row}, per column: {icons_per_col}")
print(f"Max icons per screen: {max_icons_per_screen}")

# ========== 4. Manual layout: create icons one by one and set coordinates ==========
for idx, sym in enumerate(symbol_list):
    # Skip the part beyond one screen (to show all, add scrolling; see the extension below)
    if idx >= max_icons_per_screen:
        break
    
    # Calculate the row/column of the current icon
    row = idx // icons_per_row
    col = idx % icons_per_row
    
    # Calculate icon coordinates (core formula for even distribution)
    x = SCREEN_PADDING + col * (ICON_SIZE + ICON_GAP)
    y = SCREEN_PADDING + row * (ICON_SIZE + ICON_GAP)
    
    # Create icon (directly as a child of the screen, no container)
    img = lv.image(scr)
    img.set_size(ICON_SIZE, ICON_SIZE)  # Fixed size
    img.set_src(sym)                    # Set SYMBOL icon
    img.set_pos(x, y)                   # Set coordinates manually

# ========== 5. Load screen ==========
lv.screen_load(scr)
62 12 9 108 420x320 22.2

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.