ml.utils — Utilitare ML

Modulul ml.utils conține clase și funcții utilitare pentru învățarea automată.

Funcții

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

Returnează logitul tuturor valorilor din ndarray-ul transmis.

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

Returnează sigmoida tuturor valorilor din ndarray-ul transmis.

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

Aplică un prag asupra scores (un ndarray cuantizat de tip int8, uint8, int16 sau uint16) folosind un threshold cuantizat și returnează un ndarray cu toți indicii care trec de prag.

scale este testat pentru a determina dacă valorile decuantizate sunt pozitive sau negative. Când scale > 0 se returnează indicii pentru care scores > threshold; în caz contrar se returnează indicii pentru care scores < threshold.

find_max dacă este True, înlocuiește intern scores cu un ndarray al valorilor maxime (sau minime, în funcție de scale) de-a lungul find_max_axis.

find_max_axis este axa de-a lungul căreia se calculează reducerea max/min atunci când find_max este True.

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

Convertește ndarray-ul transmis împărțind la factorul de scalare și adăugând punctul zero al modelului. Returnează value neschimbat atunci când tipul de date al ieșirii modelului la index este float.

model este modelul ai cărui parametri de cuantizare a ieșirii sunt folosiți.

value este ndarray-ul care urmează să fie cuantizat.

index selectează față de care ieșire tensorială a model-ului se face cuantizarea.

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

Convertește ndarray-ul transmis scăzând punctul zero și apoi înmulțind cu factorul de scalare al modelului. Returnează value neschimbat atunci când tipul de date al ieșirii modelului la index este float.

model este modelul ai cărui parametri de cuantizare a ieșirii sunt folosiți.

value este ndarray-ul care urmează să fie decuantizat.

index selectează față de care ieșire tensorială a model-ului se face decuantizarea.

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

Desenează casete de încadrare (sau marcaje de punct central) cu etichete text pe image.

boxes este o listă de tupluri (x, y, w, h).

labels este o listă de șiruri de etichete, câte una pentru fiecare casetă.

colors este o listă de tupluri (r, g, b), câte unul pentru fiecare casetă.

scores dacă nu este None, o listă de scoruri de încredere pentru fiecare casetă. Când este furnizată, fiecare etichetă redată este sufixată cu scorul formatat ca " %.2f".

format controlează modul în care sunt interpretate coordonatele casetei:

• "pascal_voc" – normalizat (xmin, ymin, xmax, ymax) în intervalul 0.0 până la 1.0.

• "point" – pixeli absoluți (x, y, w, h); un marcaj sub formă de cerc plin este desenat în centrul casetei în loc de un dreptunghi (util pentru detectoare bazate pe puncte centrale).

• orice altă valoare – pixeli absoluți (x, y, w, h); desenat ca un dreptunghi.

font_width este lățimea în pixeli a fiecărui caracter din etichetă.

font_height este înălțimea în pixeli a fundalului etichetei.

text_color este culoarea (r, g, b) folosită pentru textul etichetei.

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

Desenează un ndarray de valori de puncte-cheie (x, y, ...) pe image.

radius este raza cercului punctului-cheie. Când radius == 0 punctele-cheie sunt desenate ca pixeli individuali.

color este culoarea (r, g, b) a punctelor-cheie.

thickness este grosimea conturului cercului.

fill dacă este True umple cercurile punctelor-cheie.

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

Desenează un ndarray de valori de puncte-cheie (x, y, ...) pe image și apoi le conectează cu segmente de linie.

lines este o listă de tupluri (kp0_idx, kp1_idx) care specifică ce perechi de puncte-cheie să fie conectate.

kp_radius este raza cercului punctului-cheie (transmisă mai departe către draw_keypoints).

kp_color este culoarea (r, g, b) a punctelor-cheie.

kp_thickness este grosimea conturului cercului punctului-cheie.

kp_fill dacă este True umple cercurile punctelor-cheie.

line_color este culoarea (r, g, b) a liniilor.

line_thickness este grosimea liniei.

class NMS – Suprimare slabă a non-maximelor (Soft-Non-Maximum Suppression)

Obiectul NMS colectează o listă de casete de încadrare cu scorurile asociate, filtrează casetele suprapuse cu scoruri mai mici prin Soft-NMS și remapează casetele detectate într-o sub-fereastră înapoi în coordonatele imaginii originale.

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

Creează un obiect NMS.

window_w și window_h sunt lățimea și înălțimea tensorului / ferestrei de intrare a modelului.

roi este regiunea de interes (x, y, w, h) din imaginea originală pe care a fost rulat modelul (de obicei returnată de obiectul Normalization()). Folosită pentru a remapa casetele detectate înapoi în spațiul de coordonate al imaginii originale. roi[2] și roi[3] trebuie să fie >= 1.

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

Adaugă o casetă de încadrare la obiectul NMS. Casetele cu score în afara intervalului [0.0, 1.0] sau cu lățime ori înălțime zero/negativă după decupare sunt eliminate.

xmin, ymin, xmax, ymax sunt coordonatele casetei de încadrare în spațiul de pixeli al ferestrei, decupate la [0, window_w] / [0, window_h].

score este scorul de încredere al casetei de încadrare (0.0-1.0).

label_index este indicele etichetei de clasă asociate casetei de încadrare.

keypoints este un ndarray opțional de valori de puncte-cheie (x, y, ...) asociate acestei casete de încadrare.

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

Efectuează Soft-NMS asupra tuturor casetelor adăugate și returnează o listă de liste pentru fiecare clasă, indexate după label_index. Fiecare listă internă conține tupluri de forma ((x, y, w, h), score) mapate înapoi în coordonatele imaginii originale. Dacă keypoints a fost furnizat la adăugare, tuplul este extins cu ndarray-ul keypoints remapat.

După apelarea acestei metode, creați un nou obiect NMS pentru a procesa un nou set de casete de încadrare.

threshold este scorul minim pe care o casetă trebuie să îl păstreze după suprimarea Soft-NMS pentru a fi reținută.

sigma controlează funcția gaussiană folosită pentru a penaliza scorurile casetelor de încadrare suprapuse. Un sigma mai mic duce la o suprimare mai agresivă. sigma <= 0.0 dezactivează penalizarea gaussiană (scorurile casetelor suprapuse nu sunt diminuate).