注意

这是最新开发分支配套的文档，可能包含已发布版本中尚未提供的功能。如果您要查看特定版本的文档，请使用左侧的下拉菜单并选择所需要的版本。

Utils 模块 API 手册

概述

本手册旨在提供给开发人员使用 MicroPython 开发 AI Demo 时使用的一些共用处理方法。

API 介绍

计时模块 ScopedTiming

描述

ScopedTiming 类是一个用来测量代码块执行时间的上下文管理器。上下文管理器通过定义包含 __enter__ 和 __exit__ 方法的类来创建。当在 with 语句中使用该类的实例，__enter__ 在进入 with 块时被调用，__exit__ 在离开时被调用。

from libs.Utils import ScopedTiming

def test_time():
    with ScopedTiming("test",1):
        #####代码#####
        # ...
        ##############

参数

参数名称	描述	输入 / 输出	说明
info	计时部分的描述	输入	默认””
enable_profile	是否调试打印计时信息	输入	默认True

返回值

返回值	描述
-	无返回值

read_json

描述

根据json文件路径读取json中的各字段，主要用于读取部署在线训练平台脚本的配置文件。

语法

import libs.Utils import read_json

json_path="/sdcard/examples/test.json"
json_data=read_json(json_path)

参数

参数名称	描述	输入 / 输出	说明
json_path	json文件在开发板中的路径	输入	必填

返回值

返回值	描述
dict	json字段内容

read_image

描述

根据图片路径读取图片数据，用于AI推理过程中读取静态图，给到模型完成推理。

语法

import libs.Utils import read_image

img_path="/sdcard/examples/test.jpg"
img_chw,img_rgb888=read_image(img_path)

参数

参数名称	描述	输入 / 输出	说明
img_path	图片文件在开发板中的路径	输入	必填

返回值

返回值	描述
img_chw	CHW排布的ulab.numpy.ndarray格式图片数据，可以用于创建nncase_runtime.tensor给AI模型推理
img_rgb888	rgb888格式的Image实例，可以用于绘制结果

get_colors

描述

按照标签数量获取ARGB颜色数组，比如[255,191,162,208]。预置80种颜色，大于80种时取余。

语法

import libs.Utils import get_colors

classes_num=30
colors=get_colors(classes_num)

参数

参数名称	描述	输入 / 输出	说明
classes_num	标签数量	输入	必填

返回值

返回值	描述
list[list]	ARGB颜色数组

center_crop_param

描述

center_crop_param 是正方形中心裁剪函数，接收一个表示图像尺寸的输入参数 input_size，它通常是一个包含两个元素的列表，分别代表图像的宽度和高度。函数会计算出以图像中心为基准进行裁剪时，裁剪区域的左上角坐标（top 和 left）以及裁剪区域的边长 m，最终返回这些参数。

语法

from libs.Utils import center_crop_param

input_size=[640,320]
top,left,m=center_crop_param(input_size)

参数

参数名称	描述	输入 / 输出	说明
input_size	输入宽高列表	输入	必填

返回值

返回值	描述
top	裁左上角距离上边界距离
left	裁左上角距离左边界距离
m	裁边长

letterbox_pad_param

描述

letterbox_pad_param 函数用于计算对输入图像进行填充时所需的参数。该填充是一种在保持图像宽高比的前提下，将图像缩放到指定输出尺寸，并在周围添加填充的技术，常用于目标检测等计算机视觉任务中，确保输入图像能适配模型的输入尺寸。该函数会进行单边填充，即只在下侧和右侧进行填充，返回填充区域的上下左右边界宽度以及缩放比例。该方法计算结果一般和resize同时使用。

语法

from libs.Utils import letterbox_pad_param

input_size=[1920,1080]
output_size=[640,640]
top,bottom,left,right,scale=letterbox_pad_param(input_size,output_size)

参数

参数名称	描述	输入 / 输出	说明
input_size	缩放填充前的输入分辨率	输入	必填
output_size	缩放填充后的输出分辨率	输入	必填

返回值

返回值	描述
top	上侧填充值
bottom	下侧填充值
left	左侧填充值
right	右侧填充值
scale	缩放比例

center_pad_param

描述

center_pad_param 函数的主要目的是计算将输入图像以居中的方式进行填充并缩放到指定输出尺寸时所需的参数。在处理图像时，为了让图像在保持其原始宽高比的情况下适配特定的输出尺寸，通常会进行缩放操作，然后在图像的周围添加填充，使图像在输出区域中居中显示。该函数会返回填充区域的上下左右边界宽度以及缩放比例。该方法计算结果一般和resize同时使用。

语法

from libs.Utils import center_pad_param

input_size=[1920,1080]
output_size=[640,640]
top,bottom,left,right,scale=center_pad_param(input_size,output_size)

参数

参数名称	描述	输入 / 输出	说明
input_size	缩放填充前的输入分辨率	输入	必填
output_size	缩放填充后的输出分辨率	输入	必填

返回值

返回值	描述
top	上侧填充值
bottom	下侧填充值
left	左侧填充值
right	右侧填充值
scale	缩放比例

softmax

描述

softmax 函数在分类问题中广泛应用。它的主要作用是将一个实数向量转换为概率分布，使得向量中的每个元素都在 [0, 1] 区间内，并且所有元素之和为 1。通过这种方式，可以将模型的输出解释为每个类别对应的概率。

语法

from libs.Utils import softmax

input_data=[1,2,3]
output_data=softmax(input_data)

参数

参数名称	描述	输入 / 输出	说明
x	分类模型返回的一维数据	输入	必填

返回值

返回值	描述
softmax_res	类别的概率分布

sigmoid

描述

sigmoid 函数广泛应用于二分类模型中。它的作用是将任意实数映射到 (0, 1) 区间内，常用于将模型输出转换为概率值，从而用于概率判断或分类决策。

语法

from libs.Utils import sigmoid

input_data = 0.5
output_data = sigmoid(input_data)

参数

参数名称	描述	输入 / 输出	说明
input_data	任意实数	输入	必填

返回值

返回值	描述
sigmoid_res	映射到 (0, 1) 区间的数值或数组

chw2hwc

描述

将CHW排布的ulab.numpy.ndarray数据转换为HWC排布，仅适用于3维数据。

语法

from libs.Utils import chw2hwc

# chw_np是CHW排布的ulab.numpy.ndarray数据
hwc_np = chw2hwc(chw_np)

参数

参数名称	描述	输入 / 输出	说明
chw_np	3维ulab.numpy.ndarray数据	输入	必填

返回值

返回值	描述
hwc_np	排布维HWC的3维ulab.numpy.ndarray数据

hwc2chw

描述

将HWC排布的ulab.numpy.ndarray数据转换为CHW排布，仅适用于3维数据，常用于将Image实例数据转换后给AI模型使用。

语法

from libs.Utils import hwc2chw

# hwc_np是CHW排布的ulab.numpy.ndarray数据
chw_np = hwc2chw(hwc_np)

参数

参数名称	描述	输入 / 输出	说明
hwc_np	3维ulab.numpy.ndarray数据	输入	必填

返回值

返回值	描述
chw_np	排布维CHW的3维ulab.numpy.ndarray数据