Architektura CameraX

Na tej stronie opisujemy architekturę CameraX, w tym jej strukturę, sposób pracy z interfejsem API, sposób pracy z cyklami życia i sposób łączenia przypadków użycia.

Struktura CameraX

Możesz używać CameraX do komunikacji z aparatem urządzenia za pomocą abstrakcji nazywanej przypadkiem użycia. Dostępne są te przypadki użycia:

• Preview: akceptuje powierzchnię do wyświetlania podglądu, np. PreviewView.
• Analiza obrazu: udostępnia bufory dostępne dla procesora na potrzeby analizy, np. na potrzeby uczenia maszynowego.
• Robienie zdjęć: umożliwia zrobienie i zapisanie zdjęcia.
• Przechwytywanie obrazu: przechwytywanie obrazu i dźwięku za pomocą VideoCapture.

Przypadki użycia można łączyć i aktywować jednocześnie. Na przykład aplikacja może umożliwiać użytkownikowi wyświetlanie obrazu z kamery za pomocą przypadku użycia podglądu, analizować obraz, aby określić, czy osoby na zdjęciu się uśmiechają, i robić zdjęcie, gdy tak jest.

Model interfejsu API

Aby korzystać z biblioteki, musisz określić te elementy:

• żądany przypadek użycia z opcjami konfiguracji;
• co zrobić z danymi wyjściowymi, dołączając detektory.
• zamierzony przepływ, np. kiedy włączyć kamery i kiedy generować dane, przez powiązanie przypadku użycia z cyklami życia architektury Androida.

Aplikację CameraX można napisać na 2 sposoby: za pomocą CameraController (świetne rozwiązanie, jeśli chcesz używać CameraX w najprostszy sposób) lub CameraProvider (świetne rozwiązanie, jeśli potrzebujesz większej elastyczności).

Kontroler aparatu

CameraController udostępnia większość głównej funkcjonalności CameraX w jednej klasie. Wymaga niewielkiej ilości kodu konfiguracji i automatycznie obsługuje inicjowanie aparatu, zarządzanie przypadkami użycia, obracanie celu, ustawianie ostrości przez dotknięcie, powiększanie przez rozciągnięcie i inne funkcje. Klasa konkretna, która rozszerza klasę CameraController, to LifecycleCameraController.

val previewView: PreviewView = viewBinding.previewView
var cameraController = LifecycleCameraController(baseContext)
cameraController.bindToLifecycle(this)
cameraController.cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
previewView.controller = cameraController

Domyślne UseCase dla CameraController to Preview, ImageCapture i ImageAnalysis. Aby wyłączyć ImageCapture lub ImageAnalysis albo włączyć VideoCapture, użyj metody setEnabledUseCases().

Więcej zastosowań CameraController znajdziesz w przykładzie skanera kodów QR lub w filmie o podstawach CameraController.

CameraProvider

CameraProvider jest nadal łatwy w użyciu, ale ponieważ deweloper aplikacji zajmuje się większą częścią konfiguracji, istnieje więcej możliwości dostosowania konfiguracji, takich jak włączenie obracania obrazu wyjściowego lub ustawienie formatu pliku graficznego obrazu wyjściowego w ImageAnalysis. Możesz też użyć niestandardowego elementu Surface do podglądu z kamery, co zapewnia większą elastyczność, podczas gdy w przypadku CameraController musisz użyć elementu PreviewView. Użycie dotychczasowego kodu Surface może być przydatne, jeśli jest on już używany w innych częściach aplikacji.

Przypadki użycia konfigurujesz za pomocą metod set() i finalizujesz je metodą build(). Każdy obiekt przypadku użycia udostępnia zestaw interfejsów API związanych z danym przypadkiem użycia. Na przykład przypadek użycia robienia zdjęć udostępnia wywołanie metody takePicture().

Zamiast umieszczać konkretne wywołania metod uruchamiania i zatrzymywania w onResume() i onPause(), aplikacja określa cykl życia, z którym ma być powiązany aparat, za pomocą cameraProvider.bindToLifecycle(). Ten cykl życia informuje CameraX, kiedy skonfigurować sesję przechwytywania z kamery, i zapewnia, że stan kamery zmienia się odpowiednio do zmian cyklu życia.

Instrukcje implementacji w przypadku poszczególnych zastosowań znajdziesz w artykułach Implementowanie podglądu, Analizowanie obrazów, Robienie zdjęć i Nagrywanie filmów.

Przypadek użycia podglądu wchodzi w interakcję z Surface, aby wyświetlić obraz. Applications, utwórz przypadek użycia z opcjami konfiguracji za pomocą tego kodu:

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())
Architecture.kt

Więcej przykładowego kodu znajdziesz w oficjalnej przykładowej aplikacji CameraX.

Cykle życia CameraX

CameraX obserwuje cykl życia, aby określić, kiedy otworzyć aparat, kiedy utworzyć sesję przechwytywania, a kiedy zatrzymać i zamknąć. Interfejsy API przypadków użycia udostępniają wywołania metod i wywołania zwrotne do monitorowania postępów.

Jak wyjaśniono w sekcji Łączenie przypadków użycia, niektóre kombinacje przypadków użycia można powiązać z jednym cyklem życia. Jeśli aplikacja musi obsługiwać przypadki użycia, których nie można połączyć, możesz wykonać jedną z tych czynności:

• Zgrupuj zgodne przypadki użycia w więcej niż 1 fragmencie, a następnie przełączaj się między fragmentami.
• Utwórz niestandardowy komponent cyklu życia i użyj go do ręcznego sterowania cyklem życia kamery.

Jeśli rozdzielisz właścicieli cyklu życia przypadków użycia widoku i aparatu (np. jeśli używasz niestandardowego cyklu życia lub zachowanego fragmentu), musisz się upewnić, że wszystkie przypadki użycia są odłączone od CameraX za pomocą ProcessCameraProvider.unbindAll() lub przez odłączenie każdego przypadku użycia osobno. Możesz też powiązać przypadki użycia z cyklem życia, aby CameraX zarządzała otwieraniem i zamykaniem sesji przechwytywania oraz odłączaniem przypadków użycia.

Jeśli wszystkie funkcje aparatu odpowiadają cyklowi życia pojedynczego komponentu uwzględniającego cykl życia, takiego jak AppCompatActivity lub fragment AppCompat, użycie cyklu życia tego komponentu podczas wiązania wszystkich pożądanych przypadków użycia zapewni, że funkcje aparatu będą gotowe, gdy komponent uwzględniający cykl życia będzie aktywny, i bezpiecznie usunięte, gdy nie będzie aktywny, dzięki czemu nie będą zużywać żadnych zasobów.

Niestandardowe obiekty LifecycleOwner

W bardziej zaawansowanych przypadkach możesz utworzyć niestandardowy obiekt LifecycleOwner, aby umożliwić aplikacji bezpośrednie kontrolowanie cyklu życia sesji CameraX zamiast wiązania go ze standardowym obiektem LifecycleOwner Androida.

Poniższy przykładowy kod pokazuje, jak utworzyć prosty niestandardowy obiekt LifecycleOwner:

class CustomLifecycle : LifecycleOwner {
    private val lifecycleRegistry: LifecycleRegistry

    init {
        lifecycleRegistry = LifecycleRegistry(this)
        lifecycleRegistry.currentState = Lifecycle.State.CREATED
    }
    // ...
    fun doOnResume() {
        lifecycleRegistry.currentState = State.RESUMED
    }
    // ...
    override val lifecycle: Lifecycle
        get() = lifecycleRegistry
}
Architecture.kt

Za pomocą tego LifecycleOwner aplikacja może umieszczać przejścia między stanami w wybranych miejscach w kodzie. Więcej informacji o implementowaniu tej funkcji w aplikacji znajdziesz w artykule Implementowanie niestandardowego LifecycleOwner.

Przypadki użycia równoczesnego

Przypadki użycia mogą być realizowane jednocześnie. Chociaż przypadki użycia można sekwencyjnie powiązać z cyklem życia, lepiej jest powiązać wszystkie przypadki użycia za pomocą jednego wywołania CameraProcessProvider.bindToLifecycle(). Więcej informacji o sprawdzonych metodach wprowadzania zmian w konfiguracji znajdziesz w artykule Obsługa zmian w konfiguracji.

W poniższym przykładowym kodzie aplikacja określa 2 przypadki użycia, które mają zostać utworzone i uruchomione jednocześnie. Określa też cykl życia, który ma być używany w obu przypadkach, dzięki czemu oba będą uruchamiane i zatrzymywane zgodnie z cyklem życia.

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)
    )
}
Architecture.kt

CameraX umożliwia jednoczesne korzystanie z jednej instancji Preview, VideoCapture, ImageAnalysis i ImageCapture. Reklamy

• Każdy przypadek użycia może działać samodzielnie. Na przykład aplikacja może nagrywać filmy bez używania podglądu.
• Gdy rozszerzenia są włączone, gwarantowane jest działanie tylko kombinacji ImageCapture i Preview. W zależności od implementacji OEM dodanie ImageAnalysis może nie być możliwe. Nie można włączyć rozszerzeń w przypadku VideoCapture. Szczegółowe informacje znajdziesz w dokumentacji rozszerzenia.
• W zależności od możliwości aparatu niektóre aparaty mogą obsługiwać kombinację w trybach niższej rozdzielczości, ale nie w niektórych wyższych rozdzielczościach.
• Na urządzeniach z poziomem sprzętowym aparatu FULL lub niższym połączenie Preview, VideoCapture i ImageCapture lub ImageAnalysis może wymusić na CameraX zduplikowanie strumienia PRIV aparatu dla Preview i VideoCapture. To powielanie, nazywane udostępnianiem strumienia, umożliwia jednoczesne korzystanie z tych funkcji, ale wiąże się z większymi wymaganiami dotyczącymi przetwarzania. Może to spowodować nieco większe opóźnienie i skrócenie czasu 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 LEVEL_3:

@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
}
Architecture.kt

Uwaga: jeśli zostanie utworzona niezgodna kombinacja przypadków użycia, przy pierwszym wywołaniu metody createCaptureSession() zostanie wygenerowany błąd środowiska wykonawczego. Jeśli do działającej sesji zostaną dodane kolejne przypadki użycia, może być konieczna ponowna konfiguracja, co może spowodować widoczne zakłócenia.

Uprawnienia

Twoja aplikacja będzie potrzebować uprawnienia CAMERA. Aby zapisywać obrazy w plikach, aplikacja będzie też wymagać uprawnienia WRITE_EXTERNAL_STORAGE, chyba że urządzenie ma Androida 10 lub nowszego.

Więcej informacji o konfigurowaniu uprawnień aplikacji znajdziesz w artykule Prośba o uprawnienia aplikacji.

Wymagania

CameraX ma te wymagania dotyczące wersji minimalnej:

• Android API na poziomie 21
• Składniki architektury Androida 1.1.1

W przypadku aktywności uwzględniających cykl życia użyj FragmentActivity lub AppCompatActivity.

Deklarowanie zależności

Aby dodać zależność od CameraX, musisz dodać do projektu repozytorium Maven Google.

Otwórz plik settings.gradle projektu i dodaj repozytorium google(), jak pokazano poniżej:

Dynamiczny

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 Android dodaj:

Dynamiczny

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"
    }
}

Dodaj do pliku build.gradle każdego modułu aplikacji te informacje:

Groovy

dependencies {
  // CameraX core library using the camera2 implementation
  def camerax_version = "1.7.0-rc01"
  // 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-rc01"
    // 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 pod kątem tych wymagań znajdziesz w artykule Deklarowanie zależności.

Interoperacyjność CameraX z Camera2

CameraX jest oparty na Camera2 i udostępnia sposoby odczytywania, a nawet zapisywania właściwości w implementacji Camera2. Szczegółowe informacje znajdziesz w pakiecie Interop.

Aby dowiedzieć się więcej o tym, jak CameraX konfiguruje właściwości Camera2, użyj Camera2CameraInfo, aby odczytać podstawowe CameraCharacteristics. Możesz też zapisać podstawowe właściwości Camera2 na jeden z tych 2 sposobów:

• Użyj Camera2CameraControl, który pozwala ustawić właściwości podstawowego CaptureRequest, takie jak tryb autofokusu.

• Rozszerzanie UseCase CameraX za pomocą Camera2Interop.Extender. Umożliwia to ustawianie właściwości w CaptureRequest, podobnie jak w przypadku Camera2CameraControl. Zapewnia też dodatkowe opcje, takie jak ustawienie przypadku użycia strumienia w celu zoptymalizowania aparatu pod kątem scenariusza użytkowania. Więcej informacji znajdziesz w artykule o używaniu przypadków użycia strumienia w celu zwiększenia wydajności.

Uwaga: ustawienie podstawowych właściwości Camera2 jest oznaczone w CameraX jako „Eksperymentalne”, ponieważ Google oczekuje, że deweloperzy będą rozumieć jego zastosowanie. Ustawione przez Ciebie wartości zastępują wszystkie wartości ustawione przez CameraX. Zalecamy robienie tego tylko wtedy, gdy jest to absolutnie konieczne, i przeprowadzenie dodatkowych testów.

Poniższy przykładowy kod wykorzystuje przypadki użycia strumienia do optymalizacji pod kątem rozmowy wideo. Użyj Camera2CameraInfo, aby sprawdzić, czy przypadek użycia strumienia rozmowy wideo jest dostępny. Następnie użyj Camera2Interop.Extender, aby ustawić przypadek użycia strumienia podstawowego.

// 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)

Dodatkowe materiały

Więcej informacji o CameraX znajdziesz w tych materiałach:

Ćwiczenie w Codelabs

Pierwsze kroki z CameraX

Przykładowy kod

Przykładowe aplikacje CameraX