ml.utils — Utilitaires ML

Le module ml.utils contient des classes et fonctions utilitaires pour l’apprentissage automatique.

Fonctions

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

Renvoie le logit de toutes les valeurs du ndarray passé.

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

Renvoie la sigmoïde de toutes les valeurs du ndarray passé.

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

Applique un seuil à scores (un ndarray quantifié de type int8, uint8, int16 ou uint16) à l’aide d’un threshold quantifié et renvoie un ndarray de tous les indices qui dépassent le seuil.

scale est testé pour déterminer si les valeurs déquantifiées sont positives ou négatives. Lorsque scale > 0, les indices où scores > threshold sont renvoyés ; sinon, les indices où scores < threshold sont renvoyés.

find_max si True, remplace scores en interne par un ndarray du maximum (ou du minimum, selon scale) le long de find_max_axis.

find_max_axis est l’axe le long duquel la réduction max/min est calculée lorsque find_max vaut True.

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

Convertit le ndarray passé en le divisant par l’échelle et en ajoutant le point zéro du modèle. Renvoie value inchangé lorsque le type de la sortie du modèle à index est flottant.

model est le modèle dont les paramètres de quantification de sortie sont utilisés.

value est le ndarray à quantifier.

index sélectionne la sortie tensorielle du model par rapport à laquelle quantifier.

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

Convertit le ndarray passé en soustrayant le point zéro puis en multipliant par l’échelle du modèle. Renvoie value inchangé lorsque le type de la sortie du modèle à index est flottant.

model est le modèle dont les paramètres de quantification de sortie sont utilisés.

value est le ndarray à déquantifier.

index sélectionne la sortie tensorielle du model par rapport à laquelle déquantifier.

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

Dessine des boîtes englobantes (ou des marqueurs de point central) avec des étiquettes textuelles sur image.

boxes est une liste de tuples (x, y, w, h).

labels est une liste de chaînes d’étiquettes, une par boîte.

colors est une liste de tuples (r, g, b), un par boîte.

scores si différent de None, une liste de scores de confiance par boîte. Lorsqu’elle est fournie, chaque étiquette rendue est suivie du score formaté en " %.2f".

format contrôle la manière dont les coordonnées des boîtes sont interprétées :

  • "pascal_voc" – (xmin, ymin, xmax, ymax) normalisé dans la plage 0.0 à 1.0.

  • "point" – (x, y, w, h) en pixels absolus ; un marqueur en forme de cercle plein est dessiné au centre de la boîte au lieu d’un rectangle (utile pour les détecteurs de point central).

  • toute autre valeur – (x, y, w, h) en pixels absolus ; dessiné sous forme de rectangle.

font_width est la largeur en pixels de chaque caractère de l’étiquette.

font_height est la hauteur en pixels de l’arrière-plan de l’étiquette.

text_color est la couleur (r, g, b) utilisée pour le texte de l’étiquette.

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

Dessine un ndarray de valeurs de points clés (x, y, ...) sur image.

radius est le rayon du cercle des points clés. Lorsque radius == 0, les points clés sont dessinés sous forme de pixels uniques.

color est la couleur (r, g, b) des points clés.

thickness est l’épaisseur du contour du cercle.

fill si True, remplit les cercles des points clés.

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

Dessine un ndarray de valeurs de points clés (x, y, ...) sur image puis les relie par des segments de droite.

lines est une liste de tuples (kp0_idx, kp1_idx) spécifiant quelles paires de points clés relier.

kp_radius est le rayon du cercle des points clés (transmis à draw_keypoints).

kp_color est la couleur (r, g, b) des points clés.

kp_thickness est l’épaisseur du contour du cercle des points clés.

kp_fill si True, remplit les cercles des points clés.

line_color est la couleur (r, g, b) des lignes.

line_thickness est l’épaisseur des lignes.

classe NMS – Suppression Non-Maximale douce (Soft-NMS)

L’objet NMS collecte une liste de boîtes englobantes avec leurs scores associés, filtre les boîtes qui se chevauchent ayant des scores plus faibles via Soft-NMS, et remappe les boîtes détectées dans une sous-fenêtre vers les coordonnées de l’image originale.

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

Crée un objet NMS.

window_w et window_h sont la largeur et la hauteur du tenseur d’entrée du modèle / de la fenêtre.

roi est la région d’intérêt (x, y, w, h) de l’image originale sur laquelle le modèle a été exécuté (typiquement renvoyée par l’objet Normalization()). Utilisée pour remapper les boîtes détectées dans l’espace de coordonnées de l’image originale. roi[2] et roi[3] doivent être >= 1.

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

Ajoute une boîte englobante à l’objet NMS. Les boîtes dont le score est en dehors de [0.0, 1.0] ou dont la largeur ou la hauteur est nulle/négative après écrêtage sont écartées.

xmin, ymin, xmax, ymax sont les coordonnées de la boîte englobante dans l’espace en pixels de la fenêtre, écrêtées à [0, window_w] / [0, window_h].

score est le score de confiance de la boîte englobante (0.0-1.0).

label_index est l’indice de l’étiquette de classe associée à la boîte englobante.

keypoints est un ndarray optionnel de valeurs de points clés (x, y, ...) associées à cette boîte englobante.

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

Effectue une Soft-NMS sur toutes les boîtes ajoutées et renvoie une liste de listes par classe, indexée par label_index. Chaque liste interne contient des tuples ((x, y, w, h), score) remappés vers les coordonnées de l’image originale. Si keypoints a été fourni lors de l’ajout, le tuple est étendu avec le ndarray keypoints remappé.

Après avoir appelé cette méthode, créez un nouvel objet NMS pour traiter un nouvel ensemble de boîtes englobantes.

threshold est le score minimum qu’une boîte doit conserver après la suppression Soft-NMS pour être gardée.

sigma contrôle la gaussienne utilisée pour pénaliser les scores des boîtes englobantes qui se chevauchent. Un sigma plus petit entraîne une suppression plus agressive. sigma <= 0.0 désactive la pénalité gaussienne (les scores des boîtes qui se chevauchent ne sont pas atténués).