Rotationen der CameraX-Anwendungsfälle

In diesem Thema wird gezeigt, wie Sie CameraX-Anwendungsfälle in Ihrer App einrichten, um Bilder mit den richtigen Rotationsinformationen zu erhalten, unabhängig davon, ob sie aus dem Anwendungsfall ImageAnalysis oder ImageCapture stammen. Daher gilt:

  • Der ImageAnalysis des Anwendungsfalls Analyzer sollte Frames mit der richtigen Drehung empfangen.
  • Der Anwendungsfall ImageCapture sollte Bilder mit der richtigen Ausrichtung aufnehmen.

Terminologie

In diesem Thema wird die folgende Terminologie verwendet. Es ist daher wichtig, die Bedeutung der einzelnen Begriffe zu verstehen:

Displayausrichtung
Dies bezieht sich darauf, welche Seite des Geräts sich in der oberen Position befindet. Es kann einer von vier Werten sein: Hochformat, Querformat, umgekehrtes Hochformat oder umgekehrtes Querformat.
Displayausrichtung
Dies ist der von Display.getRotation() zurückgegebene Wert. Er gibt an, um wie viel Grad das Gerät gegen den Uhrzeigersinn von seiner natürlichen Ausrichtung gedreht wurde.
Zielrotation
Dies ist die Anzahl der Grad, um die das Gerät im Uhrzeigersinn gedreht werden muss, um seine natürliche Ausrichtung zu erreichen.

So ermitteln Sie die Zielrotation

Die folgenden Beispiele zeigen, wie die Zieldrehung für ein Gerät anhand seiner natürlichen Ausrichtung bestimmt wird.

Beispiel 1: Hochformat als natürliche Ausrichtung

Beispielgerät: Pixel 3 XL

Natürliche Ausrichtung = Hochformat
Aktuelle Ausrichtung = Hochformat

Displayausrichtung = 0
Zielausrichtung = 0

Natürliche Ausrichtung = Hochformat
Aktuelle Ausrichtung = Querformat

Displayausrichtung = 90
Zielausrichtung = 90

Beispiel 2: Querformat als Standardausrichtung

Beispielgerät: Pixel C

Natürliche Ausrichtung = Querformat
Aktuelle Ausrichtung = Querformat

Displayausrichtung = 0
Zielausrichtung = 0

Natürliche Ausrichtung = Querformat
Aktuelle Ausrichtung = Hochformat

Displayausrichtung = 270
Zielausrichtung = 270

Bilddrehung

Welches Ende ist oben? Die Sensorausrichtung wird in Android als konstanter Wert definiert, der die Gradzahl (0, 90, 180, 270) angibt, um die der Sensor von der Oberseite des Geräts gedreht wird, wenn sich das Gerät in einer natürlichen Position befindet. In allen Fällen in den Diagrammen beschreibt die Bilddrehung, wie die Daten im Uhrzeigersinn gedreht werden sollten, damit sie aufrecht angezeigt werden.

Die folgenden Beispiele zeigen, wie die Bilddrehung je nach Ausrichtung des Kamerasensors sein sollte. Außerdem wird davon ausgegangen, dass die Zielrotation auf die Displayrotation eingestellt ist.

Beispiel 1: Sensor um 90 Grad gedreht

Beispielgerät: Pixel 3 XL

Displayausrichtung = 0
Displayausrichtung = Hochformat
Bilddrehung = 90

Displayausrichtung = 90
Displayausrichtung = Querformat
Bildausrichtung = 0

Beispiel 2: Sensor um 270 Grad gedreht

Gerätebeispiel: Nexus 5X

Displayausrichtung = 0
Displayausrichtung = Hochformat
Bilddrehung = 270

Displayausrichtung = 90
Displayausrichtung = Querformat
Bilddrehung = 180

Beispiel 3: Sensor um 0 Grad gedreht

Gerätebeispiel: Pixel C (Tablet)

Displayausrichtung = 0
Displayausrichtung = Querformat
Bildausrichtung = 0

Displayausrichtung = 270
Displayausrichtung = Hochformat
Bilddrehung = 90

Drehung eines Bildes berechnen

ImageAnalysis

Der Analyzer von ImageAnalysis empfängt Bilder von der Kamera in Form von ImageProxys. Jedes Bild enthält Informationen zur Drehung, die über Folgendes zugänglich sind:

val rotation = imageProxy.imageInfo.rotationDegrees

Dieser Wert gibt an, um wie viel Grad das Bild im Uhrzeigersinn gedreht werden muss, um der Zieldrehung von ImageAnalysis zu entsprechen. Im Kontext einer Android-App entspricht die Zielrotation von ImageAnalysis in der Regel der Ausrichtung des Bildschirms.

ImageCapture

An eine ImageCapture-Instanz wird ein Callback angehängt, um zu signalisieren, wenn ein Aufnahmeergebnis bereit ist. Das Ergebnis kann entweder das aufgenommene Bild oder ein Fehler sein.

Beim Aufnehmen eines Bildes kann der bereitgestellte Callback einen der folgenden Typen haben:

  • OnImageCapturedCallback: Empfängt ein Bild mit In-Memory-Zugriff in Form eines ImageProxy.
  • OnImageSavedCallback: Wird aufgerufen, wenn das aufgenommene Bild erfolgreich am von ImageCapture.OutputFileOptions angegebenen Speicherort gespeichert wurde. Die Optionen können einen File, einen OutputStream oder einen Standort in MediaStore angeben.

Die Drehung des aufgenommenen Bildes, unabhängig von seinem Format (ImageProxy, File, OutputStream, MediaStore Uri), stellt die Drehgrade dar, um die das aufgenommene Bild im Uhrzeigersinn gedreht werden muss, um der Zieldrehung von ImageCapture zu entsprechen. Im Kontext einer Android-App entspricht dies in der Regel der Ausrichtung des Bildschirms.

Die Ausrichtung des aufgenommenen Bildes kann auf eine der folgenden Arten abgerufen werden:

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

Ausrichtung eines Bildes prüfen

Die Anwendungsfälle ImageAnalysis und ImageCapture erhalten nach einer erfolgreichen Aufnahmeanfrage ImageProxys von der Kamera. Ein ImageProxy umschließt ein Bild und Informationen dazu, einschließlich der Drehung. Diese Rotationsinformationen geben die Gradzahl an, um die das Bild gedreht werden muss, um der Zielrotation des Anwendungsfalls zu entsprechen.

Ablauf der Rotationsprüfung eines Bildes

Richtlinien für die Zielrotation von ImageCapture/ImageAnalysis

Da viele Geräte standardmäßig nicht in das umgekehrte Hoch- oder Querformat gedreht werden, unterstützen einige Android-Apps diese Ausrichtungen nicht. Ob eine App dies unterstützt oder nicht, wirkt sich darauf aus, wie die Zielrotation der Anwendungsfälle aktualisiert werden kann.

In den folgenden beiden Tabellen wird beschrieben, wie die Zielrotation der Anwendungsfälle mit der Displayrotation synchronisiert wird. Im ersten Beispiel wird gezeigt, wie Sie alle vier Ausrichtungen unterstützen können. Im zweiten Beispiel werden nur die Ausrichtungen behandelt, in die sich das Gerät standardmäßig dreht.

So wählen Sie aus, welche Richtlinien in Ihrer App befolgt werden sollen:

  1. Prüfe, ob die Kamera Activity deiner App eine gesperrte oder entsperrte Ausrichtung hat oder ob sie Änderungen an der Ausrichtungskonfiguration überschreibt.

  2. Entscheide, ob die Kamera Activity deiner App alle vier Geräteausrichtungen (Hochformat, umgekehrtes Hochformat, Querformat und umgekehrtes Querformat) oder nur die Ausrichtungen unterstützen soll, die das Gerät, auf dem sie ausgeführt wird, standardmäßig unterstützt.

Alle vier Ausrichtungen unterstützen

In dieser Tabelle sind bestimmte Richtlinien aufgeführt, die zu beachten sind, wenn sich das Gerät nicht in das umgekehrte Hochformat dreht. Das Gleiche gilt für Geräte, die sich nicht ins umgekehrte Querformat drehen lassen.

Szenario Richtlinien Einzelfenstermodus Splitscreen-Modus mit mehreren Fenstern
Ausrichtung entsperrt Richten Sie die Anwendungsfälle jedes Mal ein, wenn der Activity erstellt wird, z. B. im onCreate()-Callback des Activity.
Verwenden Sie onOrientationChanged() von OrientationEventListener. Aktualisieren Sie im Callback die Zieldrehung der Anwendungsfälle. Dies deckt Fälle ab, in denen das System die Activity auch nach einer Änderung der Ausrichtung nicht neu erstellt, z. B. wenn das Gerät um 180 Grad gedreht wird. Auch wenn sich das Display im umgekehrten Hochformat befindet und das Gerät nicht standardmäßig in das umgekehrte Hochformat wechselt, wird dies berücksichtigt. Behandelt auch Fälle, in denen die Activity nicht neu erstellt wird, wenn das Gerät gedreht wird (z. B. um 90 Grad). Dies geschieht auf Geräten mit kleinem Formfaktor, wenn die App die Hälfte des Bildschirms einnimmt, und auf größeren Geräten, wenn die App zwei Drittel des Bildschirms einnimmt.
Optional: Setzen Sie in der Datei AndroidManifest das Attribut screenOrientation von Activity auf fullSensor. Dadurch wird die Benutzeroberfläche aufrecht angezeigt, wenn sich das Gerät im umgekehrten Hochformat befindet, und die Activity kann vom System neu erstellt werden, wenn das Gerät um 90 Grad gedreht wird. Hat keine Auswirkungen auf Geräte, die standardmäßig nicht ins umgekehrte Hochformat gedreht werden. Der Mehrfenstermodus wird nicht unterstützt, wenn sich das Display im umgekehrten Hochformat befindet.
Gesperrte Ausrichtung Richten Sie die Anwendungsfälle nur einmal ein, wenn der Activity zum ersten Mal erstellt wird, z. B. im onCreate()-Callback des Activity.
Verwenden Sie onOrientationChanged() von OrientationEventListener. Aktualisieren Sie im Callback die Zielrotation der Anwendungsfälle mit Ausnahme der Vorschau. Behandelt auch Fälle, in denen die Activity nicht neu erstellt wird, wenn das Gerät gedreht wird (z. B. um 90 Grad). Dies geschieht auf Geräten mit kleinem Formfaktor, wenn die App die Hälfte des Bildschirms einnimmt, und auf größeren Geräten, wenn die App zwei Drittel des Bildschirms einnimmt.
Ausrichtung configChanges überschrieben Richten Sie die Anwendungsfälle nur einmal ein, wenn der Activity zum ersten Mal erstellt wird, z. B. im onCreate()-Callback des Activity.
Verwenden Sie onOrientationChanged() von OrientationEventListener. Aktualisieren Sie im Callback die Zieldrehung der Anwendungsfälle. Behandelt auch Fälle, in denen die Activity nicht neu erstellt wird, wenn das Gerät gedreht wird (z. B. um 90 Grad). Dies geschieht auf Geräten mit kleinem Formfaktor, wenn die App die Hälfte des Bildschirms einnimmt, und auf größeren Geräten, wenn die App zwei Drittel des Bildschirms einnimmt.
Optional: Legen Sie in der Datei „AndroidManifest“ das Attribut „screenOrientation“ der Aktivität auf „fullSensor“ fest. Ermöglicht, dass die Benutzeroberfläche aufrecht angezeigt wird, wenn sich das Gerät im umgekehrten Hochformat befindet. Hat keine Auswirkungen auf Geräte, die standardmäßig nicht ins umgekehrte Hochformat gedreht werden. Der Mehrfenstermodus wird nicht unterstützt, wenn sich das Display im umgekehrten Hochformat befindet.

Nur vom Gerät unterstützte Ausrichtungen unterstützen

Unterstützung nur der Ausrichtungen, die das Gerät standardmäßig unterstützt (dies kann die umgekehrte Hochformat- und/oder die umgekehrte Querformatausrichtung umfassen oder nicht).

Szenario Richtlinien Splitscreen-Modus mit mehreren Fenstern
Ausrichtung entsperrt Richten Sie die Anwendungsfälle jedes Mal ein, wenn der Activity erstellt wird, z. B. im onCreate()-Callback des Activity.
Verwenden Sie onDisplayChanged() von DisplayListener. Aktualisiere im Callback die Zieldrehung der Anwendungsfälle, z. B. wenn das Gerät um 180 Grad gedreht wird. Behandelt auch Fälle, in denen die Activity nicht neu erstellt wird, wenn das Gerät gedreht wird (z. B. um 90 Grad). Dies geschieht auf Geräten mit kleinem Formfaktor, wenn die App die Hälfte des Bildschirms einnimmt, und auf größeren Geräten, wenn die App zwei Drittel des Bildschirms einnimmt.
Gesperrte Ausrichtung Richten Sie die Anwendungsfälle nur einmal ein, wenn der Activity zum ersten Mal erstellt wird, z. B. im onCreate()-Callback des Activity.
Verwenden Sie onOrientationChanged() von OrientationEventListener. Aktualisieren Sie im Callback die Zieldrehung der Anwendungsfälle. Behandelt auch Fälle, in denen die Activity nicht neu erstellt wird, wenn das Gerät gedreht wird (z. B. um 90 Grad). Dies geschieht auf Geräten mit kleinem Formfaktor, wenn die App die Hälfte des Bildschirms einnimmt, und auf größeren Geräten, wenn die App zwei Drittel des Bildschirms einnimmt.
Ausrichtung configChanges überschrieben Richten Sie die Anwendungsfälle nur einmal ein, wenn der Activity zum ersten Mal erstellt wird, z. B. im onCreate()-Callback des Activity.
Verwenden Sie onDisplayChanged() von DisplayListener. Aktualisiere im Callback die Zieldrehung der Anwendungsfälle, z. B. wenn das Gerät um 180 Grad gedreht wird. Behandelt auch Fälle, in denen die Activity nicht neu erstellt wird, wenn das Gerät gedreht wird (z. B. um 90 Grad). Dies geschieht auf Geräten mit kleinem Formfaktor, wenn die App die Hälfte des Bildschirms einnimmt, und auf größeren Geräten, wenn die App zwei Drittel des Bildschirms einnimmt.

Ausrichtung entsperrt

Ein Activity hat eine entsperrte Ausrichtung, wenn die Displayausrichtung (z. B. Hoch- oder Querformat) mit der physischen Ausrichtung des Geräts übereinstimmt. Eine Ausnahme ist das umgekehrte Hoch- oder Querformat, das von einigen Geräten standardmäßig nicht unterstützt wird. Wenn Sie das Gerät zwingen möchten, sich in alle vier Ausrichtungen zu drehen, setzen Sie die Eigenschaft screenOrientation des Activity auf fullSensor.

Im Mehrfenstermodus wird ein Gerät, das standardmäßig kein umgekehrtes Hoch-/Querformat unterstützt, nicht in das umgekehrte Hoch-/Querformat gedreht, auch wenn das Attribut screenOrientation auf fullSensor gesetzt ist.

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

Ausrichtung gesperrt

Ein Display hat eine gesperrte Ausrichtung, wenn es unabhängig von der physischen Ausrichtung des Geräts immer dieselbe Ausrichtung (z. B. Hoch- oder Querformat) beibehält. Dazu können Sie die screenOrientation-Property eines Activity in der Deklaration in der Datei AndroidManifest.xml angeben.

Wenn die Ausrichtung des Displays gesperrt ist, wird die Activity beim Drehen des Geräts nicht zerstört und neu erstellt.

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

Änderungen der Ausrichtungskonfiguration überschrieben

Wenn eine Activity Änderungen an der Ausrichtungskonfiguration überschreibt, wird sie vom System nicht gelöscht und neu erstellt, wenn sich die physische Ausrichtung des Geräts ändert. Das System aktualisiert die Benutzeroberfläche jedoch entsprechend der physischen Ausrichtung des Geräts.

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

Anwendungsfälle für die Kamera einrichten

In den oben beschriebenen Szenarien können die Kamera-Anwendungsfälle bei der Erstellung des Activity eingerichtet werden.

Bei einer Activity mit nicht gesperrter Ausrichtung wird diese Einrichtung jedes Mal durchgeführt, wenn das Gerät gedreht wird, da das System die Activity bei Ausrichtungsänderungen löscht und neu erstellt. Dies führt dazu, dass die Anwendungsfälle standardmäßig jedes Mal ihre Zieldrehung an die Ausrichtung des Displays anpassen.

Bei einer Activity mit gesperrter Ausrichtung oder einer, die Änderungen an der Ausrichtungskonfiguration überschreibt, wird diese Einrichtung einmalig vorgenommen, wenn die Activity zum ersten Mal erstellt wird.

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 einrichten

Mit einem OrientationEventListener können Sie die Zielrotation der Kamera-Anwendungsfälle kontinuierlich aktualisieren, wenn sich die Ausrichtung des Geräts ändert.

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-Einrichtung

Mit einem DisplayListener kannst du die Zielrotation der Kamera in bestimmten Situationen aktualisieren, z. B. wenn das System die Activity nach einer Drehung des Geräts um 180 Grad nicht zerstört und neu erstellt.

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