ml.preprocessing --- ML 前處理

ml.preprocessing 模組包含用於對影像進行前處理以供機器學習模型使用的類別。

class Normalization -- 影像正規化

Normalization 物件將 image.Image 物件轉換為 ndarray 輸入張量，以供 ml.Model.predict() 使用。當影像被傳遞給 ml.Model.predict() 時，它會由 ml.Model 物件自動建立，但也可以手動實例化以控制轉換（縮放、平均值/標準差、ROI）。

class ml.preprocessing.Normalization(scale: tuple[float, float] = (0.0, 1.0), mean: tuple[float, float, float] = (0.0, 0.0, 0.0), stdev: tuple[float, float, float] = (1.0, 1.0, 1.0), roi: tuple[int, int, int, int] = None)

建立一個 Normalization 物件。

scale 是浮點數輸入張量在正規化後所預期的 (min, max) 值範圍（例如 (0.0, 1.0) 或 (-1.0, 1.0)）。對於 uint8 與 int8 輸入張量則會被忽略。

mean 是在縮放後從影像減去的每通道平均值 (R, G, B)。對於灰階張量，平均值會使用 0.299*R + 0.587*G + 0.114*B 縮減為單一亮度值。對於 uint8 與 int8 輸入張量則會被忽略。

stdev 是在減去平均值後影像所除以的每通道標準差 (R, G, B)。對於灰階張量，標準差會使用 0.299*R + 0.587*G + 0.114*B 縮減為單一亮度值。對於 uint8 與 int8 輸入張量則會被忽略。

roi 是輸入影像內一個選用的 (x, y, w, h) 感興趣區域，用以裁切。若為 None，則使用整張影像。裁切出的區域會被置中，並以雙線性方式縮放（保持長寬比並以黑色填充）至模型的輸入張量尺寸。

__call__(image: image.Image) → Normalization

__call__(buffer: bytearray, shape: tuple[int, int, int, int], dtype: int) → None

當以單一 image.Image 引數呼叫時，回傳一個繫結至該影像的新 Normalization 物件。ml.Model.predict() 內部即是叫用此繫結物件來填充輸入張量。若原始實例上未設定 roi，則會將其初始化為整張影像大小。

當以 (buffer, shape, dtype) 呼叫時，會就地以先前繫結影像的正規化輸入張量填充 buffer。shape 必須為 (1, H, W, C)，其中 C 等於 1（灰階）或 3（RGB）。dtype 是 ulab numpy 的類型碼（例如 float32 為 ord('f')、int8 為 ord('b')、uint8 為 ord('B')）。浮點張量會套用 scale、mean 與 stdev；整數張量則直接寫入（int8 會帶有偏移量）。