Na tej stronie omawiamy architekturę systemu Aparat X, w tym jego strukturę, korzystanie z interfejsu API, korzystanie z cykli życia i łączenie przypadków użycia.
Struktura systemu CameraX
Za pomocą aplikacji CameraX możesz połączyć się z kamerą urządzenia abstrakcja, czyli tzw. przypadek użycia. Dostępne są te przypadki użycia:
- Podgląd: akceptuje powierzchnię do wyświetlania podglądu, np.
PreviewView
- Analiza obrazu: udostępnia bufory dostępne dla procesora do analizy, takie jak systemów uczących się.
- Robienie zdjęć: robi i zapisuje zdjęcie.
- Nagrywanie obrazu wideo: nagrywanie obrazu i dźwięku za pomocą
VideoCapture
.
Przypadki użycia można łączyć i aktywować jednocześnie. Aplikacja może na przykład umożliwić użytkownikowi wyświetlenie obrazu z kamery w ramach przypadku użycia podglądu, uwzględnić przypadek użycia analizy obrazu, który określa, czy osoby na zdjęciu się uśmiechają, oraz uwzględnić przypadek użycia rejestrowania obrazu, aby zrobić zdjęcie, gdy tak się stanie.
Model interfejsu API
Aby pracować z biblioteką, musisz określić:
- Pożądany przypadek użycia z opcjami konfiguracji.
- Co zrobić z danymi wyjściowymi przez dołączenie słuchaczy.
- Przewidywany przebieg, np. kiedy włączyć kamery i kiedy generować dane, poprzez powiązanie przypadku użycia z cyklem życia architektury Androida.
Istnieją 2 sposoby tworzenia aplikacji CameraX: CameraController
(jeśli chcesz korzystać z CameraX w najprostszy sposób) lub CameraProvider
(jeśli potrzebujesz większej elastyczności).
Kontroler aparatu
CameraController
udostępnia większość podstawowych funkcji CameraX w jednym
zajęcia. Wymaga ona niewielkiej ilości kodu konfiguracyjnego i automatycznie obsługuje inicjowanie aparatu, zarządzanie przypadkami użycia, obracanie celu, skupianie przez dotknięcie oraz powiększanie przez zbliżenie. Klasa betonu, która rozciąga się do obiektu CameraController
, to
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);
Domyślne wartości UseCase
dla CameraController
to Preview
, ImageCapture
i ImageAnalysis
. Aby wyłączyć funkcję ImageCapture
lub ImageAnalysis
albo ją wyłączyć
VideoCapture
włączone, użyj
setEnabledUseCases()
.
Więcej informacji o CameraController
znajdziesz w przykładowym skanerze kodów QR lub CameraController
filmie wprowadzającym.
CameraProvider
Aplikacja CameraProvider
jest nadal łatwa w użyciu, ale to dlatego, że to deweloper
po konfiguracji masz więcej możliwości dostosowania konfiguracji,
np. włączyć rotację obrazu wyjściowego
lub ustawić format obrazu wyjściowego
ImageAnalysis
Możesz też użyć niestandardowego ustawienia Surface
, aby umożliwić podgląd z aparatu
dla większej elastyczności. Natomiast w przypadku kontrolera CameraController należy używać
PreviewView
Użycie istniejącego kodu Surface
może być przydatne, jeśli
już zawiera dane wejściowe
do innych części aplikacji.
Przypadki użycia konfigurujesz za pomocą metod set()
, a ich finalizację wykonujesz za pomocą metody build()
. Każdy obiekt przypadku użycia udostępnia zestaw interfejsów API związanych z konkretnym przypadkiem użycia. Na przykład przypadek użycia polegający na robieniu zdjęć zawiera wywołanie metody takePicture()
.
Zamiast stosować konkretne wywołania metod uruchamiania i zatrzymywania w
onResume()
i onPause()
, aplikacja określa cykl życia, który należy powiązać
za pomocą aparatu,
cameraProvider.bindToLifecycle()
.
Ten cykl życia informuje następnie CameraX, kiedy skonfigurować sesję nagrywania
i dba o to, aby stan kamery odpowiednio się zmieniał, odpowiednio do zmian cyklu życia.
Aby dowiedzieć się, jak wdrożyć poszczególne przypadki użycia, zapoznaj się z artykułami Wdrażanie podglądu, Analiza obrazów, Przechwytywanie obrazów i Przechwytywanie filmów.
Przypadek użycia w wersji testowej wchodzi w interakcję z tagiem
Surface
w sieci reklamowej. Aplikacje: utwórz przypadek użycia z opcjami konfiguracji za pomocą tego kodu:
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();
Więcej przykładowego kodu znajdziesz w oficjalnej przykładowej aplikacji CameraX.
Cykle życia CameraX
Aparat CameraX obserwuje cykl życia, aby określić, kiedy otworzyć aparat, a kiedy utworzyć sesję przechwytywania i zatrzymać, a kiedy wyłączyć. Interfejsy API do konkretnych zastosowań udostępniają wywołania metod i wywołania zwrotne, które umożliwiają monitorowanie postępu.
Jak wyjaśniono w sekcji Połącz przypadki użycia, możesz połączyć niektóre kombinacje przypadków użycia w jedną ścieżkę cyklu życia. Jeśli Twoja aplikacja musi obsługiwać przypadki użycia, których nie można połączyć, możesz wykonać jedną z tych czynności:
- Pogrupuj podobne przypadki użycia w kilka fragmentów, a potem przełączaj się między nimi.
- Tworzenie niestandardowego komponentu cyklu życia i używanie go do ręcznego sterowania kamerą cykl życia
Jeśli odłączysz przykłady użycia widoku i kamery Właściciele cyklu życia (np.
jeśli zastosujesz niestandardowy cykl życia
lub zapas
fragment),
musi zagwarantować, że żadne przypadki użycia nie będą powiązane z Aparatem X za pomocą funkcji
ProcessCameraProvider.unbindAll()
.
lub oddzielając każdy przypadek użycia z osobna. Zamiast tego,
do danego cyklu życia, możesz pozwolić aplikacji CameraX
zarządzać otwieraniem i zamykaniem sesji przechwytywania oraz usuwaniem powiązań przypadków użycia.
Jeśli wszystkie funkcje kamery odpowiadają cyklowi życia pojedynczego komponentu z uwzględnieniem cyklu życia, takiego jak AppCompatActivity
lub fragment AppCompat
, to użycie cyklu życia tego komponentu podczas wiązania wszystkich pożądanych przypadków użycia zapewni, że funkcje kamery będą gotowe, gdy komponent z uwzględnieniem cyklu życia będzie aktywny, a w przeciwnym razie będzie bezpiecznie usuwany, nie zużywając żadnych zasobów.
Właściciele niestandardowych cyklów życia
W bardziej zaawansowanych przypadkach możesz utworzyć
LifecycleOwner
, aby włączyć
bezpośrednio kontrolować cykl życia sesji w aplikacji CameraX, zamiast tworzyć powiązanie z
standardowy Android LifecycleOwner
.
Poniższy przykładowy kod pokazuje, jak utworzyć prosty niestandardowy element LifecycleOwner:
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; } }
Za pomocą tego interfejsu LifecycleOwner
aplikacja może wprowadzać zmiany stanów w dowolny sposób
punkty w kodzie. Więcej informacji o wdrażaniu tej funkcji w aplikacji znajdziesz w artykule Wdrażanie niestandardowego obiektu LifecycleOwner.
Przypadki użycia równoczesnego
Przypadki użycia mogą być wykonywane równolegle. Przypadki użycia można sekwencyjnie powiązać z tagiem
cyklu życia, lepiej powiązać wszystkie przypadki użycia za pomocą jednego wywołania
CameraProcessProvider.bindToLifecycle()
Więcej informacji o najlepszych
dotyczące zmian konfiguracji można znaleźć w sekcji Obsługa konfiguracji
zmian.
W poniższym przykładowym kodzie aplikacja określa 2 przypadki użycia do utworzenia i jednocześnie. Określa też cykl życia, który będzie używany zarówno w przypadku aby rozpoczynały i kończyły się zgodnie z cyklem życia.
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 umożliwia jednoczesne używanie po 1 instancji usług Preview
, VideoCapture
, ImageAnalysis
i ImageCapture
. Reklamy
- Każdy przypadek użycia może działać samodzielnie. Aplikacja może na przykład nagrywać film bez użycia podglądu.
- Gdy rozszerzenia są włączone, tylko kombinacja
ImageCapture
iPreview
gwarantuje działanie. W zależności od wdrożenia OEM może nie udać się też dodaćImageAnalysis
; rozszerzenia nie mogą w przypadku użycia funkcjiVideoCapture
. Zajrzyj do Dokument z informacjami o rozszerzeniach . - W zależności od możliwości kamery niektóre z nich mogą obsługiwać takie połączenie z niższą rozdzielczością, ale niektóre z nich nie obsługują tej samej kombinacji. i większej rozdzielczości.
- Na urządzeniach z kamerą na poziomie
FULL
lub niższym, łączniePreview
:VideoCapture
iImageCapture
lubImageAnalysis
mogą wymuszać stosowanie CameraX aby zduplikować strumieńPRIV
z kamery dotyczący elementówPreview
iVideoCapture
. Ta duplikacja, zwana udostępnianiem strumienia, umożliwia jednoczesne korzystanie z tych funkcji, ale wiąże się z większymi wymaganiami dotyczącymi przetwarzania. Możesz w rezultacie mogą wystąpić nieco większe opóźnienia i krótszy czas pracy na baterii.
obsługiwany poziom sprzętu,
można pobrać z Camera2CameraInfo
. Na przykład ten kod
sprawdza, czy domyślny tylny aparat to urządzenie z systemem LEVEL_3
:
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; }
Uprawnienia
Twoja aplikacja będzie potrzebować uprawnienia CAMERA
. Aby zapisywać obrazy w plikach, musisz też mieć uprawnienia WRITE_EXTERNAL_STORAGE
, z wyjątkiem urządzeń z Androidem 10 lub nowszym.
Więcej informacji o konfigurowaniu uprawnień aplikacji znajdziesz w artykule Prośba Uprawnienia aplikacji.
Wymagania
Aplikacja CameraX wymaga tych wersji minimalnych:
- Interfejs API Androida, poziom 21
- Komponenty architektury Androida 1.1.1
W przypadku aktywności uwzględniających cykl życia użyj wartości FragmentActivity
lub AppCompatActivity
.
Deklarowanie zależności
Aby dodać zależność od CameraX, musisz dodać do projektu repository Google Maven.
Otwórz plik settings.gradle
projektu i dodaj repozytorium google()
, jak pokazano poniżej:
Groovy
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
Kotlin
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
Na końcu bloku kodu Android dodaj następujący ciąg:
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" } }
Do pliku build.gradle
każdego modułu dodaj te elementy:
Odlotowe
dependencies { // CameraX core library using the camera2 implementation def camerax_version = "1.5.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.5.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}") }
Więcej informacji o konfigurowaniu aplikacji w celu dostosowania jej do tych wymagań znajdziesz w artykule Oświadczanie zależności.
Współdziałanie aparatu CameraX z Aparatem 2
Aparat X działa w ramach Aparatu 2, a Aparat X umożliwia odczyt, a nawet zapis w implementacji Camera2. Więcej informacji znajdziesz w pakiecie Interop.
Aby dowiedzieć się więcej o tym, jak CameraX skonfigurowała właściwości Camera2, otwórz plik Camera2CameraInfo
, aby odczytać ukryte właściwości CameraCharacteristics
. Możesz też zapisać nazwę bazową aparatu 2
właściwości w jednej z dwóch ścieżek:
Użyj
Camera2CameraControl
, który pozwala ustawiać właściwości w podstawowejCaptureRequest
, np. tryb autofokusu.Rozszerz aparat CameraX
UseCase
za pomocąCamera2Interop.Extender
Pozwala to ustawić właściwości w CaptureRequest, tak jakCamera2CameraControl
Daje też dostęp do dodatkowych ustawień, takich jak ustawienie przypadku użycia strumienia i optymalizować kamerę pod kątem scenariusza użytkowania. Więcej informacji znajdziesz w artykule Przypadki użycia przepływu danych na potrzeby poprawy wydajności.
Poniższa próbka kodu wykorzystuje przypadki użycia strumienia do optymalizacji rozmowy wideo.
Użyj formatu Camera2CameraInfo
, aby sprawdzić, czy przypadek użycia strumienia rozmowy wideo jest dostępny. Następnie użyj parametru Camera2Interop.Extender
, aby ustawić podstawowy przypadek użycia strumienia.
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)
Dodatkowe materiały
Więcej informacji o CameraX znajdziesz w tych dodatkowych materiałach.
Ćwiczenia z programowania
Przykładowy kod