ml.utils — Utilidades de ML

El módulo ml.utils contiene clases y funciones de utilidad para el aprendizaje automático.

Funciones

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

Devuelve el logit de todos los valores del ndarray proporcionado.

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

Devuelve la sigmoide de todos los valores del ndarray proporcionado.

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

Aplica un umbral a scores (un ndarray cuantizado de int8, uint8, int16 o uint16) mediante un threshold cuantizado y devuelve un ndarray con todos los índices que superan el umbral.

scale se evalúa para determinar si los valores descuantizados son positivos o negativos. Cuando scale > 0 se devuelven los índices donde scores > threshold; en caso contrario se devuelven los índices donde scores < threshold.

find_max si es True, reemplaza internamente scores por un ndarray del máximo (o mínimo, según scale) a lo largo de find_max_axis.

find_max_axis es el eje a lo largo del cual se calcula la reducción de máximo/mínimo cuando find_max es True.

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

Convierte el ndarray proporcionado dividiendo por la escala y sumando el punto cero del modelo. Devuelve value sin cambios cuando el dtype de salida del modelo en index es float.

model es el modelo cuyos parámetros de cuantización de salida se utilizan.

value es el ndarray que se va a cuantizar.

index selecciona contra qué salida tensorial del model se cuantiza.

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

Convierte el ndarray proporcionado restando el punto cero y multiplicando luego por la escala del modelo. Devuelve value sin cambios cuando el dtype de salida del modelo en index es float.

model es el modelo cuyos parámetros de cuantización de salida se utilizan.

value es el ndarray que se va a descuantizar.

index selecciona contra qué salida tensorial del model se descuantiza.

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

Dibuja cuadros delimitadores (o marcadores de punto central) con etiquetas de texto sobre image.

boxes es una lista de tuplas (x, y, w, h).

labels es una lista de cadenas de etiqueta, una por cuadro.

colors es una lista de tuplas (r, g, b), una por cuadro.

scores si no es None, es una lista de puntuaciones de confianza por cuadro. Cuando se proporciona, cada etiqueta renderizada lleva como sufijo la puntuación formateada como " %.2f".

format controla cómo se interpretan las coordenadas del cuadro:

  • "pascal_voc" – (xmin, ymin, xmax, ymax) normalizado en el rango 0.0 a 1.0.

  • "point" – (x, y, w, h) en píxeles absolutos; se dibuja un marcador circular relleno en el centro del cuadro en lugar de un rectángulo (útil para detectores de punto central).

  • cualquier otro valor – (x, y, w, h) en píxeles absolutos; dibujado como un rectángulo.

font_width es el ancho en píxeles de cada carácter de la etiqueta.

font_height es la altura en píxeles del fondo de la etiqueta.

text_color es el color (r, g, b) utilizado para el texto de la etiqueta.

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

Dibuja un ndarray de valores de punto clave (x, y, ...) sobre image.

radius es el radio del círculo del punto clave. Cuando radius == 0 los puntos clave se dibujan como píxeles individuales.

color es el color (r, g, b) del punto clave.

thickness es el grosor del contorno del círculo.

fill si es True rellena los círculos de los puntos clave.

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

Dibuja un ndarray de valores de punto clave (x, y, ...) sobre image y luego los conecta con segmentos de línea.

lines es una lista de tuplas (kp0_idx, kp1_idx) que especifican qué pares de puntos clave conectar.

kp_radius es el radio del círculo del punto clave (se pasa a draw_keypoints).

kp_color es el color (r, g, b) del punto clave.

kp_thickness es el grosor del contorno del círculo del punto clave.

kp_fill si es True rellena los círculos de los puntos clave.

line_color es el color (r, g, b) de la línea.

line_thickness es el grosor de la línea.

class NMS – Supresión suave de no máximos (Soft-Non-Maximum Suppression)

El objeto NMS recopila una lista de cuadros delimitadores con sus puntuaciones asociadas, filtra los cuadros solapados con puntuaciones más bajas mediante Soft-NMS y reasigna los cuadros detectados en una subventana de vuelta a las coordenadas de la imagen original.

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

Crea un objeto NMS.

window_w y window_h son el ancho y el alto del tensor de entrada del modelo / ventana.

roi es la región de interés (x, y, w, h) de la imagen original sobre la que se ejecutó el modelo (normalmente devuelta por el objeto Normalization()). Se utiliza para reasignar los cuadros detectados de vuelta al espacio de coordenadas de la imagen original. roi[2] y roi[3] deben ser >= 1.

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

Añade un cuadro delimitador al objeto NMS. Se descartan los cuadros con score fuera de [0.0, 1.0] o con ancho o alto cero/negativo tras el recorte.

xmin, ymin, xmax, ymax son las coordenadas del cuadro delimitador en el espacio de píxeles de la ventana, recortadas a [0, window_w] / [0, window_h].

score es la puntuación de confianza del cuadro delimitador (0.0-1.0).

label_index es el índice de la etiqueta de clase asociada al cuadro delimitador.

keypoints es un ndarray opcional de valores de punto clave (x, y, ...) asociados a este cuadro delimitador.

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

Realiza Soft-NMS sobre todos los cuadros añadidos y devuelve una lista de listas por clase, indexada por label_index. Cada lista interna contiene tuplas de ((x, y, w, h), score) reasignadas de vuelta a las coordenadas de la imagen original. Si se proporcionaron keypoints al añadir, la tupla se extiende con el ndarray de keypoints reasignado.

Después de llamar a este método, cree un nuevo objeto NMS para procesar un nuevo conjunto de cuadros delimitadores.

threshold es la puntuación mínima que un cuadro debe conservar tras la supresión Soft-NMS para ser mantenido.

sigma controla la gaussiana utilizada para penalizar las puntuaciones de los cuadros delimitadores solapados. Un sigma más pequeño produce una supresión más agresiva. sigma <= 0.0 desactiva la penalización gaussiana (las puntuaciones de los cuadros solapados no se atenúan).