Повороты в CameraX

В этой статье рассказывается, как настроить варианты использования CameraX в приложении, чтобы получать изображения с правильной информацией о повороте, будь то вариант использования ImageAnalysis или ImageCapture. Итак:

  • Analyzer сценария использования ImageAnalysis должен получать кадры с правильным поворотом.
  • При использовании ImageCapture фотографии должны быть правильно повернуты.

Терминология

В этой статье используются следующие термины:

Ориентация дисплея
Определяет, какая сторона устройства находится вверху. Возможны четыре значения: портретная, альбомная, обратная портретная и обратная альбомная.
Поворот экрана
Это значение, возвращаемое методом Display.getRotation(), которое представляет собой угол поворота устройства против часовой стрелки относительно его естественной ориентации.
Целевая ротация
Это значение представляет собой количество градусов, на которое нужно повернуть устройство по часовой стрелке, чтобы достичь его естественной ориентации.

Как определить целевую ротацию

В примерах ниже показано, как определить целевой поворот для устройства на основе его естественной ориентации.

Пример 1. Естественная вертикальная ориентация

Пример устройства: Pixel 3 XL

Естественная ориентация – вертикальная.
Текущая ориентация – вертикальная.

Поворот экрана = 0
Целевой поворот = 0

Естественная ориентация – вертикальная.
Текущая ориентация – горизонтальная.

Поворот экрана = 90
Целевой поворот = 90

Пример 2. Естественная горизонтальная ориентация

Пример устройства: Pixel C.

Естественная ориентация – горизонтальная.
Текущая ориентация – горизонтальная.

Поворот экрана = 0
Целевой поворот = 0

Естественная ориентация – горизонтальная.
Текущая ориентация – вертикальная.

Поворот экрана = 270
Целевой поворот = 270

Поворот изображения

Где верх, а где низ? Ориентация датчика определяется в Android как постоянное значение, которое представляет собой градусы (0, 90, 180, 270), на которые датчик поворачивается от верхней части устройства, когда устройство находится в естественном положении. Во всех случаях, показанных на диаграммах, поворот изображения описывает, как данные должны быть повернуты по часовой стрелке, чтобы они отображались в вертикальном положении.

В примерах ниже показано, как нужно повернуть изображение в зависимости от ориентации датчика камеры. Они также предполагают, что целевая ориентация совпадает с ориентацией экрана.

Пример 1. Датчик повернут на 90 градусов

Пример устройства: Pixel 3 XL

Поворот экрана = 0
Ориентация экрана = Вертикальная
Поворот изображения = 90

Поворот экрана = 90
Ориентация экрана = Альбомная
Поворот изображения = 0

Пример 2. Датчик повернут на 270 градусов

Пример устройства: Nexus 5X

Поворот экрана = 0
Ориентация экрана = вертикальная
Поворот изображения = 270

Поворот экрана = 90
Ориентация экрана = альбомная
Поворот изображения = 180

Пример 3. Датчик повернут на 0 градусов

Пример устройства: Pixel C (планшет)

Поворот экрана = 0
Ориентация экрана = альбомная
Поворот изображения = 0

Поворот экрана = 270
Ориентация экрана = Книжная
Поворот изображения = 90

Вычисление поворота изображения

ImageAnalysis

Analyzer ImageAnalysis получает изображения с камеры в виде ImageProxy. Каждое изображение содержит информацию о повороте, доступ к которой можно получить через:

val rotation = imageProxy.imageInfo.rotationDegrees

Это значение представляет собой угол в градусах, на который нужно повернуть изображение по часовой стрелке, чтобы оно соответствовало целевому повороту ImageAnalysis. В контексте приложения Android целевой поворот ImageAnalysis обычно соответствует ориентации экрана.

ImageCapture

Обратный вызов прикрепляется к экземпляру ImageCapture, чтобы сигнализировать о готовности результата съемки. Результатом может быть либо полученное изображение, либо ошибка.

При съемке фотографии можно использовать один из следующих типов обратного вызова:

  • OnImageCapturedCallback. Получает изображение с доступом в памяти в виде ImageProxy.
  • OnImageSavedCallback – вызывается, когда полученное изображение успешно сохранено в месте, указанном в ImageCapture.OutputFileOptions. В параметрах можно указать File, OutputStream или местоположение в MediaStore.

Поворот полученного изображения, независимо от его формата (ImageProxy, File, OutputStream, MediaStore Uri), представляет собой угол поворота, на который полученное изображение должно быть повернуто по часовой стрелке, чтобы соответствовать целевому повороту ImageCapture, который, опять же, в контексте приложения Android обычно соответствует ориентации экрана.

Получить информацию о повороте изображения можно одним из следующих способов:

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

Как проверить ориентацию изображения

После успешного запроса на съемку варианты использования ImageAnalysis и ImageCapture получают от камеры ImageProxy. Объект ImageProxy содержит изображение и информацию о нем, включая угол поворота. Эта информация о повороте представляет собой градусы, на которые необходимо повернуть изображение, чтобы оно соответствовало целевому повороту варианта использования.

Процесс проверки поворота изображения

Рекомендации по повороту целевого объекта для ImageCapture/ImageAnalysis

Поскольку многие устройства по умолчанию не поддерживают обратную книжную или обратную альбомную ориентацию, некоторые приложения Android не поддерживают эти ориентации. От этого зависит, как можно изменить целевую ротацию.

Ниже приведены две таблицы, определяющие, как синхронизировать целевой поворот вариантов использования с поворотом дисплея. В первом примере показано, как это сделать с поддержкой всех четырех ориентаций, а во втором – только с поддержкой ориентаций, которые устройство использует по умолчанию.

Чтобы выбрать, каким рекомендациям следовать в приложении:

  1. Проверьте, заблокирована ли ориентация камеры Activity в вашем приложении, разблокирована ли она или переопределяет изменения конфигурации ориентации.

  2. Решите, должна ли камера в приложении Activity поддерживать все четыре ориентации устройства (книжную, обратную книжную, альбомную и обратную альбомную) или только те, которые по умолчанию поддерживаются устройством, на котором она работает.

Поддержка всех четырех ориентаций

В таблице ниже приведены рекомендации, которым нужно следовать, если устройство не поворачивается в обратную портретную ориентацию. То же самое можно применить к устройствам, которые не поворачиваются в обратную горизонтальную ориентацию.

Сценарий Правила Однооконный режим Многооконный режим с разделением экрана
Разблокированная ориентация Настраивайте варианты использования каждый раз, когда создается Activity, например в обратном вызове onCreate() для Activity.
Используйте onOrientationChanged() OrientationEventListener. Внутри обратного вызова обновите целевой поворот вариантов использования. Это позволяет обрабатывать случаи, когда система не воссоздает Activity даже после изменения ориентации, например когда устройство поворачивается на 180 градусов. Также обрабатывает случаи, когда экран находится в обратной портретной ориентации, а устройство не поворачивается в обратную портретную ориентацию по умолчанию. Также обрабатывает случаи, когда Activity не создается заново при повороте устройства (например, на 90 градусов). Это происходит на устройствах малого форм-фактора, когда приложение занимает половину экрана, и на более крупных устройствах, когда приложение занимает две трети экрана.
Необязательно. В файле AndroidManifest задайте для свойства screenOrientation объекта Activity значение fullSensor. Это позволяет интерфейсу оставаться в вертикальном положении, когда устройство находится в обратной портретной ориентации, и позволяет системе воссоздавать Activity всякий раз, когда устройство поворачивается на 90 градусов. Не влияет на устройства, которые по умолчанию не поворачиваются в обратную портретную ориентацию. Многооконный режим не поддерживается, если экран находится в обратной портретной ориентации.
Фиксированная ориентация Настройте варианты использования только один раз, когда Activity создается впервые, например в обратном вызове onCreate() Activity.
Используйте onOrientationChanged() OrientationEventListener. Внутри обратного вызова обновите целевой поворот вариантов использования, кроме предварительного просмотра. Также обрабатывает случаи, когда Activity не создается заново при повороте устройства (например, на 90 градусов). Это происходит на устройствах малого форм-фактора, когда приложение занимает половину экрана, и на более крупных устройствах, когда приложение занимает две трети экрана.
Переопределены изменения конфигурации ориентации Настройте варианты использования только один раз, когда Activity создается впервые, например в обратном вызове onCreate() Activity.
Используйте onOrientationChanged() OrientationEventListener. Внутри обратного вызова обновите целевой поворот вариантов использования. Также обрабатывает случаи, когда Activity не создается заново при повороте устройства (например, на 90 градусов). Это происходит на устройствах малого форм-фактора, когда приложение занимает половину экрана, и на более крупных устройствах, когда приложение занимает две трети экрана.
При необходимости задайте для свойства screenOrientation объекта Activity значение fullSensor в файле AndroidManifest. Позволяет интерфейсу оставаться в вертикальном положении, когда устройство находится в обратном портретном режиме. Не влияет на устройства, которые по умолчанию не поворачиваются в обратную вертикальную ориентацию. Многооконный режим не поддерживается, если экран находится в обратной портретной ориентации.

Поддерживать только ориентации, поддерживаемые устройством

Поддерживать только ориентации, которые устройство поддерживает по умолчанию (может включать или не включать обратную вертикальную/обратную горизонтальную ориентацию).

Сценарий Правила Многооконный режим с разделением экрана
Разблокированная ориентация Настраивайте варианты использования каждый раз, когда создается Activity, например в обратном вызове onCreate() для Activity.
Используйте onDisplayChanged() DisplayListener. Внутри обратного вызова обновите целевое вращение вариантов использования, например, когда устройство повернуто на 180 градусов. Также обрабатывает случаи, когда Activity не создается заново при повороте устройства (например, на 90 градусов). Это происходит на устройствах малого форм-фактора, когда приложение занимает половину экрана, и на более крупных устройствах, когда приложение занимает две трети экрана.
Фиксированная ориентация Настройте варианты использования только один раз, когда Activity создается впервые, например в обратном вызове onCreate() Activity.
Используйте onOrientationChanged() OrientationEventListener. Внутри обратного вызова обновите целевой поворот вариантов использования. Также обрабатывает случаи, когда Activity не создается заново при повороте устройства (например, на 90 градусов). Это происходит на устройствах малого форм-фактора, когда приложение занимает половину экрана, и на более крупных устройствах, когда приложение занимает две трети экрана.
Переопределены изменения конфигурации ориентации Настройте варианты использования только один раз, когда Activity создается впервые, например в обратном вызове onCreate() Activity.
Используйте onDisplayChanged() DisplayListener. Внутри обратного вызова обновите целевое вращение вариантов использования, например, когда устройство повернуто на 180 градусов. Также обрабатывает случаи, когда Activity не создается заново при повороте устройства (например, на 90 градусов). Это происходит на устройствах малого форм-фактора, когда приложение занимает половину экрана, и на более крупных устройствах, когда приложение занимает две трети экрана.

Ориентация не заблокирована

Ориентация Activity не заблокирована, если ориентация экрана (например, книжная или альбомная) соответствует физической ориентации устройства, за исключением обратной книжной/альбомной ориентации, которая по умолчанию не поддерживается на некоторых устройствах. Чтобы принудительно включить поворот устройства во всех четырех направлениях, задайте для свойства screenOrientation объекта Activity значение fullSensor.

В многооконном режиме устройство, которое не поддерживает обратную книжную/альбомную ориентацию, по умолчанию не будет поворачиваться в обратную книжную/альбомную ориентацию, даже если для его свойства screenOrientation задано значение 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" />

Ориентация заблокирована

Экран имеет фиксированную ориентацию, если он остается в одной и той же ориентации (например, книжной или альбомной) независимо от физической ориентации устройства. Для этого укажите свойство screenOrientation элемента Activity в его объявлении в файле AndroidManifest.xml.

Если ориентация экрана заблокирована, система не уничтожает и не воссоздает Activity при повороте устройства.

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

Изменения конфигурации ориентации переопределены

Если Activity переопределяет изменения конфигурации ориентации, система не уничтожает и не воссоздает его при изменении физической ориентации устройства. Однако система обновляет интерфейс в соответствии с физической ориентацией устройства.

<!-- 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" />

Настройка вариантов использования камеры

В описанных выше сценариях варианты использования камеры можно настроить при первом создании Activity.

Если ориентация Activity не заблокирована, то эта настройка выполняется каждый раз при повороте устройства, поскольку система уничтожает и заново создает Activity при изменении ориентации. В результате целевой поворот для вариантов использования по умолчанию всегда соответствует ориентации экрана.

Если в Activity заблокирована ориентация или переопределены изменения конфигурации ориентации, эта настройка выполняется один раз при создании Activity.

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

Настройка OrientationEventListener

Использование OrientationEventListener позволяет вам постоянно обновлять целевое вращение вариантов использования камеры по мере изменения ориентации устройства.

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

Настройка DisplayListener

Использование DisplayListener позволяет обновлять целевой поворот камеры в определенных ситуациях, например когда система не уничтожает и не воссоздает Activity после поворота устройства на 180 градусов.

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