Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for a specific release, use the drop-down menu on the left.

DisplayConfig Module API Manual

Overview

libs/DisplayConfig.py is used to solve the display adaptation issue when running the same AI example on different development boards. The development boards in the K230/K230D ecosystem are equipped with different screens (HDMI, ST7701, HX8399, ILI9806…), and previously examples required manually modifying display_mode to run on another board. This module centrally maintains the “board type → screen driver” mapping, and combined with display_mode="auto", it enables cross-board operation.

The module provides three functions and one class:

Name	Purpose
get_default_display_mode	Queries the default screen driver name for the current development board
get_display_type	Resolves the driver name into the driver constant required by Display.init()
init_display	Initializes the display and returns the actual display resolution, suitable for scenarios that do not use PipeLine
DisplayImage	Uses AI2D to scale RGB888 data of any resolution to the display resolution

Tip

AI programs that use PipeLine do not need to call this module directly; just set display_mode to "auto", and PipeLine will automatically handle the resolution internally. This module is mainly intended for scenarios that do not use PipeLine, such as UVC cameras, MP4 decoding playback, LVGL applications, etc.

API Introduction

get_default_display_mode

Description

Returns the default screen driver name for the development board based on the board model. The board type is obtained through os.uname()[-1].

Note

The return value is the recommended driver that comes with the development board, not a hardware detection result of which screen is actually connected. If you are using a non-standard screen, please explicitly specify display_mode.

Syntax

from libs.DisplayConfig import get_default_display_mode

mode = get_default_display_mode()          # Query the current development board
mode = get_default_display_mode("k230_canmv_01studio")   # Query a specific board type

Parameters

Parameter Name	Description	Input / Output	Notes
board_type	Development board model string	Input	Optional, default None means querying the currently running firmware

Return Value

Return Value	Description
str	Screen driver name, such as hdmi, st7701, hx8399, etc., which can be passed directly to PipeLine’s display_mode

Supported development boards and their default screen drivers:

Default Driver	Development Board
hdmi	k230_canmv、k230_canmv_v3p0
hx8399	k230_evb、k230d_evb
nt35516	k230_canmv_rtt_evb
st7701	k230_canmv_01studio、k230_canmv_lckfb、k230_canmv_yahboom、k230_canmv_mrt、k230_canmv_hiwonder、k230_labplus_1956、k230d_canmv_bpi_zero、k230d_canmv_atk_dnk230d、k230d_canmv_junroc_ai_cam、k230d_canmv_lushanpi_lite、k230d_canmv_mini、k230d_labplus_ai_camera、k230d_labplus_ai_camera_v2
ili9806	k230_canmv_dongshanpi
gc9503	k230_canmv_gt6700
jd9852	k230_canmv_wondermk

Note

When the board type is not in the table above, ValueError: No default display for board <model>; set display_mode explicitly will be raised. In this case, please explicitly specify the screen driver instead of using auto.

get_display_type

Description

Resolves the screen driver name into the driver constant required by Display.init().

Syntax

from libs.DisplayConfig import get_display_type
from media.display import Display

display_type = get_display_type("auto")
Display.init(display_type)

Parameters

Parameter Name	Description	Input / Output	Notes
display_mode	Screen driver name or Display constant	Input	Default "auto". See the display_mode value table in the PipeLine manual for valid values. When an int type (i.e., Display.XXX constant) is passed, it is returned as-is

Return Value

Return Value	Description
int	Driver constant accepted by Display.init()

Note

Passing an unsupported string will not raise an error; it will fall back to Display.ST7701. This behavior is retained for compatibility with old code; new code should use the standard values.

init_display

Description

Initializes the display device and returns the actually effective display resolution. The screen driver may not support the requested resolution and will use its own default instead, so subsequent layout calculations must use the return value of this function as the source of truth, not the passed-in display_size.

Syntax

from libs.DisplayConfig import init_display

display_size = init_display(display_mode="auto", osd_num=1, to_ide=True)
width, height = display_size

Parameters

Parameter Name	Description	Input / Output	Notes
display_mode	Screen driver name or Display constant	Input	Default "auto"
display_size	Expected display resolution [width, height]	Input	Optional, default None means using the driver’s default resolution. Please use this parameter instead of the width/height keyword arguments
**kwargs	Other parameters passed through to Display.init()	Input	Such as osd_num, to_ide, etc.

Return Value

Return Value	Description
list[int]	Actual display resolution [width, height]

Note

This function is only responsible for initializing the display; the caller needs to call Display.deinit() on its own. It also does not start the sensor, nor does it change the AI inference resolution, decoding resolution, or recording resolution; these need to be configured separately.

DisplayImage

Description

Uses AI2D hardware to scale RGB888 data of any resolution to the display resolution, and wraps it into an image.Image for display use. A typical scenario is adapting when the resolution of images output from a UVC camera or MP4 decoding does not match the screen.

Internally, the same AI2D pipeline is reused, and it is only rebuilt when the input resolution changes, so the overhead of per-frame calls is very low.

Syntax

from libs.DisplayConfig import init_display, DisplayImage

display_size = init_display(display_mode="auto")
resizer = DisplayImage(display_size, planar=False)

while True:
    img = resizer.run(frame_np)     # frame_np is HWC-layout uint8 RGB data
    Display.show_image(img)

resizer.deinit()

Constructor Parameters

Parameter Name	Description	Input / Output	Notes
display_size	Target resolution [width, height]	Input	Required, usually pass the return value of init_display() directly
planar	Whether the input data is in planar layout	Input	True means the input is in CHW layout, False (default) means HWC layout

run Method

Parameter Name	Description	Input / Output	Notes
input_np	Data to be scaled, of type ulab.numpy.ndarray	Input	Contiguous uint8 RGB data; the layout must match the planar setting during construction

Return Value	Description
image.Image	An Image instance in RGB888 format, with the resolution specified during construction

deinit Method

Releases the AI2D resources held by DisplayImage; no parameters and no return value. Must be called before the program exits.

Note

• run() internally makes a copy of the AI2D output; the returned Image references an independent data copy, so the next run() will not overwrite it, and it is safe to retain across frames.

• The passed-in input_np must remain valid until run() returns (e.g., borrowed data from to_numpy_ref()).

• The underlying AI2D pipeline is only rebuilt when the input shape changes, so the overhead of per-frame calls is very low.

Example Program

Below is the framework code that does not use PipeLine and directly uses this module to adapt the display:

from media.display import Display
from libs.DisplayConfig import init_display, DisplayImage
import gc

resizer = None
try:
    # Automatically select the screen according to the development board model, return the actual resolution
    display_size = init_display(display_mode="auto", osd_num=1, to_ide=True)
    print("display size:", display_size)

    # When the source frame resolution does not match the screen, use DisplayImage to scale
    resizer = DisplayImage(display_size, planar=False)

    while True:
        frame_np = get_frame_from_somewhere()   # UVC / VDEC and other sources, HWC uint8 RGB
        img = resizer.run(frame_np)
        Display.show_image(img)
        gc.collect()
finally:
    if resizer is not None:
        resizer.deinit()
    Display.deinit()      # init_display is not responsible for deinitialization, you need to call it yourself