ml.utils --- ML 工具

ml.utils 模組包含用於機器學習的工具類別與函式。

函式

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

傳回所傳入 ndarray 中所有值的 logit。

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

傳回所傳入 ndarray 中所有值的 sigmoid。

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

依量化後的 threshold 對 scores（int8、uint8、int16 或 uint16 的量化 ndarray）進行閾值處理，並傳回一個包含所有通過閾值之索引的 ndarray。

會測試 scale 以判斷反量化後的值為正或負。當 scale > 0 時傳回 scores > threshold 的索引；否則傳回 scores < threshold 的索引。

find_max 若為 True，會在內部將 scores 替換為沿著 find_max_axis 取得最大值（或最小值，視 scale 而定）的 ndarray。

find_max_axis 是當 find_max 為 True 時，用以計算最大／最小值縮減的軸。

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

將所傳入的 ndarray 除以 scale 並加上模型的零點以進行轉換。當模型在 index 處的輸出 dtype 為浮點數時，會原樣傳回 value。

model 是其輸出量化參數將被使用的模型。

value 是要量化的 ndarray。

index 用以選擇要對 model 的哪一個張量輸出進行量化。

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

將所傳入的 ndarray 減去零點後再乘以模型的 scale 以進行轉換。當模型在 index 處的輸出 dtype 為浮點數時，會原樣傳回 value。

model 是其輸出量化參數將被使用的模型。

value 是要反量化的 ndarray。

index 用以選擇要對 model 的哪一個張量輸出進行反量化。

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

在 image 上繪製附帶文字標籤的邊界框（或中心點標記）。

boxes 是一個 (x, y, w, h) 元組的清單。

labels 是一個標籤字串的清單，每個邊界框對應一個。

colors 是一個 (r, g, b) 元組的清單，每個邊界框對應一個。

scores 若不為 None，則為每個邊界框的信心分數清單。提供此參數時，每個繪製的標籤後方會加上以 " %.2f" 格式化的分數。

format 控制如何解讀邊界框座標：

• "pascal_voc" -- 範圍在 0.0 到 1.0 之間的正規化 (xmin, ymin, xmax, ymax)。

• "point" -- 絕對像素 (x, y, w, h)；會在邊界框中心繪製一個填滿的圓形標記，而非矩形（適用於中心點偵測器）。

• 其他任何值 -- 絕對像素 (x, y, w, h)；以矩形繪製。

font_width 是標籤中每個字元的寬度（以像素為單位）。

font_height 是標籤背景的高度（以像素為單位）。

text_color 是用於標籤文字的 (r, g, b) 色彩。

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

在 image 上繪製一個包含關鍵點 (x, y, ...) 值的 ndarray。

radius 是關鍵點圓形的半徑。當 radius == 0 時，關鍵點會以單一像素繪製。

color 是關鍵點的 (r, g, b) 色彩。

thickness 是圓形外框的線寬。

fill 若為 True 則填滿關鍵點圓形。

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

在 image 上繪製一個包含關鍵點 (x, y, ...) 值的 ndarray，然後以線段將它們連接起來。

lines 是一個 (kp0_idx, kp1_idx) 元組的清單，指定要連接哪些關鍵點配對。

kp_radius 是關鍵點圓形的半徑（會傳遞給 draw_keypoints）。

kp_color 是關鍵點的 (r, g, b) 色彩。

kp_thickness 是關鍵點圓形外框的線寬。

kp_fill 若為 True 則填滿關鍵點圓形。

line_color 是線條的 (r, g, b) 色彩。

line_thickness 是線條的線寬。

class NMS -- 軟性非極大值抑制（Soft-Non-Maximum Suppression）

NMS 物件會收集一份附帶分數的邊界框清單，透過 Soft-NMS 過濾掉分數較低的重疊邊界框，並將在子視窗中偵測到的邊界框重新對應回原始影像座標。

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

建立一個 NMS 物件。

window_w 與 window_h 是模型輸入張量／視窗的寬度與高度。

roi 是模型執行所在之原始影像的 (x, y, w, h) 感興趣區域（通常由 Normalization() 物件傳回）。用以將偵測到的邊界框重新對應回原始影像的座標空間。roi[2] 與 roi[3] 必須 >= 1。

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

將一個邊界框加入 NMS 物件。score 落在 [0.0, 1.0] 之外，或經裁切後寬度或高度為零／為負的邊界框會被捨棄。

xmin、ymin、xmax、ymax 是視窗像素空間中的邊界框座標，裁切至 [0, window_w] / [0, window_h]。

score 是邊界框的信心分數（0.0-1.0）。

label_index 是與該邊界框關聯之類別標籤的索引。

keypoints 是與此邊界框關聯之關鍵點 (x, y, ...) 值的選用 ndarray。

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

對所有已加入的邊界框執行 Soft-NMS，並傳回一份依 label_index 索引的、每類別一個清單的清單。每個內層清單包含對應回原始影像座標的 ((x, y, w, h), score) 元組。若加入時提供了 keypoints，元組會額外附上重新對應後的 keypoints ndarray。

呼叫此方法後，請建立一個新的 NMS 物件以處理新的一組邊界框。

threshold 是邊界框在 Soft-NMS 抑制後必須保留、方能被保留下來的最低分數。

sigma 控制用於懲罰重疊邊界框分數的高斯函式。較小的 sigma 會導致更積極的抑制。sigma <= 0.0 會停用高斯懲罰（重疊邊界框的分數不會衰減）。