ml.utils — Narzędzia ML

Moduł ml.utils zawiera klasy i funkcje pomocnicze dla uczenia maszynowego.

Funkcje

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

Zwraca logit wszystkich wartości w przekazanej tablicy ndarray.

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

Zwraca sigmoidę wszystkich wartości w przekazanej tablicy ndarray.

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

Progowanie scores (skwantyzowana tablica ndarray typu int8, uint8, int16 lub uint16) względem skwantyzowanego progu threshold i zwraca tablicę ndarray wszystkich indeksów przekraczających próg.

Wartość scale jest sprawdzana, aby ustalić, czy zdekwantyzowane wartości są dodatnie czy ujemne. Gdy scale > 0, zwracane są indeksy, dla których scores > threshold; w przeciwnym razie zwracane są indeksy, dla których scores < threshold.

find_max jeśli ma wartość True, wewnętrznie zastępuje scores tablicą ndarray zawierającą maksimum (lub minimum, w zależności od scale) wzdłuż find_max_axis.

find_max_axis to oś, wzdłuż której obliczana jest redukcja max/min, gdy find_max ma wartość True.

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

Konwertuje przekazaną tablicę ndarray poprzez podzielenie przez skalę i dodanie punktu zerowego modelu. Zwraca value bez zmian, gdy typ wyjściowy modelu o indeksie index jest zmiennoprzecinkowy.

model to model, którego parametry kwantyzacji wyjścia są wykorzystywane.

value to tablica ndarray do skwantyzowania.

index wybiera, względem którego wyjścia tensorowego model ma być przeprowadzona kwantyzacja.

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

Konwertuje przekazaną tablicę ndarray poprzez odjęcie punktu zerowego, a następnie pomnożenie przez skalę modelu. Zwraca value bez zmian, gdy typ wyjściowy modelu o indeksie index jest zmiennoprzecinkowy.

model to model, którego parametry kwantyzacji wyjścia są wykorzystywane.

value to tablica ndarray do zdekwantyzowania.

index wybiera, względem którego wyjścia tensorowego model ma być przeprowadzona dekwantyzacja.

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

Rysuje ramki ograniczające (lub znaczniki punktu środkowego) wraz z etykietami tekstowymi na obrazie image.

boxes to lista krotek (x, y, w, h).

labels to lista ciągów etykiet, po jednym na ramkę.

colors to lista krotek (r, g, b), po jednej na ramkę.

scores jeśli nie ma wartości None, to lista wyników pewności dla poszczególnych ramek. Gdy zostanie podana, każda renderowana etykieta jest uzupełniana o wynik sformatowany jako " %.2f".

format kontroluje sposób interpretacji współrzędnych ramki:

• "pascal_voc" – znormalizowane (xmin, ymin, xmax, ymax) w zakresie od 0.0 do 1.0.

• "point" – bezwzględne piksele (x, y, w, h); w środku ramki rysowany jest wypełniony znacznik kołowy zamiast prostokąta (przydatne dla detektorów punktów środkowych).

• dowolna inna wartość – bezwzględne piksele (x, y, w, h); rysowane jako prostokąt.

font_width to szerokość każdego znaku etykiety w pikselach.

font_height to wysokość tła etykiety w pikselach.

text_color to kolor (r, g, b) używany do tekstu etykiety.

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

Rysuje tablicę ndarray wartości punktów kluczowych (x, y, ...) na obrazie image.

radius to promień koła punktu kluczowego. Gdy radius == 0, punkty kluczowe są rysowane jako pojedyncze piksele.

color to kolor (r, g, b) punktu kluczowego.

thickness to grubość obrysu koła.

fill jeśli ma wartość True, wypełnia koła punktów kluczowych.

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

Rysuje tablicę ndarray wartości punktów kluczowych (x, y, ...) na obrazie image, a następnie łączy je odcinkami linii.

lines to lista krotek (kp0_idx, kp1_idx) określających, które pary punktów kluczowych należy połączyć.

kp_radius to promień koła punktu kluczowego (przekazywany do draw_keypoints).

kp_color to kolor (r, g, b) punktu kluczowego.

kp_thickness to grubość obrysu koła punktu kluczowego.

kp_fill jeśli ma wartość True, wypełnia koła punktów kluczowych.

line_color to kolor (r, g, b) linii.

line_thickness to grubość linii.

klasa NMS – Soft-Non-Maximum Suppression

Obiekt NMS gromadzi listę ramek ograniczających z powiązanymi wynikami, filtruje nakładające się ramki o niższych wynikach za pomocą Soft-NMS oraz przemapowuje ramki wykryte w podoknie z powrotem na współrzędne oryginalnego obrazu.

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

Tworzy obiekt NMS.

window_w i window_h to szerokość i wysokość tensora wejściowego / okna modelu.

roi to obszar zainteresowania (x, y, w, h) oryginalnego obrazu, na którym uruchomiono model (zwykle zwracany przez obiekt Normalization()). Używany do przemapowania wykrytych ramek z powrotem na przestrzeń współrzędnych oryginalnego obrazu. roi[2] i roi[3] muszą być >= 1.

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

Dodaje ramkę ograniczającą do obiektu NMS. Ramki z wynikiem score poza zakresem [0.0, 1.0] lub z zerową/ujemną szerokością bądź wysokością po przycięciu są odrzucane.

xmin, ymin, xmax, ymax to współrzędne ramki ograniczającej w przestrzeni pikseli okna, przycięte do [0, window_w] / [0, window_h].

score to wynik pewności ramki ograniczającej (0.0-1.0).

label_index to indeks etykiety klasy powiązanej z ramką ograniczającą.

keypoints to opcjonalna tablica ndarray wartości punktów kluczowych (x, y, ...) powiązanych z tą ramką ograniczającą.

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

Wykonuje Soft-NMS na wszystkich dodanych ramkach i zwraca listę list dla poszczególnych klas, indeksowaną przez label_index. Każda wewnętrzna lista zawiera krotki ((x, y, w, h), score) przemapowane z powrotem na współrzędne oryginalnego obrazu. Jeśli przy dodawaniu podano keypoints, krotka jest rozszerzana o przemapowaną tablicę ndarray keypoints.

Po wywołaniu tej metody utwórz nowy obiekt NMS, aby przetworzyć nowy zestaw ramek ograniczających.

threshold to minimalny wynik, jaki ramka musi zachować po tłumieniu Soft-NMS, aby została zachowana.

sigma kontroluje funkcję Gaussa używaną do karania wyników nakładających się ramek ograniczających. Mniejsza wartość sigma skutkuje bardziej agresywnym tłumieniem. sigma <= 0.0 wyłącza karę Gaussa (wyniki nakładających się ramek nie są zmniejszane).