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 the documentation for a specific release, use the drop-down menu on the left and select the desired version.

Utils Module API Manual

Overview

This manual provides some common processing methods for developers to use when developing AI Demos with MicroPython.

API Introduction

Timing Module ScopedTiming

Description

The ScopedTiming class is a context manager used to measure the execution time of a code block. A context manager is created by defining a class that contains the __enter__ and __exit__ methods. When an instance of this class is used in a with statement, __enter__ is called upon entering the with block, and __exit__ is called upon leaving.

from libs.Utils import ScopedTiming

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

Parameters

Parameter Name	Description	Input / Output	Notes
info	Description of the timed section	Input	Default “”
enable_profile	Whether to debug and print timing information	Input	Default True

Return Value

Return Value	Description
-	No return value

read_json

Description

Reads fields from a json file based on the json file path, primarily used to read configuration files for scripts deployed on the online training platform.

Syntax

import libs.Utils import read_json

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

Parameters

Parameter Name	Description	Input / Output	Notes
json_path	Path of the json file on the development board	Input	Required

Return Value

Return Value	Description
dict	json field contents

read_image

Description

Reads image data based on the image path, used to read static images during AI inference and pass them to the model for inference.

Syntax

import libs.Utils import read_image

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

Parameters

Parameter Name	Description	Input / Output	Notes
img_path	Path of the image file on the development board	Input	Required

Return Value

Return Value	Description
img_chw	Image data in CHW layout as ulab.numpy.ndarray format, which can be used to create nncase_runtime.tensor for AI model inference
img_rgb888	Image instance in rgb888 format, which can be used to draw results

get_colors

Description

Gets an ARGB color array based on the number of labels, such as [255,191,162,208]. 80 colors are preset; when the number exceeds 80, the modulo operation is applied.

Syntax

import libs.Utils import get_colors

classes_num=30
colors=get_colors(classes_num)

Parameters

Parameter Name	Description	Input / Output	Notes
classes_num	Number of labels	Input	Required

Return Value

Return Value	Description
list[list]	ARGB color array

center_crop_param

Description

center_crop_param is a square center crop function that takes an input parameter input_size representing the image size, which is typically a list containing two elements representing the image’s width and height. The function calculates the coordinates (top and left) of the upper-left corner of the crop region based on the image center, as well as the side length m of the crop region, and finally returns these parameters.

Syntax

from libs.Utils import center_crop_param

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

Parameters

Parameter Name	Description	Input / Output	Notes
input_size	Input width and height list	Input	Required

Return Value

Return Value	Description
top	Distance from the upper-left corner of the crop to the top boundary
left	Distance from the upper-left corner of the crop to the left boundary
m	Crop side length

letterbox_pad_param

Description

The letterbox_pad_param function is used to calculate the parameters required for padding the input image. This padding is a technique that scales the image to a specified output size while maintaining the aspect ratio, and adds padding around it. It is commonly used in computer vision tasks such as object detection to ensure the input image fits the model’s input size. This function performs single-side padding, i.e., only padding on the bottom and right sides, and returns the top, bottom, left, and right padding widths as well as the scale ratio. The result calculated by this method is typically used together with resize.

Syntax

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)

Parameters

Parameter Name	Description	Input / Output	Notes
input_size	Input resolution before scaling and padding	Input	Required
output_size	Output resolution after scaling and padding	Input	Required

Return Value

Return Value	Description
top	Top padding value
bottom	Bottom padding value
left	Left padding value
right	Right padding value
scale	Scale ratio

center_pad_param

Description

The main purpose of the center_pad_param function is to calculate the parameters required for centering and scaling the input image to a specified output size with padding. When processing images, in order to fit a specific output size while maintaining the original aspect ratio, a scaling operation is usually performed, and then padding is added around the image so that the image is centered in the output area. This function returns the top, bottom, left, and right padding widths as well as the scale ratio. The result calculated by this method is typically used together with resize.

Syntax

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)

Parameters

Parameter Name	Description	Input / Output	Notes
input_size	Input resolution before scaling and padding	Input	Required
output_size	Output resolution after scaling and padding	Input	Required

Return Value

Return Value	Description
top	Top padding value
bottom	Bottom padding value
left	Left padding value
right	Right padding value
scale	Scale ratio

softmax

Description

The softmax function is widely used in classification problems. Its main purpose is to convert a real-valued vector into a probability distribution, where each element in the vector is in the [0, 1] range and the sum of all elements equals 1. In this way, the model output can be interpreted as the probability corresponding to each class.

Syntax

from libs.Utils import softmax

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

Parameters

Parameter Name	Description	Input / Output	Notes
x	One-dimensional data returned by the classification model	Input	Required

Return Value

Return Value	Description
softmax_res	Probability distribution of classes

sigmoid

Description

The sigmoid function is widely used in binary classification models. Its purpose is to map any real number to the (0, 1) range, commonly used to convert model outputs into probability values for probability judgment or classification decisions.

Syntax

from libs.Utils import sigmoid

input_data = 0.5
output_data = sigmoid(input_data)

Parameters

Parameter Name	Description	Input / Output	Notes
input_data	Any real number	Input	Required

Return Value

Return Value	Description
sigmoid_res	Value or array mapped to the (0, 1) range

chw2hwc

Description

Converts ulab.numpy.ndarray data in CHW layout to HWC layout, applicable only to 3-dimensional data.

Syntax

from libs.Utils import chw2hwc

# chw_np is ulab.numpy.ndarray data in CHW layout
hwc_np = chw2hwc(chw_np)

Parameters

Parameter Name	Description	Input / Output	Notes
chw_np	3-dimensional ulab.numpy.ndarray data	Input	Required

Return Value

Return Value	Description
hwc_np	3-dimensional ulab.numpy.ndarray data in HWC layout

hwc2chw

Description

Converts ulab.numpy.ndarray data in HWC layout to CHW layout, applicable only to 3-dimensional data, commonly used to convert Image instance data for use by AI models.

Syntax

from libs.Utils import hwc2chw

# hwc_np is ulab.numpy.ndarray data in CHW layout
chw_np = hwc2chw(hwc_np)

Parameters

Parameter Name	Description	Input / Output	Notes
hwc_np	3-dimensional ulab.numpy.ndarray data	Input	Required

Return Value

Return Value	Description
chw_np	3-dimensional ulab.numpy.ndarray data in CHW layout