Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Multi-camera API

Примечание. На этой странице рассматривается пакет Camera2. Если вашему приложению не требуются определенные низкоуровневые функции Camera2, рекомендуем использовать CameraX. Обе библиотеки поддерживают Android 5.0 (API уровня 21) и более поздние версии.

Поддержка нескольких камер была добавлена в Android 9 (уровень API 28). С момента выпуска API на рынке появились устройства, которые его поддерживают. Многие варианты использования нескольких камер тесно связаны с конкретной конфигурацией оборудования. Другими словами, не все сценарии использования совместимы с каждым устройством, что делает функции с несколькими камерами хорошим кандидатом для Play Feature Delivery.

Вот несколько примеров:

Масштабирование. Переключение между камерами в зависимости от области кадрирования или выбранного фокусного расстояния.
Глубина. Использование нескольких камер для создания карты глубины.
Боке. Использование информации о глубине для имитации узкого диапазона фокусировки, как у цифровых зеркальных камер.

Разница между логическими и физическими камерами

Чтобы понять, как работает API для нескольких камер, нужно разобраться в разнице между логическими и физическими камерами. Для примера рассмотрим устройство с тремя задними камерами. В этом примере каждая из трех задних камер считается физической. Логическая камера – это группа из двух или более физических камер. Выходные данные логической камеры могут представлять собой поток, поступающий от одной из физических камер, или объединенный поток, поступающий от нескольких физических камер одновременно. В любом случае поток обрабатывается аппаратно-зависимым уровнем (HAL) камеры.

Многие производители телефонов разрабатывают собственные приложения для камеры, которые обычно предустановлены на их устройствах. Чтобы использовать все возможности оборудования, они могут применять закрытые или скрытые API или получать особые права от драйвера, недоступные другим приложениям. Некоторые устройства реализуют концепцию логических камер, предоставляя объединенный поток кадров с разных физических камер, но только для определенных привилегированных приложений. Часто фреймворку доступна только одна из физических камер. На диаграмме ниже показано, как обстояли дела со сторонними разработчиками до выхода Android 9.

**Рисунок 1.** Функции камеры, которые обычно доступны только привилегированным приложениям.

Начиная с Android 9, в приложениях для Android запрещено использовать закрытые API. Поскольку в фреймворке есть поддержка нескольких камер, производителям телефонов настоятельно рекомендуется предоставлять логическую камеру для всех физических камер, направленных в одну сторону. Ниже описано, что сторонние разработчики увидят на устройствах с Android 9 и более поздними версиями.

**Рисунок 2.** Полный доступ разработчиков ко всем камерам, начиная с Android 9.

Возможности логической камеры полностью зависят от реализации HAL камеры OEM-производителем. Например, на устройстве Pixel 3 логическая камера выбирает одну из физических камер в зависимости от заданного фокусного расстояния и области кадрирования.

API для нескольких камер

В новом API добавлены следующие константы, классы и методы:

В связи с изменениями в документе CDD (Android Compatibility Definition Document) к разработчикам, использующим API для нескольких камер, предъявляются определенные требования. Устройства с двумя камерами существовали и до Android 9, но одновременное открытие нескольких камер требовало проб и ошибок. В Android 9 и более поздних версиях набор правил определяет, когда можно открыть пару физических камер, которые являются частью одной логической камеры.

В большинстве случаев устройства с Android 9 и более поздними версиями ОС поддерживают все физические камеры (за исключением, возможно, менее распространенных типов датчиков, таких как инфракрасные) наряду с более простой в использовании логической камерой. Для каждой комбинации потоков, которые гарантированно будут работать, один поток, принадлежащий логической камере, можно заменить двумя потоками от базовых физических камер.

Несколько трансляций одновременно

В разделе Одновременное использование нескольких видео с камеры описаны правила одновременного использования нескольких видео с одной камеры. Для нескольких камер действуют те же правила, за одним исключением. CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA объясняет, как заменить логический поток YUV_420_888 или необработанный поток двумя физическими потоками. То есть каждый поток типа YUV или RAW можно заменить двумя потоками идентичного типа и размера. Для начала можно использовать трансляцию с камеры со следующей гарантированной конфигурацией для устройств с одной камерой:

Поток 1: тип YUV, размер MAXIMUM из логической камеры id = 0.

Затем устройство с поддержкой нескольких камер позволяет создать сеанс, заменяющий этот логический поток YUV двумя физическими потоками:

Поток 1: тип YUV, размер MAXIMUM с физической камеры id = 1
Поток 2: тип YUV, размер MAXIMUM с физической камеры id = 2

Вы можете заменить поток YUV или RAW двумя эквивалентными потоками, только если эти две камеры входят в логическую группу камер, указанную в CameraCharacteristics.getPhysicalCameraIds().

Гарантии, предоставляемые фреймворком, – это лишь необходимый минимум для одновременного получения кадров с нескольких физических камер. Дополнительные потоки поддерживаются на большинстве устройств, иногда даже позволяя открывать несколько физических камер независимо друг от друга. Поскольку фреймворк не гарантирует этого, вам придется тестировать и настраивать каждое устройство методом проб и ошибок.

Как создать сеанс с несколькими физическими камерами

При использовании физических камер на устройстве с поддержкой нескольких камер откройте одну камеру CameraDevice (логическую) и взаимодействуйте с ней в рамках одного сеанса. Создайте один сеанс с помощью API CameraDevice.createCaptureSession(SessionConfiguration config), который был добавлен на уровне API 28. В конфигурации сеанса есть несколько конфигураций вывода, у каждой из которых есть набор целей вывода и, при необходимости, выбранный идентификатор физической камеры.

**Рисунок 3.** Модель SessionConfiguration и OutputConfiguration

С запросами на запись связан целевой вывод. Фреймворк определяет, на какую физическую (или логическую) камеру отправляются запросы, в зависимости от того, какая цель вывода подключена. Если цель вывода соответствует одной из целей вывода, отправленных в качестве конфигурации вывода вместе с идентификатором физической камеры, то эта физическая камера получает и обрабатывает запрос.

Использование двух физических камер

Ещё одно дополнение к API камеры для нескольких камер – возможность идентифицировать логические камеры и находить физические камеры за ними. Вы можете определить функцию, которая поможет определить потенциальные пары физических камер, которые можно использовать для замены одного из потоков логической камеры:

/**
 * Helper class used to encapsulate a logical camera and two underlying
 * physical cameras
 */
data class DualCamera(val logicalId: String, val physicalId1: String, val physicalId2: String)

fun findDualCameras(manager: CameraManager, facing: Int? = null): List<DualCamera> {
    val dualCameras = mutableListOf<DualCamera>()

    // Iterate over all the available camera characteristics.
    manager.cameraIdList.map {
        Pair(manager.getCameraCharacteristics(it), it)
    }.filter {
        // Filter by cameras facing the requested direction.
        facing == null || it.first.get(CameraCharacteristics.LENS_FACING) == facing
    }.filter {
        // Filter by logical cameras.
        // CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA requires API >= 28.
        it.first.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)?.contains(
            CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
        ) ?: false
    }.forEach {
        // All possible pairs from the list of physical cameras are valid results.
        // NOTE: There could be N physical cameras as part of a logical camera grouping.
        // getPhysicalCameraIds() requires API >= 28.
        val physicalCameras = it.first.physicalCameraIds.toTypedArray()
        for (idx1 in 0 until physicalCameras.size) {
            for (idx2 in (idx1 + 1) until physicalCameras.size) {
                dualCameras.add(
                    DualCamera(
                        it.second, physicalCameras[idx1], physicalCameras[idx2]
                    )
                )
            }
        }
    }

    return dualCameras
}MultiCamera.kt

Управление состоянием физических камер контролируется логической камерой. Чтобы открыть двойную камеру, откройте логическую камеру, соответствующую физическим камерам:

fun openDualCamera(
    cameraManager: CameraManager,
    dualCamera: DualCamera,
    executor: Executor,
    callback: (CameraDevice) -> Unit
) {

    // openCamera() requires API >= 28.
    cameraManager.openCamera(
        dualCamera.logicalId, executor,
        object : CameraDevice.StateCallback() {
            override fun onOpened(device: CameraDevice) = callback(device)
            // Omitting for brevity...
            override fun onError(device: CameraDevice, error: Int) = onDisconnected(device)
            override fun onDisconnected(device: CameraDevice) = device.close()
        }
    )
}MultiCamera.kt

В остальном процесс не отличается от того, как камера открывалась в предыдущих версиях Android. При создании сеанса захвата с помощью нового API конфигурации сеанса фреймворк связывает определенные цели с идентификаторами физических камер:

/**
 * Helper type definition that encapsulates 3 sets of output targets:
 *
 * 1. Logical camera
 * 2. First physical camera
 * 3. Second physical camera
 */
typealias DualCameraOutputs =
    Triple<MutableList<Surface>?, MutableList<Surface>?, MutableList<Surface>?>

fun createDualCameraSession(
    cameraManager: CameraManager,
    dualCamera: DualCamera,
    targets: DualCameraOutputs,
    executor: Executor,
    callback: (CameraCaptureSession) -> Unit
) {

    // Create 3 sets of output configurations: one for the logical camera, and
    // one for each of the physical cameras.
    val outputConfigsLogical = targets.first?.map { OutputConfiguration(it) }
    val outputConfigsPhysical1 = targets.second?.map {
        OutputConfiguration(it).apply { setPhysicalCameraId(dualCamera.physicalId1) }
    }
    val outputConfigsPhysical2 = targets.third?.map {
        OutputConfiguration(it).apply { setPhysicalCameraId(dualCamera.physicalId2) }
    }

    // Put all the output configurations into a single flat array.
    val outputConfigsAll = arrayOf(
        outputConfigsLogical, outputConfigsPhysical1, outputConfigsPhysical2
    )
        .filterNotNull().flatMap { it }

    // Instantiate a session configuration that can be used to create a session.
    val sessionConfiguration = SessionConfiguration(
        SessionConfiguration.SESSION_REGULAR,
        outputConfigsAll, executor,
        object : CameraCaptureSession.StateCallback() {
            override fun onConfigured(session: CameraCaptureSession) = callback(session)
            // Omitting for brevity...
            override fun onConfigureFailed(session: CameraCaptureSession) = session.device.close()
        }
    )

    // Open the logical camera using the previously defined function.
    openDualCamera(cameraManager, dualCamera, executor = executor) {

        // Finally create the session and return using the callback.
        it.createCaptureSession(sessionConfiguration)
    }
}MultiCamera.kt

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

Когда сеанс камеры будет готов, отправьте выбранные запросы на съемку. Каждая цель запроса на захват получает данные от связанной с ней физической камеры, если она используется, или возвращается к логической камере.

Пример использования Zoom

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

Пример переключения камер для масштабирования — **Рисунок 4.** Пример переключения камер для использования уровня масштабирования (из рекламы Pixel 3)

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

fun findShortLongCameraPair(manager: CameraManager, facing: Int? = null): DualCamera? {

    return findDualCameras(manager, facing).map {
        val characteristics1 = manager.getCameraCharacteristics(it.physicalId1)
        val characteristics2 = manager.getCameraCharacteristics(it.physicalId2)

        // Query the focal lengths advertised by each physical camera.
        val focalLengths1 = characteristics1.get(
            CameraCharacteristics.LENS_INFO_AVAILABLE_FOCAL_LENGTHS
        ) ?: floatArrayOf(0F)
        val focalLengths2 = characteristics2.get(
            CameraCharacteristics.LENS_INFO_AVAILABLE_FOCAL_LENGTHS
        ) ?: floatArrayOf(0F)

        // Compute the largest difference between min and max focal lengths between cameras.
        val focalLengthsDiff1 = (focalLengths2.maxOrNull() ?: 0f) - (focalLengths1.minOrNull() ?: 0f)
        val focalLengthsDiff2 = (focalLengths1.maxOrNull() ?: 0f) - (focalLengths2.minOrNull() ?: 0f)

        // Return the pair of camera IDs and the difference between min and max focal lengths.
        if (focalLengthsDiff1 < focalLengthsDiff2) {
            Pair(DualCamera(it.logicalId, it.physicalId1, it.physicalId2), focalLengthsDiff1)
        } else {
            Pair(DualCamera(it.logicalId, it.physicalId2, it.physicalId1), focalLengthsDiff2)
        }

        // Return only the pair with the largest difference, or null if no pairs are found.
    }.maxByOrNull { it.second }?.first
}MultiCamera.kt

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

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

val cameraManager: CameraManager = ...
val cameraExecutor: Executor = ...  // owned by your activity / fragment

// Get the two output targets from the activity / fragment.
val surface1 = ...  // from SurfaceView
val surface2 = ...  // from SurfaceView

val dualCamera = findShortLongCameraPair(cameraManager) ?: return
val outputTargets = DualCameraOutputs(
    null, mutableListOf(surface1), mutableListOf(surface2)
)

// Here you open the logical camera, configure the outputs and create a session.
createDualCameraSession(
    cameraManager, dualCamera, targets = outputTargets, executor = cameraExecutor
) { session ->

    // Create a single request which has one target for each physical camera.
    // NOTE: Each target receive frames from only its associated physical camera.
    val requestTemplate = CameraDevice.TEMPLATE_PREVIEW
    val captureRequest = session.device.createCaptureRequest(requestTemplate).apply {
        arrayOf(surface1, surface2).forEach { addTarget(it) }
    }.build()

    // Set the sticky request for the session and you are done.
    session.setRepeatingRequest(captureRequest, null, null)
}MultiCamera.kt

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

Искажение объектива

Все объективы в той или иной степени искажают изображение. В Android вы можете запросить искажение, создаваемое линзами, с помощью CameraCharacteristics.LENS_DISTORTION, которое заменяет устаревшее CameraCharacteristics.LENS_RADIAL_DISTORTION. Для логических камер искажение минимально, и ваше приложение может использовать кадры практически в том виде, в каком они поступают с камеры. У физических камер могут быть очень разные конфигурации объективов, особенно у широкоугольных.

На некоторых устройствах может быть реализована автоматическая коррекция искажений с помощью CaptureRequest.DISTORTION_CORRECTION_MODE. На большинстве устройств коррекция искажений включена по умолчанию.

val cameraSession: CameraCaptureSession = ...

// Use still capture template to build the capture request.
val captureRequest = cameraSession.device.createCaptureRequest(
    CameraDevice.TEMPLATE_STILL_CAPTURE
)

// Determine if this device supports distortion correction.
val characteristics: CameraCharacteristics = ...
val supportsDistortionCorrection = characteristics.get(
    CameraCharacteristics.DISTORTION_CORRECTION_AVAILABLE_MODES
)?.contains(
    CameraMetadata.DISTORTION_CORRECTION_MODE_HIGH_QUALITY
) ?: false

if (supportsDistortionCorrection) {
    captureRequest.set(
        CaptureRequest.DISTORTION_CORRECTION_MODE,
        CameraMetadata.DISTORTION_CORRECTION_MODE_HIGH_QUALITY
    )
}

// Add output target, set other capture request parameters...

// Dispatch the capture request.
cameraSession.capture(captureRequest.build(), ...)MultiCamera.kt

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

Multi-camera API Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.