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
ImageCapturepowinien 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 Obrót obrazu = 0 |
|
|
Orientacja naturalna = pionowa Obrót obrazu = 90 |
|
Przykład 2. Naturalna orientacja pozioma
| Przykładowe urządzenie: Pixel C | |
|---|---|
|
Orientacja naturalna = pozioma Obrót obrazu = 0 |
|
|
Orientacja naturalna = pozioma Obrót obrazu = 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 |
|
|
Obrót obrazu = 90 |
|
Przykład 2. Czujnik obrócony o 270 stopni
| Przykładowe urządzenie: Nexus 5X | |
|---|---|
|
Obrót obrazu = 0 |
|
|
Obrót obrazu = 90 |
|
Przykład 3. Czujnik obrócony o 0 stopni
| Przykładowe urządzenie: Pixel C (tablet) | |
|---|---|
|
Obrót obrazu = 0 |
|
|
Obrót obrazu = 270 |
|
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 postaciImageProxy.OnImageSavedCallback: wywoływane, gdy przechwycony obraz zostanie zapisany w lokalizacji określonej przezImageCapture.OutputFileOptions. Opcje mogą określaćFile,OutputStreamlub lokalizację wMediaStore.
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.
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:
Sprawdź, czy aparat w aplikacji
Activityma zablokowaną lub odblokowaną orientację albo czy zastępuje zmiany konfiguracji orientacji.Zdecyduj, czy kamera aplikacji
Activitypowinna 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) } }