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érent. Voici certains cas d'utilisation types :

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

Le traitement des trames entraîne des coûts de performances considérables, et le coût est multiplié lors du traitement parallèle par flux ou par pipeline.

Les ressources telles que le processeur, le GPU et le DSP peuvent exploiter les fonctionnalités de retraitement du framework, mais les ressources telles que la mémoire augmenteront 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 de caméra avec un flux pour l'aperçu de l'appareil photo et un autre pour le traitement de l'image:

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)

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

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

Type de sortie

Le type de sortie fait référence au format dans lequel les trames 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 des frames et ImageFormat.JPEG pour les images fixes. Pour les scénarios de prévisualisation et d'enregistrement, vous utiliserez probablement un élément SurfaceView, TextureView, MediaRecorder, MediaCodec ou RenderScript.Allocation. Dans ce cas, ne spécifiez pas de format d'image. Pour des raisons de compatibilité, elle sera comptabilisée comme ImageFormat.PRIVATE, quel que soit le format réel utilisé en interne. Pour interroger les formats acceptés par un appareil en fonction de son CameraCharacteristics, utilisez le code suivant:

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

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 d'entre elles sont liées à la compatibilité: PREVIEW et MAXIMUM. Les tailles servent de limites supérieures. Si un élément de taille PREVIEW fonctionne, tout élément de taille inférieure à PREVIEW fonctionnera également. Il en va de même pour MAXIMUM. Ces tailles sont décrites dans la documentation sur CameraDevice.

Les tailles de sortie disponibles dépendent du format choisi. Compte tenu de la valeur CameraCharacteristics et d'un format, vous pouvez interroger les tailles de sortie disponibles comme suit:

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

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 acceptées. Le format sera géré par le framework de l'appareil photo lui-même:

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

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:

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

 @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. Il est possible que le format ne corresponde pas exactement à celui de l'écran. Vous devrez donc peut-être appliquer un format letterbox ou un recadrage au 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 de l'écran, tout en tenant compte du fait que celui-ci peut pivoter.

Le code suivant définit une classe d'assistance, SmartSize, qui facilite légèrement les comparaisons de taille:

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

/** 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.

Un objet CameraCharacteristics vous permet de récupérer le niveau matériel à l'aide d'une seule instruction:

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)

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

Assembler toutes les pièces

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

LEGACY est le niveau de 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 avec la configuration appropriée, et s'il n'y a pas trop de frais généraux qui limitent les performances, telles que des contraintes de mémoire, de processeur ou de température.

Votre application doit également configurer le ciblage des tampons de sortie. Par exemple, pour cibler un appareil avec un niveau de matériel LEGACY, vous pouvez configurer deux surfaces de sortie cibles, l'une utilisant ImageFormat.PRIVATE et l'autre avec ImageFormat.YUV_420_888. Il s'agit d'une combinaison acceptée lorsque vous utilisez la taille PREVIEW. À l'aide de la fonction définie précédemment dans cet article, vous devez utiliser le code suivant pour obtenir les tailles d'aperçu requises pour un ID d'appareil photo:

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)

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

Vous devez attendre que SurfaceView soit prêt à l'aide des rappels fournis:

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

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 SurfaceView à correspondre à la taille de sortie de la caméra en appelant SurfaceHolder.setFixedSize() ou vous pouvez adopter une approche semblable à AutoFitSurfaceView à partir du module commun des échantillons de caméra sur GitHub, qui définit une taille absolue en tenant compte à la fois du format et de l'espace disponible, tout en ajustant automatiquement lorsque des modifications d'activité sont déclenchées.

Il est plus facile de configurer l'autre surface à partir de ImageReader avec le format souhaité, car il n'y a aucun rappel à attendre:

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)

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 frames après les avoir utilisés:

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

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

Le niveau de matériel LEGACY cible les appareils avec le 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 avec un niveau de matériel LIMITED, ou même l'augmenter à MAXIMUM pour les appareils avec un niveau de matériel FULL.