class ImageIO – אובייקט ImageIO

המחלקה ImageIO מקליטה ומנגנת זרמים של פריימים מסוג Image בפורמט הדיסק המקורי של OpenMV. זרם בודד יכול להכיל פריימים הטרוגניים (פורמטי פיקסל / גדלים שונים) ומקליט עבור כל אחד את מרווח הזמן בין הפריימים, כך שהניגון משחזר את קצב הפריימים המקורי.

קיימים שני מאגרי אחסון:

• זרם קובץ – פריימים נקראים מתוך / מצורפים לקובץ במערכת הקבצים. הקובץ מתחיל בכותרת קסם (magic header) באורך 16 בתים OMV IMG STR Vx.y ואחריה מקטעים לכל פריים. הכותב הנוכחי מפיק V2.0; קבצים ישנים יותר מסוג V1.0 ו-V1.1 עדיין ניתנים לקריאה.

• זרם זיכרון – פריימים נקראים מתוך / נכתבים אל חוצץ RAM בגודל קבוע המוקצה בזמן הבנייה. שימושי למעבר הלוך-ושוב של פריימים דרך מסננים הזקוקים להקלטה מבלי לגעת במערכת הקבצים.

class image.ImageIO(path: str | Tuple[int, int, int], mode: str | int)

יצירת זרם ImageIO.

אם path הוא מחרוזת, נפתח זרם קובץ בנתיב זה. mode חייב להיות אחד מהבאים:

• 'r' – פתיחת קובץ קיים לקריאה. כותרת הקסם מאומתת והגרסה (V1.0 / V1.1 / V2.0) נרשמת לשימוש על ידי version().

• 'w' – קיצוץ / יצירת הקובץ וכתיבת כותרת קסם חדשה V2.0. פריימים מצורפים בכל write().

אם path הוא שלשה (3-tuple) (w, h, pixformat), מוקצה זרם זיכרון. mode הוא אז מספר משבצות הפריימים השלם שיש להקצות מראש. החוצץ מותאם לגודל של count פריימים בגודל (w, h, pixformat) ואינו רשאי לגדול לאחר היצירה. pixformat הוא אחד מ-image.BINARY, image.GRAYSCALE, image.RGB565, image.BAYER, image.YUV422, image.JPEG, או image.PNG. עבור הפורמטים הדחוסים (image.JPEG, image.PNG) גודל כל משבצת מוערך ב-2 bpp; פריימים גדולים מההערכה מעלים ValueError בזמן write().

בדיקה

type() → int

מחזיר את מאגר האחסון של הזרם: FILE_STREAM עבור זרם קובץ, MEMORY_STREAM עבור זרם זיכרון.

is_closed() → bool

מחזיר True אם close() נקרא על אובייקט זה. לאחר הסגירה הזרם מעלה OSError("Stream closed") בכל פעולת קריאה/כתיבה/דילוג נוספת.

count() → int

מחזיר את מספר הפריימים המאוחסנים כעת בזרם. עבור זרמי קובץ מספר זה גדל ככל ש-write() מצרף פריימים; עבור זרמי זיכרון הוא קבוע בזמן הבנייה.

offset() → int

מחזיר את אינדקס הפריים הנוכחי. מוגדל על ידי read() ו-write(), מאופס על ידי seek().

version() → int | None

מחזיר את גרסת פורמט הדיסק עבור זרמי קובץ (10 עבור V1.0, 11 עבור V1.1, 20 עבור V2.0). מחזיר None עבור זרמי זיכרון.

buffer_size() → int | None

מחזיר את גודל חוצץ הפיקסלים לכל משבצת בבתים עבור זרמי זיכרון (גודל המשבצת פחות כותרת ניהול הרשומות הפנימית של Image). מחזיר None עבור זרמי קובץ. השתמש בזה יחד עם count() כדי לבדוק האם גודל פריים מסוים ייכנס.

size() → int

מחזיר את סך הבתים שהזרם צורך – גודל הקובץ בדיסק עבור זרמי קובץ, או גודל חוצץ ה-RAM המלא (count * per_slot_size כולל כותרת כל משבצת) עבור זרמי זיכרון.

I/O

write(img: Image) → ImageIO

מצרף (זרם קובץ) או מאחסן-בהיסט (זרם זיכרון) את img ומקדם את offset() באחד.

עבור זרמי קובץ הקובץ גדל ככל שפריימים מצורפים. כתיבה בהיסט שאינו הסוף מקצצת את שאר הקובץ כך שהמונה יכול להתכווץ.

עבור זרמי זיכרון הפריים נכתב לתוך המשבצת הנוכחית; כתיבה מעבר למשבצת האחרונה מעלה EOFError("End of stream") וכתיבת פריים גדול מ-buffer_size() מעלה ValueError("Invalid frame size").

מחזיר self כך שניתן לשרשר קריאות.

read(copy_to_fb: bool = True, *, loop: bool = True, pause: bool = True) → Image | None

קורא את הפריים בהיסט הנוכחי offset(), מקדם את ההיסט, ומחזיר את ה-Image החדש. משקף את צד הניגון של write().

copy_to_fb – כאשר True (ברירת מחדל) הפריים המפוענח מוצב בחוצץ הפריימים של המצלמה (frame buffer) (אותו מקום שאליו מגיע csi.CSI.snapshot()), כך שניתן לצייר על ה-Image המוחזר דרך התצוגה המקדימה של ה-IDE. כאשר False הפריים מוקצה במקום זאת על ערימת ה-MicroPython.

loop (זרמי קובץ בלבד) – כאשר True (ברירת מחדל) קריאה מעבר לפריים האחרון מדלגת חזרה לפריים הראשון וממשיכה. כאשר False הקריאה מחזירה None ברגע שמגיעים לסוף הקובץ.

pause – כאשר True (ברירת מחדל) הקריאה חוסמת עד שמרווח הזמן בין הפריימים שהוקלט במקור חולף, כך שהניגון רץ בקצב הפריימים המקורי של ההקלטה. הגדר ל-False עבור ניגון מהיר ככל האפשר.

seek(offset: int) → ImageIO

מעביר את offset() לפריים offset. offset חייב להיות לא-שלילי; היסטים של זרם זיכרון חייבים גם להיות קטנים מ-count().

דילוגים בזרם קובץ עוברים על הקובץ פריים אחר פריים מההתחלה מאחר ומקטעי הפריימים הם בגדלים משתנים – צפה לזמן O(offset) עבור קפיצות גדולות.

מחזיר self כך שניתן לשרשר קריאות.

sync() → ImageIO

שוטף כתיבות ממתינות לדיסק עבור זרמי קובץ (קורא ל-sync הבסיסי של מערכת הקבצים). ללא פעולה עבור זרמי זיכרון.

מחזיר self כך שניתן לשרשר קריאות.

close() → None

סוגר את הזרם. משחרר את חוצץ הזיכרון (זרמי זיכרון) או סוגר את הקובץ (זרמי קובץ). לאחר close() לא ניתן לעשות שימוש חוזר באובייקט ImageIO; פעולות עוקבות מעלות OSError("Stream closed"). קריאה ל-close() פעמיים אינה מבצעת דבר.

אובייקט ImageIO נסגר גם אוטומטית כאשר הוא נאסף על ידי אוסף הזבל (garbage-collected) (הוא רושם פעולת סיום בזמן הבנייה).

קבועים

FILE_STREAM: int

ערך המוחזר על ידי type() עבור זרמים מגובי קובץ.

MEMORY_STREAM: int

ערך המוחזר על ידי type() עבור זרמים בזיכרון.