ml.utils --- أدوات تعلم الآلة

تحتوي وحدة 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

تطبّق عتبة على 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 الممرَّر بالقسمة على المقياس وإضافة نقطة الصفر الخاصة بالنموذج. يُرجع value دون تغيير عندما يكون نوع بيانات خرج النموذج عند index من نوع float.

model هو النموذج الذي تُستخدم معاملات تكميم خرجه.

value هو الـ ndarray المراد تكميمه.

يحدد index أي خرج موتر (tensor) من model يُجرى التكميم بالنسبة إليه.

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

يحوّل الـ ndarray الممرَّر بطرح نقطة الصفر ثم الضرب في مقياس النموذج. يُرجع value دون تغيير عندما يكون نوع بيانات خرج النموذج عند index من نوع float.

model هو النموذج الذي تُستخدم معاملات تكميم خرجه.

value هو الـ ndarray المراد إلغاء تكميمه.

يحدد index أي خرج موتر (tensor) من 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 هي قائمة من الصفوف بالصيغة (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 من قيم النقاط المفتاحية (x, y, ...) على image.

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

يرسم ndarray من قيم النقاط المفتاحية (x, y, ...) على image ثم يصلها بقطع مستقيمة.

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 هو ndarray اختياري من قيم النقاط المفتاحية (x, y, ...) المرتبطة بمربع الإحاطة هذا.

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

يُجري Soft-NMS على جميع المربعات المضافة ويُرجع قائمة من القوائم لكل فئة، مفهرسة بـ label_index. تحتوي كل قائمة داخلية على صفوف بالصيغة ((x, y, w, h), score) معيَّنة إلى إحداثيات الصورة الأصلية. إذا تم توفير keypoints عند الإضافة، فإن الصف يُمدَّد بـ ndarray النقاط المفتاحية keypoints بعد إعادة تعيينها.

بعد استدعاء هذه الدالة أنشئ كائن NMS جديدًا لمعالجة مجموعة جديدة من مربعات الإحاطة.

threshold هي الحد الأدنى للدرجة التي يجب أن يحتفظ بها المربع بعد كبت Soft-NMS لكي يُبقى عليه.

يتحكم sigma في الدالة الغاوسية المستخدمة لمعاقبة درجات مربعات الإحاطة المتداخلة. تؤدي قيمة sigma الأصغر إلى كبت أكثر حدة. تعطّل القيمة sigma <= 0.0 العقوبة الغاوسية (لا تُخفَّض درجات المربعات المتداخلة).