tof --- مشغل مستشعر زمن الرحلة

تقود الوحدة tof مستشعرات قياس المدى بزمن الرحلة (ToF) المتصلة بكاميرا OpenMV Cam عبر I2C. يُعيد كل إطار قيمة عمق لكل بكسل بالمليمتر لشبكة مناطق 8x8 (VL53L5CX / VL53L8CX)، والتي يمكن عرضها كصورة عمق مستقلة باستخدام snapshot() أو دمجها على إطار ضوء مرئي من مستشعر CSI باستخدام draw_depth()، عادةً عبر لوحة ألوان مثل image.PALETTE_DEPTH.

مثال على الاستخدام:

import csi
import tof

csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize(csi.QVGA)

tof.init()

while True:
    img = csi0.snapshot()
    depth, depth_min, depth_max = tof.read_depth()
    tof.draw_depth(img, depth)
    print("====================")
    print("Min depth in mm seen: %0.2f" % depth_min)
    print("Max depth in mm seen: %0.2f" % depth_max)

إذا كنت تريد تدوير مصفوفة/صورة العمق بمضاعفات 90 درجة، مرّر التوليفات التالية من hmirror/vflip/transpose إلى read_depth أو draw_depth أو snapshot:

  • vflip=False, hmirror=False, transpose=False -> تدوير بمقدار 0 درجة

  • vflip=True,  hmirror=False, transpose=True -> تدوير بمقدار 90 درجة

  • vflip=True,  hmirror=True,  transpose=False -> تدوير بمقدار 180 درجة

  • vflip=False, hmirror=True,  transpose=True -> تدوير بمقدار 270 درجة

الدوال

tof.init(type: int = -1) → None

تُهيّئ مستشعر عمق مدمجًا.

type يشير إلى نوع مستشعر TOF:

افتراضيًا، يكون type هو -1 مما يجعل tof.init() يمسح ويُهيّئ تلقائيًا مستشعر TOF متصلًا بناءً على عنوان I2C.

tof.reset() → None

تُعيد تعيين حالة مستشعر العمق.

tof.deinit() → None

تُلغي تهيئة مستشعر العمق محرّرةً الموارد.

tof.width() → int

تُعيد عرض (الدقة الأفقية) مستشعر العمق المستخدم. تُطلق RuntimeError إذا لم يكن المستشعر مُهيّأً.

tof.height() → int

تُعيد ارتفاع (الدقة الرأسية) مستشعر العمق المستخدم. تُطلق RuntimeError إذا لم يكن المستشعر مُهيّأً.

tof.type() → int

تُعيد نوع مستشعر العمق المستخدم:

تُطلق RuntimeError إذا لم يكن المستشعر مُهيّأً.

tof.refresh() → int

تُعيد معدل التحديث (بالهرتز) لمستشعر العمق المستخدم:

تُطلق RuntimeError إذا لم يكن المستشعر مُهيّأً.

tof.read_depth(hmirror: bool = False, vflip: bool = False, transpose: bool = False, timeout: int = 100) → Tuple[List[float], float, float]

تُعيد صفًا يحتوي على قائمة العمق (عدد width * height من القيم العشرية بالمليمتر)، وأدنى عمق مرئي، وأقصى عمق مرئي.

hmirror إذا كانت True تعكس مصفوفة العمق أفقيًا.

vflip إذا كانت True تقلب مصفوفة العمق رأسيًا.

transpose إذا كانت True تُحوِّل مصفوفة العمق (تبديل).

timeout كم عدد المللي ثانية للانتظار من أجل الإطار الجديد قبل إطلاق RuntimeError. إذا كانت 0 فالانتظار إلى الأبد.

tof.draw_depth(image: image.Image, depth: List[float], x: int = 0, y: int = 0, x_scale: float | None = None, y_scale: float | None = None, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int = image.PALETTE_DEPTH, alpha_palette: int | None = None, hint: int = 0, scale: Tuple[float, float] | None = None) → None

ترسم مصفوفة depth (كما تُعيدها read_depth) على image التي تبدأ زاويتها العلوية اليسرى عند الموقع x وy.

x_scale يتحكم في مقدار تحجيم الصورة المعروضة في اتجاه x (قيمة عشرية). إذا كانت هذه القيمة سالبة تُقلب الصورة أفقيًا. إذا لم تُحدَّد فإنها تطابق y_scale للحفاظ على نسبة العرض إلى الارتفاع.

y_scale يتحكم في مقدار تحجيم الصورة المعروضة في اتجاه y (قيمة عشرية). إذا كانت هذه القيمة سالبة تُقلب الصورة رأسيًا. إذا لم تُحدَّد فإنها تطابق x_scale للحفاظ على نسبة العرض إلى الارتفاع.

roi هو صف مستطيل منطقة الاهتمام (x, y, w, h) من مصفوفة العمق المصدر المراد رسمها.

rgb_channel هو قناة RGB (0=R، 1=G، 2=B) المراد استخلاصها من المصدر. -1 (الافتراضي) يستخدم كل القنوات.

alpha يتحكم في مقدار مزج المصدر في صورة الوجهة. 255 معتم، و0 ينتج عنه عدم تعديل. النطاق: 0-255.

color_palette هو تعداد لوحة ألوان (مثل image.PALETTE_DEPTH وimage.PALETTE_RAINBOW) أو صورة RGB565 بحجم 256 بكسل تُستخدم كجدول بحث للألوان على قيمة العمق ذات تدرج الرمادي.

alpha_palette إذا لم تكن None فهي صورة GRAYSCALE بحجم 256 بكسل تُستخدم كجدول بحث ألفا يُعدّل alpha لكل بكسل.

hint هو OR منطقي من:

scale هو صف من قيمتين (min, max) يتحكم في أدنى وأقصى عمق (بالمليمتر) المستخدم لتحجيم صورة العمق. القيمة الافتراضية هي أدنى وأقصى قيمة فعلية لمصفوفة العمق.

ملاحظة

تتذكر read_depth ما إذا استُدعيت بـ transpose=True وتستخدم draw_depth ذلك داخليًا لتحديد حجم المصفوفة المصدر.

tof.snapshot(hmirror: bool = False, vflip: bool = False, transpose: bool = False, x_scale: float | None = None, y_scale: float | None = None, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int = image.PALETTE_DEPTH, alpha_palette: int | None = None, hint: int = 0, scale: Tuple[float, float] | None = None, pixformat: int = image.RGB565, copy_to_fb: bool = False, timeout: int = 100) → image.Image

تقرأ إطارًا من مستشعر العمق وتُعيد كائن image.Image جديدًا يكون إما image.GRAYSCALE أو image.RGB565.

hmirror إذا كانت True تعكس الصورة الجديدة أفقيًا.

vflip إذا كانت True تقلب الصورة الجديدة رأسيًا.

transpose إذا كانت True تُحوِّل الصورة الجديدة (تبديل).

x_scale يتحكم في مقدار تحجيم الصورة في اتجاه x (قيمة عشرية). تقلب القيم السالبة أفقيًا. إذا لم تُحدَّد فإنها تطابق y_scale.

y_scale يتحكم في مقدار تحجيم الصورة في اتجاه y (قيمة عشرية). تقلب القيم السالبة رأسيًا. إذا لم تُحدَّد فإنها تطابق x_scale.

roi هو صف مستطيل منطقة الاهتمام (x, y, w, h) من المصدر المراد استخلاصه.

rgb_channel هو قناة RGB (0=R، 1=G، 2=B) المراد استخلاصها. -1 (الافتراضي) يستخدم كل القنوات.

alpha يتحكم في المزج من المصدر إلى الوجهة. 255 معتم، و0 يترك الوجهة دون تغيير. النطاق: 0-255.

color_palette هو تعداد لوحة ألوان (مثل image.PALETTE_DEPTH) أو صورة RGB565 بحجم 256 بكسل تُستخدم كجدول بحث للألوان.

alpha_palette إذا لم تكن None فهي صورة GRAYSCALE بحجم 256 بكسل تُستخدم كجدول بحث ألفا.

hint هو OR منطقي من:

scale هو صف من قيمتين (min, max) يتحكم في أدنى وأقصى عمق (بالمليمتر) المستخدم لتحجيم الصورة. القيمة الافتراضية هي أدنى/أقصى قيمة فعلية للإطار.

pixformat يتحكم في صيغة بكسل الصورة النهائية. يجب أن تكون image.GRAYSCALE أو image.RGB565.

copy_to_fb إذا كانت True تكتب الصورة الجديدة في مخزن الإطارات بدلًا من تخصيصها على كومة MicroPython.

timeout كم عدد المللي ثانية للانتظار من أجل الإطار الجديد قبل إطلاق RuntimeError. إذا كانت 0 فالانتظار إلى الأبد.

الثوابت

tof.TOF_VL53LX: int

مستشعر TOF من نوع VL53L5CX أو VL53L8CX (8x8 بكسل).