Nota: En esta página, se hace referencia al paquete Camera2. A menos que tu app requiera funciones específicas y de bajo nivel de Camera2, te recomendamos usar 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 a la vez. En algunos casos, las diferentes transmisiones incluso requieren una resolución de fotograma 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, otra que se codifica y se guarda en un archivo.
- Escaneo de códigos de barras: Una transmisión para la vista previa y otra para la detección de códigos de barras.
- Fotografía computacional: una transmisión para la vista previa, otra para la detección de rostro o escena.
Existe un costo de rendimiento no trivial cuando se procesan marcos, y el costo se multiplica cuando se realiza un procesamiento de canalización o transmisión en paralelo.
Los recursos como la CPU, la GPU y la DSP pueden aprovechar las capacidades de reprocesamiento del framework, pero los recursos como la memoria crecerán de manera lineal.
Varios objetivos por solicitud
Se pueden combinar varias transmisiones de cámara en una sola 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 las plataformas de destino de forma correcta, este código producirá solo 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 ofrece algunas garantías para admitir combinaciones específicas según tres variables: tipo de salida, tamaño de salida y nivel de hardware.
El uso de una combinación de variables no compatible puede funcionar a una velocidad de fotogramas baja; de lo contrario, se activará una de las devoluciones de llamada de error.
En la documentación de createCaptureSession
, se describe lo que se garantiza que funciona.
Tipo de salida
Tipo de salida se refiere al formato en el que se codifican los marcos. Los valores posibles son PRIV, YUV, JPEG y RAW. En la documentación de createCaptureSession
, se describen.
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 imágenes estáticas. Para situaciones 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 la compatibilidad, se contará como ImageFormat.PRIVATE
, independientemente del formato real que se usa internamente. Para consultar los formatos compatibles con un dispositivo según 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 la 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 inferior a 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. A partir de 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 objetivo para determinar los tamaños compatibles. El framework de la cámara controlará el 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 muestra 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 tal vez debas aplicar formato letterbox o recorte a 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 y ten en cuenta que la pantalla se puede rotar.
El siguiente código define una clase auxiliar, SmartSize
, que facilitará 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 compatible
Para determinar las funciones disponibles en el tiempo de ejecución, verifica el nivel de hardware compatible mediante CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL
.
Con un objeto CameraCharacteristics
, puedes recuperar el nivel de hardware con una sola declaració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);
Reunir 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 los parámetros de configuración admitidos por un CameraDevice
con nivel de hardware LEGACY
.
Objetivo 1 | Objetivo 2 | Objetivo 3 | Casos de uso de muestra | |||
---|---|---|---|---|---|---|
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 estáticas sin visor. | ||||
YUV |
MAXIMUM |
Procesamiento de imágenes y videos en la aplicación | ||||
PRIV |
PREVIEW |
JPEG |
MAXIMUM |
Imágenes fijas estándar. | ||
YUV |
PREVIEW |
JPEG |
MAXIMUM |
Procesamiento en la app y captura. | ||
PRIV |
PREVIEW |
PRIV |
PREVIEW |
Grabación estándar | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
Vista previa y procesamiento en la app. | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
Vista previa y procesamiento en la app. | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
JPEG |
MAXIMUM |
De todos modos, captura más procesamiento en la app. |
LEGACY
es el nivel de hardware más bajo posible. En esta tabla, se muestra que cada dispositivo compatible con Camera2 (nivel de API 21 y versiones posteriores) puede generar hasta tres transmisiones simultáneas con la configuración adecuada y si no hay demasiada sobrecarga que limite el rendimiento, como restricciones térmicas, de memoria o de CPU.
Tu app también debe configurar búferes de salida de segmentación. Por ejemplo, para orientar a un dispositivo con el nivel de hardware LEGACY
, puedes configurar dos plataformas de salida objetivo, una con ImageFormat.PRIVATE
y otra con ImageFormat.YUV_420_888
. Esta es una combinación admitida cuando se usa el tamaño PREVIEW
. Con 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);
Debes esperar hasta que SurfaceView
esté listo mediante 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 hacer 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
desde el módulo común de las muestras de la cámara en GitHub, que establece un tamaño absoluto y tiene en cuenta tanto la relación de aspecto como el espacio disponible, al mismo tiempo que se ajusta automáticamente cuando se activan los cambios de actividad.
Configurar la otra plataforma 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 mínimo denominador común. Puedes agregar ramas 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 a un tamaño MAXIMUM
para dispositivos con nivel de hardware FULL
.