CameraX kullanım alanı döndürmeleri

Bu konuda, ImageAnalysis veya ImageCapture kullanım alanından doğru rotasyon bilgileriyle resim almak için uygulamanızda CameraX kullanım alanlarını nasıl ayarlayacağınız gösterilmektedir. Bu durumda:

  • ImageAnalysis kullanım alanının Analyzer, doğru dönüşe sahip kareler almalıdır.
  • ImageCapture kullanım alanı, resimleri doğru döndürme açısıyla çekmelidir.

Terminoloji

Bu konuda aşağıdaki terminoloji kullanıldığından her bir terimin ne anlama geldiğini anlamak önemlidir:

Ekran yönü
Bu, cihazın hangi tarafının yukarı baktığını gösterir ve şu dört değerden biri olabilir: dikey, yatay, ters dikey veya ters yatay.
Ekran döndürme
Bu, Display.getRotation() tarafından döndürülen değerdir ve cihazın doğal yönünden saat yönünün tersine döndürüldüğü dereceyi temsil eder.
Hedef rotasyon
Bu, cihazın doğal yönüne ulaşması için saat yönünde döndürülmesi gereken derece sayısını gösterir.

Hedef rotasyonu belirleme

Aşağıdaki örneklerde, bir cihazın doğal yönüne göre hedef dönüşünün nasıl belirleneceği gösterilmektedir.

1. örnek: Doğal dikey yön

Cihaz örneği: Pixel 3 XL

Doğal yön = Dikey
Mevcut yön = Dikey

Ekran döndürme = 0
Hedef döndürme = 0

Doğal yön = Dikey
Mevcut yön = Yatay

Ekran döndürme = 90
Hedef döndürme = 90

2. örnek: Yatay doğal yön

Cihaz örneği: Pixel C

Doğal yön = Yatay
Mevcut yön = Yatay

Ekran döndürme = 0
Hedef döndürme = 0

Doğal yön = Yatay
Mevcut yön = Dikey

Ekran döndürme = 270
Hedef döndürme = 270

Resim döndürme

Hangi taraf yukarıda? Sensör yönü, Android'de sabit bir değer olarak tanımlanır. Bu değer, cihaz doğal konumdayken sensörün cihazın üst kısmından döndürüldüğü dereceyi (0, 90, 180, 270) temsil eder. Diyagramlardaki tüm durumlarda, resim döndürme, verilerin dik görünmesi için saat yönünde nasıl döndürülmesi gerektiğini açıklar.

Aşağıdaki örneklerde, kamera sensörünün yönüne bağlı olarak resim döndürmenin nasıl olması gerektiği gösterilmektedir. Ayrıca hedef dönüşün ekran dönüşüne ayarlandığını varsayarlar.

1. örnek: Sensör 90 derece döndürülmüş

Cihaz örneği: Pixel 3 XL

Ekran döndürme = 0
Ekran yönü = Dikey
Resim döndürme = 90

Ekran döndürme = 90
Ekran yönü = Yatay
Resim döndürme = 0

2. örnek: Sensör 270 derece döndürülmüş

Cihaz örneği: Nexus 5X

Ekran döndürme = 0
Ekran yönü = Dikey
Resim döndürme = 270

Ekran döndürme = 90
Ekran yönü = Yatay
Resim döndürme = 180

3. örnek: Sensör 0 derece döndürülmüş

Cihaz örneği: Pixel C (Tablet)

Ekran döndürme = 0
Ekran yönü = Yatay
Resim döndürme = 0

Ekran döndürme = 270
Ekran yönü = Dikey
Resim döndürme = 90

Resmin dönüşü hesaplanıyor

ImageAnalysis

ImageAnalysis adlı kullanıcının Analyzer cihazı, kameradan ImageProxy biçiminde resimler alır. Her resim, aşağıdaki yöntemlerle erişilebilen döndürme bilgileri içerir:

val rotation = imageProxy.imageInfo.rotationDegrees

Bu değer, resmin ImageAnalysis hedef dönüşüyle eşleşmesi için saat yönünde döndürülmesi gereken dereceyi gösterir. Android uygulaması bağlamında, ImageAnalysis öğesinin hedef dönüşü genellikle ekranın yönüyle eşleşir.

ImageCapture

Bir yakalama sonucunun hazır olduğunu bildirmek için ImageCapture örneğine bir geri çağırma eklenir. Sonuç, yakalanan görüntü veya bir hata olabilir.

Fotoğraf çekerken sağlanan geri çağırma aşağıdaki türlerden biri olabilir:

  • OnImageCapturedCallback: Bellek içi erişime sahip bir resmi ImageProxy biçiminde alır.
  • OnImageSavedCallback: Yakalanan resim, ImageCapture.OutputFileOptions tarafından belirtilen konuma başarıyla kaydedildiğinde çağrılır. Seçenekler bir File, OutputStream veya MediaStore konumunu belirtebilir.

Yakalanan görüntünün dönüşü, biçiminden (ImageProxy, File, OutputStream, MediaStore Uri) bağımsız olarak, yakalanan görüntünün ImageCapture'nin hedef dönüşüyle eşleşmesi için saat yönünde döndürülmesi gereken dönüş derecelerini temsil eder. Bu, Android uygulaması bağlamında genellikle ekranın yönüyle eşleşir.

Çekilen görüntünün dönüşü aşağıdaki yöntemlerden biriyle alınabilir:

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

Resmin yönünü doğrulama

ImageAnalysis ve ImageCapture kullanım alanları, başarılı bir yakalama isteğinden sonra kameradan ImageProxy alır. ImageProxy, bir resmi ve dönüşü de dahil olmak üzere resimle ilgili bilgileri sarmalar. Bu döndürme bilgisi, kullanım alanının hedef döndürme açısıyla eşleşmesi için resmin kaç derece döndürülmesi gerektiğini gösterir.

Bir resmin döndürme doğrulama akışı

ImageCapture/ImageAnalysis hedef döndürme yönergeleri

Birçok cihaz varsayılan olarak ters dikey veya ters yatay yöne dönmediğinden bazı Android uygulamaları bu yönleri desteklemez. Bir uygulamanın bunu destekleyip desteklememesi, kullanım alanlarının hedef rotasyonunun güncellenme şeklini değiştirir.

Aşağıdaki iki tabloda, kullanım alanlarının hedef rotasyonunun ekran rotasyonuyla nasıl senkronize edileceği açıklanmaktadır. İlk örnekte, dört yönün de desteklendiği bir senaryo, ikinci örnekte ise yalnızca cihazın varsayılan olarak döndürüldüğü yönlerin desteklendiği bir senaryo gösterilmektedir.

Uygulamanızda hangi kurallara uyulacağını seçmek için:

  1. Uygulamanızın kamerasının Activity yönünün kilitli mi yoksa kilitsiz mi olduğunu ya da yön yapılandırması değişikliklerini geçersiz kılıp kılmadığını doğrulayın.

  2. Uygulamanızın kamerasının Activity dört cihaz yönünü de (dikey, ters dikey, yatay ve ters yatay) destekleyip desteklemeyeceğine veya yalnızca çalıştığı cihazın varsayılan olarak desteklediği yönleri destekleyip desteklemeyeceğine karar verin.

Dört yönü de destekleme

Bu tabloda, cihazın ters dikey yöne dönmediği durumlarda uyulması gereken belirli kurallar belirtilmiştir. Aynı durum, ters yatay konuma dönmeyen cihazlar için de geçerlidir.

Senaryo Kurallar Tek pencere modu Çoklu pencere bölünmüş ekran modu
Kilidi açılmış yönlendirme Activity her oluşturulduğunda kullanım alanlarını ayarlayın (ör. Activity'nin onCreate() geri çağırma işlevinde).
OrientationEventListener'ın onOrientationChanged() özelliğini kullanın. Geri çağırma işlevinde, kullanım alanlarının hedef dönüşünü güncelleyin. Bu, sistemin yön değişikliğinden sonra bile Activity öğesini yeniden oluşturmadığı durumları (ör. cihaz 180 derece döndürüldüğünde) ele alır. Ayrıca ekran ters dikey yöndeyken ve cihaz varsayılan olarak ters dikey yöne dönmediğinde de kullanılır. Ayrıca, cihaz döndürüldüğünde (örneğin, 90 derece) Activity öğesinin yeniden oluşturulmadığı durumları da ele alır. Bu durum, küçük form faktörlü cihazlarda uygulama ekranın yarısını kapladığında, daha büyük cihazlarda ise uygulama ekranın üçte ikisini kapladığında gerçekleşir.
İsteğe bağlı: AndroidManifest dosyasında Activity öğesinin screenOrientation özelliğini fullSensor olarak ayarlayın. Bu sayede, cihaz ters dikey konumdayken kullanıcı arayüzü dik durur ve cihaz 90 derece döndürüldüğünde Activity sistem tarafından yeniden oluşturulur. Varsayılan olarak ters dikey yöne döndürülmeyen cihazları etkilemez. Ekran ters dikey yöndeyken çoklu pencere modu desteklenmez.
Kilitli yön Kullanım alanlarını yalnızca bir kez, Activity ilk oluşturulduğunda (ör. Activity'in onCreate() geri çağırma işlevinde) ayarlayın.
OrientationEventListener'ın onOrientationChanged() özelliğini kullanın. Geri çağırma işlevinde, Önizleme dışındaki kullanım alanlarının hedef dönüşünü güncelleyin. Ayrıca, cihaz döndürüldüğünde (örneğin, 90 derece) Activity öğesinin yeniden oluşturulmadığı durumları da ele alır. Bu durum, küçük form faktörlü cihazlarda uygulama ekranın yarısını kapladığında, daha büyük cihazlarda ise uygulama ekranın üçte ikisini kapladığında gerçekleşir.
Yön configChanges geçersiz kılındı Kullanım alanlarını yalnızca bir kez, Activity ilk oluşturulduğunda (ör. Activity'in onCreate() geri çağırma işlevinde) ayarlayın.
OrientationEventListener'ın onOrientationChanged() özelliğini kullanın. Geri çağırma işlevinde, kullanım alanlarının hedef dönüşünü güncelleyin. Ayrıca, cihaz döndürüldüğünde (örneğin, 90 derece) Activity öğesinin yeniden oluşturulmadığı durumları da ele alır. Bu durum, küçük form faktörlü cihazlarda uygulama ekranın yarısını kapladığında, daha büyük cihazlarda ise uygulama ekranın üçte ikisini kapladığında gerçekleşir.
İsteğe bağlı: AndroidManifest dosyasında etkinliğin screenOrientation özelliğini fullSensor olarak ayarlayın. Cihaz ters dikey konumdayken kullanıcı arayüzünün dik olmasını sağlar. Varsayılan olarak ters dikey yöne döndürülmeyen cihazları etkilemez. Ekran ters dikey yöndeyken çoklu pencere modu desteklenmez.

Yalnızca cihaz tarafından desteklenen yönleri destekleme

Yalnızca cihazın varsayılan olarak desteklediği yönleri destekleyin (ters dikey/ters yatay yönleri içerebilir veya içermeyebilir).

Senaryo Kurallar Çoklu pencere bölünmüş ekran modu
Kilidi açılmış yönlendirme Activity her oluşturulduğunda kullanım alanlarını ayarlayın (ör. Activity'nin onCreate() geri çağırma işlevinde).
DisplayListener'ın onDisplayChanged() özelliğini kullanın. Geri çağırma işlevinde, kullanım alanlarının hedef rotasyonunu güncelleyin (ör. cihaz 180 derece döndürüldüğünde). Ayrıca, cihaz döndürüldüğünde (örneğin, 90 derece) Activity öğesinin yeniden oluşturulmadığı durumları da ele alır. Bu durum, küçük form faktörlü cihazlarda uygulama ekranın yarısını kapladığında, daha büyük cihazlarda ise uygulama ekranın üçte ikisini kapladığında gerçekleşir.
Kilitli yön Kullanım alanlarını yalnızca bir kez, Activity ilk oluşturulduğunda (ör. Activity'in onCreate() geri çağırma işlevinde) ayarlayın.
OrientationEventListener'ın onOrientationChanged() özelliğini kullanın. Geri çağırma işlevinde, kullanım alanlarının hedef dönüşünü güncelleyin. Ayrıca, cihaz döndürüldüğünde (örneğin, 90 derece) Activity öğesinin yeniden oluşturulmadığı durumları da ele alır. Bu durum, küçük form faktörlü cihazlarda uygulama ekranın yarısını kapladığında, daha büyük cihazlarda ise uygulama ekranın üçte ikisini kapladığında gerçekleşir.
Yön configChanges geçersiz kılındı Kullanım alanlarını yalnızca bir kez, Activity ilk oluşturulduğunda (ör. Activity'in onCreate() geri çağırma işlevinde) ayarlayın.
DisplayListener'ın onDisplayChanged() özelliğini kullanın. Geri çağırma işlevinde, cihaz 180 derece döndürüldüğünde olduğu gibi kullanım alanlarının hedef dönüşünü güncelleyin. Ayrıca, cihaz döndürüldüğünde (örneğin, 90 derece) Activity öğesinin yeniden oluşturulmadığı durumları da ele alır. Bu durum, küçük form faktörlü cihazlarda uygulama ekranın yarısını kapladığında, daha büyük cihazlarda ise uygulama ekranın üçte ikisini kapladığında gerçekleşir.

Kilidi açılmış yön

Bir Activity, ekran yönü (dikey veya yatay gibi) cihazın fiziksel yönüyle eşleştiğinde kilitli olmayan bir yöne sahiptir. Bazı cihazların varsayılan olarak desteklemediği ters dikey/yatay yönler bu kuralın dışındadır. Cihazı dört yöne de dönmeye zorlamak için Activity öğesinin screenOrientation özelliğini fullSensor olarak ayarlayın.

Çoklu pencere modunda, varsayılan olarak ters dikey/yatay modu desteklemeyen bir cihaz, screenOrientation özelliği fullSensor olarak ayarlanmış olsa bile ters dikey/yatay moda dönmez.

<!-- 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" />

Kilitli yön

Bir ekran, cihazın fiziksel yönünden bağımsız olarak aynı ekran yönünde (ör. dikey veya yatay) kaldığında kilitli bir yöne sahip olur. Bu işlem, AndroidManifest.xml dosyasındaki bildiriminde bir Activity öğesinin screenOrientation özelliğini belirterek yapılabilir.

Ekranın yönü kilitliyse sistem, cihaz döndürüldüğünde Activity öğesini yok edip yeniden oluşturmaz.

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

Yön yapılandırması değişiklikleri geçersiz kılındı

Bir Activity, yön yapılandırması değişikliklerini geçersiz kıldığında sistem, cihazın fiziksel yönü değiştiğinde bunu yok edip yeniden oluşturmaz. Ancak sistem, kullanıcı arayüzünü cihazın fiziksel yönüne uyacak şekilde günceller.

<!-- 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" />

Kamera kullanım alanları kurulumu

Yukarıda açıklanan senaryolarda, kamera kullanım alanları Activity ilk oluşturulduğunda ayarlanabilir.

Yönü kilitli olmayan bir Activity söz konusu olduğunda, sistem yön değişikliklerinde Activity öğesini yok edip yeniden oluşturduğundan bu kurulum, cihaz her döndürüldüğünde yapılır. Bu durum, kullanım alanlarının hedef dönüşlerini her seferinde varsayılan olarak ekranın yönüyle eşleşecek şekilde ayarlamasına neden olur.

Yönü kilitli olan veya yön yapılandırması değişikliklerini geçersiz kılan bir Activity söz konusu olduğunda bu kurulum, Activity ilk oluşturulduğunda bir kez yapılır.

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 kurulumu

OrientationEventListener kullanmak, cihazın yönü değiştikçe kamera kullanım alanlarının hedef dönüşünü sürekli olarak güncellemenize olanak tanır.

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 kurulumu

DisplayListener kullanarak, belirli durumlarda kamera kullanım alanlarının hedef dönüşünü güncelleyebilirsiniz. Örneğin, cihaz 180 derece döndükten sonra sistem Activity öğesini yok edip yeniden oluşturmaz.

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)
    }
}