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
ImageAnalysisdes AnwendungsfallsAnalyzersollte Frames mit der richtigen Drehung empfangen. - Der Anwendungsfall
ImageCapturesollte 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 Displayausrichtung = 0 |
|
|
Natürliche Ausrichtung = Hochformat Displayausrichtung = 90 |
|
Beispiel 2: Querformat als Standardausrichtung
| Beispielgerät: Pixel C | |
|---|---|
|
Natürliche Ausrichtung = Querformat Displayausrichtung = 0 |
|
|
Natürliche Ausrichtung = Querformat Displayausrichtung = 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 = 90 |
|
Beispiel 2: Sensor um 270 Grad gedreht
| Gerätebeispiel: Nexus 5X | |
|---|---|
|
Displayausrichtung = 0 |
|
|
Displayausrichtung = 90 |
|
Beispiel 3: Sensor um 0 Grad gedreht
| Gerätebeispiel: Pixel C (Tablet) | |
|---|---|
|
Displayausrichtung = 0 |
|
|
Displayausrichtung = 270 |
|
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 einesImageProxy.OnImageSavedCallback: Wird aufgerufen, wenn das aufgenommene Bild erfolgreich am vonImageCapture.OutputFileOptionsangegebenen Speicherort gespeichert wurde. Die Optionen können einenFile, einenOutputStreamoder einen Standort inMediaStoreangeben.
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.
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:
Prüfe, ob die Kamera
Activitydeiner App eine gesperrte oder entsperrte Ausrichtung hat oder ob sie Änderungen an der Ausrichtungskonfiguration überschreibt.Entscheide, ob die Kamera
Activitydeiner 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) } }