סיבובי תרחישי שימוש של CameraX

בנושא הזה מוסבר איך להגדיר תרחישי שימוש של CameraX באפליקציה כדי לקבל תמונות עם מידע נכון על סיבוב, בין אם הן מתרחיש השימוש ImageAnalysis או ImageCapture. כך:

  • ה-Analyzer של תרחיש השימוש ImageAnalysis צריך לקבל פריימים עם הסיבוב הנכון.
  • תרחיש השימוש ImageCapture אמור לצלם תמונות עם הסיבוב הנכון.

הסברים על המונחים

בנושא הזה נעשה שימוש במונחים הבאים, ולכן חשוב להבין את המשמעות של כל אחד מהם:

כיוון המסך
הכוונה היא לאיזה צד של המכשיר פונה כלפי מעלה, ויכול להיות אחד מארבעה ערכים: לאורך, לרוחב, לאורך הפוך או לרוחב הפוך.
סיבוב מסך
זה הערך שמוחזר על ידי Display.getRotation(), והוא מייצג את המעלות שבהן המכשיר מסובב נגד כיוון השעון מהכיוון הטבעי שלו.
סיבוב היעד
הערך הזה מייצג את מספר המעלות שבהן צריך לסובב את המכשיר בכיוון השעון כדי להגיע לאוריינטציה הטבעית שלו.

איך לקבוע את כיוון הסיבוב הרצוי

הדוגמאות הבאות מראות איך לקבוע את סיבוב היעד של מכשיר על סמך הכיוון הטבעי שלו.

דוגמה 1: כיוון טבעי לאורך

דוגמה למכשיר: Pixel 3 XL

כיוון טבעי = לאורך
כיוון נוכחי = לאורך

סיבוב המסך = 0
סיבוב היעד = 0

כיוון טבעי = לאורך
כיוון נוכחי = לרוחב

סיבוב המסך = 90
סיבוב היעד = 90

דוגמה 2: כיוון טבעי לרוחב

דוגמה למכשיר: Pixel C

כיוון טבעי = לרוחב
כיוון נוכחי = לרוחב

סיבוב המסך = 0
סיבוב היעד = 0

כיוון טבעי = לרוחב
כיוון נוכחי = לאורך

סיבוב המסך = 270
סיבוב היעד = 270

סיבוב תמונה

איזה צד הוא למעלה? כיוון החיישן מוגדר ב-Android כערך קבוע, שמייצג את המעלות (0, 90, 180, 270) שבהן החיישן מסובב מהחלק העליון של המכשיר כשהמכשיר נמצא במיקום טבעי. בכל המקרים שמוצגים בתרשימים, סיבוב התמונה מתאר את האופן שבו צריך לסובב את הנתונים בכיוון השעון כדי שהתמונה תופיע בצורה אנכית.

בדוגמאות הבאות מוצג סיבוב התמונה בהתאם לכיוון של חיישן המצלמה. הם גם מניחים שהסיבוב של היעד מוגדר לסיבוב של המסך.

דוגמה 1: החיישן מסובב ב-90 מעלות

דוגמה למכשיר: Pixel 3 XL

סיבוב המסך = 0
כיוון המסך = לאורך
סיבוב התמונה = 90

סיבוב המסך = 90
כיוון המסך = לרוחב
סיבוב התמונה = 0

דוגמה 2: החיישן מסובב ב-270 מעלות

דוגמה למכשיר: Nexus 5X

סיבוב המסך = 0
כיוון המסך = לאורך
סיבוב התמונה = 270

סיבוב המסך = 90
כיוון המסך = לרוחב
סיבוב התמונה = 180

דוגמה 3: החיישן מסובב ב-0 מעלות

דוגמה למכשיר: Pixel C (טאבלט)

סיבוב המסך = 0
כיוון המסך = לרוחב
סיבוב התמונה = 0

סיבוב המסך = 270
כיוון המסך = לאורך
סיבוב התמונה = 90

חישוב סיבוב התמונה

ImageAnalysis

‫Analyzer של ImageAnalysis מקבל תמונות מהמצלמה בפורמט ImageProxy. כל תמונה מכילה מידע על סיבוב, שאפשר לגשת אליו דרך:

val rotation = imageProxy.imageInfo.rotationDegrees

הערך הזה מייצג את מספר המעלות שבהן צריך לסובב את התמונה בכיוון השעון כדי להתאים לסיבוב היעד של ImageAnalysis. בהקשר של אפליקציה ל-Android, כיוון היעד של ImageAnalysis בדרך כלל תואם לכיוון המסך.

ImageCapture

קריאה חוזרת (callback) מצורפת למכונה של ImageCapture כדי לאותת כשתוצאת הצילום מוכנה. התוצאה יכולה להיות התמונה שצולמה או שגיאה.

כשמצלמים תמונה, ה-callback שסופק יכול להיות אחד מהסוגים הבאים:

  • ‫OnImageCapturedCallback: מקבל תמונה עם גישה בזיכרון בצורת ImageProxy.
  • ‫OnImageSavedCallback: מופעל כשהתמונה שצולמה נשמרה בהצלחה במיקום שצוין על ידי ImageCapture.OutputFileOptions. האפשרויות יכולות לציין File, OutputStream או מיקום ב-MediaStore.

הסיבוב של התמונה שצולמה, בלי קשר לפורמט שלה (ImageProxy, File, OutputStream, MediaStore Uri), מייצג את מעלות הסיבוב שבהן צריך לסובב את התמונה שצולמה בכיוון השעון כדי להתאים לסיבוב היעד של ImageCapture. בהקשר של אפליקציה ל-Android, הסיבוב הזה בדרך כלל יתאים לכיוון המסך.

כדי לאחזר את סיבוב התמונה שצולמה, אפשר להשתמש באחת מהדרכים הבאות:

ImageProxy

val rotation = imageProxy.imageInfo.rotationDegrees

File

val exif = Exif.createFromFile(file)
val rotation = exif.rotation

OutputStream

val byteArray = outputStream.toByteArray()
val exif = Exif.createFromInputStream(ByteArrayInputStream(byteArray))
val rotation = exif.rotation

MediaStore uri

val inputStream = contentResolver.openInputStream(outputFileResults.savedUri)
val exif = Exif.createFromInputStream(inputStream)
val rotation = exif.rotation

אימות סיבוב התמונה

תרחישי השימוש ImageAnalysis ו-ImageCapture מקבלים ImageProxy מהמצלמה אחרי בקשת צילום מוצלחת. ImageProxy כולל תמונה ומידע עליה, כולל הסיבוב שלה. המידע הזה מייצג את מספר המעלות שבהן צריך לסובב את התמונה כדי להתאים אותה לזווית הסיבוב הרצויה.

תהליך אימות של סיבוב תמונה

הנחיות לסיבוב היעד של ImageCapture/ImageAnalysis

מכיוון שהרבה מכשירים לא מסתובבים לתצוגה לאורך הפוכה או לתצוגה לרוחב הפוכה כברירת מחדל, חלק מהאפליקציות ל-Android לא תומכות בכיוונים האלה. אם האפליקציה תומכת בזה או לא, זה משנה את האופן שבו אפשר לעדכן את סיבוב היעד של תרחישי השימוש.

בטבלאות הבאות מוסבר איך לסנכרן את כיוון היעד של תרחישי השימוש עם כיוון המסך. הראשונה מראה איך לעשות את זה תוך תמיכה בכל ארבעת הכיוונים, והשנייה מטפלת רק בכיוונים שהמכשיר מסתובב אליהם כברירת מחדל.

כדי לבחור אילו הנחיות ליישם באפליקציה:

  1. בודקים אם כיוון הצילום של המצלמה באפליקציה Activity נעול או לא, או אם הוא מבטל שינויים בהגדרות של כיוון הצילום.

  2. מחליטים אם המצלמה של האפליקציה Activity צריכה לטפל בכל ארבעת כיווני המכשיר (לאורך, לאורך הפוך, לרוחב ולרוחב הפוך), או אם היא צריכה לטפל רק בכיוונים שהמכשיר שהיא פועלת בו תומך בהם כברירת מחדל.

תמיכה בכל ארבעת הכיוונים

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

תרחיש הנחיות מצב חלון יחיד מצב מסך מפוצל עם ריבוי חלונות
כיוון לא נעול מגדירים את תרחישי השימוש בכל פעם שנוצר Activity, למשל בקריאה החוזרת (callback) של onCreate() ב-Activity.
משתמשים בonOrientationChanged() של OrientationEventListener. בתוך ה-callback, מעדכנים את סיבוב היעד של תרחישי השימוש. כך מטפלים במקרים שבהם המערכת לא יוצרת מחדש את ה-Activity גם אחרי שינוי כיוון, למשל כשמסובבים את המכשיר ב-180 מעלות. הוא גם מטפל במקרים שבהם המסך נמצא בכיוון לאורך הפוך והמכשיר לא מסתובב לאורך הפוך כברירת מחדל. הוא גם מטפל במקרים שבהם ה-Activity לא נוצר מחדש כשהמכשיר מסתובב (למשל, ב-90 מעלות). זה קורה במכשירים עם גורם צורה קטן כשהאפליקציה תופסת חצי מהמסך, ובמכשירים גדולים יותר כשהאפליקציה תופסת שני שלישים מהמסך.
אופציונלי: מגדירים את המאפיין screenOrientation של Activity לערך fullSensor בקובץ AndroidManifest. כך ממשק המשתמש יכול להיות במצב אנכי כשהמכשיר במצב לאורך הפוך, וניתן ליצור מחדש את Activity על ידי המערכת בכל פעם שהמכשיר מסובב ב-90 מעלות. אין להגדרה הזו השפעה על מכשירים שלא מסתובבים לאורך הפוך כברירת מחדל. אין תמיכה במצב ריבוי חלונות כשהמסך בכיוון לאורך הפוך.
כיוון נעול מגדירים את תרחישי השימוש רק פעם אחת, כשה-Activity נוצר בפעם הראשונה, למשל בקריאה החוזרת (callback) של onCreate() ב-Activity.
משתמשים בonOrientationChanged() של OrientationEventListener. בתוך ה-callback, מעדכנים את סיבוב היעד של תרחישי השימוש, חוץ מהתצוגה המקדימה. הוא גם מטפל במקרים שבהם ה-Activity לא נוצר מחדש כשהמכשיר מסתובב (למשל, ב-90 מעלות). זה קורה במכשירים עם גורם צורה קטן כשהאפליקציה תופסת חצי מהמסך, ובמכשירים גדולים יותר כשהאפליקציה תופסת שני שלישים מהמסך.
הגדרת configChanges של הכיוון בוטלה מגדירים את תרחישי השימוש רק פעם אחת, כשה-Activity נוצר בפעם הראשונה, למשל בקריאה החוזרת (callback) של onCreate() ב-Activity.
משתמשים בonOrientationChanged() של OrientationEventListener. בתוך הקריאה החוזרת (callback), מעדכנים את סיבוב היעד של תרחישי השימוש. הוא גם מטפל במקרים שבהם ה-Activity לא נוצר מחדש כשהמכשיר מסתובב (למשל, ב-90 מעלות). זה קורה במכשירים עם גורם צורה קטן כשהאפליקציה תופסת חצי מהמסך, ובמכשירים גדולים יותר כשהאפליקציה תופסת שני שלישים מהמסך.
אופציונלי: מגדירים את המאפיין screenOrientation של הפעילות ל-fullSensor בקובץ AndroidManifest. מאפשרת לממשק המשתמש להיות זקוף כשהמכשיר במצב לאורך הפוך. אין להגדרה הזו השפעה על מכשירים שלא מסתובבים לאורך הפוך כברירת מחדל. אי אפשר להשתמש במצב ריבוי חלונות כשהמסך בכיוון לאורך הפוך.

תמיכה רק בכיווני מסך שנתמכים במכשיר

תמיכה רק בכיוונים שהמכשיר תומך בהם כברירת מחדל (יכול להיות שהם כוללים או לא כוללים כיוון לאורך הפוך או לרוחב הפוך).

תרחיש הנחיות מצב מסך מפוצל עם ריבוי חלונות
כיוון לא נעול מגדירים את תרחישי השימוש בכל פעם שנוצר Activity, למשל בקריאה החוזרת (callback) של onCreate() ב-Activity.
משתמשים בonDisplayChanged() של DisplayListener. בתוך פונקציית ה-callback, מעדכנים את סיבוב היעד של תרחישי השימוש, למשל כשהמכשיר מסובב ב-180 מעלות. הוא גם מטפל במקרים שבהם ה-Activity לא נוצר מחדש כשהמכשיר מסתובב (למשל, ב-90 מעלות). זה קורה במכשירים עם גורם צורה קטן כשהאפליקציה תופסת חצי מהמסך, ובמכשירים גדולים יותר כשהאפליקציה תופסת שני שלישים מהמסך.
כיוון נעול מגדירים את תרחישי השימוש רק פעם אחת, כשה-Activity נוצר בפעם הראשונה, למשל בקריאה החוזרת (callback) של onCreate() ב-Activity.
משתמשים בonOrientationChanged() של OrientationEventListener. בתוך הקריאה החוזרת (callback), מעדכנים את סיבוב היעד של תרחישי השימוש. הוא גם מטפל במקרים שבהם ה-Activity לא נוצר מחדש כשהמכשיר מסתובב (למשל, ב-90 מעלות). זה קורה במכשירים עם גורם צורה קטן כשהאפליקציה תופסת חצי מהמסך, ובמכשירים גדולים יותר כשהאפליקציה תופסת שני שלישים מהמסך.
הגדרת configChanges של הכיוון בוטלה מגדירים את תרחישי השימוש רק פעם אחת, כשה-Activity נוצר בפעם הראשונה, למשל בקריאה החוזרת (callback) של onCreate() ב-Activity.
משתמשים בonDisplayChanged() של DisplayListener. בתוך פונקציית ה-callback, מעדכנים את סיבוב היעד של תרחישי השימוש, למשל כשהמכשיר מסובב ב-180 מעלות. הוא גם מטפל במקרים שבהם ה-Activity לא נוצר מחדש כשהמכשיר מסתובב (למשל, ב-90 מעלות). זה קורה במכשירים עם גורם צורה קטן כשהאפליקציה תופסת חצי מהמסך, ובמכשירים גדולים יותר כשהאפליקציה תופסת שני שלישים מהמסך.

כיוון לא נעול

Activity פתוח לשינוי כיוון התצוגה כשהכיוון שלו (למשל, לאורך או לרוחב) תואם לכיוון הפיזי של המכשיר, למעט כיוון הפוך לאורך או לרוחב, שחלק מהמכשירים לא תומכים בו כברירת מחדל. כדי לאלץ את המכשיר להסתובב לכל ארבעת הכיוונים, מגדירים את המאפיין screenOrientation של Activity לערך fullSensor.

במצב ריבוי חלונות, מכשיר שלא תומך כברירת מחדל בפריסה הפוכה לאורך או לרוחב לא יסתובב לפריסה הפוכה לאורך או לרוחב, גם אם המאפיין screenOrientation שלו מוגדר כ-fullSensor.

<!-- The Activity has an unlocked orientation, but might not rotate to reverse
portrait/landscape in single-window mode if the device doesn't support it by
default. -->
<activity android:name=".UnlockedOrientationActivity" />

<!-- The Activity has an unlocked orientation, and will rotate to all four
orientations in single-window mode. -->
<activity
   android:name=".UnlockedOrientationActivity"
   android:screenOrientation="fullSensor" />

כיוון נעול

כיוון המסך נעול כשהוא נשאר באותו כיוון (למשל לאורך או לרוחב) בלי קשר לכיוון הפיזי של המכשיר. כדי לעשות את זה, צריך לציין את המאפיין screenOrientation של Activity בהצהרה שלו בקובץ AndroidManifest.xml.

כשהכיוון של המסך נעול, המערכת לא משמידה ויוצרת מחדש את ה-Activity כשהמכשיר מסתובב.

<!-- The Activity keeps a portrait orientation even as the device rotates. -->
<activity
   android:name=".LockedOrientationActivity"
   android:screenOrientation="portrait" />

שינויים בהגדרות הכיוון בוטלו

כשהמערכת מבטלת את השינויים בהגדרות הכיוון של Activity, היא לא משמידה ויוצרת אותו מחדש כשהכיוון הפיזי של המכשיר משתנה. עם זאת, המערכת מעדכנת את ממשק המשתמש בהתאם לכיוון הפיזי של המכשיר.

<!-- The Activity's UI might not rotate in reverse portrait/landscape if the
device doesn't support it by default. -->
<activity
   android:name=".OrientationConfigChangesOverriddenActivity"
   android:configChanges="orientation|screenSize" />

<!-- The Activity's UI will rotate to all 4 orientations in single-window
mode. -->
<activity
   android:name=".OrientationConfigChangesOverriddenActivity"
   android:configChanges="orientation|screenSize"
   android:screenOrientation="fullSensor" />

הגדרת תרחישים לדוגמה של המצלמה

בתרחישים שתוארו למעלה, אפשר להגדיר את תרחישי השימוש במצלמה כשיוצרים את ה-Activity בפעם הראשונה.

במקרה של Activity עם כיוון לא נעול, ההגדרה הזו מתבצעת בכל פעם שמסובבים את המכשיר, כי המערכת משמידה ויוצרת מחדש את ה-Activity בשינויי כיוון. כתוצאה מכך, תרחישי השימוש מגדירים את סיבוב היעד כך שיתאים לכיוון התצוגה כברירת מחדל בכל פעם.

במקרה של Activity עם כיוון נעול או כזה שמבטל שינויים בהגדרות הכיוון, ההגדרה הזו מתבצעת פעם אחת, כשה-Activity נוצר בפעם הראשונה.

class CameraActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val cameraProcessFuture = ProcessCameraProvider.getInstance(this)
        cameraProcessFuture.addListener(
            Runnable {
                val cameraProvider = cameraProcessFuture.get()

                // By default, the use cases set their target rotation to match the
                // display’s rotation.
                val preview = buildPreview()
                val imageAnalysis = buildImageAnalysis()
                val imageCapture = buildImageCapture()

                cameraProvider.bindToLifecycle(
                    this, cameraSelector, preview, imageAnalysis, imageCapture
                )
            },
            mainExecutor
        )
    }
}

הגדרת OrientationEventListener

שימוש ב-OrientationEventListener מאפשר לעדכן באופן רציף את סיבוב היעד של תרחישי השימוש במצלמה כשהכיוון של המכשיר משתנה.

class CameraActivity : AppCompatActivity() {

    private val orientationEventListener by lazy {
        object : OrientationEventListener(this) {
            override fun onOrientationChanged(orientation: Int) {
                if (orientation == ORIENTATION_UNKNOWN) {
                    return
                }

                val rotation = when (orientation) {
                     in 45 until 135 -> Surface.ROTATION_270
                     in 135 until 225 -> Surface.ROTATION_180
                     in 225 until 315 -> Surface.ROTATION_90
                     else -> Surface.ROTATION_0
                 }

                 imageAnalysis.targetRotation = rotation
                 imageCapture.targetRotation = rotation
            }
        }
    }

    override fun onStart() {
        super.onStart()
        orientationEventListener.enable()
    }

    override fun onStop() {
        super.onStop()
        orientationEventListener.disable()
    }
}

הגדרת DisplayListener

שימוש ב-DisplayListener מאפשר לעדכן את סיבוב היעד של תרחישי השימוש במצלמה במצבים מסוימים, למשל כשהמערכת לא משמידה ויוצרת מחדש את ה-Activity אחרי שהמכשיר מסתובב ב-180 מעלות.

class CameraActivity : AppCompatActivity() {

    private val displayListener = object : DisplayManager.DisplayListener {
        override fun onDisplayChanged(displayId: Int) {
            if (rootView.display.displayId == displayId) {
                val rotation = rootView.display.rotation
                imageAnalysis.targetRotation = rotation
                imageCapture.targetRotation = rotation
            }
        }

        override fun onDisplayAdded(displayId: Int) {
        }

        override fun onDisplayRemoved(displayId: Int) {
        }
    }

    override fun onStart() {
        super.onStart()
        val displayManager = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
        displayManager.registerDisplayListener(displayListener, null)
    }

    override fun onStop() {
        super.onStop()
        val displayManager = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
        displayManager.unregisterDisplayListener(displayListener)
    }
}