ml.utils — Утилиты ML

Модуль ml.utils содержит вспомогательные классы и функции для машинного обучения.

Функции

ml.utils.logit(x: ndarray) → ndarray

Возвращает логит всех значений переданного ndarray.

ml.utils.sigmoid(x: ndarray) → ndarray

Возвращает сигмоиду всех значений переданного ndarray.

ml.utils.threshold(scores: ndarray, threshold: float, scale: float, find_max: bool = False, find_max_axis: int = 1) → ndarray

Применяет порог к scores (квантованному ndarray типа int8, uint8, int16 или uint16) с использованием квантованного порога threshold и возвращает ndarray всех индексов, прошедших порог.

Значение scale проверяется для определения того, являются ли деквантованные значения положительными или отрицательными. Когда scale > 0, возвращаются индексы, для которых scores > threshold; в противном случае возвращаются индексы, для которых scores < threshold.

find_max если True, внутренне заменяет scores на ndarray максимумов (или минимумов, в зависимости от scale) вдоль find_max_axis.

find_max_axis — это ось, вдоль которой вычисляется свёртка максимума/минимума, когда find_max равно True.

ml.utils.quantize(model: ml.Model, value: ndarray, index: int = 0) → ndarray

Преобразует переданный ndarray, деля на масштаб и прибавляя нулевую точку модели. Возвращает value без изменений, если тип выходных данных модели по индексу index является float.

model — это модель, чьи параметры квантования выхода используются.

value — это ndarray для квантования.

index выбирает, относительно какого тензора выхода model производить квантование.

ml.utils.dequantize(model: ml.Model, value: ndarray, index: int = 0) → ndarray

Преобразует переданный ndarray, вычитая нулевую точку и затем умножая на масштаб модели. Возвращает value без изменений, если тип выходных данных модели по индексу index является float.

model — это модель, чьи параметры квантования выхода используются.

value — это ndarray для деквантования.

index выбирает, относительно какого тензора выхода model производить деквантование.

ml.utils.draw_predictions(image: image.Image, boxes: list[tuple[float, float, float, float]], labels: list[str], colors: list[tuple[int, int, int]], scores: list[float] | None = None, format: str = 'pascal_voc', font_width: int = 8, font_height: int = 10, text_color: tuple[int, int, int] = (255, 255, 255)) → None

Рисует ограничивающие рамки (или маркеры центральных точек) с текстовыми метками на image.

boxes — это список кортежей (x, y, w, h).

labels — это список строк-меток, по одной на каждую рамку.

colors — это список кортежей (r, g, b), по одному на каждую рамку.

scores если не None, список оценок достоверности для каждой рамки. Когда он предоставлен, к каждой отрисованной метке добавляется оценка, отформатированная как " %.2f".

format управляет тем, как интерпретируются координаты рамки:

• "pascal_voc" — нормализованные (xmin, ymin, xmax, ymax) в диапазоне от 0.0 до 1.0.

• "point" — абсолютные пиксельные (x, y, w, h); в центре рамки рисуется заполненный круглый маркер вместо прямоугольника (полезно для детекторов центральных точек).

• любое другое значение — абсолютные пиксельные (x, y, w, h); рисуется как прямоугольник.

font_width — это ширина в пикселях каждого символа метки.

font_height — это высота в пикселях фона метки.

text_color — это цвет (r, g, b), используемый для текста метки.

ml.utils.draw_keypoints(image: image.Image, keypoints: ndarray, radius: int = 4, color: tuple[int, int, int] = (255, 0, 0), thickness: int = 1, fill: bool = False) → None

Рисует ndarray значений ключевых точек (x, y, ...) на image.

radius — это радиус круга ключевой точки. Когда radius == 0, ключевые точки рисуются как отдельные пиксели.

color — это цвет (r, g, b) ключевой точки.

thickness — это толщина контура круга.

fill если True, заполняет круги ключевых точек.

ml.utils.draw_skeleton(image: image.Image, keypoints: ndarray, lines: list[tuple[int, int]], kp_radius: int = 4, kp_color: tuple[int, int, int] = (255, 0, 0), kp_thickness: int = 1, kp_fill: bool = False, line_color: tuple[int, int, int] = (0, 255, 0), line_thickness: int = 1) → None

Рисует ndarray значений ключевых точек (x, y, ...) на image, а затем соединяет их отрезками линий.

lines — это список кортежей (kp0_idx, kp1_idx), указывающих, какие пары ключевых точек соединять.

kp_radius — это радиус круга ключевой точки (передаётся в draw_keypoints).

kp_color — это цвет (r, g, b) ключевой точки.

kp_thickness — это толщина контура круга ключевой точки.

kp_fill если True, заполняет круги ключевых точек.

line_color — это цвет (r, g, b) линии.

line_thickness — это толщина линии.

class NMS — Soft-Non-Maximum Suppression (мягкое подавление немаксимумов)

Объект NMS собирает список ограничивающих рамок со связанными оценками, отфильтровывает перекрывающиеся рамки с меньшими оценками с помощью Soft-NMS и пересчитывает рамки, обнаруженные в подокне, обратно в координаты исходного изображения.

class ml.utils.NMS(window_w: int, window_h: int, roi: tuple[int, int, int, int])

Создаёт объект NMS.

window_w и window_h — это ширина и высота входного тензора / окна модели.

roi — это область интереса (x, y, w, h) исходного изображения, на котором была запущена модель (обычно возвращается объектом Normalization()). Используется для пересчёта обнаруженных рамок обратно в координатное пространство исходного изображения. Значения roi[2] и roi[3] должны быть >= 1.

add_bounding_box(xmin: float, ymin: float, xmax: float, ymax: float, score: float, label_index: int, keypoints: ndarray | None = None) → None

Добавляет ограничивающую рамку в объект NMS. Рамки со значением score за пределами [0.0, 1.0] или с нулевой/отрицательной шириной или высотой после отсечения отбрасываются.

xmin, ymin, xmax, ymax — это координаты ограничивающей рамки в пиксельном пространстве окна, отсечённые до [0, window_w] / [0, window_h].

score — это оценка достоверности ограничивающей рамки (0.0-1.0).

label_index — это индекс метки класса, связанной с ограничивающей рамкой.

keypoints — это необязательный ndarray значений ключевых точек (x, y, ...), связанных с данной ограничивающей рамкой.

get_bounding_boxes(threshold: float = 0.1, sigma: float = 0.1) → list[list[tuple]]

Выполняет Soft-NMS над всеми добавленными рамками и возвращает список списков по классам, индексированных по label_index. Каждый внутренний список содержит кортежи ((x, y, w, h), score), отображённые обратно в координаты исходного изображения. Если при добавлении были предоставлены keypoints, кортеж дополняется пересчитанным ndarray keypoints.

После вызова этого метода создайте новый объект NMS для обработки нового набора ограничивающих рамок.

threshold — это минимальная оценка, которую рамка должна сохранить после подавления Soft-NMS, чтобы быть оставленной.

sigma управляет функцией Гаусса, используемой для штрафования оценок перекрывающихся ограничивающих рамок. Меньшее значение sigma приводит к более агрессивному подавлению. sigma <= 0.0 отключает гауссовский штраф (оценки перекрывающихся рамок не уменьшаются).