Rotazioni del caso d'uso di CameraX

Questo argomento mostra come configurare i casi d'uso di CameraX all'interno della tua app per ottenere immagini con le informazioni di rotazione corrette, sia che provengano dal caso d'uso ImageAnalysis o ImageCapture. Così:

  • Il Analyzer del caso d'uso ImageAnalysis deve ricevere i frame con la rotazione corretta.
  • Il caso d'uso ImageCapture deve scattare foto con la rotazione corretta.

Terminologia

Questo argomento utilizza la seguente terminologia, quindi è importante comprendere il significato di ogni termine:

Orientamento del display
Questo valore indica quale lato del dispositivo è rivolto verso l'alto e può essere uno dei quattro valori seguenti: verticale, orizzontale, verticale inverso o orizzontale inverso.
Rotazione del display
Questo è il valore restituito da Display.getRotation() e rappresenta i gradi di rotazione del dispositivo in senso antiorario rispetto al suo orientamento naturale.
Rotazione target
Rappresenta il numero di gradi di rotazione del dispositivo in senso orario per raggiungere l'orientamento naturale.

Come determinare la rotazione target

I seguenti esempi mostrano come determinare la rotazione target per un dispositivo in base al suo orientamento naturale.

Esempio 1: orientamento verticale naturale

Esempio di dispositivo: Pixel 3 XL

Orientamento naturale = verticale
Orientamento attuale = verticale

Rotazione del display = 0
Rotazione target = 0

Orientamento naturale = verticale
Orientamento attuale = orizzontale

Rotazione del display = 90
Rotazione target = 90

Esempio 2: orientamento orizzontale naturale

Esempio di dispositivo: Pixel C

Orientamento naturale = Orizzontale
Orientamento attuale = Orizzontale

Rotazione del display = 0
Rotazione target = 0

Orientamento naturale = Orizzontale
Orientamento attuale = Verticale

Rotazione del display = 270
Rotazione target = 270

Rotazione dell'immagine

Qual è il lato superiore? L'orientamento del sensore è definito in Android come un valore costante, che rappresenta i gradi (0, 90, 180, 270) di rotazione del sensore rispetto alla parte superiore del dispositivo quando quest'ultimo si trova in una posizione naturale. Per tutti i casi nei diagrammi, la rotazione dell'immagine descrive come i dati devono essere ruotati in senso orario per apparire in posizione verticale.

I seguenti esempi mostrano quale dovrebbe essere la rotazione dell'immagine in base all'orientamento del sensore della fotocamera. Inoltre, presuppongono che la rotazione target sia impostata sulla rotazione del display.

Esempio 1: sensore ruotato di 90 gradi

Esempio di dispositivo: Pixel 3 XL

Rotazione del display = 0
Orientamento del display = verticale
Rotazione dell'immagine = 90

Rotazione del display = 90
Orientamento del display = Orizzontale
Rotazione dell'immagine = 0

Esempio 2: sensore ruotato di 270 gradi

Esempio di dispositivo: Nexus 5X

Rotazione del display = 0
Orientamento del display = Verticale
Rotazione dell'immagine = 270

Rotazione del display = 90
Orientamento del display = Orizzontale
Rotazione dell'immagine = 180

Esempio 3: sensore ruotato di 0 gradi

Esempio di dispositivo: Pixel C (tablet)

Rotazione del display = 0
Orientamento del display = Orizzontale
Rotazione dell'immagine = 0

Rotazione del display = 270
Orientamento del display = Verticale
Rotazione dell'immagine = 90

Calcolo della rotazione di un'immagine

ImageAnalysis

Analyzer di ImageAnalysis riceve le immagini dalla videocamera sotto forma di ImageProxy. Ogni immagine contiene informazioni sulla rotazione, accessibili tramite:

val rotation = imageProxy.imageInfo.rotationDegrees

Questo valore rappresenta i gradi di rotazione dell'immagine in senso orario per corrispondere alla rotazione target di ImageAnalysis. Nel contesto di un'app per Android, la rotazione target di ImageAnalysis corrisponde in genere all'orientamento dello schermo.

ImageCapture

Un callback è collegato a un'istanza ImageCapture per segnalare quando un risultato di acquisizione è pronto. Il risultato può essere l'immagine acquisita o un errore.

Quando scatti una foto, il callback fornito può essere di uno dei seguenti tipi:

  • OnImageCapturedCallback: riceve un'immagine con accesso in memoria sotto forma di ImageProxy.
  • OnImageSavedCallback: viene richiamato quando l'immagine acquisita è stata archiviata correttamente nella posizione specificata da ImageCapture.OutputFileOptions. Le opzioni possono specificare un File, un OutputStream o una località in MediaStore.

La rotazione dell'immagine acquisita, indipendentemente dal formato (ImageProxy, File, OutputStream, MediaStore Uri), rappresenta i gradi di rotazione in base ai quali l'immagine acquisita deve essere ruotata in senso orario per corrispondere alla rotazione target di ImageCapture, che, nel contesto di un'app per Android, corrisponde in genere all'orientamento dello schermo.

Il recupero della rotazione dell'immagine acquisita può essere eseguito in uno dei seguenti modi:

ImageProxy

val rotation = imageProxy.imageInfo.rotationDegrees

File

val exif = Exif.createFromFile(file)
val rotation = exif.rotation

OutputStream

val byteArray = outputStream.toByteArray()
val exif = Exif.createFromInputStream(ByteArrayInputStream(byteArray))
val rotation = exif.rotation

MediaStore uri

val inputStream = contentResolver.openInputStream(outputFileResults.savedUri)
val exif = Exif.createFromInputStream(inputStream)
val rotation = exif.rotation

Verifica la rotazione di un'immagine

I casi d'uso ImageAnalysis e ImageCapture ricevono ImageProxy dalla fotocamera dopo una richiesta di acquisizione riuscita. Un ImageProxy racchiude un'immagine e le relative informazioni, inclusa la rotazione. Queste informazioni sulla rotazione rappresentano i gradi di cui l'immagine deve essere ruotata per corrispondere alla rotazione target del caso d'uso.

Flusso di verifica della rotazione di un'immagine

Linee guida per la rotazione target di ImageCapture/ImageAnalysis

Poiché molti dispositivi non ruotano per impostazione predefinita in verticale o orizzontale invertito, alcune app per Android non supportano questi orientamenti. Il fatto che un'app lo supporti o meno cambia il modo in cui è possibile aggiornare la rotazione target dei casi d'uso.

Di seguito sono riportate due tabelle che definiscono come mantenere sincronizzata la rotazione target dei casi d'uso con la rotazione del display. Il primo mostra come farlo supportando tutti e quattro gli orientamenti, mentre il secondo gestisce solo gli orientamenti in cui il dispositivo ruota per impostazione predefinita.

Per scegliere quali linee guida seguire nella tua app:

  1. Verifica se la fotocamera Activity della tua app ha un orientamento bloccato, un orientamento sbloccato o se esegue l'override delle modifiche alla configurazione dell'orientamento.

  2. Decidi se la fotocamera della tua app Activity deve gestire tutti e quattro gli orientamenti del dispositivo (verticale, verticale inverso, orizzontale e orizzontale inverso) o se deve gestire solo gli orientamenti supportati per impostazione predefinita dal dispositivo su cui è in esecuzione.

Supporta tutti e quattro gli orientamenti

Questa tabella riporta alcune linee guida da seguire nei casi in cui il dispositivo non ruota in modalità Ritratto invertito. Lo stesso vale per i dispositivi che non ruotano in modalità orizzontale invertita.

Scenario Linee guida Modalità finestra singola Modalità schermo diviso multi-finestra
Orientamento sbloccato Configura i casi d'uso ogni volta che viene creato Activity, ad esempio nel callback onCreate() di Activity.
Utilizza la onOrientationChanged() di OrientationEventListener. All'interno del callback, aggiorna la rotazione target dei casi d'uso. In questo modo vengono gestiti i casi in cui il sistema non ricrea l'oggetto Activity anche dopo un cambio di orientamento, ad esempio quando il dispositivo viene ruotato di 180 gradi. Gestisce anche i casi in cui il display è in orientamento verticale inverso e il dispositivo non ruota in orientamento verticale inverso per impostazione predefinita. Gestisce anche i casi in cui Activity non viene ricreato quando il dispositivo ruota (ad esempio di 90 gradi). Questo accade sui dispositivi con fattori di forma piccoli quando l'app occupa metà dello schermo e sui dispositivi più grandi quando l'app occupa due terzi dello schermo.
(Facoltativo) Imposta la proprietà screenOrientation di Activity su fullSensor nel file AndroidManifest. In questo modo, la UI è in posizione verticale quando il dispositivo è in modalità Ritratto inverso e il sistema può ricreare Activity ogni volta che il dispositivo viene ruotato di 90 gradi. Non ha alcun effetto sui dispositivi che non ruotano in verticale capovolto per impostazione predefinita. La modalità multi-finestra non è supportata quando il display è in orientamento verticale inverso.
Orientamento bloccato Configura i casi d'uso una sola volta, quando Activity viene creato per la prima volta, ad esempio nel callback onCreate() di Activity.
Utilizza la onOrientationChanged() di OrientationEventListener. All'interno del callback, aggiorna la rotazione target dei casi d'uso, ad eccezione di Preview. Gestisce anche i casi in cui Activity non viene ricreato quando il dispositivo ruota (ad esempio di 90 gradi). Questo accade sui dispositivi con fattori di forma piccoli quando l'app occupa metà dello schermo e sui dispositivi più grandi quando l'app occupa due terzi dello schermo.
Override di configChanges per l'orientamento Configura i casi d'uso una sola volta, quando Activity viene creato per la prima volta, ad esempio nel callback onCreate() di Activity.
Utilizza la onOrientationChanged() di OrientationEventListener. All'interno del callback, aggiorna la rotazione target dei casi d'uso. Gestisce anche i casi in cui Activity non viene ricreato quando il dispositivo ruota (ad esempio di 90 gradi). Questo accade sui dispositivi con fattori di forma piccoli quando l'app occupa metà dello schermo e sui dispositivi più grandi quando l'app occupa due terzi dello schermo.
(Facoltativo) Imposta la proprietà screenOrientation dell'attività su fullSensor nel file AndroidManifest. Consente di visualizzare la UI in verticale quando il dispositivo è in modalità verticale inversa. Non ha alcun effetto sui dispositivi che non ruotano in verticale capovolto per impostazione predefinita. La modalità multi-finestra non è supportata quando il display è in orientamento verticale inverso.

Supporta solo gli orientamenti supportati dal dispositivo

Supporta solo gli orientamenti supportati dal dispositivo per impostazione predefinita (che possono includere o meno l'orientamento verticale/orizzontale invertito).

Scenario Linee guida Modalità schermo diviso multi-finestra
Orientamento sbloccato Configura i casi d'uso ogni volta che viene creato Activity, ad esempio nel callback onCreate() di Activity.
Utilizza onDisplayChanged() di DisplayListener. All'interno del callback, aggiorna la rotazione target dei casi d'uso, ad esempio quando il dispositivo viene ruotato di 180 gradi. Gestisce anche i casi in cui Activity non viene ricreato quando il dispositivo ruota (ad esempio di 90 gradi). Questo accade sui dispositivi con fattori di forma piccoli quando l'app occupa metà dello schermo e sui dispositivi più grandi quando l'app occupa due terzi dello schermo.
Orientamento bloccato Configura i casi d'uso una sola volta, quando Activity viene creato per la prima volta, ad esempio nel callback onCreate() di Activity.
Utilizza la onOrientationChanged() di OrientationEventListener. All'interno del callback, aggiorna la rotazione target dei casi d'uso. Gestisce anche i casi in cui Activity non viene ricreato quando il dispositivo ruota (ad esempio di 90 gradi). Questo accade sui dispositivi con fattori di forma piccoli quando l'app occupa metà dello schermo e sui dispositivi più grandi quando l'app occupa due terzi dello schermo.
Override di configChanges per l'orientamento Configura i casi d'uso una sola volta, quando Activity viene creato per la prima volta, ad esempio nel callback onCreate() di Activity.
Utilizza onDisplayChanged() di DisplayListener. All'interno del callback, aggiorna la rotazione target dei casi d'uso, ad esempio quando il dispositivo viene ruotato di 180 gradi. Gestisce anche i casi in cui Activity non viene ricreato quando il dispositivo ruota (ad esempio di 90 gradi). Questo accade sui dispositivi con fattori di forma piccoli quando l'app occupa metà dello schermo e sui dispositivi più grandi quando l'app occupa due terzi dello schermo.

Orientamento sbloccato

Un'Activity ha un orientamento sbloccato quando l'orientamento del display (ad esempio verticale o orizzontale) corrisponde all'orientamento fisico del dispositivo, ad eccezione dell'orientamento verticale/orizzontale inverso, che non è supportato per impostazione predefinita da alcuni dispositivi. Per forzare la rotazione del dispositivo in tutti e quattro gli orientamenti, imposta la proprietà screenOrientation di Activity su fullSensor.

In modalità multi-finestra, un dispositivo che non supporta la modalità verticale/orizzontale invertita per impostazione predefinita non ruoterà in modalità verticale/orizzontale invertita, anche se la sua proprietà screenOrientation è impostata su fullSensor.

<!-- The Activity has an unlocked orientation, but might not rotate to reverse
portrait/landscape in single-window mode if the device doesn't support it by
default. -->
<activity android:name=".UnlockedOrientationActivity" />

<!-- The Activity has an unlocked orientation, and will rotate to all four
orientations in single-window mode. -->
<activity
   android:name=".UnlockedOrientationActivity"
   android:screenOrientation="fullSensor" />

Orientamento bloccato

Un display ha un orientamento bloccato quando rimane nello stesso orientamento (ad esempio verticale o orizzontale) indipendentemente dall'orientamento fisico del dispositivo. A questo scopo, specifica la proprietà screenOrientation di un Activity all'interno della relativa dichiarazione nel file AndroidManifest.xml.

Quando il display ha un orientamento bloccato, il sistema non distrugge e ricrea l'Activity mentre il dispositivo viene ruotato.

<!-- The Activity keeps a portrait orientation even as the device rotates. -->
<activity
   android:name=".LockedOrientationActivity"
   android:screenOrientation="portrait" />

Modifiche alla configurazione dell'orientamento ignorate

Quando un'Activity esegue l'override delle modifiche alla configurazione dell'orientamento, il sistema non la distrugge e non la ricrea quando l'orientamento fisico del dispositivo cambia. Tuttavia, il sistema aggiorna la UI in modo che corrisponda all'orientamento fisico del dispositivo.

<!-- The Activity's UI might not rotate in reverse portrait/landscape if the
device doesn't support it by default. -->
<activity
   android:name=".OrientationConfigChangesOverriddenActivity"
   android:configChanges="orientation|screenSize" />

<!-- The Activity's UI will rotate to all 4 orientations in single-window
mode. -->
<activity
   android:name=".OrientationConfigChangesOverriddenActivity"
   android:configChanges="orientation|screenSize"
   android:screenOrientation="fullSensor" />

Configurazione dei casi d'uso della fotocamera

Negli scenari descritti sopra, i casi d'uso della videocamera possono essere configurati al momento della creazione di Activity.

Nel caso di un Activity con orientamento sbloccato, questa configurazione viene eseguita ogni volta che il dispositivo viene ruotato, poiché il sistema distrugge e ricrea l'Activity in caso di modifiche dell'orientamento. In questo modo, i casi d'uso impostano la rotazione target in modo che corrisponda all'orientamento del display per impostazione predefinita ogni volta.

Nel caso di un Activity con un orientamento bloccato o che esegue l'override delle modifiche alla configurazione dell'orientamento, questa configurazione viene eseguita una sola volta, quando il Activity viene creato per la prima volta.

class CameraActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val cameraProcessFuture = ProcessCameraProvider.getInstance(this)
        cameraProcessFuture.addListener(
            Runnable {
                val cameraProvider = cameraProcessFuture.get()

                // By default, the use cases set their target rotation to match the
                // display’s rotation.
                val preview = buildPreview()
                val imageAnalysis = buildImageAnalysis()
                val imageCapture = buildImageCapture()

                cameraProvider.bindToLifecycle(
                    this, cameraSelector, preview, imageAnalysis, imageCapture
                )
            },
            mainExecutor
        )
    }
}

Configurazione di OrientationEventListener

L'utilizzo di un OrientationEventListener ti consente di aggiornare continuamente la rotazione target dei casi d'uso della fotocamera man mano che l'orientamento del dispositivo cambia.

class CameraActivity : AppCompatActivity() {

    private val orientationEventListener by lazy {
        object : OrientationEventListener(this) {
            override fun onOrientationChanged(orientation: Int) {
                if (orientation == ORIENTATION_UNKNOWN) {
                    return
                }

                val rotation = when (orientation) {
                     in 45 until 135 -> Surface.ROTATION_270
                     in 135 until 225 -> Surface.ROTATION_180
                     in 225 until 315 -> Surface.ROTATION_90
                     else -> Surface.ROTATION_0
                 }

                 imageAnalysis.targetRotation = rotation
                 imageCapture.targetRotation = rotation
            }
        }
    }

    override fun onStart() {
        super.onStart()
        orientationEventListener.enable()
    }

    override fun onStop() {
        super.onStop()
        orientationEventListener.disable()
    }
}

Configurazione di DisplayListener

L'utilizzo di un DisplayListener consente di aggiornare la rotazione target dei casi d'uso della fotocamera in determinate situazioni, ad esempio quando il sistema non distrugge e ricrea l'Activity dopo che il dispositivo ruota di 180 gradi.

class CameraActivity : AppCompatActivity() {

    private val displayListener = object : DisplayManager.DisplayListener {
        override fun onDisplayChanged(displayId: Int) {
            if (rootView.display.displayId == displayId) {
                val rotation = rootView.display.rotation
                imageAnalysis.targetRotation = rotation
                imageCapture.targetRotation = rotation
            }
        }

        override fun onDisplayAdded(displayId: Int) {
        }

        override fun onDisplayRemoved(displayId: Int) {
        }
    }

    override fun onStart() {
        super.onStart()
        val displayManager = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
        displayManager.registerDisplayListener(displayListener, null)
    }

    override fun onStop() {
        super.onStop()
        val displayManager = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
        displayManager.unregisterDisplayListener(displayListener)
    }
}