ml.utils — Utility ML

Il modulo ml.utils contiene classi e funzioni di utilità per il machine learning.

Funzioni

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

Restituisce il logit di tutti i valori nell”ndarray passato.

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

Restituisce il sigmoide di tutti i valori nell”ndarray passato.

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

Applica una soglia a scores (un ndarray quantizzato di tipo int8, uint8, int16 o uint16) usando una threshold quantizzata e restituisce un ndarray di tutti gli indici che superano la soglia.

scale viene verificato per determinare se i valori dequantizzati sono positivi o negativi. Quando scale > 0 vengono restituiti gli indici dove scores > threshold; altrimenti vengono restituiti gli indici dove scores < threshold.

find_max se True, sostituisce internamente scores con un ndarray del massimo (o del minimo, a seconda di scale) lungo find_max_axis.

find_max_axis è l’asse lungo il quale viene calcolata la riduzione max/min quando find_max è True.

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

Converte l”ndarray passato dividendo per la scala e aggiungendo lo zero point del modello. Restituisce value invariato quando il dtype di output del modello all”index è float.

model è il modello i cui parametri di quantizzazione dell’output vengono utilizzati.

value è l”ndarray da quantizzare.

index seleziona quale output tensore del model utilizzare per la quantizzazione.

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

Converte l”ndarray passato sottraendo lo zero point e poi moltiplicando per la scala del modello. Restituisce value invariato quando il dtype di output del modello all”index è float.

model è il modello i cui parametri di quantizzazione dell’output vengono utilizzati.

value è l”ndarray da dequantizzare.

index seleziona quale output tensore del model utilizzare per la dequantizzazione.

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

Disegna bounding box (o marcatori del punto centrale) con etichette di testo su image.

boxes è una lista di tuple (x, y, w, h).

labels è una lista di stringhe di etichetta, una per box.

colors è una lista di tuple (r, g, b), una per box.

scores se non None, una lista di punteggi di confidenza per box. Quando fornita, ogni etichetta disegnata viene completata con il punteggio formattato come " %.2f".

format controlla come vengono interpretate le coordinate del box:

• "pascal_voc" – (xmin, ymin, xmax, ymax) normalizzate nell’intervallo da 0.0 a 1.0.

• "point" – pixel assoluti (x, y, w, h); al centro del box viene disegnato un marcatore a cerchio pieno invece di un rettangolo (utile per i rilevatori basati sul punto centrale).

• qualsiasi altro valore – pixel assoluti (x, y, w, h); disegnato come un rettangolo.

font_width è la larghezza in pixel di ciascun carattere dell’etichetta.

font_height è l’altezza in pixel dello sfondo dell’etichetta.

text_color è il colore (r, g, b) usato per il testo dell’etichetta.

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

Disegna un ndarray di valori keypoint (x, y, ...) su image.

radius è il raggio del cerchio del keypoint. Quando radius == 0 i keypoint vengono disegnati come singoli pixel.

color è il colore (r, g, b) del keypoint.

thickness è lo spessore del contorno del cerchio.

fill se True riempie i cerchi dei keypoint.

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

Disegna un ndarray di valori keypoint (x, y, ...) su image e poi li collega con segmenti di linea.

lines è una lista di tuple (kp0_idx, kp1_idx) che specificano quali coppie di keypoint collegare.

kp_radius è il raggio del cerchio del keypoint (passato a draw_keypoints).

kp_color è il colore (r, g, b) del keypoint.

kp_thickness è lo spessore del contorno del cerchio del keypoint.

kp_fill se True riempie i cerchi dei keypoint.

line_color è il colore (r, g, b) della linea.

line_thickness è lo spessore della linea.

class NMS – Soft-Non-Maximum Suppression

L’oggetto NMS raccoglie una lista di bounding box con i relativi punteggi, filtra i box sovrapposti con punteggi più bassi tramite Soft-NMS e rimappa i box rilevati in una sotto-finestra alle coordinate dell’immagine originale.

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

Crea un oggetto NMS.

window_w e window_h sono la larghezza e l’altezza del tensore di input / finestra del modello.

roi è la regione di interesse (x, y, w, h) dell’immagine originale su cui è stato eseguito il modello (tipicamente restituita dall’oggetto Normalization()). Usata per rimappare i box rilevati nello spazio delle coordinate dell’immagine originale. roi[2] e roi[3] devono essere >= 1.

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

Aggiunge un bounding box all’oggetto NMS. I box con score al di fuori di [0.0, 1.0] o con larghezza o altezza nulla/negativa dopo il clipping vengono scartati.

xmin, ymin, xmax, ymax sono le coordinate del bounding box nello spazio dei pixel della finestra, limitate a [0, window_w] / [0, window_h].

score è il punteggio di confidenza del bounding box (0.0-1.0).

label_index è l’indice dell’etichetta di classe associata al bounding box.

keypoints è un ndarray opzionale di valori keypoint (x, y, ...) associati a questo bounding box.

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

Esegue Soft-NMS su tutti i box aggiunti e restituisce una lista di liste per classe, indicizzate per label_index. Ogni lista interna contiene tuple ((x, y, w, h), score) rimappate nelle coordinate dell’immagine originale. Se keypoints è stato fornito al momento dell’aggiunta, la tupla viene estesa con l”ndarray di keypoints rimappato.

Dopo aver chiamato questo metodo, crea un nuovo oggetto NMS per elaborare un nuovo insieme di bounding box.

threshold è il punteggio minimo che un box deve mantenere dopo la soppressione Soft-NMS per essere conservato.

sigma controlla la gaussiana usata per penalizzare i punteggi dei bounding box sovrapposti. Un sigma più piccolo produce una soppressione più aggressiva. sigma <= 0.0 disabilita la penalità gaussiana (i punteggi dei box sovrapposti non vengono decaduti).