Architektura CameraX

Na tej stronie omówiliśmy architekturę CameraX, w tym jej strukturę, sposób pracy z interfejsem API, sposób pracy z cyklem życia oraz sposób łączenia przypadków użycia.

Struktura CameraX

Za pomocą CameraX możesz nawiązać połączenie z kamerą urządzenia za pomocą abstrakcji zwanej przypadkiem użycia. Dostępne są te przypadki użycia:

  • Podgląd: przyjmuje powierzchnię do wyświetlania podglądu, np. PreviewView.
  • Analiza obrazu: udostępnia bufory dostępne dla procesora na potrzeby analizy, np. na potrzeby systemów uczących się.
  • Robienie zdjęć: robi i zapisuje zdjęcie.
  • Nagrywanie wideo: nagrywanie wideo 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).

CameraController

CameraController zapewnia większość funkcji podstawowych CameraX w jednej klasie. Wymaga niewiele kodowania, a do tego automatycznie obsługuje inicjowanie aparatu, zarządzanie przypadkiem użycia, obrót celu, dotykanie ostrości, powiększanie przez ściąganie palców i inne czynności. Konkretna klasa, która rozszerza zakres 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ć ImageCapture lub ImageAnalysis albo włączyć VideoCapture, użyj metody setEnabledUseCases().

Więcej informacji o CameraController znajdziesz w przykładowym skanerze kodów QR lub CameraControllerfilmie wprowadzającym.

Dostawca kamery

Interfejs CameraProvider jest nadal łatwy w użyciu, ale ponieważ to deweloper aplikacji zajmuje się większą konfiguracją, ma więcej możliwości dostosowania konfiguracji, np. włączenie rotacji obrazu wyjściowego lub ustawienie formatu obrazu wyjściowego w narzędziu ImageAnalysis. Możesz też użyć niestandardowego Surface do podglądu aparatu, co zapewnia większą elastyczność. W przypadku klasy CameraController musisz użyć PreviewView. Użycie dotychczasowego kodu Surface może być przydatne, jeśli jest on już używany w innych częściach aplikacji.

Możesz skonfigurować przypadki użycia za pomocą metod set() i finalizować je 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 umieszczania w metodach onResume()onPause() konkretnych wywołań metody rozpoczęcia i zatrzymania, aplikacja określa cykl życia, z którym ma być powiązana kamera, za pomocą atrybutu cameraProvider.bindToLifecycle(). Cykl życia informuje CameraX, kiedy skonfigurować sesję rejestrowania aparatu, i zapewnia odpowiednie zmiany stanu aparatu, aby pasowały do przejść w 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ówPrzechwytywanie filmów.

Podczas wyświetlania podglądu aplikacja Surface wchodzi w interakcję z urządzeniem. 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 aplikacji CameraX (wersja demonstracyjna).

Cykle życia CameraX

CameraX obserwuje cykl życia, aby określić, kiedy otworzyć kamerę, kiedy utworzyć sesję rejestrowania i kiedy ją zatrzymać oraz kiedy zamknąć. 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.
  • Utworzenie niestandardowego komponentu cyklu życia i używanie go do ręcznego sterowania cyklem życia kamery

Jeśli chcesz rozdzielić właścicieli cyklu życia przypadków użycia widoku i aparatu (np. jeśli używasz niestandardowego cyklu życia lub fragmentu do zachowania), musisz zadbać o to, aby wszystkie przypadki użycia były odłączone od CameraX. Możesz to zrobić za pomocą metody ProcessCameraProvider.unbindAll() lub odłączając poszczególne przypadki użycia. Z kolei, gdy powiążesz przypadki użycia z cyklem życia, możesz zezwolić aplikacji CameraX na otwieranie i zamykanie sesji przechwytywania oraz usuwanie 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 zostaną bezpiecznie usunięte, nie zużywając żadnych zasobów.

Niestandardowi właściciele cyklu życia

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

Poniższy przykładowy kod pokazuje, jak utworzyć prosty niestandardowy obiekt 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 komponentu LifecycleOwner aplikacja może umieszczać przejścia stanów w wybranych punktach kodu. 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ą działać jednocześnie. Chociaż przypadki użycia można powiązać z cyklem życia, lepiej jest powiązać wszystkie przypadki użycia za pomocą pojedynczego wywołania funkcji CameraProcessProvider.bindToLifecycle(). Więcej informacji o najlepszych rozwiązaniach dotyczących zmian w konfiguracji znajdziesz w artykule Zarządzanie zmianami w konfiguracji.

W poniższym przykładowym kodzie aplikacja określa 2 przypadki użycia, które należy utworzyć i uruchomić jednocześnie. Określa ona też cykl życia, który ma być używany w obu przypadkach użycia, tak aby oba były uruchamiane i zatrzymywane zgodnie z tym cyklem.

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, ImageAnalysisImageCapture. Reklamy

  • Każdy przypadek użycia może działać samodzielnie. Aplikacja może na przykład nagrać film bez korzystania z podglądu.
  • Gdy rozszerzenia są włączone, tylko kombinacja ImageCapturePreview gwarantuje działanie. W zależności od implementacji OEM może nie być możliwe dodanie atrybutu ImageAnalysis. W przypadku użycia typu VideoCapture nie można włączyć rozszerzeń. Szczegóły znajdziesz w dokumentacji dotyczącej rozszerzeń.
  • W zależności od możliwości aparatu niektóre aparaty mogą obsługiwać tę kombinację w trybach o niższej rozdzielczości, ale nie mogą obsługiwać tej samej kombinacji w niektórych wyższych rozdzielczościach.
  • Na urządzeniach z poziomem sprzętu kamery FULL lub niższym połączenie funkcji Preview, VideoCapture, ImageCapture lub ImageAnalysis może zmusić CameraX do powielenia strumienia danych PRIV kamery dla PreviewVideoCapture. Takie duplikowanie, nazywane udostępnianiem strumienia, umożliwia jednoczesne korzystanie z tych funkcji, ale powoduje wzrost zapotrzebowania na przetwarzanie. Może to spowodować nieco większą latencję 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 jest urządzeniem 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 o uprawnienia aplikacji.

Wymagania

Aplikacja CameraX wymaga tych wersji minimalnych:

  • Poziom interfejsu API Androida 21
  • Składniki 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 repozitorium 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 Androida dodaj:

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

Dodaj do pliku build.gradle dla aplikacji te informacje:

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

Więcej informacji o konfigurowaniu aplikacji w celu dostosowania jej do tych wymagań znajdziesz w artykule Oświadczanie zależności.

Współpraca CameraX z Camera2

Biblioteka CameraX jest oparta na interfejsie Camera2 i zawiera sposoby odczytu i nawet zapisu właściwości w ramach implementacji Camera2. Więcej informacji znajdziesz w pakiecie Interop.

Aby dowiedzieć się więcej o tym, jak w aplikacji AparatX skonfigurowano właściwości Aparatu2, użyj polecenia Camera2CameraInfo, aby odczytać bazowe informacje CameraCharacteristics. Możesz też zapisać właściwości Camera2 w jednym z tych 2 sposobów:

Poniższy przykładowy kod wykorzystuje przypadki użycia strumienia do optymalizacji na potrzeby rozmowy wideo. Użyj Camera2CameraInfo, aby sprawdzić, czy dostępnych jest więcej niż 1 przypadek użycia strumienia rozmów wideo. 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

  • Pierwsze kroki z AparatemX
  • Przykładowy kod

  • Przykładowe aplikacje AparatuX