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, einen sogenannten Anwendungsfall, mit der Kamera eines Geräts interagieren. Die folgenden Anwendungsfälle sind verfügbar:
- Vorschau: Akzeptiert eine Oberfläche zur Anzeige einer Vorschau, z. B. eine
PreviewView. - Bildanalyse: Stellt CPU-zugängliche Puffer für die Analyse bereit, z. B. für maschinelles Lernen.
- Bildaufnahme: Nimmt ein Foto auf und speichert es.
- Videoaufnahme: Nimmt Video und Audio mit
VideoCaptureauf.
Anwendungsfälle können kombiniert und gleichzeitig aktiv sein. Beispielsweise kann eine App dem Nutzer mit einem Vorschau-Anwendungsfall das Bild anzeigen, das die Kamera sieht. Ein Bildanalyse-Anwendungsfall kann ermitteln, ob die Personen auf dem Foto lächeln, und ein Bildaufnahme-Anwendungsfall kann ein Foto aufnehmen, sobald sie lächeln.
API-Modell
Wenn Sie mit der Bibliothek arbeiten möchten, müssen Sie Folgendes angeben:
- Den gewünschten Anwendungsfall mit Konfigurationsoptionen.
- Was mit den Ausgabedaten geschehen soll, indem Sie Listener anhängen.
- Den beabsichtigten Ablauf, z. B. wann Kameras aktiviert und wann Daten erzeugt werden sollen, indem Sie den Anwendungsfall an Android Architecture Lifecycles binden.
Es gibt zwei Möglichkeiten, eine CameraX-App zu schreiben: mit
CameraController (ideal, wenn
Sie CameraX auf die einfachste Weise verwenden möchten) oder mit
CameraProvider (ideal, wenn Sie
mehr Flexibilität benötigen).
CameraController
Ein CameraController bietet die meisten CameraX-Kernfunktionen in einer einzigen Klasse. Er erfordert wenig Einrichtungscode und verarbeitet automatisch die Kamerainitialisierung, die Anwendungsfallverwaltung, die Zielrotation, das Tippen zum Fokussieren, das Zoomen mit zwei Fingern 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
setEnabledUseCases()
Methode.
Weitere Informationen zur Verwendung von CameraController finden Sie im
Beispiel für den QR-Code-Scanner
oder im
CameraController Grundlagen-Video.
CameraProvider
Ein CameraProvider ist weiterhin einfach zu verwenden. Da der App-Entwickler jedoch mehr Einrichtungsschritte ausführt, gibt es mehr Möglichkeiten, die Konfiguration anzupassen, z. B. die Rotation des Ausgabebilds 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. Mit CameraController müssen Sie 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 Methode build() ab. Jedes Anwendungsfallobjekt bietet eine Reihe von anwendungsfallspezifischen APIs. Der Anwendungsfall für die Bildaufnahme bietet beispielsweise einen takePicture()-Methodenaufruf.
Statt dass eine Anwendung bestimmte Methodenaufrufe für Start und Stopp in
onResume() und onPause() platziert, gibt die Anwendung mit
cameraProvider.bindToLifecycle() einen Lebenszyklus an, mit dem
die Kamera verknüpft werden soll.
Dieser Lebenszyklus informiert CameraX dann darüber, wann die Kameraaufnahmesitzung konfiguriert werden soll, und sorgt dafür, dass sich der Kamerastatus entsprechend den Lebenszyklusübergängen ändert.
Implementierungsschritte für die einzelnen Anwendungsfälle finden Sie unter Implementierung einer Vorschau, Bilder analysieren, Bild aufnahme und Videoaufnahme.
Der Anwendungsfall für die Vorschau interagiert mit einer
Surface zur Anzeige. Anwendungen erstellen den Anwendungsfall mit Konfigurationsoptionen mit dem folgenden Code:
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 sie beendet 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:
- Gruppieren Sie kompatible Anwendungsfälle in mehreren Fragmenten und wechseln Sie dann zwischen den Fragmenten.
- Erstellen Sie eine benutzerdefinierte Lebenszykluskomponente und verwenden Sie sie, um den Lebenszyklus der Kamera manuell zu steuern.
Wenn Sie die Lebenszyklusinhaber Ihrer Ansichts- und Kamera-Anwendungsfälle entkoppeln (z. B.
wenn Sie einen benutzerdefinierten Lebenszyklus oder ein Fragment mit Beibehaltungverwenden), dann müssen Sie
dafür sorgen, dass alle Anwendungsfälle mit
ProcessCameraProvider.unbindAll()
von CameraX getrennt werden oder indem Sie jeden Anwendungsfall einzeln trennen. Alternativ können Sie, wenn Sie Anwendungsfälle an einen Lebenszyklus binden, CameraX die Verwaltung des Öffnens und Schließens der Aufnahmesitzung und des Trennens der Anwendungsfälle überlassen.
Wenn alle Ihre Kamerafunktionen dem Lebenszyklus einer einzelnen
lebenszyklusfähigen 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 verfügbar sind,
wenn die lebenszyklusfähige Komponente aktiv ist, und andernfalls sicher verworfen werden, ohne
Ressourcen zu verbrauchen.
Benutzerdefinierte LifecycleOwner
In erweiterten Fällen können Sie ein benutzerdefiniertes
LifecycleOwner erstellen, damit Ihre
App den Lebenszyklus der CameraX-Sitzung explizit steuern kann, anstatt ihn an ein
Standard-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 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 sie 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 einer Instanz von Preview, VideoCapture, ImageAnalysis und ImageCapture. Außerdem
- kann jeder Anwendungsfall eigenständig funktionieren. Beispielsweise kann eine App Videos aufnehmen, ohne eine Vorschau zu verwenden.
- Wenn Erweiterungen aktiviert sind, funktioniert garantiert 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 in der Referenzdokumentation zu Erweiterungen. - Je nach Kamerafunktion unterstützen einige Kameras die Kombination möglicherweise in Modi mit niedrigerer Auflösung, aber nicht bei einigen höheren Auflösungen.
- Auf Geräten mit der Kamera-Hardwareebene
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 aber zu einem höheren Verarbeitungsaufwand. Dadurch kann es zu einer etwas höheren Latenz und einer kürzeren Akkulaufzeit kommen.
Die unterstützte Hardwareebene
kann von Camera2CameraInfo abgerufen werden. Der folgende Code prüft beispielsweise, ob die standardmäßige nach hinten gerichtete 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
CAMERA Berechtigung. Zum
Speichern von Bildern in Dateien ist auch die
WRITE_EXTERNAL_STORAGE
Berechtigung 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-Ebene 21
- Android Architecture Components 1.1.1
Verwenden Sie für lebenszyklusfähige Aktivitäten
FragmentActivity oder
AppCompatActivity.
Abhängigkeiten deklarieren
Für eine Abhängigkeit von CameraX 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() wie unten gezeigt hinzu:
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 App Folgendes hinzu:
Groovy
dependencies { // CameraX core library using the camera2 implementation def camerax_version = "1.7.0-alpha01" // 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-alpha01" // 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 App gemäß diesen Anforderungen, siehe 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. Weitere Informationen finden Sie im Interop-Paket.
Weitere Informationen dazu, wie CameraX Camera2-Eigenschaften konfiguriert hat, finden Sie unter
Camera2CameraInfo
, um die zugrunde liegenden CameraCharacteristics zu lesen. Sie können die zugrunde liegenden Camera2-Eigenschaften auch auf eine der folgenden beiden Arten schreiben:
Verwenden Sie
Camera2CameraControl, mit dem Sie Eigenschaften für die zugrunde liegendeCaptureRequest, z. B. den Autofokusmodus festlegen können.Erweitern Sie einen CameraX
UseCasemit einemCamera2Interop.Extender. So können Sie Eigenschaften für die CaptureRequest festlegen, genau wieCamera2CameraControl. Außerdem haben Sie einige zusätzliche Steuerelemente, z. B. zum Festlegen des Stream-Anwendungsfalls, um die Kamera für Ihr Nutzungsszenario zu optimieren. Weitere Informationen finden Sie unter Stream-Anwendungsfälle für eine bessere Leistung.
Im folgenden Codebeispiel werden Stream-Anwendungsfälle verwendet, um die Leistung für einen Videoanruf zu optimieren.
Verwenden Sie Camera2CameraInfo
, um abzurufen, ob der Stream-Anwendungsfall für Videoanrufe 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 finden Sie in den folgenden zusätzlichen Ressourcen.
Codelab
Codebeispiel