注意

这是最新开发分支的文档，可能包含尚未在发布版本中提供的功能。如果您在寻找特定版本的文档，请使用左侧的下拉菜单选择。

DisplayConfig 模块API手册

概述

libs/DisplayConfig.py 用于解决同一份 AI 例程在不同开发板上显示适配的问题。K230/K230D 生态中的开发板搭载的屏幕各不相同（HDMI、ST7701、HX8399、ILI9806……），过去例程需要手动修改 display_mode 才能在另一块板子上跑起来。该模块把”板型 → 屏驱动”的对应关系集中维护，配合 display_mode="auto" 即可实现跨板运行。

模块提供三个函数和一个类：

名称	用途
get_default_display_mode	查询当前开发板的默认屏驱动名称
get_display_type	把驱动名称解析成 Display.init() 需要的驱动常量
init_display	初始化显示并返回实际显示分辨率，适合不使用 PipeLine 的场景
DisplayImage	用 AI2D 把任意分辨率的 RGB888 数据缩放到显示分辨率

提示

使用 PipeLine 的 AI 程序不需要直接调用本模块，只要把 display_mode 设为 "auto"，PipeLine 内部会自动完成解析。本模块主要面向不走 PipeLine 的场景，例如 UVC 摄像头、MP4 解码播放、LVGL 应用等。

API 介绍

get_default_display_mode

描述

根据开发板型号返回该板的默认屏驱动名称。板型通过 os.uname()[-1] 获取。

注意

返回的是该开发板配套推荐的驱动，而不是对实际插着哪块屏的硬件探测结果。如果您接的是非标配屏幕，请显式指定 display_mode。

语法

from libs.DisplayConfig import get_default_display_mode

mode = get_default_display_mode()          # 查询当前开发板
mode = get_default_display_mode("k230_canmv_01studio")   # 查询指定板型

参数

参数名称	描述	输入 / 输出	说明
board_type	开发板型号字符串	输入	可选，默认 None 表示查询当前运行的固件

返回值

返回值	描述
str	屏驱动名称，如 hdmi、st7701、hx8399 等，可直接传给 PipeLine 的 display_mode

已收录的开发板与默认屏驱动：

默认驱动	开发板
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

注意

板型不在上表中时会抛出 ValueError: No default display for board <型号>; set display_mode explicitly。此时请显式指定屏驱动，不要使用 auto。

get_display_type

描述

把屏驱动名称解析成 Display.init() 所需的驱动常量。

语法

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

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

参数

参数名称	描述	输入 / 输出	说明
display_mode	屏驱动名称或 Display 常量	输入	默认 "auto"。取值见 PipeLine 手册的 display_mode 取值表。传入 int 类型（即 Display.XXX 常量）时原样返回

返回值

返回值	描述
int	Display.init() 接受的驱动常量

注意

传入未收录的字符串不会报错，会回退到 Display.ST7701。该行为是为兼容旧代码保留的，新代码请使用规范取值。

init_display

描述

初始化显示设备，并返回实际生效的显示分辨率。屏驱动可能不支持请求的分辨率而使用自己的默认值，因此后续布局计算必须以该函数的返回值为准，不能沿用传入的 display_size。

语法

from libs.DisplayConfig import init_display

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

参数

参数名称	描述	输入 / 输出	说明
display_mode	屏驱动名称或 Display 常量	输入	默认 "auto"
display_size	期望的显示分辨率 [width, height]	输入	可选，默认 None 表示使用驱动默认分辨率。请使用该参数而不是 width/height 关键字
**kwargs	透传给 Display.init() 的其它参数	输入	如 osd_num、to_ide 等

返回值

返回值	描述
list[int]	实际显示分辨率 [width, height]

注意

该函数只负责初始化显示，调用方需要自行调用 Display.deinit()。它也不会启动 sensor，更不会改变 AI 推理分辨率、解码分辨率或录像分辨率，这些需要各自单独配置。

DisplayImage

描述

用 AI2D 硬件把任意分辨率的 RGB888 数据缩放到显示分辨率，并封装成 image.Image 供显示使用。典型场景是 UVC 摄像头或 MP4 解码出来的画面分辨率与屏幕不一致时的适配。

内部复用同一套 AI2D 管线，只有输入分辨率发生变化时才会重建，因此逐帧调用开销很低。

语法

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 为 HWC 排布的 uint8 RGB 数据
    Display.show_image(img)

resizer.deinit()

构造函数参数

参数名称	描述	输入 / 输出	说明
display_size	目标分辨率 [width, height]	输入	必填，通常直接传 init_display() 的返回值
planar	输入数据是否为平面排布	输入	True 表示输入为 CHW 排布，False（默认）表示 HWC 排布

run 方法

参数名称	描述	输入 / 输出	说明
input_np	待缩放数据，ulab.numpy.ndarray 类型	输入	连续的 uint8 RGB 数据，排布需与构造时的 planar 一致

返回值	描述
image.Image	RGB888 格式的 Image 实例，分辨率为构造时指定的 display_size

deinit 方法

释放 DisplayImage 持有的 AI2D 资源，无参数无返回值。程序退出前必须调用。

注意

• run() 内部会对 AI2D 的输出做一次拷贝，返回的 Image 引用的是独立的数据副本，因此下一次 run() 不会覆盖它，可以安全跨帧保留。

• 传入的 input_np 在 run() 返回前必须保持有效（例如来自 to_numpy_ref() 的借用数据）。

• 只有当输入 shape 发生变化时才会重建底层 AI2D 管线，因此逐帧调用的开销很低。

示例程序

以下给出不使用 PipeLine、直接用本模块适配显示的框架代码：

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

resizer = None
try:
    # 按开发板型号自动选屏，返回实际分辨率
    display_size = init_display(display_mode="auto", osd_num=1, to_ide=True)
    print("display size:", display_size)

    # 源画面分辨率与屏幕不一致时，用 DisplayImage 缩放
    resizer = DisplayImage(display_size, planar=False)

    while True:
        frame_np = get_frame_from_somewhere()   # UVC / VDEC 等来源，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 不负责反初始化，需自行调用