Cómo usar varias transmisiones de cámara a la vez

Nota: Esta página hace referencia al paquete Camera2. A menos que tu app requiera funciones específicas de bajo nivel de Camera2, te recomendamos que uses CameraX. CameraX y Camera2 admiten Android 5.0 (nivel de API 21) y versiones posteriores.

Una aplicación de cámara puede usar más de una transmisión de fotogramas de forma simultánea. En algunos casos, los diferentes flujos incluso requieren una resolución de fotogramas o un formato de píxeles diferentes. Estos son algunos casos prácticos típicos:

• Grabación de video: Una transmisión para la vista previa y otra que se codifica y guarda en un archivo.
• Escaneo de códigos de barras: Un flujo para la vista previa y otro para la detección de códigos de barras.
• Fotografía computacional: Un flujo para la vista previa y otro para la detección de rostros o escenas

El procesamiento de fotogramas tiene un costo de rendimiento no trivial, y este costo se multiplica cuando se realiza el procesamiento de canalizaciones o transmisiones paralelas.

Es posible que los recursos como la CPU, la GPU y el DSP puedan aprovechar las capacidades de preprocesamiento del framework, pero los recursos como la memoria crecerán de forma lineal.

Varios objetivos por solicitud

Se pueden combinar varias transmisiones de cámara en un solo objeto CameraCaptureRequest. En el siguiente fragmento de código, se muestra cómo configurar una sesión de cámara con una transmisión para la vista previa de la cámara y otra para el procesamiento de imágenes:

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

Si configuras correctamente las plataformas de destino, este código solo producirá transmisiones que cumplan con el FPS mínimo determinado por StreamComfigurationMap.GetOutputMinFrameDuration(int, Size) y StreamComfigurationMap.GetOutputStallDuration(int, Size). El rendimiento real varía de un dispositivo a otro, aunque Android proporciona algunas garantías para admitir combinaciones específicas según tres variables: tipo de salida, tamaño de salida y nivel de hardware.

Usar una combinación no admitida de variables puede funcionar con una velocidad de fotogramas baja. Si no funciona, se activará una de las devoluciones de llamada de error. En la documentación de createCaptureSession, se describe lo que se garantiza que funcionará.

Tipo de salida

El tipo de salida hace referencia al formato en el que se codifican los fotogramas. Los valores posibles son PRIV, YUV, JPEG y RAW. La documentación de createCaptureSession los describe.

Cuando elijas el tipo de salida de tu aplicación, si el objetivo es maximizar la compatibilidad, usa ImageFormat.YUV_420_888 para el análisis de fotogramas y ImageFormat.JPEG para las imágenes fijas. En los casos de vista previa y grabación, es probable que uses SurfaceView, TextureView, MediaRecorder, MediaCodec o RenderScript.Allocation. En esos casos, no especifiques un formato de imagen. Para garantizar la compatibilidad, se contabilizará como ImageFormat.PRIVATE, independientemente del formato real que se use de forma interna. Para consultar los formatos compatibles con un dispositivo determinado, dado su CameraCharacteristics, usa el siguiente código:

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

Tamaño de salida

Todos los tamaños de salida disponibles se enumeran por StreamConfigurationMap.getOutputSizes(), pero solo dos están relacionados con la compatibilidad: PREVIEW y MAXIMUM. Los tamaños actúan como límites superiores. Si algo de tamaño PREVIEW funciona, también funcionará cualquier elemento con un tamaño menor que PREVIEW. Lo mismo sucede con MAXIMUM. En la documentación de CameraDevice, se explican estos tamaños.

Los tamaños de salida disponibles dependen del formato elegido. Dado CameraCharacteristics y un formato, puedes consultar los tamaños de salida disponibles de la siguiente manera:

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

En los casos de uso de vista previa y grabación de la cámara, usa la clase de destino para determinar los tamaños admitidos. El marco de la cámara se encargará del formato:

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

Para obtener el tamaño de MAXIMUM, ordena los tamaños de salida por área y devuelve el más 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 hace referencia a la mejor coincidencia de tamaño en relación con la resolución de pantalla del dispositivo o a 1080p (1920 x 1080), el que sea menor. Es posible que la relación de aspecto no coincida exactamente con la de la pantalla, por lo que es posible que debas aplicar el formato letterbox o recortar la transmisión para mostrarla en modo de pantalla completa. Para obtener el tamaño de vista previa correcto, compara los tamaños de salida disponibles con el tamaño de la pantalla, teniendo en cuenta que la pantalla puede rotarse.

El siguiente código define una clase de ayuda, SmartSize, que facilitará un poco las comparaciones de tamaño:

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

Cómo verificar el nivel de hardware admitido

Para determinar las capacidades disponibles en el tiempo de ejecución, verifica el nivel de hardware compatible con CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL.

Con un objeto CameraCharacteristics, puedes recuperar el nivel de hardware con una sola instrucción:

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

Cómo unir todas las piezas

Con el tipo de salida, el tamaño de salida y el nivel de hardware, puedes determinar qué combinaciones de transmisiones son válidas. El siguiente gráfico es una instantánea de las configuraciones compatibles con un CameraDevice con el nivel de hardware LEGACY.

Objetivo 1		Objetivo 2		Objetivo 3		Casos de uso de ejemplo
Tipo	Tamaño máximo	Tipo	Tamaño máximo	Tipo	Tamaño máximo
PRIV	MAXIMUM					Vista previa simple, procesamiento de video con GPU o grabación de video sin vista previa.
JPEG	MAXIMUM					Captura de imágenes fijas sin visor
YUV	MAXIMUM					Procesamiento de imágenes y videos en la aplicación
PRIV	PREVIEW	JPEG	MAXIMUM			Imágenes fijas estándares
YUV	PREVIEW	JPEG	MAXIMUM			Procesamiento en la app y captura de primer plano
PRIV	PREVIEW	PRIV	PREVIEW			Grabación estándar.
PRIV	PREVIEW	YUV	PREVIEW			Vista previa y procesamiento en la app
PRIV	PREVIEW	YUV	PREVIEW	JPEG	MAXIMUM	Captura de imágenes fijas y procesamiento en la app

LEGACY es el nivel de hardware más bajo posible. En esta tabla, se muestra que cada dispositivo que admite Camera2 (nivel de API 21 y versiones posteriores) puede generar hasta tres transmisiones simultáneas con la configuración correcta y si no hay una sobrecarga excesiva que limite el rendimiento, como restricciones de memoria, CPU o térmicas.

Tu app también debe configurar los búferes de salida de segmentación. Por ejemplo, para segmentar un dispositivo con el nivel de hardware LEGACY, puedes configurar dos superficies de salida de destino, una con ImageFormat.PRIVATE y otra con ImageFormat.YUV_420_888. Esta es una combinación admitida cuando se usa el tamaño PREVIEW. Si usas la función definida anteriormente en este tema, obtener los tamaños de vista previa requeridos para un ID de cámara requiere el siguiente código:

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

Requiere esperar hasta que SurfaceView esté listo con las devoluciones de llamada proporcionadas:

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

Puedes forzar que SurfaceView coincida con el tamaño de salida de la cámara llamando a SurfaceHolder.setFixedSize() o puedes adoptar un enfoque similar a AutoFitSurfaceView del módulo Common de los ejemplos de la cámara en GitHub, que establece un tamaño absoluto, teniendo en cuenta la relación de aspecto y el espacio disponible, mientras se ajusta automáticamente cuando se activan los cambios de actividad.

Configurar la otra superficie desde ImageReader con el formato deseado es más fácil, ya que no hay devoluciones de llamada que esperar:

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

Cuando uses un búfer de destino de bloqueo, como ImageReader, descarta los fotogramas después de usarlos:

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

El nivel de hardware de LEGACY se orienta a los dispositivos con el denominador común más bajo. Puedes agregar bifurcaciones condicionales y usar el tamaño RECORD para una de las superficies de destino de salida en dispositivos con nivel de hardware LIMITED, o incluso aumentarlo al tamaño MAXIMUM para dispositivos con nivel de hardware FULL.