Utilizzare più stream della videocamera contemporaneamente

Nota: questa pagina fa riferimento al pacchetto Camera2. A meno che la tua app non richieda funzionalità specifiche di basso livello di Camera2, ti consigliamo di utilizzare CameraX. Sia CameraX che Camera2 supportano Android 5.0 (livello API 21) e versioni successive.

Un'applicazione per la fotocamera può utilizzare più di un flusso di frame contemporaneamente. In alcuni casi, stream diversi richiedono persino una risoluzione dei fotogrammi o un formato pixel diversi. Alcuni casi d'uso tipici includono:

• Registrazione video: un flusso per l'anteprima, un altro codificato e salvato in un file.
• Scansione del codice a barre: un flusso per l'anteprima, un altro per il rilevamento del codice a barre.
• Fotografia computazionale: uno stream per l'anteprima, un altro per il rilevamento di volti/scene.

L'elaborazione dei frame comporta un costo di rendimento non trascurabile, che viene moltiplicato quando si esegue l'elaborazione parallela di stream o pipeline.

Risorse come CPU, GPU e DSP potrebbero essere in grado di sfruttare le funzionalità di riprocessamento del framework, ma risorse come la memoria aumenteranno in modo lineare.

Più target per richiesta

È possibile combinare più stream di videocamere in un unico CameraCaptureRequest. Il seguente snippet di codice mostra come configurare una sessione della videocamera con uno stream per l'anteprima della videocamera e un altro stream per l'elaborazione delle immagini:

Kotlin

val session: CameraCaptureSession = ...  // from CameraCaptureSession.StateCallback

// You will use the preview capture template for the combined streams
// because it is optimized for low latency; for high-quality images, use
// TEMPLATE_STILL_CAPTURE, and for a steady frame rate use TEMPLATE_RECORD
val requestTemplate = CameraDevice.TEMPLATE_PREVIEW
val combinedRequest = session.device.createCaptureRequest(requestTemplate)

// Link the Surface targets with the combined request
combinedRequest.addTarget(previewSurface)
combinedRequest.addTarget(imReaderSurface)

// In this simple case, the SurfaceView gets updated automatically. ImageReader
// has its own callback that you have to listen to in order to retrieve the
// frames so there is no need to set up a callback for the capture request
session.setRepeatingRequest(combinedRequest.build(), null, null)

Java

CameraCaptureSession session = …;  // from CameraCaptureSession.StateCallback

// You will use the preview capture template for the combined streams
// because it is optimized for low latency; for high-quality images, use
// TEMPLATE_STILL_CAPTURE, and for a steady frame rate use TEMPLATE_RECORD
        CaptureRequest.Builder combinedRequest = session.getDevice().createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);

// Link the Surface targets with the combined request
        combinedRequest.addTarget(previewSurface);
        combinedRequest.addTarget(imReaderSurface);

// In this simple case, the SurfaceView gets updated automatically. ImageReader
// has its own callback that you have to listen to in order to retrieve the
// frames so there is no need to set up a callback for the capture request
        session.setRepeatingRequest(combinedRequest.build(), null, null);

Se configuri correttamente le piattaforme di destinazione, questo codice produrrà solo stream che soddisfano il numero minimo di FPS determinato da StreamComfigurationMap.GetOutputMinFrameDuration(int, Size) e StreamComfigurationMap.GetOutputStallDuration(int, Size). Le prestazioni effettive variano da dispositivo a dispositivo, anche se Android fornisce alcune garanzie per il supporto di combinazioni specifiche a seconda di tre variabili: tipo di output, dimensioni dell'output e livello hardware.

L'utilizzo di una combinazione di variabili non supportata potrebbe funzionare a un frame rate basso. In caso contrario, verrà attivata una delle callback di errore. La documentazione di createCaptureSession descrive ciò che è garantito.

Tipo di output

Tipo di output si riferisce al formato in cui vengono codificati i frame. I valori possibili sono PRIV, YUV, JPEG e RAW. La documentazione per createCaptureSession li descrive.

Quando scegli il tipo di output dell'applicazione, se l'obiettivo è massimizzare la compatibilità, utilizza ImageFormat.YUV_420_888 per l'analisi dei frame e ImageFormat.JPEG per le immagini statiche. Per gli scenari di anteprima e registrazione, probabilmente utilizzerai SurfaceView, TextureView, MediaRecorder, MediaCodec o RenderScript.Allocation. In questi casi, non specificare un formato dell'immagine. Per compatibilità, verrà conteggiato come ImageFormat.PRIVATE, indipendentemente dal formato effettivo utilizzato internamente. Per eseguire una query sui formati supportati da un dispositivo dato il suo CameraCharacteristics, utilizza il seguente codice:

Kotlin

val characteristics: CameraCharacteristics = ...
val supportedFormats = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).outputFormats

Java

CameraCharacteristics characteristics = …;
        int[] supportedFormats = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).getOutputFormats();

Dimensioni output

Tutte le dimensioni di output disponibili sono elencate per StreamConfigurationMap.getOutputSizes(), ma solo due sono correlate alla compatibilità: PREVIEW e MAXIMUM. Le dimensioni fungono da limiti superiori. Se qualcosa di dimensioni PREVIEW funziona, funzionerà anche qualsiasi elemento con dimensioni inferiori a PREVIEW. Lo stesso vale per MAXIMUM. La documentazione di CameraDevice spiega queste dimensioni.

Le dimensioni di output disponibili dipendono dalla scelta del formato. Dato il CameraCharacteristics e un formato, puoi eseguire una query per le dimensioni di output disponibili nel seguente modo:

Kotlin

val characteristics: CameraCharacteristics = ...
val outputFormat: Int = ...  // such as ImageFormat.JPEG
val sizes = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
    .getOutputSizes(outputFormat)

Java

CameraCharacteristics characteristics = …;
        int outputFormat = …;  // such as ImageFormat.JPEG
Size[] sizes = characteristics.get(
                CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
                .getOutputSizes(outputFormat);

Nei casi d'uso di anteprima e registrazione della videocamera, utilizza la classe target per determinare le dimensioni supportate. Il formato verrà gestito dal framework della videocamera stesso:

Kotlin

val characteristics: CameraCharacteristics = ...
val targetClass: Class <T> = ...  // such as SurfaceView::class.java
val sizes = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
    .getOutputSizes(targetClass)

Java

CameraCharacteristics characteristics = …;
   int outputFormat = …;  // such as ImageFormat.JPEG
   Size[] sizes = characteristics.get(
                CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
                .getOutputSizes(outputFormat);

Per ottenere le dimensioni di MAXIMUM, ordina le dimensioni dell'output per area e restituisci quella più grande:

Kotlin

fun <T>getMaximumOutputSize(
    characteristics: CameraCharacteristics, targetClass: Class <T>, format: Int? = null):
    Size {
  val config = characteristics.get(
      CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)

  // If image format is provided, use it to determine supported sizes; or else use target class
  val allSizes = if (format == null)
    config.getOutputSizes(targetClass) else config.getOutputSizes(format)
  return allSizes.maxBy { it.height * it.width }
}

Java

 @RequiresApi(api = Build.VERSION_CODES.N)
    <T> Size getMaximumOutputSize(CameraCharacteristics characteristics,
                                            Class <T> targetClass,
                                            Integer format) {
        StreamConfigurationMap config = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);

        // If image format is provided, use it to determine supported sizes; else use target class
        Size[] allSizes;
        if (format == null) {
            allSizes = config.getOutputSizes(targetClass);
        } else {
            allSizes = config.getOutputSizes(format);
        }
        return Arrays.stream(allSizes).max(Comparator.comparing(s -> s.getHeight() * s.getWidth())).get();
    }

PREVIEW si riferisce alla dimensione che meglio corrisponde alla risoluzione dello schermo del dispositivo o a 1080p (1920 x 1080), a seconda di quale sia la più piccola. Le proporzioni potrebbero non corrispondere esattamente a quelle dello schermo, pertanto potresti dover applicare il letterbox o il ritaglio allo stream per visualizzarlo in modalità a schermo intero. Per ottenere le dimensioni di anteprima corrette, confronta le dimensioni di output disponibili con le dimensioni del display, tenendo conto che il display potrebbe essere ruotato.

Il seguente codice definisce una classe helper, SmartSize, che semplificherà un po' i confronti delle dimensioni:

Kotlin

/** Helper class used to pre-compute shortest and longest sides of a [Size] */
class SmartSize(width: Int, height: Int) {
    var size = Size(width, height)
    var long = max(size.width, size.height)
    var short = min(size.width, size.height)
    override fun toString() = "SmartSize(${long}x${short})"
}

/** Standard High Definition size for pictures and video */
val SIZE_1080P: SmartSize = SmartSize(1920, 1080)

/** Returns a [SmartSize] object for the given [Display] */
fun getDisplaySmartSize(display: Display): SmartSize {
    val outPoint = Point()
    display.getRealSize(outPoint)
    return SmartSize(outPoint.x, outPoint.y)
}

/**
 * Returns the largest available PREVIEW size. For more information, see:
 * https://d.android.com/reference/android/hardware/camera2/CameraDevice
 */
fun <T>getPreviewOutputSize(
        display: Display,
        characteristics: CameraCharacteristics,
        targetClass: Class <T>,
        format: Int? = null
): Size {

    // Find which is smaller: screen or 1080p
    val screenSize = getDisplaySmartSize(display)
    val hdScreen = screenSize.long >= SIZE_1080P.long || screenSize.short >= SIZE_1080P.short
    val maxSize = if (hdScreen) SIZE_1080P else screenSize

    // If image format is provided, use it to determine supported sizes; else use target class
    val config = characteristics.get(
            CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)!!
    if (format == null)
        assert(StreamConfigurationMap.isOutputSupportedFor(targetClass))
    else
        assert(config.isOutputSupportedFor(format))
    val allSizes = if (format == null)
        config.getOutputSizes(targetClass) else config.getOutputSizes(format)

    // Get available sizes and sort them by area from largest to smallest
    val validSizes = allSizes
            .sortedWith(compareBy { it.height * it.width })
            .map { SmartSize(it.width, it.height) }.reversed()

    // Then, get the largest output size that is smaller or equal than our max size
    return validSizes.first { it.long <= maxSize.long && it.short <= maxSize.short }.size
}

Java

/** Helper class used to pre-compute shortest and longest sides of a [Size] */
    class SmartSize {
        Size size;
        double longSize;
        double shortSize;

        public SmartSize(Integer width, Integer height) {
            size = new Size(width, height);
            longSize = max(size.getWidth(), size.getHeight());
            shortSize = min(size.getWidth(), size.getHeight());
        }

        @Override
        public String toString() {
            return String.format("SmartSize(%sx%s)", longSize, shortSize);
        }
    }

    /** Standard High Definition size for pictures and video */
    SmartSize SIZE_1080P = new SmartSize(1920, 1080);

    /** Returns a [SmartSize] object for the given [Display] */
    SmartSize getDisplaySmartSize(Display display) {
        Point outPoint = new Point();
        display.getRealSize(outPoint);
        return new SmartSize(outPoint.x, outPoint.y);
    }

    /**
     * Returns the largest available PREVIEW size. For more information, see:
     * https://d.android.com/reference/android/hardware/camera2/CameraDevice
     */
    @RequiresApi(api = Build.VERSION_CODES.N)
    <T> Size getPreviewOutputSize(
            Display display,
            CameraCharacteristics characteristics,
            Class <T> targetClass,
            Integer format
    ){

        // Find which is smaller: screen or 1080p
        SmartSize screenSize = getDisplaySmartSize(display);
        boolean hdScreen = screenSize.longSize >= SIZE_1080P.longSize || screenSize.shortSize >= SIZE_1080P.shortSize;
        SmartSize maxSize;
        if (hdScreen) {
            maxSize = SIZE_1080P;
        } else {
            maxSize = screenSize;
        }

        // If image format is provided, use it to determine supported sizes; else use target class
        StreamConfigurationMap config = characteristics.get(
                CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);
        if (format == null)
            assert(StreamConfigurationMap.isOutputSupportedFor(targetClass));
        else
            assert(config.isOutputSupportedFor(format));
        Size[] allSizes;
        if (format == null) {
            allSizes = config.getOutputSizes(targetClass);
        } else {
            allSizes = config.getOutputSizes(format);
        }

        // Get available sizes and sort them by area from largest to smallest
        List <Size> sortedSizes = Arrays.asList(allSizes);
        List <SmartSize> validSizes =
                sortedSizes.stream()
                        .sorted(Comparator.comparing(s -> s.getHeight() * s.getWidth()))
                        .map(s -> new SmartSize(s.getWidth(), s.getHeight()))
                        .sorted(Collections.reverseOrder()).collect(Collectors.toList());

        // Then, get the largest output size that is smaller or equal than our max size
        return validSizes.stream()
                .filter(s -> s.longSize <= maxSize.longSize && s.shortSize <= maxSize.shortSize)
                .findFirst().get().size;
    }

Controllare il livello hardware supportato

Per determinare le funzionalità disponibili in fase di runtime, controlla il livello hardware supportato utilizzando CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL.

Con un CameraCharacteristics oggetto, puoi recuperare il livello hardware con una sola istruzione:

Kotlin

val characteristics: CameraCharacteristics = ...

// Hardware level will be one of:
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3
val hardwareLevel = characteristics.get(
        CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL)

Java

CameraCharacteristics characteristics = ...;

// Hardware level will be one of:
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL,
// - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3
Integer hardwareLevel = characteristics.get(
                CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);

Mettere insieme tutti i pezzi

Con il tipo di output, le dimensioni dell'output e il livello hardware, puoi determinare quali combinazioni di stream sono valide. Il seguente grafico è un'istantanea delle configurazioni supportate da un CameraDevice con LEGACY a livello di hardware.

Target 1		Target 2		Target 3		Esempio/i di caso d'uso
Tipo	Dimensione massima	Tipo	Dimensione massima	Tipo	Dimensione massima
PRIV	MAXIMUM					Anteprima semplice, elaborazione video della GPU o registrazione video senza anteprima.
JPEG	MAXIMUM					Acquisizione di immagini fisse senza mirino.
YUV	MAXIMUM					Elaborazione di video/immagini in-app.
PRIV	PREVIEW	JPEG	MAXIMUM			Immagini statiche standard.
YUV	PREVIEW	JPEG	MAXIMUM			Elaborazione in-app più acquisizione di foto.
PRIV	PREVIEW	PRIV	PREVIEW			Registrazione standard.
PRIV	PREVIEW	YUV	PREVIEW			Anteprima più elaborazione in-app.
PRIV	PREVIEW	YUV	PREVIEW	JPEG	MAXIMUM	Acquisizione di foto e video e relativa elaborazione in-app.

LEGACY è il livello hardware più basso possibile. Questa tabella mostra che ogni dispositivo che supporta Camera2 (livello API 21 e versioni successive) può generare fino a tre stream simultanei utilizzando la configurazione corretta e se non c'è troppo overhead che limita le prestazioni, ad esempio vincoli di memoria, CPU o termici.

La tua app deve anche configurare i buffer di output del targeting. Ad esempio, per scegliere come target un dispositivo con livello hardware LEGACY, puoi configurare due superfici di output di destinazione, una che utilizza ImageFormat.PRIVATE e un'altra che utilizza ImageFormat.YUV_420_888. Questa è una combinazione supportata durante l'utilizzo delle dimensioni PREVIEW. Utilizzando la funzione definita in precedenza in questo argomento, per ottenere le dimensioni di anteprima richieste per un ID fotocamera è necessario il seguente codice:

Kotlin

val characteristics: CameraCharacteristics = ...
val context = this as Context  // assuming you are inside of an activity

val surfaceViewSize = getPreviewOutputSize(
    context, characteristics, SurfaceView::class.java)
val imageReaderSize = getPreviewOutputSize(
    context, characteristics, ImageReader::class.java, format = ImageFormat.YUV_420_888)

Java

CameraCharacteristics characteristics = ...;
        Context context = this; // assuming you are inside of an activity

        Size surfaceViewSize = getPreviewOutputSize(
                context, characteristics, SurfaceView.class);
        Size imageReaderSize = getPreviewOutputSize(
                context, characteristics, ImageReader.class, format = ImageFormat.YUV_420_888);

Richiede di attendere che SurfaceView sia pronto utilizzando i callback forniti:

Kotlin

val surfaceView = findViewById <SurfaceView>(...)
surfaceView.holder.addCallback(object : SurfaceHolder.Callback {
  override fun surfaceCreated(holder: SurfaceHolder) {
    // You do not need to specify image format, and it will be considered of type PRIV
    // Surface is now ready and you could use it as an output target for CameraSession
  }
  ...
})

Java

SurfaceView surfaceView = findViewById <SurfaceView>(...);

surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() {
            @Override
            public void surfaceCreated(@NonNull SurfaceHolder surfaceHolder) {
                // You do not need to specify image format, and it will be considered of type PRIV
                // Surface is now ready and you could use it as an output target for CameraSession
            }
            ...
        });

Puoi forzare SurfaceView in modo che corrisponda alle dimensioni dell'output della videocamera chiamando SurfaceHolder.setFixedSize() oppure puoi adottare un approccio simile a AutoFitSurfaceView dal modulo Common degli esempi di videocamera su GitHub, che imposta una dimensione assoluta, tenendo conto sia delle proporzioni che dello spazio disponibile, mentre si regola automaticamente quando vengono attivati i cambiamenti di attività.

Configurare l'altra superficie da ImageReader con il formato desiderato è più semplice, poiché non ci sono callback da attendere:

Kotlin

val frameBufferCount = 3  // just an example, depends on your usage of ImageReader
val imageReader = ImageReader.newInstance(
    imageReaderSize.width, imageReaderSize.height, ImageFormat.YUV_420_888,
    frameBufferCount)

Java

int frameBufferCount = 3;  // just an example, depends on your usage of ImageReader
ImageReader imageReader = ImageReader.newInstance(
                imageReaderSize.width, imageReaderSize.height, ImageFormat.YUV_420_888,
                frameBufferCount);

Quando utilizzi un buffer di destinazione di blocco come ImageReader, scarta i frame dopo averli utilizzati:

Kotlin

imageReader.setOnImageAvailableListener({
  val frame =  it.acquireNextImage()
  // Do something with "frame" here
  it.close()
}, null)

Java

imageReader.setOnImageAvailableListener(listener -> {
            Image frame = listener.acquireNextImage();
            // Do something with "frame" here
            listener.close();
        }, null);

Il livello hardware LEGACY ha come target i dispositivi con il minimo comune denominatore. Puoi aggiungere ramificazioni condizionali e utilizzare le dimensioni RECORD per una delle superfici di destinazione dell'output nei dispositivi con livello hardware LIMITED o persino aumentarle fino alle dimensioni MAXIMUM per i dispositivi con livello hardware FULL.