ml.utils — כלי עזר ל-ML

המודול ml.utils מכיל מחלקות עזר ופונקציות עבור למידת מכונה.

פונקציות

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

מחזירה את ה-logit של כל הערכים ב-ndarray שהועבר.

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

מחזירה את ה-sigmoid של כל הערכים ב-ndarray שהועבר.

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

מבצעת ספירה (threshold) על scores (ndarray מקוונטז מסוג int8, uint8, int16 או uint16) לפי threshold מקוונטז ומחזירה ndarray של כל האינדקסים שעוברים את הסף.

scale נבדק כדי לקבוע אם הערכים המפוענחים חיוביים או שליליים. כאשר scale > 0 מוחזרים האינדקסים שבהם scores > threshold; אחרת מוחזרים האינדקסים שבהם scores < threshold.

find_max אם True, מחליף את scores באופן פנימי ב-ndarray של המקסימום (או המינימום, בהתאם ל-scale) לאורך find_max_axis.

find_max_axis הוא הציר שלאורכו מחושב צמצום המקסימום/מינימום כאשר find_max הוא True.

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

ממירה את ה-ndarray שהועבר באמצעות חלוקה ב-scale והוספת ה-zero point של המודל. מחזירה את value ללא שינוי כאשר ה-dtype של פלט המודל ב-index הוא float.

model הוא המודל שפרמטרי הקוונטיזציה של הפלט שלו משמשים.

value הוא ה-ndarray לקוונטיזציה.

index בוחר מול איזה פלט טנזור של ה-model לבצע קוונטיזציה.

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

ממירה את ה-ndarray שהועבר באמצעות חיסור ה-zero point ולאחר מכן הכפלה ב-scale של המודל. מחזירה את value ללא שינוי כאשר ה-dtype של פלט המודל ב-index הוא float.

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 היא רשימה של tuples מסוג (x, y, w, h).

labels היא רשימה של מחרוזות תווית, אחת לכל תיבה.

colors היא רשימה של tuples מסוג (r, g, b), אחד לכל תיבה.

scores אם אינו None, רשימה של ציוני ביטחון לכל תיבה. כאשר היא מסופקת, לכל תווית מרונדרת מתווסף הציון בסיומת בפורמט " %.2f".

format שולט באופן שבו מפורשות קואורדינטות התיבה:

• "pascal_voc" – (xmin, ymin, xmax, ymax) מנורמלים בטווח 0.0 עד 1.0.

• "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

מציירת ndarray של ערכי keypoint (x, y, ...) על גבי image.

radius הוא רדיוס עיגול ה-keypoint. כאשר radius == 0 ה-keypoints מצוירים כפיקסלים בודדים.

color הוא צבע ה-keypoint (r, g, b).

thickness הוא עובי קו המתאר של העיגול.

fill אם True ממלא את עיגולי ה-keypoint.

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

מציירת ndarray של ערכי keypoint (x, y, ...) על גבי image ולאחר מכן מחברת אותם בקטעי קו.

lines היא רשימה של tuples מסוג (kp0_idx, kp1_idx) המציינים אילו זוגות keypoint לחבר.

kp_radius הוא רדיוס עיגול ה-keypoint (מועבר אל draw_keypoints).

kp_color הוא צבע ה-keypoint (r, g, b).

kp_thickness הוא עובי קו המתאר של עיגול ה-keypoint.

kp_fill אם True ממלא את עיגולי ה-keypoint.

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 הוא ndarray אופציונלי של ערכי keypoint (x, y, ...) המשויכים לתיבה תוחמת זו.

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

מבצעת Soft-NMS על כל התיבות שנוספו ומחזירה רשימה של רשימות לכל מחלקה, מאונדקסות לפי label_index. כל רשימה פנימית מכילה tuples מסוג ((x, y, w, h), score) הממופים בחזרה לקואורדינטות התמונה המקורית. אם keypoints סופק בעת ההוספה, ה-tuple מורחב עם ה-ndarray של ה-keypoints הממופה מחדש.

לאחר קריאה למתודה זו צרו אובייקט NMS חדש כדי לעבד קבוצה חדשה של תיבות תוחמות.

threshold הוא הציון המינימלי שתיבה חייבת לשמר לאחר דיכוי Soft-NMS כדי להישמר.

sigma שולט בגאוסיאן המשמש להענשת הציונים של תיבות תוחמות חופפות. sigma קטן יותר מביא לדיכוי אגרסיבי יותר. sigma <= 0.0 משבית את ענישת הגאוסיאן (הציונים של תיבות חופפות אינם נחלשים).