API 文档

class mltools.data.BaseBbox(bbox: list, *, bbox_type: str = 'xmin_ymin_xmax_ymax')

基类：object

基础边界框类，用于表示物体的边界框。

center_w_h() → list

返回边界框的坐标表示

返回:

边界框的坐标表示，格式为 [class_id, x_min + (x_max - x_min) / 2, y_min + (y_max - y_min) / 2, x_max - x_min, y_max - y_min]

返回类型:

list

static normalize(bbox: list, *, width: int, height: int) → list

归一化边界框坐标

参数:

• bbox (list) -- 边界框参数，格式为 [class_id, x_min, y_min, x_max, y_max]

• width (int) -- 图片宽度

• height (int) -- 图片高度

返回:

归一化后的边界框参数，格式为 [class_id, x_min / width, y_min / height, x_max / width, y_max / height]

返回类型:

list

static unnormalize(bbox: list, *, width: int, height: int) → list

反归一化边界框坐标

参数:

• bbox (list) -- 归一化后的边界框参数，格式为 [class_id, x_min / width, y_min / height, x_max / width, y_max / height]

• width (int) -- 图片宽度

• height (int) -- 图片高度

返回:

反归一化后的边界框参数，格式为 [class_id, int(x_min * width), int(y_min * height), int(x_max * width), int(y_max * height)]

返回类型:

list

xmin_ymin_w_h() → list

返回边界框的坐标表示

返回:

边界框的坐标表示，格式为 [class_id, x_min, y_min, x_max - x_min, y_max - y_min]

返回类型:

list

xmin_ymin_xmax_ymax() → list

返回边界框的坐标表示

返回:

边界框的坐标表示，格式为 [class_id, x_min, y_min, x_max, y_max]

返回类型:

list

class mltools.data.Bbox(bboxes: list, *, bbox_type: str = 'xmin_ymin_xmax_ymax')

基类：object

边界框容器类

center_w_h() → list

返回边界框的坐标表示

返回:

边界框的坐标表示，格式为 [class_id, x_min + (x_max - x_min) / 2, y_min + (y_max - y_min) / 2, x_max - x_min, y_max - y_min]

返回类型:

list

static normalize(bboxes: list, *, width: int, height: int) → list

归一化边界框坐标

参数:

• bboxes (list) -- 边界框列表，每个元素为 BaseBbox 实例

• width (int) -- 图片宽度

• height (int) -- 图片高度

返回:

归一化后的边界框列表，每个元素为 BaseBbox 实例

返回类型:

list

static unnormalize(bboxes: list, *, width: int, height: int) → list

反归一化边界框坐标

参数:

• bboxes (list) -- 归一化后的边界框列表，每个元素为 BaseBbox 实例

• width (int) -- 图片宽度

• height (int) -- 图片高度

返回:

反归一化后的边界框列表，每个元素为 BaseBbox 实例

返回类型:

list

xmin_ymin_w_h() → list

返回边界框的坐标表示

返回:

边界框的坐标表示，格式为 [class_id, x_min, y_min, x_max - x_min, y_max - y_min]

返回类型:

list

xmin_ymin_xmax_ymax() → list

返回边界框的坐标表示

返回:

边界框的坐标表示，格式为 [class_id, x_min, y_min, x_max, y_max]

返回类型:

list

class mltools.data.MyDataset(datas: list)

基类：Dataset

自定义数据集类，继承自 torch.utils.data.Dataset，用于管理机器学习任务中的数据。

mltools.data.batch_rename(image_dir_path: str, label_dir_path: str, *, prefix: str, offset: int = 0)

批量重命名图片和标签文件

参数:

• image_dir_path (str) -- 图片目录路径

• label_dir_path (str) -- 标签目录路径

• prefix (str) -- 文件名前缀

• offset (int, optional) -- 文件名偏移量，默认为 0

mltools.data.bbox(bboxes: list, *, bbox_type: str = 'xmin_ymin_xmax_ymax', normalize: bool = True, width: int = None, height: int = None) → Bbox

创建 Bbox 实例

参数:

• bboxes (list) -- 边界框列表，每个元素为 BaseBbox 实例

• bbox_type (str, optional) -- 边界框类型，可选值为 "xmin_ymin_xmax_ymax"、"xmin_ymin_w_h" 或 "center_w_h"，默认为 "xmin_ymin_xmax_ymax"

• normalize (bool, optional) -- 是否归一化边界框坐标，默认为 True

• width (int, optional) -- 图片宽度，默认为 None

• height (int, optional) -- 图片高度，默认为 None

返回:

Bbox 实例

返回类型:

Bbox

抛出:

ValueError -- 如果 normalize 为 False 时，width 和 height 未提供

mltools.data.download_file(url: str, *, save_path: str) → str

下载文件

参数:

• url (str) -- 文件的 URL 地址

• save_path (str) -- 保存文件的路径

返回:

下载的文件名

返回类型:

str

mltools.data.iter_data(datas: list, *, batch_size: int, shuffle: bool = True, num_workers: int = 0, pin_memory: bool = False, drop_last: bool = False) → DataLoader

迭代数据集

参数:

• datas (list) -- 数据集内容，可以是任何格式的数据

• batch_size (int) -- 每个批次的样本数量

• shuffle (bool, optional) -- 是否在每个 epoch 开始时打乱数据. 默认值为 True.

• num_workers (int, optional) -- 用于数据加载的子进程数量. 默认值为 0.

• pin_memory (bool, optional) -- 是否将数据加载到 CUDA 固定内存中. 默认值为 False.

• drop_last (bool, optional) -- 是否丢弃最后一个批次, 如果数据集大小不能被批次大小整除. 默认值为 False.

返回:

数据加载器，用于迭代数据集

返回类型:

data.DataLoader

mltools.data.mask_to_bbox(mask: ndarray, mask_type: str = 'gray') → Bbox

将二值掩码转换为边界框

参数:

• np_mask (np.ndarray) -- 二值掩码数组

• mask_type (str, optional) -- 掩码类型，可选值为 "gray"，默认为 "gray"

返回:

边界框实例

返回类型:

Bbox

抛出:

• ValueError -- 如果 np_mask 不是 2 维数组

• ValueError -- 如果 mask_type 不是 'gray'

mltools.data.read_label_file(label_file_path: str, bbox_type: str = 'xmin_ymin_xmax_ymax') → Bbox

读取标签文件并返回边界框实例

参数:

• label_file_path (str) -- 标签文件路径

• bbox_type (str, optional) -- 边界框类型，可选值为 "xmin_ymin_xmax_ymax"、"xmin_ymin_w_h" 或 "center_w_h"，默认为 "xmin_ymin_xmax_ymax"

返回:

边界框实例

返回类型:

Bbox

mltools.data.rename_file(file_path: str, new_name: str)

重命名文件

参数:

• file_path (str) -- 文件路径

• new_name (str) -- 新文件名

抛出:

FileExistsError -- 如果新文件名已存在

mltools.data.split_data(datas: list, ratio: list) → list

划分数据集

参数:

• datas (list) -- 数据集内容，可以是任何格式的数据

• ratio (list) -- 划分比例，例如 [0.8, 0.2] 表示划分成 80% 训练集和 20% 测试集

返回:

划分后的数据集，每个元素都是一个数据集

返回类型:

list

class mltools.learn.AutoSaveLoader

基类：object

自动保存加载器，将多个数据的保存和加载功能整合在一起， 支持添加自定义的保存和加载函数。

add_load_func(func: callable)

添加加载函数。

参数:

func (callable) -- 加载函数。

add_save_func(func: callable)

添加保存函数。

参数:

func (callable) -- 保存函数。

load(dir_path: str)

加载数据。

参数:

dir_path (str) -- 数据加载的目录路径。

save(dir_path: str)

保存数据。

参数:

dir_path (str) -- 数据保存的目录路径。

class mltools.learn.Epoch(parent: object)

基类：object

机器学习 Epoch，用于管理训练轮数，支持保存和加载总训练轮数。

load(path: str, label: str = 'epoch')

从 JSON 文件中加载总训练轮数。

参数:

• path (str) -- JSON 文件的路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'epoch'。

save(path: str, label: str = 'epoch')

保存总训练轮数到 JSON 文件。

参数:

• path (str) -- JSON 文件的保存路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'epoch'。

property totol_epoch: int

返回总迭代次数。

返回:

总训练轮数。

返回类型:

int

class mltools.learn.MachineLearning(file_name: str)

基类：object

机器学习工具类，提供批量创建训练辅助对象、管理模型和数据的保存与加载等功能。

add_model(model: Module, label: str = 'model')

添加模型。

参数:

• model -- 模型。

• label (str, optional) -- 模型的标签，建议和模型变量名相同。默认值为 'model'。

抛出:

RuntimeError -- 如果模型不是 nn.Module 类型。

batch_create(create_epoch: bool = True, create_timer: bool = True, create_recorder: bool = True) → tuple

批量创建 Epoch、Timer 和 Recorder 对象。

参数:

• create_epoch (bool, optional) -- 是否创建 Epoch 对象。默认值为 True。

• create_timer (bool, optional) -- 是否创建计时器对象。默认值为 True。

• create_recorder (bool, optional) -- 是否创建记录器对象。默认值为 True。

返回:

包含创建的 Epoch、Timer 和 Recorder 对象的元组，不包含 None 值。

返回类型:

tuple

create_animator(xlabel: str = None, ylabel: str = None, xlim: tuple = None, ylim: tuple = None, legend: list = None, fmts: list = None, label: str = 'animator') → Animator

创建动画器。

参数:

• xlabel (str, optional) -- x 轴标签。默认值为 None。

• ylabel (str, optional) -- y 轴标签。默认值为 None。

• xlim (tuple, optional) -- x 轴范围。默认值为 None。

• ylim (tuple, optional) -- y 轴范围。默认值为 None。

• legend (list, optional) -- 图例。默认值为 None。

• fmts (list, optional) -- 格式。默认值为 None。

• label (str, optional) -- 动画器的标签，建议和被赋值变量名相同。默认值为 'animator'。

返回:

创建的动画器对象。

返回类型:

Animator

create_epoch(label: str = 'num_epochs') → Epoch

创建 Epoch 参数。

参数:

label (str, optional) -- Epoch 的标签，建议和被赋值变量名相同。默认值为 'num_epochs'。

返回:

创建的 Epoch 对象。

返回类型:

Epoch

create_recorder(recorder_num: int, label: str = 'recorder') → Recorder

创建记录器。

参数:

• recorder_num (int) -- 记录器的数量。

• label (str, optional) -- 记录器的标签，建议和被赋值变量名相同。默认值为 'recorder'。

返回:

创建的记录器对象。

返回类型:

Recorder

create_timer(label: str = 'timer') → Timer

创建计时器。

参数:

label (str, optional) -- 计时器的标签，建议和被赋值变量名相同。默认值为 'timer'。

返回:

创建的计时器对象。

返回类型:

Timer

load(dir_name: str = None)

加载数据。

参数:

dir_name (str, optional) -- 数据加载的目录名。默认值为 None。

model_params(model: Module, label: str = 'model')

打印模型参数数量。

参数:

model -- 模型对象。

抛出:

RuntimeError -- 如果模型不是 nn.Module 类型。

print_training_time_massage(timer: Timer, num_epochs: int, current_epoch: int)

打印模型训练时间相关信息，包括已训练时长、平均训练时长和预估剩余训练时长。

参数:

• timer (Timer) -- 计时器对象，用于获取训练时间数据。

• num_epochs (int) -- 总训练轮数。

• current_epoch (int) -- 当前训练到的轮数。

save(dir_name: str = None)

保存数据。

参数:

dir_name (str, optional) -- 数据保存的目录名。默认值为 None。

class mltools.draw.Animator(xlabel: str = None, ylabel: str = None, xlim: tuple[int, int] = None, ylim: tuple[int, int] = None, legend: list[str] = None, fmts: list[str] = None)

基类：object

在动画中绘制数据，用于动态展示训练过程中的指标变化。

save(path: str)

保存动画为图片文件。

参数:

path (str) -- 图片文件的保存路径。

show(Y: list[list[float]])

展示动画。

参数:

Y (list[list[float]]) -- y轴数据列表。

mltools.draw.draw_bbox(image_path: str, bbox: Bbox)

绘制边界框。

参数:

• image_path (str) -- 图片文件路径。

• bbox (data.Bbox) -- 边界框对象。

mltools.draw.images(images: ndarray, labels: list[str], shape: tuple[int, int])

展示图片。

参数:

• images (np.ndarray) -- 图片数据数组。

• labels (list[str]) -- 图片标签列表。

• shape (tuple[int, int]) -- 子图布局形状。

抛出:

TypeError -- 如果images不是numpy数组。

mltools.draw.numpy_to_image(numpy_array: ndarray)

展示图片。

参数:

numpy_array (np.ndarray) -- 图片数据数组。

抛出:

TypeError -- 如果numpy_array不是numpy数组。

mltools.draw.set_axes(axes: Axes | list[Axes], *, axis: bool = True, **kwargs: dict)

设置axes。

参数:

• axes (matplotlib.axes.Axes | list[matplotlib.axes.Axes]) -- 子图对象列表。

• axis (bool, optional) -- 是否显示坐标轴。默认值为True。

• **kwargs (dict) -- 其他axes设置参数。

class mltools.utils.Accumulator(n: int)

基类：object

在 n 个变量上累加，用于统计训练过程中的指标。

add(*args: int | float)

添加数据到累加器。

参数:

*args (int | float) -- 要添加的数据。

reset()

重置累加器的数据。

class mltools.utils.DataSaveToJson

基类：object

json数据保存器，提供将数据保存到 JSON 文件和从 JSON 文件加载数据的功能。

static load_data(path: str, label: str) → any

从指定路径的 JSON 文件中加载数据。

参数:

• path (str) -- JSON 文件的路径。

• label (str) -- 数据在 JSON 文件中的键名。

返回:

从 JSON 文件中加载的数据。

static save_data(path: str, label: str, datas: dict)

保存数据到指定路径的 JSON 文件中。

参数:

• path (str) -- JSON 文件的保存路径。

• label (str) -- 数据在 JSON 文件中的键名。

• datas (dict) -- 要保存的数据。

class mltools.utils.Recorder(n: int)

基类：object

n 个记录器，用于记录训练过程中的多个变量的值，支持保存和加载。

get_latest_record() → list[float]

返回最新记录。

返回:

最新记录的列表。

返回类型:

list[float]

load(path: str, label: str = 'recorder')

从 JSON 文件中加载记录器的数据。

参数:

• path (str) -- JSON 文件的路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'recorder'。

max_record_size() → int

返回最长记录长度。

返回:

最长记录的长度。

返回类型:

int

reset()

重置记录器的数据。

save(path: str, label: str = 'recorder')

保存记录器的数据到 JSON 文件。

参数:

• path (str) -- JSON 文件的保存路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'recorder'。

class mltools.utils.Timer

基类：object

记录多次运行时间，支持保存和加载记录的时间数据。

avg() → float

返回平均时间。

返回:

平均时间，单位为秒。如果没有记录时间，则返回 0。

返回类型:

float

load(path: str, label: str = 'timer')

从 JSON 文件中加载计时器的时间数据。

参数:

• path (str) -- JSON 文件的路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'timer'。

save(path: str, label: str = 'timer')

保存计时器的时间数据到 JSON 文件。

参数:

• path (str) -- JSON 文件的保存路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'timer'。

start()

启动计时器。

stop() → float

停止计时器并将时间记录在列表中。

返回:

本次记录的时间。

返回类型:

float

static str(times: float) → str

将时间转换为格式化的字符串。

参数:

times (float) -- 时间，单位为秒。

返回:

格式化后的时间字符串，格式为 "HH:MM:SS"。

返回类型:

str

sum() → float

计算记录的所有时间的总和。

返回:

记录的所有时间的总和，单位为秒。如果没有记录时间，则返回 0。

返回类型:

float

mltools.utils.add_ignore_file(dir: str)

为指定目录添加 .gitignore 文件，用于忽略所有文件。

参数:

dir (str) -- 目录路径。

class mltools.tokenize.Tokenizer(datas: list[str], min_freq: int = 0)

基类：object

分词器，将文本数据转换为词元索引，支持词元与索引之间的相互转换，并提供保存和加载词表的功能。

decode(indices: Tensor) → str | list[str]

根据索引返回词元。

参数:

indices (torch.Tensor) -- 输入的词元索引。

返回:

解码后的词元。

返回类型:

str 或 list[str]

抛出:

TypeError -- 如果输入的 indices 不是 torch.Tensor 类型。

encode(texts: str | list[str] | tuple[str], max_length: int = None) → Tensor

根据词元返回索引。

参数:

• texts (str 或 list[str] 或 tuple[str]) -- 输入的词元。

• max_length (int, optional) -- 最大长度，用于填充或截断。默认值为 None。

返回:

转换后的词元索引。

返回类型:

torch.Tensor

抛出:

TypeError -- 如果输入的 texts 不是 str、list[str] 或 tuple[str] 类型。

load(path: str, label: str = 'tokenizer')

从 JSON 文件中加载分词器的词表。

参数:

• path (str) -- JSON 文件的路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'tokenizer'。

save(path: str, label: str = 'tokenizer')

保存分词器的词表到 JSON 文件。

参数:

• path (str) -- JSON 文件的保存路径。

• label (str, optional) -- 数据在 JSON 文件中的键名。默认值为 'tokenizer'。