Auf dieser Seite wird die Architektur von CameraX erläutert, einschließlich ihrer Struktur, der Arbeit mit der API, der Verwendung von Lebenszyklen und der Kombination von Anwendungsfällen.
CameraX-Struktur
Mit CameraX können Sie über eine Abstraktion, die als Anwendungsfall bezeichnet wird, mit der Kamera eines Geräts kommunizieren. Folgende Anwendungsfälle sind verfügbar:
- Vorschau: Hier wird eine Oberfläche für die Anzeige einer Vorschau akzeptiert, z. B. eine
PreviewView
. - Bildanalyse: Bietet CPU-zugängliche Buffers für die Analyse, z. B. für maschinelles Lernen.
- Bildaufnahme: Hiermit wird ein Foto aufgenommen und gespeichert.
- Videoaufnahme: Mit
VideoCapture
können Sie Video- und Audioinhalte aufnehmen.
Anwendungsfälle können kombiniert und gleichzeitig aktiv sein. Eine App kann beispielsweise wenn sich der Nutzer das Bild, das die Kamera sieht, mit einem Anwendungsfall in der Vorabversion ansieht, eine einen Anwendungsfall für die Bildanalyse, der bestimmt, ob die Personen auf dem Foto und einen Anwendungsfall für die Bilderfassung einfügen.
API-Modell
Um mit der Bibliothek zu arbeiten, müssen Sie Folgendes angeben:
- Der gewünschte Anwendungsfall mit Konfigurationsoptionen.
- Was mit Ausgabedaten durch Anhängen von Listenern geschehen soll.
- Der beabsichtigte Ablauf, z. B. wann Kameras aktiviert und wann Daten erzeugt werden Binden Sie den Anwendungsfall an die Android-Architektur Lebenszyklen:
Es gibt zwei Möglichkeiten, eine CameraX-App zu entwickeln:
CameraController
(toll, wenn
die einfachste Methode, CameraX zu verwenden) oder ein
CameraProvider
(wenn Sie
mehr Flexibilität benötigen).
Kamera-Controller
Ein CameraController
bietet die meisten Hauptfunktionen von CameraX in einem
. Es erfordert wenig Einrichtungscode und die Kamera verarbeitet die Kamera automatisch.
Initialisierung, Anwendungsfallmanagement, Zielrotation,
durch Auseinander- und Zusammenziehen der Finger zoomen. Die konkrete Klasse, die CameraController
erweitert, ist
LifecycleCameraController
Kotlin
val previewView: PreviewView = viewBinding.previewView var cameraController = LifecycleCameraController(baseContext) cameraController.bindToLifecycle(this) cameraController.cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA previewView.controller = cameraController
Java
PreviewView previewView = viewBinding.previewView; LifecycleCameraController cameraController = new LifecycleCameraController(baseContext); cameraController.bindToLifecycle(this); cameraController.setCameraSelector(CameraSelector.DEFAULT_BACK_CAMERA); previewView.setController(cameraController);
Die Standard-UseCase
s für CameraController
sind Preview
, ImageCapture
und ImageAnalysis
. Zum Ausschalten von ImageCapture
oder ImageAnalysis
VideoCapture
aktiviert haben, verwenden Sie
setEnabledUseCases()
.
Weitere Verwendungsmöglichkeiten von CameraController
finden Sie im Beispiel für den QR-Code-Scanner oder im Video zu den Grundlagen von CameraController
.
CameraProvider
Ein CameraProvider
ist immer noch einfach zu verwenden, aber da der App-Entwickler
mehr Einrichtungsschritte, dann gibt es mehr Möglichkeiten, die Konfiguration anzupassen,
wie das Aktivieren der Ausgabebildrotation
oder das Festlegen des Ausgabebildformats in
ImageAnalysis
. Sie können auch ein benutzerdefiniertes Surface
verwenden, um die Kameravorschau zu aktivieren.
für mehr Flexibilität, während mit CameraController ein
PreviewView
. Die Verwendung des vorhandenen Surface
-Codes kann nützlich sein, wenn er bereits als Eingabe für andere Teile Ihrer App verwendet wird.
Sie konfigurieren Anwendungsfälle mit set()
-Methoden und schließen sie mit der build()
ab
. Jedes Anwendungsfallobjekt bietet eine Reihe von nutzungsfallspezifischen APIs. Der Anwendungsfall „Bildaufnahme“ enthält beispielsweise einen takePicture()
-Methodenaufruf.
Anstatt eine Anwendung spezifische
Start- und Stopp-Methodenaufrufe in
onResume()
und onPause()
, die Anwendung gibt den zu verknüpfenden Lebenszyklus an
mit der Kamera und
cameraProvider.bindToLifecycle()
Anhand dieses Lebenszyklus wird CameraX darüber informiert, wann die Kameraaufnahmesitzung konfiguriert werden soll.
und sorgt dafür, dass sich der Kamerastatus entsprechend ändert.
Implementierungsschritte für die einzelnen Anwendungsfälle finden Sie unter Implementieren eines „preview“, „Analysieren“ Bilder, Bild Capture und Videoaufnahme.
Der Anwendungsfall „Vorschau“ interagiert mit einem
Surface
für die Anzeige. In Anwendungen wird der Anwendungsfall mit Konfigurationsoptionen mit dem folgenden Code erstellt:
Kotlin
val preview = Preview.Builder().build() val viewFinder: PreviewView = findViewById(R.id.previewView) // The use case is bound to an Android Lifecycle with the following code val camera = cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview) // PreviewView creates a surface provider and is the recommended provider preview.setSurfaceProvider(viewFinder.getSurfaceProvider())
Java
Preview preview = new Preview.Builder().build(); PreviewView viewFinder = findViewById(R.id.view_finder); // The use case is bound to an Android Lifecycle with the following code Camera camera = cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview); // PreviewView creates a surface provider, using a Surface from a different // kind of view will require you to implement your own surface provider. preview.previewSurfaceProvider = viewFinder.getSurfaceProvider();
Weitere Beispielcodes finden Sie in der offiziellen CameraX-Beispiel-App.
Kamera-Lebenszyklen
CameraX überwacht einen Lebenszyklus, um zu bestimmen, wann die Kamera geöffnet, wann eine Aufnahmesitzung erstellt und wann die Aufnahme beendet und die Kamera heruntergefahren werden soll. Anwendungsfall-APIs bieten Methodenaufrufe und Callbacks an, um den Fortschritt zu überwachen.
Wie unter Anwendungsfälle kombinieren erläutert, können Sie eine Mischung aus Anwendungsfällen an einen einzelnen Lebenszyklus binden. Wenn Ihre App Anwendungsfälle unterstützen muss, die sich nicht kombinieren lassen, haben Sie folgende Möglichkeiten:
- Kompatible Anwendungsfälle in mehreren Fragmenten gruppieren und dann zwischen den Fragmenten wechseln
- Benutzerdefinierte Lebenszykluskomponente erstellen und damit den Kameralebenszyklus manuell steuern
Wenn Sie Sicht- und Kameraanwendungsfälle entkoppeln, Lebenszyklusinhaber (z. B.
wenn Sie einen benutzerdefinierten Lebenszyklus oder eine
Fragment), können Sie
müssen sicherstellen, dass alle Anwendungsfälle mit CameraX getrennt sind, indem
ProcessCameraProvider.unbindAll()
oder die Verknüpfung für jeden Anwendungsfall einzeln aufheben. Wenn Sie Anwendungsfälle an einen Lebenszyklus binden, können Sie CameraX auch das Öffnen und Schließen der Aufnahmesitzung und das Aufheben der Bindung der Anwendungsfälle verwalten lassen.
Wenn alle Kamerafunktionen dem Lebenszyklus eines einzelnen Geräts
Lebenszyklus-bewusste Komponente wie
AppCompatActivity
oder ein
AppCompat
-Fragment, dann wird der Lebenszyklus dieser Komponente beim Binden verwendet
um sicherzustellen, dass die Kamera
funktionsfähig ist.
Lebenszyklus-bewusste Komponente aktiv ist und sicher entsorgt wird,
sonst alle Ressourcen verbraucht.
Benutzerdefinierte LifecycleOwner
Für erweiterte Anwendungsfälle können Sie eine benutzerdefinierte LifecycleOwner
erstellen, damit Ihre App den CameraX-Sitzungslebenszyklus explizit steuern kann, anstatt ihn an eine standardmäßige Android-LifecycleOwner
zu binden.
Das folgende Codebeispiel zeigt, wie ein einfacher benutzerdefinierter LifecycleOwner erstellt wird:
Kotlin
class CustomLifecycle : LifecycleOwner { private val lifecycleRegistry: LifecycleRegistry init { lifecycleRegistry = LifecycleRegistry(this); lifecycleRegistry.markState(Lifecycle.State.CREATED) } ... fun doOnResume() { lifecycleRegistry.markState(State.RESUMED) } ... override fun getLifecycle(): Lifecycle { return lifecycleRegistry } }
Java
public class CustomLifecycle implements LifecycleOwner { private LifecycleRegistry lifecycleRegistry; public CustomLifecycle() { lifecycleRegistry = new LifecycleRegistry(this); lifecycleRegistry.markState(Lifecycle.State.CREATED); } ... public void doOnResume() { lifecycleRegistry.markState(State.RESUMED); } ... public Lifecycle getLifecycle() { return lifecycleRegistry; } }
Mit diesem LifecycleOwner
kann deine App zu gewünschten Statusübergängen wechseln
Punkte in seinem Code. Weitere Informationen zur Implementierung dieser Funktion in Ihrer App
siehe Implementierung eines benutzerdefinierten
LifecycleOwner
Gleichzeitige Anwendungsfälle
Anwendungsfälle können gleichzeitig ausgeführt werden. Anwendungsfälle können zwar nacheinander an einen Lebenszyklus gebunden werden, es ist jedoch besser, alle Anwendungsfälle mit einem einzigen Aufruf von CameraProcessProvider.bindToLifecycle()
zu binden. Weitere Informationen zur
Best Practices für Konfigurationsänderungen finden Sie unter Umgang mit der Konfiguration.
Änderungen.
Im folgenden Codebeispiel werden für die Anwendung die beiden zu erstellenden Anwendungsfälle angegeben. gleichzeitig ausgeführt werden. Außerdem wird der Lebenszyklus für beide Anwendungsfälle angegeben, damit beide gemäß dem Lebenszyklus gestartet und beendet werden.
Kotlin
private lateinit var imageCapture: ImageCapture override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) val cameraProviderFuture = ProcessCameraProvider.getInstance(this) cameraProviderFuture.addListener(Runnable { // Camera provider is now guaranteed to be available val cameraProvider = cameraProviderFuture.get() // Set up the preview use case to display camera preview. val preview = Preview.Builder().build() // Set up the capture use case to allow users to take photos. imageCapture = ImageCapture.Builder() .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY) .build() // Choose the camera by requiring a lens facing val cameraSelector = CameraSelector.Builder() .requireLensFacing(CameraSelector.LENS_FACING_FRONT) .build() // Attach use cases to the camera with the same lifecycle owner val camera = cameraProvider.bindToLifecycle( this as LifecycleOwner, cameraSelector, preview, imageCapture) // Connect the preview use case to the previewView preview.setSurfaceProvider( previewView.getSurfaceProvider()) }, ContextCompat.getMainExecutor(this)) }
Java
private ImageCapture imageCapture; @Override public void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); PreviewView previewView = findViewById(R.id.previewView); ListenableFuture<ProcessCameraProvider> cameraProviderFuture = ProcessCameraProvider.getInstance(this); cameraProviderFuture.addListener(() -> { try { // Camera provider is now guaranteed to be available ProcessCameraProvider cameraProvider = cameraProviderFuture.get(); // Set up the view finder use case to display camera preview Preview preview = new Preview.Builder().build(); // Set up the capture use case to allow users to take photos imageCapture = new ImageCapture.Builder() .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY) .build(); // Choose the camera by requiring a lens facing CameraSelector cameraSelector = new CameraSelector.Builder() .requireLensFacing(lensFacing) .build(); // Attach use cases to the camera with the same lifecycle owner Camera camera = cameraProvider.bindToLifecycle( ((LifecycleOwner) this), cameraSelector, preview, imageCapture); // Connect the preview use case to the previewView preview.setSurfaceProvider( previewView.getSurfaceProvider()); } catch (InterruptedException | ExecutionException e) { // Currently no exceptions thrown. cameraProviderFuture.get() // shouldn't block since the listener is being called, so no need to // handle InterruptedException. } }, ContextCompat.getMainExecutor(this)); }
CameraX ermöglicht die gleichzeitige Verwendung einer Instanz von Preview
,
VideoCapture
, ImageAnalysis
und ImageCapture
. Außerdem gilt:
- Jeder Anwendungsfall kann für sich stehen. Eine App kann beispielsweise Videos aufzeichnen. ohne die Vorschau zu verwenden.
- Wenn Erweiterungen aktiviert sind, funktioniert nur die Kombination aus
ImageCapture
undPreview
garantiert. Je nach OEM-Implementierung Möglicherweise ist es nicht möglich, auchImageAnalysis
hinzuzufügen. Erweiterungen können nicht für den AnwendungsfallVideoCapture
aktiviert werden. Überprüfen Sie die Referenzdokument zu Erweiterungen . - Je nach Kamerafunktion wird diese Kombination bei einigen Kameras unter Umständen Modi mit niedrigerer Auflösung, können jedoch nicht die gleiche Kombination höherer Auflösungen.
- Auf Geräten mit einer Kamerahardwareebene von
FULL
oder niedriger kann die Kombination vonPreview
,VideoCapture
und entwederImageCapture
oderImageAnalysis
dazu führen, dass CameraX denPRIV
-Stream der Kamera fürPreview
undVideoCapture
dupliziert. Dieses Streamfreigabe genannt, ermöglicht die gleichzeitige Nutzung Funktionen, aber zulasten der erhöhten Verarbeitungsanforderungen. Dies kann zu einer etwas höheren Latenz und einer kürzeren Akkulaufzeit führen.
Die unterstützte Hardwareebene kann unter Camera2CameraInfo
abgerufen werden. Der folgende Code
Prüft, ob die Standardkamera auf der Rückseite ein LEVEL_3
-Gerät ist:
Kotlin
@androidx.annotation.OptIn(ExperimentalCamera2Interop::class) fun isBackCameraLevel3Device(cameraProvider: ProcessCameraProvider) : Boolean { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) { return CameraSelector.DEFAULT_BACK_CAMERA .filter(cameraProvider.availableCameraInfos) .firstOrNull() ?.let { Camera2CameraInfo.from(it) } ?.getCameraCharacteristic(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL) == CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 } return false }
Java
@androidx.annotation.OptIn(markerClass = ExperimentalCamera2Interop.class) Boolean isBackCameraLevel3Device(ProcessCameraProvider cameraProvider) { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) { List\<CameraInfo\> filteredCameraInfos = CameraSelector.DEFAULT_BACK_CAMERA .filter(cameraProvider.getAvailableCameraInfos()); if (!filteredCameraInfos.isEmpty()) { return Objects.equals( Camera2CameraInfo.from(filteredCameraInfos.get(0)).getCameraCharacteristic( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL), CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3); } } return false; }
Berechtigungen
Deine App benötigt die
CAMERA
-Berechtigung. Zum Speichern von Bildern in Dateien ist außerdem die Berechtigung WRITE_EXTERNAL_STORAGE
erforderlich, mit Ausnahme von Geräten mit Android 10 oder höher.
Weitere Informationen zum Konfigurieren von Berechtigungen für Ihre App finden Sie unter App-Berechtigungen anfordern.
Voraussetzungen
Für CameraX gelten die folgenden Mindestversionsanforderungen:
- Android API-Level 21
- Android-Architekturkomponenten 1.1.1
Verwenden Sie für lebenszyklusbezogene Aktivitäten
FragmentActivity
oder
AppCompatActivity
Abhängigkeiten deklarieren
Wenn Sie eine Abhängigkeit von CameraX hinzufügen möchten, müssen Sie Ihrem Projekt das Google Maven-Repository hinzufügen.
Öffnen Sie die settings.gradle
-Datei Ihres Projekts und fügen Sie das google()
-Repository wie unten gezeigt hinzu:
Cool
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
Kotlin
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
Fügen Sie am Ende des Android-Blocks Folgendes ein:
Groovy
android { compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } // For Kotlin projects kotlinOptions { jvmTarget = "1.8" } }
Kotlin
android { compileOptions { sourceCompatibility = JavaVersion.VERSION_1_8 targetCompatibility = JavaVersion.VERSION_1_8 } // For Kotlin projects kotlinOptions { jvmTarget = "1.8" } }
Fügen Sie der build.gradle
-Datei jedes Moduls für eine App Folgendes hinzu:
Groovy
dependencies { // CameraX core library using the camera2 implementation def camerax_version = "1.5.0-alpha03" // The following line is optional, as the core library is included indirectly by camera-camera2 implementation "androidx.camera:camera-core:${camerax_version}" implementation "androidx.camera:camera-camera2:${camerax_version}" // If you want to additionally use the CameraX Lifecycle library implementation "androidx.camera:camera-lifecycle:${camerax_version}" // If you want to additionally use the CameraX VideoCapture library implementation "androidx.camera:camera-video:${camerax_version}" // If you want to additionally use the CameraX View class implementation "androidx.camera:camera-view:${camerax_version}" // If you want to additionally add CameraX ML Kit Vision Integration implementation "androidx.camera:camera-mlkit-vision:${camerax_version}" // If you want to additionally use the CameraX Extensions library implementation "androidx.camera:camera-extensions:${camerax_version}" }
Kotlin
dependencies { // CameraX core library using the camera2 implementation val camerax_version = "1.5.0-alpha03" // The following line is optional, as the core library is included indirectly by camera-camera2 implementation("androidx.camera:camera-core:${camerax_version}") implementation("androidx.camera:camera-camera2:${camerax_version}") // If you want to additionally use the CameraX Lifecycle library implementation("androidx.camera:camera-lifecycle:${camerax_version}") // If you want to additionally use the CameraX VideoCapture library implementation("androidx.camera:camera-video:${camerax_version}") // If you want to additionally use the CameraX View class implementation("androidx.camera:camera-view:${camerax_version}") // If you want to additionally add CameraX ML Kit Vision Integration implementation("androidx.camera:camera-mlkit-vision:${camerax_version}") // If you want to additionally use the CameraX Extensions library implementation("androidx.camera:camera-extensions:${camerax_version}") }
Weitere Informationen dazu, wie Sie Ihre App so konfigurieren, dass sie diesen Anforderungen entspricht, Siehe Deklarieren Abhängigkeiten.
Interoperabilität von CameraX mit Camera2
CameraX baut auf Camera2 auf und CameraX bietet Möglichkeiten zum Lesen und Schreiben in der Camera2-Implementierung fest. Weitere Informationen finden Sie im Interoperabilitätspaket.
Weitere Informationen dazu, wie KameraX die Eigenschaften von Kamera2 konfiguriert hat, findest du unter
Camera2CameraInfo
um den zugrunde liegenden CameraCharacteristics
zu lesen. Sie können die zugrunde liegenden Camera2-Eigenschaften auch in einem der folgenden beiden Pfade schreiben:
Verwenden Sie
Camera2CameraControl
, um Eigenschaften für das zugrunde liegendeCaptureRequest
festzulegen, z. B. den Autofokusmodus.Erweitern Sie eine CameraX-
UseCase
mit einerCamera2Interop.Extender
. So können Sie Attribute für CaptureRequest festlegen,Camera2CameraControl
Außerdem stehen euch zusätzliche Steuerungsmöglichkeiten zur Verfügung. So könnt ihr z. B. den Anwendungsfall des Streams auf einen bestimmten die Kamera für Ihr Anwendungsszenario zu optimieren. Weitere Informationen finden Sie unter Anwendungsfälle für Streams zur besseren Leistung.
Im folgenden Codebeispiel werden Stream-Anwendungsfälle verwendet, um die Leistung für einen Videoanruf zu optimieren.
Mit Camera2CameraInfo
kannst du abrufen, ob der Anwendungsfall für Videoanrufstreams verfügbar ist. Verwenden Sie dann
Camera2Interop.Extender
um den Anwendungsfall für den zugrunde liegenden Stream festzulegen.
Kotlin
// Set underlying Camera2 stream use case to optimize for video calls. val videoCallStreamId = CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_VIDEO_CALL.toLong() // Check available CameraInfos to find the first one that supports // the video call stream use case. val frontCameraInfo = cameraProvider.getAvailableCameraInfos() .first { cameraInfo -> val isVideoCallStreamingSupported = Camera2CameraInfo.from(cameraInfo) .getCameraCharacteristic( CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES )?.contains(videoCallStreamId) val isFrontFacing = (cameraInfo.getLensFacing() == CameraSelector.LENS_FACING_FRONT) (isVideoCallStreamingSupported == true) && isFrontFacing } val cameraSelector = frontCameraInfo.cameraSelector // Start with a Preview Builder. val previewBuilder = Preview.Builder() .setTargetAspectRatio(screenAspectRatio) .setTargetRotation(rotation) // Use Camera2Interop.Extender to set the video call stream use case. Camera2Interop.Extender(previewBuilder).setStreamUseCase(videoCallStreamId) // Bind the Preview UseCase and the corresponding CameraSelector. val preview = previewBuilder.build() camera = cameraProvider.bindToLifecycle(this, cameraSelector, preview)
Java
// Set underlying Camera2 stream use case to optimize for video calls. Long videoCallStreamId = CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_VIDEO_CALL.toLong(); // Check available CameraInfos to find the first one that supports // the video call stream use case. List<CameraInfo> cameraInfos = cameraProvider.getAvailableCameraInfos(); CameraInfo frontCameraInfo = null; for (cameraInfo in cameraInfos) { Long[] availableStreamUseCases = Camera2CameraInfo.from(cameraInfo) .getCameraCharacteristic( CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES ); boolean isVideoCallStreamingSupported = Arrays.List(availableStreamUseCases) .contains(videoCallStreamId); boolean isFrontFacing = (cameraInfo.getLensFacing() == CameraSelector.LENS_FACING_FRONT); if (isVideoCallStreamingSupported && isFrontFacing) { frontCameraInfo = cameraInfo; } } if (frontCameraInfo == null) { // Handle case where video call streaming is not supported. } CameraSelector cameraSelector = frontCameraInfo.getCameraSelector(); // Start with a Preview Builder. Preview.Builder previewBuilder = Preview.Builder() .setTargetAspectRatio(screenAspectRatio) .setTargetRotation(rotation); // Use Camera2Interop.Extender to set the video call stream use case. Camera2Interop.Extender(previewBuilder).setStreamUseCase(videoCallStreamId); // Bind the Preview UseCase and the corresponding CameraSelector. Preview preview = previewBuilder.build() Camera camera = cameraProvider.bindToLifecycle(this, cameraSelector, preview)
Weitere Informationen
Weitere Informationen zu CameraX finden Sie in den folgenden Ressourcen.
Codelab
Codebeispiel