Utiliser plusieurs flux d'appareil photo simultanément

Remarque : Cette page fait référence au package Camera2. Sauf si votre application nécessite des fonctionnalités spécifiques de bas niveau de Camera2, nous vous recommandons d'utiliser CameraX. CameraX et Camera2 sont compatibles avec Android 5.0 (niveau d'API 21) ou version ultérieure.

Une application d'appareil photo peut utiliser plusieurs flux d'images simultanément. Dans certains cas, différents flux nécessitent même une résolution d'image ou un format de pixel différents. Voici certains cas d'utilisation types :

• Enregistrement vidéo : un flux pour l'aperçu, un autre encodé et enregistré dans un fichier.
• Lecture de codes-barres : un flux pour l'aperçu, un autre pour la détection de codes-barres.
• Photographie computationnelle : un flux pour l'aperçu, un autre pour la détection des visages ou des scènes.

Le traitement des frames entraîne un coût de performances non négligeable, qui est multiplié lors du traitement de flux ou de pipelines parallèles.

Les ressources telles que le processeur, le GPU et le DSP peuvent tirer parti des capacités de retraitement du framework, mais les ressources telles que la mémoire augmentent de manière linéaire.

Plusieurs cibles par requête

Plusieurs flux de caméra peuvent être combinés en un seul CameraCaptureRequest. L'extrait de code suivant montre comment configurer une session d'appareil photo avec un flux pour l'aperçu de l'appareil photo et un autre flux pour le traitement d'image :

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 basic 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 basic 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 vous configurez correctement les surfaces cibles, ce code ne produira que des flux qui respectent le nombre minimal d'images par seconde déterminé par StreamComfigurationMap.GetOutputMinFrameDuration(int, Size) et StreamComfigurationMap.GetOutputStallDuration(int, Size). Les performances réelles varient d'un appareil à l'autre, bien qu'Android fournisse certaines garanties pour la prise en charge de combinaisons spécifiques en fonction de trois variables : le type de sortie, la taille de sortie et le niveau matériel.

L'utilisation d'une combinaison de variables non compatible peut fonctionner à une fréquence d'images faible. Si ce n'est pas le cas, l'un des rappels d'échec sera déclenché. La documentation de createCaptureSession décrit ce qui est garanti de fonctionner.

Type de sortie

Le type de sortie fait référence au format dans lequel les images sont encodées. Les valeurs possibles sont PRIV, YUV, JPEG et RAW. La documentation de createCaptureSession les décrit.

Lorsque vous choisissez le type de sortie de votre application, si l'objectif est de maximiser la compatibilité, utilisez ImageFormat.YUV_420_888 pour l'analyse d'images et ImageFormat.JPEG pour les images fixes. Pour les scénarios d'aperçu et d'enregistrement, vous utiliserez probablement un SurfaceView, un TextureView, un MediaRecorder, un MediaCodec ou un RenderScript.Allocation. Dans ce cas, ne spécifiez pas de format d'image. Pour des raisons de compatibilité, il sera comptabilisé comme ImageFormat.PRIVATE, quel que soit le format réellement utilisé en interne. Pour interroger les formats compatibles avec un appareil en fonction de son CameraCharacteristics, utilisez le code suivant :

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

Taille de sortie

Toutes les tailles de sortie disponibles sont listées par StreamConfigurationMap.getOutputSizes(), mais seules deux sont liées à la compatibilité : PREVIEW et MAXIMUM. Les tailles agissent comme des limites supérieures. Si une taille PREVIEW fonctionne, toutes les tailles inférieures à PREVIEW fonctionneront également. Il en va de même pour MAXIMUM. La documentation de CameraDevice explique ces tailles.

Les tailles de sortie disponibles dépendent du format choisi. En fonction de l'CameraCharacteristics et d'un format, vous pouvez interroger les tailles de sortie disponibles comme suit :

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

Dans les cas d'utilisation de l'aperçu et de l'enregistrement de l'appareil photo, utilisez la classe cible pour déterminer les tailles compatibles. Le format sera géré par le framework de l'appareil photo lui-même :

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

Pour obtenir la taille de MAXIMUM, triez les tailles de sortie par zone et renvoyez la plus 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 correspond à la meilleure taille correspondant à la résolution d'écran de l'appareil ou à 1 080p (1 920 x 1 080 pixels), selon la taille la plus petite. Le format peut ne pas correspondre exactement à celui de l'écran. Vous devrez peut-être appliquer un format letterbox ou recadrer le flux pour l'afficher en mode plein écran. Pour obtenir la bonne taille d'aperçu, comparez les tailles de sortie disponibles avec la taille d'affichage, en tenant compte du fait que l'écran peut être pivoté.

Le code suivant définit une classe d'assistance, SmartSize, qui facilitera les comparaisons de tailles :

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

Vérifier le niveau de matériel compatible

Pour déterminer les fonctionnalités disponibles au moment de l'exécution, vérifiez le niveau matériel compatible à l'aide de CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL.

Avec un objet CameraCharacteristics, vous pouvez récupérer le niveau matériel avec une seule instruction :

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

Assemblage du jeu…

Le type de sortie, la taille de sortie et le niveau matériel vous permettent de déterminer les combinaisons de flux valides. Le graphique suivant est un instantané des configurations compatibles avec un CameraDevice avec un niveau matériel LEGACY.

Objectif 1		Objectif 2		Objectif 3		Exemples de cas d'utilisation
Type	Taille maximale	Type	Taille maximale	Type	Taille maximale
PRIV	MAXIMUM					Aperçu simple, traitement vidéo GPU ou enregistrement vidéo sans aperçu.
JPEG	MAXIMUM					Capture d'images fixes sans viseur.
YUV	MAXIMUM					Traitement des vidéos/images dans l'application.
PRIV	PREVIEW	JPEG	MAXIMUM			Image fixe standard.
YUV	PREVIEW	JPEG	MAXIMUM			Traitement dans l'application et capture d'images fixes.
PRIV	PREVIEW	PRIV	PREVIEW			Enregistrement standard.
PRIV	PREVIEW	YUV	PREVIEW			Aperçu et traitement dans l'application.
PRIV	PREVIEW	YUV	PREVIEW	JPEG	MAXIMUM	Capture d'images fixes et traitement dans l'application.

LEGACY est le niveau matériel le plus bas possible. Ce tableau montre que chaque appareil compatible avec Camera2 (niveau d'API 21 ou supérieur) peut générer jusqu'à trois flux simultanés en utilisant la bonne configuration et s'il n'y a pas trop de surcharge limitant les performances, comme des contraintes de mémoire, de processeur ou thermiques.

Votre application doit également configurer les tampons de sortie de ciblage. Par exemple, pour cibler un appareil avec un niveau matériel LEGACY, vous pouvez configurer deux surfaces de sortie cibles, l'une utilisant ImageFormat.PRIVATE et l'autre utilisant ImageFormat.YUV_420_888. Cette combinaison est compatible avec la taille PREVIEW. En utilisant la fonction définie précédemment dans ce document, l'obtention des tailles d'aperçu requises pour un ID de caméra nécessite le code suivant :

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

Il faut attendre que SurfaceView soit prêt à l'aide des rappels fournis :

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

Vous pouvez forcer la SurfaceView à correspondre à la taille de sortie de la caméra en appelant SurfaceHolder.setFixedSize() ou adopter une approche semblable à AutoFitSurfaceView à partir du module commun des exemples de caméras sur GitHub, qui définit une taille absolue, en tenant compte à la fois du format et de l'espace disponible, tout en s'ajustant automatiquement lorsque des changements d'activité sont déclenchés.

La configuration de l'autre surface à partir de ImageReader avec le format choisi est plus simple, car il n'y a pas de rappels à attendre :

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

Lorsque vous utilisez un tampon cible bloquant tel que ImageReader, supprimez les images après les avoir utilisées :

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

Le niveau matériel LEGACY cible les appareils au plus petit dénominateur commun. Vous pouvez ajouter une branche conditionnelle et utiliser la taille RECORD pour l'une des surfaces cibles de sortie sur les appareils de niveau matériel LIMITED, ou même l'augmenter à la taille MAXIMUM pour les appareils de niveau matériel FULL.