ml.utils — ML-Hilfsfunktionen

Das Modul ml.utils enthält Hilfsklassen und -funktionen für maschinelles Lernen.

Funktionen

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

Gibt das Logit aller Werte im übergebenen ndarray zurück.

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

Gibt die Sigmoidfunktion aller Werte im übergebenen ndarray zurück.

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

Wendet einen Schwellenwert auf scores (ein quantisiertes ndarray vom Typ int8, uint8, int16 oder uint16) anhand eines quantisierten threshold an und gibt ein ndarray aller Indizes zurück, die den Schwellenwert überschreiten.

scale wird geprüft, um zu bestimmen, ob die dequantisierten Werte positiv oder negativ sind. Wenn scale > 0 ist, werden Indizes zurückgegeben, bei denen scores > threshold gilt; andernfalls werden Indizes zurückgegeben, bei denen scores < threshold gilt.

find_max ersetzt, falls True, scores intern durch ein ndarray des Maximums (oder Minimums, je nach scale) entlang find_max_axis.

find_max_axis ist die Achse, entlang derer die Max-/Min-Reduktion berechnet wird, wenn find_max True ist.

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

Konvertiert das übergebene ndarray, indem durch die Skalierung geteilt und der Nullpunkt des Modells addiert wird. Gibt value unverändert zurück, wenn der Ausgabedatentyp des Modells bei index float ist.

model ist das Modell, dessen Quantisierungsparameter der Ausgabe verwendet werden.

value ist das zu quantisierende ndarray.

index wählt aus, gegen welche Tensorausgabe des model quantisiert wird.

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

Konvertiert das übergebene ndarray, indem der Nullpunkt subtrahiert und anschließend mit der Skalierung des Modells multipliziert wird. Gibt value unverändert zurück, wenn der Ausgabedatentyp des Modells bei index float ist.

model ist das Modell, dessen Quantisierungsparameter der Ausgabe verwendet werden.

value ist das zu dequantisierende ndarray.

index wählt aus, gegen welche Tensorausgabe des model dequantisiert wird.

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

Zeichnet Begrenzungsrahmen (oder Mittelpunktmarkierungen) mit Textlabels auf image.

boxes ist eine Liste von (x, y, w, h)-Tupeln.

labels ist eine Liste von Label-Strings, eines pro Box.

colors ist eine Liste von (r, g, b)-Tupeln, eines pro Box.

scores ist, falls nicht None, eine Liste von Konfidenzwerten pro Box. Wenn angegeben, wird an jedes gerenderte Label der als " %.2f" formatierte Wert angehängt.

format steuert, wie die Box-Koordinaten interpretiert werden:

• "pascal_voc" – normalisierte (xmin, ymin, xmax, ymax) im Bereich 0.0 bis 1.0.

• "point" – absolute Pixel (x, y, w, h); anstelle eines Rechtecks wird eine gefüllte Kreismarkierung in der Mitte der Box gezeichnet (nützlich für Mittelpunktdetektoren).

• jeder andere Wert – absolute Pixel (x, y, w, h); als Rechteck gezeichnet.

font_width ist die Breite jedes Zeichens im Label in Pixeln.

font_height ist die Höhe des Label-Hintergrunds in Pixeln.

text_color ist die für den Label-Text verwendete (r, g, b)-Farbe.

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

Zeichnet ein ndarray von Schlüsselpunktwerten (x, y, ...) auf image.

radius ist der Radius des Schlüsselpunktkreises. Wenn radius == 0 ist, werden die Schlüsselpunkte als einzelne Pixel gezeichnet.

color ist die (r, g, b)-Farbe der Schlüsselpunkte.

thickness ist die Dicke des Kreisumrisses.

fill füllt, falls True, die Schlüsselpunktkreise.

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

Zeichnet ein ndarray von Schlüsselpunktwerten (x, y, ...) auf image und verbindet diese anschließend mit Liniensegmenten.

lines ist eine Liste von (kp0_idx, kp1_idx)-Tupeln, die angeben, welche Schlüsselpunktpaare verbunden werden sollen.

kp_radius ist der Radius des Schlüsselpunktkreises (wird an draw_keypoints durchgereicht).

kp_color ist die (r, g, b)-Farbe der Schlüsselpunkte.

kp_thickness ist die Dicke des Schlüsselpunktkreisumrisses.

kp_fill füllt, falls True, die Schlüsselpunktkreise.

line_color ist die (r, g, b)-Linienfarbe.

line_thickness ist die Liniendicke.

class NMS – Soft-Non-Maximum-Suppression

Das NMS-Objekt sammelt eine Liste von Begrenzungsrahmen mit zugehörigen Konfidenzwerten, filtert überlappende Boxen mit niedrigeren Werten per Soft-NMS und bildet in einem Teilfenster erkannte Boxen wieder auf die ursprünglichen Bildkoordinaten ab.

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

Erstellt ein NMS-Objekt.

window_w und window_h sind die Breite und Höhe des Eingabetensors / Fensters des Modells.

roi ist der (x, y, w, h)-Interessensbereich des Originalbilds, auf dem das Modell ausgeführt wurde (typischerweise vom Normalization()-Objekt zurückgegeben). Wird verwendet, um erkannte Boxen wieder in den ursprünglichen Bildkoordinatenraum abzubilden. roi[2] und roi[3] müssen >= 1 sein.

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

Fügt dem NMS-Objekt einen Begrenzungsrahmen hinzu. Boxen mit einem score außerhalb von [0.0, 1.0] oder mit einer Breite oder Höhe von null bzw. negativ nach dem Zuschneiden werden verworfen.

xmin, ymin, xmax, ymax sind die Koordinaten des Begrenzungsrahmens im Pixelraum des Fensters, zugeschnitten auf [0, window_w] / [0, window_h].

score ist der Konfidenzwert des Begrenzungsrahmens (0.0-1.0).

label_index ist der Index des Klassenlabels, das dem Begrenzungsrahmen zugeordnet ist.

keypoints ist ein optionales ndarray von Schlüsselpunktwerten (x, y, ...), das diesem Begrenzungsrahmen zugeordnet ist.

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

Führt Soft-NMS über alle hinzugefügten Boxen aus und gibt eine Liste von Listen pro Klasse zurück, indexiert nach label_index. Jede innere Liste enthält Tupel der Form ((x, y, w, h), score), die wieder auf die ursprünglichen Bildkoordinaten abgebildet sind. Wenn beim Hinzufügen keypoints angegeben wurde, wird das Tupel um das umgerechnete keypoints-ndarray erweitert.

Erstellen Sie nach dem Aufruf dieser Methode ein neues NMS-Objekt, um eine neue Menge von Begrenzungsrahmen zu verarbeiten.

threshold ist der Mindestwert, den eine Box nach der Soft-NMS-Unterdrückung behalten muss, um beibehalten zu werden.

sigma steuert die Gaußfunktion, die zur Bestrafung der Werte überlappender Begrenzungsrahmen verwendet wird. Ein kleineres sigma führt zu einer aggressiveren Unterdrückung. sigma <= 0.0 deaktiviert die Gauß-Bestrafung (die Werte überlappender Boxen werden nicht verringert).