בנושא הזה מוסבר איך להגדיר תרחישי שימוש של CameraX באפליקציה כדי לקבל תמונות עם מידע נכון על סיבוב, בין אם הן מתרחיש השימוש ImageAnalysis או ImageCapture. כך:
- ה-
Analyzerשל תרחיש השימושImageAnalysisצריך לקבל פריימים עם הסיבוב הנכון. - תרחיש השימוש
ImageCaptureאמור לצלם תמונות עם הסיבוב הנכון.
הסברים על המונחים
בנושא הזה נעשה שימוש במונחים הבאים, ולכן חשוב להבין את המשמעות של כל אחד מהם:
- כיוון המסך
- הכוונה היא לאיזה צד של המכשיר פונה כלפי מעלה, ויכול להיות אחד מארבעה ערכים: לאורך, לרוחב, לאורך הפוך או לרוחב הפוך.
- סיבוב מסך
- זה הערך שמוחזר על ידי
Display.getRotation(), והוא מייצג את המעלות שבהן המכשיר מסובב נגד כיוון השעון מהכיוון הטבעי שלו. - סיבוב היעד
- הערך הזה מייצג את מספר המעלות שבהן צריך לסובב את המכשיר בכיוון השעון כדי להגיע לאוריינטציה הטבעית שלו.
איך לקבוע את כיוון הסיבוב הרצוי
הדוגמאות הבאות מראות איך לקבוע את סיבוב היעד של מכשיר על סמך הכיוון הטבעי שלו.
דוגמה 1: כיוון טבעי לאורך
| דוגמה למכשיר: Pixel 3 XL | |
|---|---|
|
כיוון טבעי = לאורך סיבוב המסך = 0 |
|
|
כיוון טבעי = לאורך סיבוב המסך = 90 |
|
דוגמה 2: כיוון טבעי לרוחב
| דוגמה למכשיר: Pixel C | |
|---|---|
|
כיוון טבעי = לרוחב סיבוב המסך = 0 |
|
|
כיוון טבעי = לרוחב סיבוב המסך = 270 |
|
סיבוב תמונה
איזה צד הוא למעלה? כיוון החיישן מוגדר ב-Android כערך קבוע, שמייצג את המעלות (0, 90, 180, 270) שבהן החיישן מסובב מהחלק העליון של המכשיר כשהמכשיר נמצא במיקום טבעי. בכל המקרים שמוצגים בתרשימים, סיבוב התמונה מתאר את האופן שבו צריך לסובב את הנתונים בכיוון השעון כדי שהתמונה תופיע בצורה אנכית.
בדוגמאות הבאות מוצג סיבוב התמונה בהתאם לכיוון של חיישן המצלמה. הם גם מניחים שהסיבוב של היעד מוגדר לסיבוב של המסך.
דוגמה 1: החיישן מסובב ב-90 מעלות
| דוגמה למכשיר: Pixel 3 XL | |
|---|---|
|
סיבוב המסך = 0 |
|
|
סיבוב המסך = 90 |
|
דוגמה 2: החיישן מסובב ב-270 מעלות
| דוגמה למכשיר: Nexus 5X | |
|---|---|
|
סיבוב המסך = 0 |
|
|
סיבוב המסך = 90 |
|
דוגמה 3: החיישן מסובב ב-0 מעלות
| דוגמה למכשיר: Pixel C (טאבלט) | |
|---|---|
|
סיבוב המסך = 0 |
|
|
סיבוב המסך = 270 |
|
חישוב סיבוב התמונה
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 לא תומכות בכיוונים האלה. אם האפליקציה תומכת בזה או לא, זה משנה את האופן שבו אפשר לעדכן את סיבוב היעד של תרחישי השימוש.
בטבלאות הבאות מוסבר איך לסנכרן את כיוון היעד של תרחישי השימוש עם כיוון המסך. הראשונה מראה איך לעשות את זה תוך תמיכה בכל ארבעת הכיוונים, והשנייה מטפלת רק בכיוונים שהמכשיר מסתובב אליהם כברירת מחדל.
כדי לבחור אילו הנחיות ליישם באפליקציה:
בודקים אם כיוון הצילום של המצלמה באפליקציה
Activityנעול או לא, או אם הוא מבטל שינויים בהגדרות של כיוון הצילום.מחליטים אם המצלמה של האפליקציה
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) } }