Auf dieser Seite wird die Architektur von CameraX beschrieben, einschließlich der Struktur, der Verwendung 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 interagieren. Die folgenden Anwendungsfälle sind verfügbar:
- Vorschau: Akzeptiert eine Oberfläche zum Anzeigen einer Vorschau, z. B. ein
PreviewView. - Bildanalyse: Stellt CPU-zugängliche Zwischenspeicher für die Analyse bereit, z. B. für maschinelles Lernen.
- Bilderfassung: Ein Foto wird aufgenommen und gespeichert.
- Videoaufnahme: Video und Audio mit
VideoCaptureaufnehmen
Anwendungsfälle können kombiniert und gleichzeitig aktiv sein. Eine App kann dem Nutzer beispielsweise ermöglichen, das Bild, das die Kamera sieht, über einen Vorschau-Anwendungsfall anzusehen, einen Anwendungsfall für die Bildanalyse zu haben, der bestimmt, ob die Personen auf dem Foto lächeln, und einen Anwendungsfall für die Bilderfassung zu haben, um ein Bild aufzunehmen, sobald sie lächeln.
API-Modell
Wenn Sie mit der Bibliothek arbeiten, geben Sie Folgendes an:
- Der gewünschte Anwendungsfall mit Konfigurationsoptionen.
- Was mit Ausgabedaten geschehen soll, indem Listener angehängt werden.
- Der beabsichtigte Ablauf, z. B. wann Kameras aktiviert und wann Daten erzeugt werden sollen, indem der Anwendungsfall an Android-Architekturlebenszyklen gebunden wird.
Es gibt zwei Möglichkeiten, eine CameraX-App zu schreiben: mit einem CameraController (ideal, wenn Sie CameraX auf einfachste Weise verwenden möchten) oder mit einem CameraProvider (ideal, wenn Sie mehr Flexibilität benötigen).
CameraController
Ein CameraController bietet die meisten Hauptfunktionen von CameraX in einer einzigen Klasse. Sie erfordert nur wenig Einrichtungscode und übernimmt automatisch die Kamerainitialisierung, die Verwaltung von Anwendungsfällen, die Zielrotation, das Tippen zum Fokussieren, das Zoomen durch Auf- und Zuziehen und vieles mehr. 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-UseCases für CameraController sind Preview, ImageCapture und ImageAnalysis. Wenn Sie ImageCapture oder ImageAnalysis deaktivieren oder VideoCapture aktivieren möchten, verwenden Sie die Methode setEnabledUseCases().
Weitere Verwendungsmöglichkeiten für CameraController finden Sie im Beispiel für einen 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 von der Einrichtung übernimmt, gibt es mehr Möglichkeiten, die Konfiguration anzupassen, z. B. die Drehung des Ausgabebildes zu aktivieren oder das Ausgabebildformat in ImageAnalysis festzulegen. Sie können auch eine benutzerdefinierte Surface für die Kameravorschau verwenden, was mehr Flexibilität bietet. Bei CameraController müssen Sie jedoch eine PreviewView verwenden. Die Verwendung Ihres vorhandenen Surface-Codes kann nützlich sein, wenn er bereits als Eingabe für andere Teile Ihrer App dient.
Sie konfigurieren Anwendungsfälle mit set()-Methoden und schließen sie mit der build()-Methode ab. Jedes Anwendungsfallobjekt bietet eine Reihe von anwendungsspezifischen APIs. Der Anwendungsfall für die Bilderfassung bietet beispielsweise einen takePicture()-Methodenaufruf.
Anstatt dass eine Anwendung bestimmte Start- und Stopp-Methodenaufrufe in onResume() und onPause() platziert, gibt die Anwendung einen Lebenszyklus an, mit dem die Kamera verknüpft werden soll. Dazu wird cameraProvider.bindToLifecycle() verwendet.
Dieser Lebenszyklus informiert CameraX dann darüber, wann die Kameraaufnahmesitzung konfiguriert werden muss, und sorgt dafür, dass sich der Kamerastatus entsprechend den Lebenszyklusübergängen ändert.
Die Implementierungsschritte für die einzelnen Anwendungsfälle finden Sie unter Vorschau implementieren, Bilder analysieren, Bilderfassung und Videoaufnahme.
Der Anwendungsfall für die Vorschau interagiert mit einer Surface für die Anzeige. Anwendungen erstellen den Anwendungsfall mit Konfigurationsoptionen mithilfe des folgenden Codes:
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 Codebeispiele finden Sie in der offiziellen CameraX-Beispiel-App.
CameraX-Lebenszyklen
CameraX beobachtet einen Lebenszyklus, um zu bestimmen, wann die Kamera geöffnet, wann eine Aufnahmesitzung erstellt und wann die Kamera gestoppt und heruntergefahren werden soll. Anwendungsfall-APIs bieten Methodenaufrufe und Callbacks, um den Fortschritt zu überwachen.
Wie unter Anwendungsfälle kombinieren erläutert, können Sie einige Kombinationen von Anwendungsfällen an einen einzelnen Lebenszyklus binden. Wenn Ihre App Anwendungsfälle unterstützen muss, die nicht kombiniert werden können, haben Sie folgende Möglichkeiten:
- Kompatible Anwendungsfälle in mehreren Fragmenten gruppieren und dann zwischen Fragmenten wechseln
- Benutzerdefinierte Lebenszykluskomponente erstellen und damit den Kameralebenszyklus manuell steuern
Wenn Sie die Lifecycle-Inhaber der Anwendungsfälle für Ansicht und Kamera entkoppeln (z. B. wenn Sie einen benutzerdefinierten Lebenszyklus oder ein beibehaltenes Fragment verwenden), müssen Sie dafür sorgen, dass alle Anwendungsfälle von CameraX entbunden werden. Verwenden Sie dazu ProcessCameraProvider.unbindAll() oder entbinden Sie jeden Anwendungsfall einzeln. Alternativ können Sie, wenn Sie Anwendungsfälle an einen Lebenszyklus binden, CameraX das Öffnen und Schließen der Aufnahmesitzung und das Aufheben der Bindung der Anwendungsfälle überlassen.
Wenn alle Kamerafunktionen dem Lebenszyklus einer einzelnen lebenszyklusorientierten Komponente wie einer AppCompatActivity oder einem AppCompat-Fragment entsprechen, sorgt die Verwendung des Lebenszyklus dieser Komponente beim Binden aller gewünschten Anwendungsfälle dafür, dass die Kamerafunktionen bereit sind, wenn die lebenszyklusorientierte Komponente aktiv ist. Andernfalls werden sie sicher entfernt und verbrauchen keine Ressourcen.
Benutzerdefinierte LifecycleOwner
Für erweiterte Fälle können Sie einen benutzerdefinierten LifecycleOwner erstellen, damit Ihre App den Lebenszyklus der CameraX-Sitzung explizit steuern kann, anstatt ihn an einen Standard-LifecycleOwner von Android zu binden.
Das folgende Codebeispiel zeigt, wie Sie einen einfachen benutzerdefinierten LifecycleOwner erstellen:
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 Ihre App Zustandsübergänge an den gewünschten Stellen im Code platzieren. Weitere Informationen zur Implementierung dieser Funktion in Ihrer App finden Sie unter Benutzerdefinierten LifecycleOwner implementieren.
Gleichzeitige Anwendungsfälle
Anwendungsfälle können gleichzeitig ausgeführt werden. Anwendungsfälle können zwar sequenziell an einen Lebenszyklus gebunden werden, es ist jedoch besser, alle Anwendungsfälle mit einem einzigen Aufruf von CameraProcessProvider.bindToLifecycle() zu binden. Weitere Informationen zu Best Practices für Konfigurationsänderungen finden Sie unter Konfigurationsänderungen verarbeiten.
Im folgenden Codebeispiel gibt die App die beiden Anwendungsfälle an, die gleichzeitig erstellt und ausgeführt werden sollen. Außerdem wird der Lebenszyklus für beide Anwendungsfälle angegeben, sodass beide entsprechend 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 von jeweils einer Instanz von Preview, VideoCapture, ImageAnalysis und ImageCapture. Außerdem
- Jeder Anwendungsfall kann eigenständig funktionieren. Eine App kann beispielsweise Videos ohne Vorschau aufnehmen.
- Wenn Erweiterungen aktiviert sind, funktioniert nur die Kombination aus
ImageCaptureundPreview. Je nach OEM-Implementierung ist es möglicherweise nicht möglich, auchImageAnalysishinzuzufügen. Erweiterungen können für den AnwendungsfallVideoCapturenicht aktiviert werden. Weitere Informationen finden Sie im Referenzdokument für Erweiterungen. - Je nach Kamerafunktionen unterstützen einige Kameras die Kombination bei niedrigeren Auflösungsmodi, aber nicht bei einigen höheren Auflösungen.
- Auf Geräten mit Kamera-Hardware-Level
FULLoder niedriger kann die Kombination vonPreview,VideoCaptureund entwederImageCaptureoderImageAnalysisdazu führen, dass CameraX denPRIV-Stream der Kamera fürPreviewundVideoCapturedupliziert. Diese Duplizierung, die als Streamfreigabe bezeichnet wird, ermöglicht die gleichzeitige Verwendung dieser Funktionen, führt jedoch zu höheren Verarbeitungsanforderungen. Dies kann zu einer etwas höheren Latenz und einer kürzeren Akkulaufzeit führen.
Die unterstützte Hardwarestufe kann von Camera2CameraInfo abgerufen werden. Mit dem folgenden Code wird beispielsweise geprüft, ob die standardmäßige rückwärtsgerichtete Kamera 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
Ihre App benötigt die Berechtigung CAMERA. Zum Speichern von Bildern in Dateien ist außerdem die Berechtigung WRITE_EXTERNAL_STORAGE erforderlich, außer auf 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 lebenszyklusbewusste 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 Datei settings.gradle für Ihr Projekt und fügen Sie das Repository google() hinzu, wie im Folgenden gezeigt:
Groovy
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 hinzu:
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 Datei build.gradle jedes Moduls für eine Anwendung Folgendes hinzu:
Groovy
dependencies { // CameraX core library using the camera2 implementation def camerax_version = "1.7.0-alpha02" // 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.7.0-alpha02" // 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 zum Konfigurieren Ihrer Anwendung gemäß diesen Anforderungen finden Sie unter Abhängigkeiten deklarieren.
CameraX-Interoperabilität mit Camera2
CameraX basiert auf Camera2 und bietet Möglichkeiten, Eigenschaften in der Camera2-Implementierung zu lesen und sogar zu schreiben. Ausführliche Informationen finden Sie im Interop-Paket.
Weitere Informationen dazu, wie CameraX Camera2-Eigenschaften konfiguriert hat, findest du unter Camera2CameraInfo. Dort kannst du die zugrunde liegende CameraCharacteristics lesen. Du kannst die zugrunde liegenden Camera2-Eigenschaften auch auf eine der folgenden beiden Arten schreiben:
Verwenden Sie
Camera2CameraControl, um Attribute für die zugrunde liegendeCaptureRequestfestzulegen, z. B. den Autofokusmodus.Erweitere eine CameraX-
UseCasemit einerCamera2Interop.Extender. So kannst du Properties für die CaptureRequest festlegen, genau wie beiCamera2CameraControl. Außerdem stehen dir zusätzliche Einstellungen zur Verfügung, z. B. die Festlegung des Stream-Anwendungsfalls, um die Kamera für dein Nutzungsszenario zu optimieren. Weitere Informationen finden Sie unter Stream-Anwendungsfälle für eine bessere Leistung verwenden.
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 den Videoanrufstream verfügbar ist. Verwenden Sie dann einen Camera2Interop.Extender, um den zugrunde liegenden Stream-Anwendungsfall 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)
Zusätzliche Ressourcen
Weitere Informationen zu CameraX findest du in den folgenden zusätzlichen Ressourcen.
Codelab
Codebeispiel