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
Analyzerdel caso d'usoImageAnalysisdeve ricevere i frame con la rotazione corretta. - Il caso d'uso
ImageCapturedeve 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 Rotazione del display = 0 |
|
|
Orientamento naturale = verticale Rotazione del display = 90 |
|
Esempio 2: orientamento orizzontale naturale
| Esempio di dispositivo: Pixel C | |
|---|---|
|
Orientamento naturale = Orizzontale Rotazione del display = 0 |
|
|
Orientamento naturale = Orizzontale Rotazione del display = 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 |
|
|
Rotazione del display = 90 |
|
Esempio 2: sensore ruotato di 270 gradi
| Esempio di dispositivo: Nexus 5X | |
|---|---|
|
Rotazione del display = 0 |
|
|
Rotazione del display = 90 |
|
Esempio 3: sensore ruotato di 0 gradi
| Esempio di dispositivo: Pixel C (tablet) | |
|---|---|
|
Rotazione del display = 0 |
|
|
Rotazione del display = 270 |
|
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 diImageProxy.OnImageSavedCallback: viene richiamato quando l'immagine acquisita è stata archiviata correttamente nella posizione specificata daImageCapture.OutputFileOptions. Le opzioni possono specificare unFile, unOutputStreamo una località inMediaStore.
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.
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:
Verifica se la fotocamera
Activitydella tua app ha un orientamento bloccato, un orientamento sbloccato o se esegue l'override delle modifiche alla configurazione dell'orientamento.Decidi se la fotocamera della tua app
Activitydeve 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) } }