Rotacja przypadków użycia w aplikacji CameraX

W tym temacie pokazujemy, jak skonfigurować przypadki użycia CameraX w aplikacji, aby uzyskiwać obrazy z prawidłową informacją o obrocie, niezależnie od tego, czy pochodzą one z przypadku użycia ImageAnalysis czy ImageCapture. A więc:

  • Przypadek użycia ImageAnalysis (Analyzer) powinien otrzymywać klatki z prawidłowym obrotem.
  • Przypadek użycia ImageCapture powinien robić zdjęcia z prawidłowym obrotem.

Terminologia

W tym temacie używamy poniższych terminów, dlatego ważne jest, aby zrozumieć, co oznacza każdy z nich:

Orientacja wyświetlacza
Określa, która strona urządzenia jest skierowana do góry. Może mieć jedną z 4 wartości: pionowa, pozioma, odwrócona pionowa lub odwrócona pozioma.
Obrót obrazu
Jest to wartość zwracana przez Display.getRotation() i reprezentuje stopnie, o które urządzenie jest obrócone w lewo względem swojej naturalnej orientacji.
Rotacja docelowa
Wartość ta określa liczbę stopni, o jaką należy obrócić urządzenie zgodnie z ruchem wskazówek zegara, aby uzyskać jego naturalną orientację.

Jak określić docelową rotację

Poniższe przykłady pokazują, jak określić docelowy obrót urządzenia na podstawie jego naturalnej orientacji.

Przykład 1. Orientacja pionowa jako naturalna

Przykładowe urządzenie: Pixel 3 XL

Orientacja naturalna = pionowa
Orientacja bieżąca = pionowa

Obrót obrazu = 0
Obrót docelowy = 0

Orientacja naturalna = pionowa
Orientacja bieżąca = pozioma

Obrót obrazu = 90
Obrót docelowy = 90

Przykład 2. Naturalna orientacja pozioma

Przykładowe urządzenie: Pixel C

Orientacja naturalna = pozioma
Bieżąca orientacja = pozioma

Obrót obrazu = 0
Obrót docelowy = 0

Orientacja naturalna = pozioma
Bieżąca orientacja = pionowa

Obrót obrazu = 270
Obrót docelowy = 270

Obrót obrazu

Która strona jest górna? Orientacja czujnika jest zdefiniowana w Androidzie jako stała wartość, która reprezentuje stopnie (0, 90, 180, 270), o które czujnik jest obrócony względem górnej części urządzenia, gdy urządzenie jest w pozycji naturalnej. We wszystkich przypadkach na diagramach obrót obrazu określa, jak należy obrócić dane zgodnie z ruchem wskazówek zegara, aby były wyświetlane w pionie.

Poniższe przykłady pokazują, jak należy obrócić obraz w zależności od orientacji czujnika aparatu. Zakładają też, że obrót docelowy jest ustawiony na obrót wyświetlacza.

Przykład 1. Czujnik obrócony o 90 stopni

Przykładowe urządzenie: Pixel 3 XL

Obrót obrazu = 0
Orientacja wyświetlacza = pionowa
Obrót obrazu = 90

Obrót obrazu = 90
Orientacja wyświetlacza = pozioma
Obrót obrazu = 0

Przykład 2. Czujnik obrócony o 270 stopni

Przykładowe urządzenie: Nexus 5X

Obrót obrazu = 0
Orientacja wyświetlacza = pionowa
Obrót obrazu = 270

Obrót obrazu = 90
Orientacja wyświetlacza = pozioma
Obrót obrazu = 180

Przykład 3. Czujnik obrócony o 0 stopni

Przykładowe urządzenie: Pixel C (tablet)

Obrót obrazu = 0
Orientacja wyświetlacza = pozioma
Obrót obrazu = 0

Obrót obrazu = 270
Orientacja wyświetlacza = pionowa
Obrót obrazu = 90

Obliczanie obrotu obrazu

ImageAnalysis

Analyzer firmy ImageAnalysis otrzymuje obrazy z kamery w formie ImageProxy. Każdy obraz zawiera informacje o obrocie, które są dostępne w:

val rotation = imageProxy.imageInfo.rotationDegrees

Ta wartość określa, o ile stopni należy obrócić obraz w prawo, aby dopasować go do docelowego obrotu elementu ImageAnalysis. W kontekście aplikacji na Androida docelowy obrót ImageAnalysis zwykle odpowiada orientacji ekranu.

ImageCapture

Wywołanie zwrotne jest dołączone do instancji ImageCapture, aby sygnalizować, kiedy wynik przechwytywania jest gotowy. Wynikiem może być przechwycony obraz lub błąd.

Podczas robienia zdjęcia podane wywołanie zwrotne może być jednego z tych typów:

  • OnImageCapturedCallback: odbiera obraz z dostępem w pamięci w postaci ImageProxy.
  • OnImageSavedCallback: wywoływane, gdy przechwycony obraz zostanie zapisany w lokalizacji określonej przez ImageCapture.OutputFileOptions. Opcje mogą określać File, OutputStream lub lokalizację w MediaStore.

Obrót przechwyconego obrazu, niezależnie od jego formatu (ImageProxy, File, OutputStream, MediaStore Uri), reprezentuje stopnie obrotu, o które należy obrócić przechwycony obraz zgodnie z ruchem wskazówek zegara, aby dopasować go do docelowego obrotu ImageCapture, który w kontekście aplikacji na Androida zwykle odpowiada orientacji ekranu.

Obrót przechwyconego obrazu można pobrać na jeden z tych sposobów:

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

Sprawdzanie obrotu obrazu

Przypadki użycia ImageAnalysis i ImageCapture otrzymują ImageProxy z kamery po udanym żądaniu przechwycenia. ImageProxy zawiera obraz i informacje o nim, w tym o jego obrocie. Te informacje o obrocie reprezentują stopnie, o które należy obrócić obraz, aby dopasować go do docelowego obrotu w danym przypadku użycia.

Proces weryfikacji obrotu obrazu

Wytyczne dotyczące obrotu docelowego ImageCapture/ImageAnalysis

Wiele urządzeń nie obraca się domyślnie do odwróconej orientacji pionowej ani poziomej, dlatego niektóre aplikacje na Androida nie obsługują tych orientacji. To, czy aplikacja obsługuje tę funkcję, wpływa na sposób aktualizowania docelowego obrotu w przypadkach użycia.

Poniżej znajdują się 2 tabele, które pokazują, jak zsynchronizować docelowy obrót przypadków użycia z obrotem wyświetlacza. Pierwszy pokazuje, jak to zrobić, obsługując wszystkie 4 orientacje, a drugi obsługuje tylko orientacje, do których urządzenie obraca się domyślnie.

Aby wybrać wytyczne, których chcesz przestrzegać w aplikacji:

  1. Sprawdź, czy aparat w aplikacji Activity ma zablokowaną lub odblokowaną orientację albo czy zastępuje zmiany konfiguracji orientacji.

  2. Zdecyduj, czy kamera aplikacji Activity powinna obsługiwać wszystkie 4 orientacje urządzenia (pionową, odwróconą pionową, poziomą i odwróconą poziomą), czy tylko te, które domyślnie obsługuje urządzenie, na którym jest uruchomiona.

Obsługa wszystkich 4 orientacji

W tej tabeli znajdziesz wskazówki, których należy przestrzegać, gdy urządzenie nie obraca się do odwróconej orientacji pionowej. To samo dotyczy urządzeń, które nie obracają się do odwróconej orientacji poziomej.

Scenariusz Wskazówki Tryb jednego okna Tryb podzielonego ekranu z wieloma oknami
Odblokowana orientacja Skonfiguruj przypadki użycia za każdym razem, gdy tworzony jest obiekt Activity, np. w wywołaniu zwrotnym onCreate() obiektu Activity.
Użyj onOrientationChanged() w OrientationEventListener. W wywołaniu zwrotnym zaktualizuj docelowy obrót przypadków użycia. Dotyczy to przypadków, gdy system nie odtwarza Activity nawet po zmianie orientacji, np. gdy urządzenie zostanie obrócone o 180 stopni. Obsługuje też sytuacje, gdy wyświetlacz jest w odwróconej orientacji pionowej, a urządzenie nie obraca się domyślnie do odwróconej orientacji pionowej. Obsługuje też przypadki, w których Activity nie jest odtwarzany po obróceniu urządzenia (np. o 90 stopni). Dzieje się tak na urządzeniach o małych rozmiarach, gdy aplikacja zajmuje połowę ekranu, oraz na większych urządzeniach, gdy aplikacja zajmuje 2/3 ekranu.
Opcjonalnie: ustaw właściwość screenOrientation elementu Activity na fullSensor w pliku AndroidManifest. Dzięki temu interfejs jest wyświetlany pionowo, gdy urządzenie jest w odwróconej orientacji pionowej, a Activity może zostać odtworzony przez system, gdy urządzenie zostanie obrócone o 90 stopni. Nie ma wpływu na urządzenia, które domyślnie nie obracają się do odwróconej orientacji pionowej. Tryb wielu okien nie jest obsługiwany, gdy wyświetlacz jest w orientacji pionowej odwróconej.
Zablokowana orientacja Skonfiguruj przypadki użycia tylko raz, podczas tworzenia Activity, np. w wywołaniu zwrotnym onCreate() Activity.
Użyj onOrientationChanged() w OrientationEventListener. W wywołaniu zwrotnym zaktualizuj docelowy obrót przypadków użycia z wyjątkiem podglądu. Obsługuje też przypadki, w których Activity nie jest odtwarzany po obróceniu urządzenia (np. o 90 stopni). Dzieje się tak na urządzeniach o małych rozmiarach, gdy aplikacja zajmuje połowę ekranu, oraz na większych urządzeniach, gdy aplikacja zajmuje 2/3 ekranu.
Zastąpienie configChanges orientacji Skonfiguruj przypadki użycia tylko raz, podczas tworzenia Activity, np. w wywołaniu zwrotnym onCreate() Activity.
Użyj onOrientationChanged() w OrientationEventListener. W wywołaniu zwrotnym zaktualizuj docelowy obrót przypadków użycia. Obsługuje też przypadki, w których Activity nie jest odtwarzany po obróceniu urządzenia (np. o 90 stopni). Dzieje się tak na urządzeniach o małych rozmiarach, gdy aplikacja zajmuje połowę ekranu, oraz na większych urządzeniach, gdy aplikacja zajmuje 2/3 ekranu.
Opcjonalnie: w pliku AndroidManifest ustaw właściwość screenOrientation aktywności na fullSensor. Umożliwia wyświetlanie interfejsu w orientacji pionowej, gdy urządzenie jest w odwróconej orientacji pionowej. Nie ma wpływu na urządzenia, które domyślnie nie obracają się do odwróconej orientacji pionowej. Tryb wielu okien nie jest obsługiwany, gdy wyświetlacz jest w orientacji pionowej odwróconej.

Obsługuj tylko orientacje obsługiwane przez urządzenie

Obsługuj tylko orientacje, które urządzenie obsługuje domyślnie (może to obejmować odwróconą orientację pionową lub poziomą).

Scenariusz Wskazówki Tryb podzielonego ekranu z wieloma oknami
Odblokowana orientacja Skonfiguruj przypadki użycia za każdym razem, gdy tworzony jest obiekt Activity, np. w wywołaniu zwrotnym onCreate() obiektu Activity.
Użyj onDisplayChanged() w DisplayListener. W wywołaniu zwrotnym zaktualizuj docelowy obrót przypadków użycia, np. gdy urządzenie zostanie obrócone o 180 stopni. Obsługuje też przypadki, w których Activity nie jest odtwarzany po obróceniu urządzenia (np. o 90 stopni). Dzieje się tak na urządzeniach o małych rozmiarach, gdy aplikacja zajmuje połowę ekranu, oraz na większych urządzeniach, gdy aplikacja zajmuje 2/3 ekranu.
Zablokowana orientacja Skonfiguruj przypadki użycia tylko raz, podczas tworzenia Activity, np. w wywołaniu zwrotnym onCreate() Activity.
Użyj onOrientationChanged() w OrientationEventListener. W wywołaniu zwrotnym zaktualizuj docelowy obrót przypadków użycia. Obsługuje też przypadki, w których Activity nie jest odtwarzany po obróceniu urządzenia (np. o 90 stopni). Dzieje się tak na urządzeniach o małych rozmiarach, gdy aplikacja zajmuje połowę ekranu, oraz na większych urządzeniach, gdy aplikacja zajmuje 2/3 ekranu.
Zastąpienie configChanges orientacji Skonfiguruj przypadki użycia tylko raz, podczas tworzenia Activity, np. w wywołaniu zwrotnym onCreate() Activity.
Użyj onDisplayChanged() w DisplayListener. W wywołaniu zwrotnym zaktualizuj docelowy obrót przypadków użycia, np. gdy urządzenie zostanie obrócone o 180 stopni. Obsługuje też przypadki, w których Activity nie jest odtwarzany po obróceniu urządzenia (np. o 90 stopni). Dzieje się tak na urządzeniach o małych rozmiarach, gdy aplikacja zajmuje połowę ekranu, oraz na większych urządzeniach, gdy aplikacja zajmuje 2/3 ekranu.

Odblokowana orientacja

Activity ma odblokowaną orientację, gdy orientacja wyświetlacza (np. pionowa lub pozioma) odpowiada fizycznej orientacji urządzenia, z wyjątkiem odwróconej orientacji pionowej/poziomej, której niektóre urządzenia domyślnie nie obsługują. Aby wymusić obracanie urządzenia we wszystkich 4 orientacjach, ustaw właściwość screenOrientation elementu Activity na fullSensor.

W trybie wielu okien urządzenie, które nie obsługuje odwróconej orientacji pionowej/poziomej, domyślnie nie będzie się obracać do odwróconej orientacji pionowej/poziomej, nawet jeśli właściwość screenOrientation jest ustawiona na 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" />

Zablokowana orientacja

Wyświetlacz ma zablokowaną orientację, gdy pozostaje w tej samej orientacji (np. pionowej lub poziomej) niezależnie od fizycznej orientacji urządzenia. Można to zrobić, określając właściwość screenOrientation elementu Activity w jego deklaracji w pliku AndroidManifest.xml.

Gdy wyświetlacz ma zablokowaną orientację, system nie niszczy i nie odtwarza Activity podczas obracania urządzenia.

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

Zmiany konfiguracji orientacji zostały zastąpione

Gdy Activity zastępuje zmiany konfiguracji orientacji, system nie niszczy i nie odtwarza jej, gdy zmienia się fizyczna orientacja urządzenia. System aktualizuje jednak interfejs, aby dopasować go do fizycznej orientacji urządzenia.

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

Konfigurowanie przypadków użycia aparatu

W opisanych powyżej sytuacjach przypadki użycia kamery można skonfigurować podczas tworzenia Activity.

W przypadku elementu Activity z odblokowaną orientacją konfiguracja jest przeprowadzana przy każdym obróceniu urządzenia, ponieważ system niszczy i ponownie tworzy element Activity przy zmianie orientacji. W rezultacie przypadki użycia domyślnie ustawiają docelowy obrót tak, aby pasował do orientacji wyświetlacza.

W przypadku Activity z zablokowaną orientacją lub takiej, która zastępuje zmiany konfiguracji orientacji, konfiguracja jest wykonywana raz, podczas tworzenia 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
        )
    }
}

Konfiguracja OrientationEventListener

Użycie OrientationEventListener pozwala na ciągłe aktualizowanie docelowego obrotu przypadków użycia aparatu w miarę zmiany orientacji urządzenia.

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

Konfiguracja DisplayListener

Użycie DisplayListener pozwala w niektórych sytuacjach zaktualizować docelowy obrót przypadków użycia aparatu, na przykład gdy system nie niszczy i nie odtwarza Activity po obróceniu urządzenia o 180 stopni.

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