Architettura di CameraX

Questa pagina illustra l'architettura di CameraX, compresa la sua struttura, come lavorare con l'API, come lavorare con i cicli di vita e come combinare i casi d'uso.

Struttura CameraX

Puoi utilizzare CameraX per interfacciarsi con la fotocamera di un dispositivo tramite un'astrazione chiamata caso d'uso. Sono disponibili i seguenti casi d'uso:

• Anteprima: accetta una piattaforma per la visualizzazione di un'anteprima, come una PreviewView.
• Analisi delle immagini: fornisce buffer accessibili alla CPU per l'analisi, ad esempio per il machine learning.
• Acquisizione di immagini: acquisisce e salva una foto.
• Acquisizione video: acquisisci video e audio con VideoCapture

I casi d'uso possono essere combinati e attivi contemporaneamente. Ad esempio, un'app può consentire all'utente di visualizzare l'immagine inquadrata dalla videocamera utilizzando un caso d'uso di anteprima, avere un caso d'uso di analisi delle immagini che determina se le persone ritratte nella foto sorride e includere un caso d'uso di acquisizione di immagini per scattare una foto quando lo sono.

Modello API

Per lavorare con la libreria, specifica quanto segue:

• Il caso d'uso desiderato con le opzioni di configurazione.
• Cosa fare con i dati di output collegando i listener.
• Il flusso previsto, ad esempio quando abilitare le fotocamere e quando generare i dati, associando il caso d'uso ai cicli di vita dell'architettura Android.

Esistono due modi per scrivere un'app CameraX: una CameraController (ideale se vuoi il modo più semplice per utilizzare CameraX) o una CameraProvider (ideale se hai bisogno di maggiore flessibilità).

Controller videocamera

Un'CameraController fornisce la maggior parte delle funzionalità di base di CameraX in un'unica classe. Richiede poco codice di configurazione e gestisce automaticamente l'inizializzazione della fotocamera, la gestione dei casi d'uso, la rotazione del target, il tocco per mettere a fuoco, pizzica per lo zoom e altro ancora. La classe concreta che estende CameraController è LifecycleCameraController.

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

PreviewView previewView = viewBinding.previewView;
LifecycleCameraController cameraController = new LifecycleCameraController(baseContext);
cameraController.bindToLifecycle(this);
cameraController.setCameraSelector(CameraSelector.DEFAULT_BACK_CAMERA);
previewView.setController(cameraController);

I valori predefiniti di UseCase per CameraController sono Preview, ImageCapture e ImageAnalysis. Per disattivare ImageCapture o ImageAnalysis, oppure per attivare VideoCapture, utilizza il metodo setEnabledUseCases().

Per ulteriori utilizzi di CameraController, consulta l'esempio di Scanner di codici QR o il video di base di CameraController.

Fornitore fotocamera

L'elemento CameraProvider è comunque facile da usare, ma poiché lo sviluppatore dell'app gestisce una parte più ampia della configurazione, esistono più opportunità per personalizzare la configurazione, ad esempio attivando la rotazione dell'immagine di output o impostando il formato dell'immagine di output in ImageAnalysis. Puoi anche utilizzare un Surface personalizzato per l'anteprima della videocamera per una maggiore flessibilità, mentre con CameraController devi utilizzare un PreviewView. L'utilizzo del codice Surface esistente potrebbe essere utile se è già un input per altre parti della tua app.

Puoi configurare i casi d'uso utilizzando i metodi set() e finalizzarli con il metodo build(). Ogni oggetto caso d'uso fornisce un insieme di API specifiche per il caso d'uso. Ad esempio, il caso d'uso di acquisizione di immagini fornisce una chiamata al metodo takePicture().

Invece di un'applicazione che effettua chiamate ai metodi di avvio e di interruzione specifiche in onResume() e onPause(), l'applicazione specifica un ciclo di vita a cui associare la videocamera utilizzando cameraProvider.bindToLifecycle(). Questo ciclo di vita informa CameraX quando deve configurare la sessione di acquisizione della videocamera e garantisce che lo stato della videocamera cambi in modo appropriato per adattarsi alle transizioni del ciclo di vita.

Per la procedura di implementazione per ogni caso d'uso, consulta Implementare un'anteprima, Analisi delle immagini, Acquisizione di immagini e Acquisizione video

Il caso d'uso dell'anteprima interagisce con un Surface per la visualizzazione. Le applicazioni creano il caso d'uso con opzioni di configurazione utilizzando il seguente codice:

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

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();

Per altri esempi di codice, consulta l'app di esempio CameraX ufficiale.

Cicli di vita di CameraX

CameraX osserva un ciclo di vita per determinare quando aprire la fotocamera, quando creare una sessione di acquisizione e quando arrestare e arrestare. Le API dei casi d'uso forniscono chiamate di metodo e callback per monitorare l'avanzamento.

Come spiegato in Combinare i casi d'uso, puoi associare alcuni mix di casi d'uso a un singolo ciclo di vita. Se la tua app deve supportare casi d'uso che non possono essere combinati, puoi:

• Raggruppa i casi d'uso compatibili in più di un frammento e poi passa da un frammento all'altro
• Creare un componente personalizzato del ciclo di vita e utilizzarlo per controllare manualmente il ciclo di vita della fotocamera

Se disaccoppia la vista e i proprietari del ciclo di vita dei casi d'uso della fotocamera (ad esempio, se utilizzi un ciclo di vita personalizzato o un frammento di conservazione), devi assicurarti che tutti i casi d'uso non siano associati a CameraX utilizzando ProcessCameraProvider.unbindAll() o svincolando singolarmente ogni caso d'uso. In alternativa, quando associ i casi d'uso a un ciclo di vita, puoi consentire a CameraX di gestire l'apertura e la chiusura della sessione di acquisizione e lo svincolo dei casi d'uso.

Se tutte le funzionalità della videocamera corrispondono al ciclo di vita di un singolo componente sensibile al ciclo di vita, ad esempio un frammento AppCompatActivity o AppCompat, l'utilizzo del ciclo di vita di quel componente quando si associano tutti i casi d'uso desiderati garantirà che la funzionalità della fotocamera sia pronta quando il componente sensibile al ciclo di vita è attivo e smaltito in modo sicuro, senza consumare alcuna risorsa.

Proprietari ciclo di vita personalizzato

Per i casi avanzati, puoi creare una LifecycleOwner personalizzata per consentire alla tua app di controllare esplicitamente il ciclo di vita della sessione di CameraX anziché associarla a un LifecycleOwner Android standard.

Il seguente esempio di codice mostra come creare un LifecycleOwner personalizzato semplice:

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

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

Con questo LifecycleOwner, l'app può inserire le transizioni di stato nei punti voluti nel codice. Per ulteriori informazioni sull'implementazione di questa funzionalità nella tua app, consulta Implementazione di un LifecycleOwner personalizzato.

Casi d'uso simultanei

I casi d'uso possono essere eseguiti contemporaneamente. Sebbene i casi d'uso possano essere associati in modo sequenziale a un ciclo di vita, è meglio associare tutti i casi d'uso con una singola chiamata a CameraProcessProvider.bindToLifecycle(). Per ulteriori informazioni sulle best practice per le modifiche alla configurazione, consulta Gestire le modifiche alla configurazione.

Nel seguente esempio di codice, l'app specifica i due casi d'uso da creare ed eseguire contemporaneamente. Specifica inoltre il ciclo di vita da utilizzare per entrambi i casi d'uso, in modo che entrambi si avviino e si arrestino in base al ciclo di vita.

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

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

È garantito che le seguenti combinazioni di configurazione siano supportate (quando è richiesta l'anteprima o l'acquisizione video, ma non entrambe contemporaneamente):

Quando sono necessarie sia l'anteprima che l'acquisizione video, le seguenti combinazioni di casi d'uso sono supportate in modo condizionale:

Inoltre,

• Ogni caso d'uso può funzionare da solo. Ad esempio, un'app può registrare video senza usare l'anteprima.
• Quando le estensioni sono attivate, il funzionamento è garantito solo dalla combinazione ImageCapture e Preview. A seconda dell'implementazione dell'OEM, potrebbe non essere possibile aggiungere anche ImageAnalysis; le estensioni non possono essere abilitate per il caso d'uso VideoCapture. Per maggiori dettagli, consulta il documento di riferimento sulle estensioni.
• A seconda delle funzionalità della videocamera, alcune videocamere potrebbero supportare la combinazione con modalità a risoluzione più bassa, ma non possono supportare la stessa combinazione ad alcune risoluzioni più elevate.

Il livello hardware supportato può essere recuperato da Camera2CameraInfo. Ad esempio, il seguente codice verifica se la fotocamera posteriore predefinita è un dispositivo 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
}

@androidx.annotation.OptIn(markerClass = ExperimentalCamera2Interop.class)
Boolean isBackCameraLevel3Device(ProcessCameraProvider cameraProvider) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
        List\ 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;
}

Autorizzazioni

La tua app deve avere l'autorizzazione CAMERA. Per salvare le immagini nei file, sarà necessaria anche l'autorizzazione WRITE_EXTERNAL_STORAGE, ad eccezione dei dispositivi con Android 10 o versioni successive.

Per ulteriori informazioni sulla configurazione delle autorizzazioni per la tua app, consulta Richiedere le autorizzazioni app.

Requisiti

CameraX ha i seguenti requisiti di versione minimi:

• Livello API Android 21
• Componenti dell'architettura Android 1.1.1

Per le attività consapevoli del ciclo di vita, utilizza FragmentActivity o AppCompatActivity.

Dichiara le dipendenze

Per aggiungere una dipendenza su CameraX, devi aggiungere il repository Google Maven al tuo progetto.

Apri il file settings.gradle del tuo progetto e aggiungi il repository google() come mostrato di seguito:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Aggiungi il seguente codice alla fine del blocco Android:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Aggiungi quanto segue al file build.gradle di ogni modulo per un'app:

dependencies {
  // CameraX core library using the camera2 implementation
  def camerax_version = "1.4.0-beta02"
  // 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}"
}

dependencies {
    // CameraX core library using the camera2 implementation
    val camerax_version = "1.4.0-beta02"
    // 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}")
}

Per ulteriori informazioni sulla configurazione dell'app in modo che sia conforme a questi requisiti, consulta la sezione Dichiarare le dipendenze.

Interoperabilità di CameraX con Camera2

CameraX è basata su Camera2 e offre modalità di lettura e scrittura per le proprietà nell'implementazione di Camera2. Per i dettagli completi, consulta il pacchetto Interop.

Per ulteriori informazioni su come CameraX ha configurato le proprietà Camera2, utilizza Camera2CameraInfo per leggere l'elemento CameraCharacteristics sottostante. Puoi anche scegliere di scrivere le proprietà Camera2 sottostanti in uno dei seguenti due percorsi:

• Utilizza Camera2CameraControl, che consente di impostare le proprietà sull'elemento CaptureRequest sottostante, come la modalità di messa a fuoco automatica.

• Estendi una FotocameraX UseCase con un Camera2Interop.Extender. In questo modo puoi impostare le proprietà in CaptureRequest, proprio come Camera2CameraControl. Offre anche alcuni controlli aggiuntivi, come l'impostazione del caso d'uso dello stream per ottimizzare la videocamera in base al tuo scenario di utilizzo. Per informazioni, vedi Utilizzare i casi d'uso di Stream per migliorare le prestazioni.

Il seguente esempio di codice utilizza casi d'uso di streaming per ottimizzare per una videochiamata. Utilizza Camera2CameraInfo per determinare se il caso d'uso dello stream di videochiamata è disponibile. Quindi, utilizza un Camera2Interop.Extender per impostare il caso d'uso dello stream sottostante.

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

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

Risorse aggiuntive

Per saperne di più su CameraX, consulta le risorse aggiuntive che seguono.

Codelab

Esempio di codice