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 using MicroPython to develop AI Demos.

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	Note
info	Description of the timed section	Input	Default “”
enable_profile	Whether to print timing information during debugging	Input	Default True

Return Value

Return Value	Description
-	No return value

read_json

Description

Reads fields from a JSON file based on the 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	Note
json_path	Path of the JSON file on the development board	Input	Required

Return Value

Return Value	Description
dict	Contents of the JSON fields

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 to complete 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	Note
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	An Image instance in rgb888 format, which can be used to draw results

get_colors

Description

Retrieves an ARGB color array based on the number of labels, e.g., [255,191,162,208]. Up to 80 colors are preset; when the count 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	Note
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. It takes an input parameter input_size that represents the image dimensions, typically a list containing two elements representing the image width and height. The function calculates the coordinates of the top-left corner of the crop area (top and left) based on the image center, as well as the side length m of the crop area, 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	Note
input_size	Input width and height list	Input	Required

Return Value

Return Value	Description
top	Distance from the top-left corner of the crop to the top boundary
left	Distance from the top-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 dimensions. The function performs single-side padding, i.e., only on the bottom and right sides, and returns the padding widths for the top, bottom, left, and right boundaries, as well as the scale ratio. The calculation result of 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	Note
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 center_pad_param function is primarily used to calculate the parameters required for centering and scaling the input image to a specified output size. When processing images, in order to fit the image to a specific output size while maintaining its original aspect ratio, scaling is typically performed, and then padding is added around the image so that the image is centered in the output area. The function returns the padding widths for the top, bottom, left, and right boundaries, as well as the scale ratio. The calculation result of 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	Note
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 vector of real numbers into a probability distribution, such that each element in the vector is in the [0, 1] range, and the sum of all elements is 1. In this way, the model’s 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	Note
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 output to a probability value for probability-based 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	Note
input_data	Any real number	Input	Required

Return Value

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

chw2hwc

Description

Converts ulab.numpy.ndarray data in CHW layout to HWC layout. Only applicable 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	Note
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. Only applicable 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	Note
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