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

Архитектура CameraX

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

Структура CameraX

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

Preview – принимает поверхность для отображения предварительного просмотра, например PreviewView.
Анализ изображений. Предоставляет буферы, доступные ЦП, для анализа, например для машинного обучения.
Фотосъемка. Сделайте и сохраните фотографию.
Запись видео. Записывайте видео и аудио с помощью VideoCapture.

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

Модель API

Чтобы работать с библиотекой, укажите следующее:

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

Приложение CameraX можно написать двумя способами: с помощью CameraController (самый простой способ) или CameraProvider (если вам нужно больше гибкости).

CameraController

CameraController предоставляет большинство основных функций CameraX в одном классе. Для него требуется минимум кода настройки, и он автоматически обрабатывает инициализацию камеры, управление вариантами использования, целевое вращение, фокусировку по касанию, масштабирование щипком и многое другое. Конкретный класс, расширяющий CameraController, – это LifecycleCameraController.

val previewView: PreviewView = viewBinding.previewView
var cameraController = LifecycleCameraController(baseContext)
cameraController.bindToLifecycle(this)
cameraController.cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
previewView.controller = cameraController

Для CameraController по умолчанию используются следующие UseCase: Preview, ImageCapture и ImageAnalysis. Чтобы отключить ImageCapture или ImageAnalysis или включить VideoCapture, используйте метод setEnabledUseCases().

Другие примеры использования CameraController можно найти в примере сканера QR-кодов или в видео об основах CameraController.

CameraProvider

CameraProvider также прост в использовании, но поскольку разработчик приложений выполняет больше настроек, у него есть больше возможностей для персонализации конфигурации, например включение поворота выходного изображения или настройка графического формата выходного изображения в ImageAnalysis. Вы также можете использовать собственный Surface для предварительного просмотра камеры, что обеспечивает большую гибкость, тогда как с CameraController вы должны использовать PreviewView. Использовать существующий код Surface может быть полезно, если он уже является входными данными для других частей вашего приложения.

Вы настраиваете варианты использования с помощью методов set() и завершаете их с помощью метода build(). Каждый объект предоставляет набор API, предназначенных для конкретного случая. Например, в случае с фотосъемкой используется вызов метода takePicture().

Вместо того чтобы размещать вызовы методов запуска и остановки в onResume() и onPause(), приложение указывает жизненный цикл, с которым нужно связать камеру, используя cameraProvider.bindToLifecycle(). Затем этот жизненный цикл сообщает CameraX, когда нужно настроить сеанс съемки, и обеспечивает соответствующее изменение состояния камеры в соответствии с переходами жизненного цикла.

Инструкции по реализации для каждого варианта использования приведены в разделах Реализация предварительного просмотра, Анализ изображений, Фотосъемка и Захват видео.

Для показа предварительного изображения используется Surface. Для приложений создайте вариант использования с параметрами конфигурации, используя следующий код:

val preview = Preview.Builder().build()
val viewFinder: PreviewView = findViewById(R.id.previewView)

// The use case is bound to an Android Lifecycle with the following code.
val camera = cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview)

// PreviewView creates a surface provider and is the recommended provider.
preview.setSurfaceProvider(viewFinder.getSurfaceProvider())Architecture.kt

Дополнительные примеры кода можно найти в официальном примере приложения CameraX.

Жизненные циклы CameraX

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

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

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

Если вы разделите владельцев жизненного цикла для представлений и вариантов использования камеры (например, если вы используете собственный жизненный цикл или сохраняемый фрагмент), то вам нужно будет убедиться, что все варианты использования отвязаны от CameraX. Для этого используйте ProcessCameraProvider.unbindAll() или отвяжите каждый вариант использования по отдельности. Кроме того, при привязке вариантов использования к жизненному циклу вы можете разрешить CameraX управлять открытием и закрытием сеанса съемки и отменять привязку вариантов использования.

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

Собственные LifecycleOwner

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

В следующем примере кода показано, как создать простой пользовательский LifecycleOwner:

class CustomLifecycle : LifecycleOwner {
    private val lifecycleRegistry: LifecycleRegistry

    init {
        lifecycleRegistry = LifecycleRegistry(this)
        lifecycleRegistry.currentState = Lifecycle.State.CREATED
    }
    // ...
    fun doOnResume() {
        lifecycleRegistry.currentState = State.RESUMED
    }
    // ...
    override val lifecycle: Lifecycle
        get() = lifecycleRegistry
}Architecture.kt

С помощью этого LifecycleOwner ваше приложение может размещать переходы между состояниями в нужных точках своего кода. Подробнее о том, как реализовать собственный LifecycleOwner…

Примеры одновременного использования

Сценарии использования могут выполняться одновременно. Хотя варианты использования можно последовательно привязать к жизненному циклу, лучше привязать все варианты использования с помощью одного вызова CameraProcessProvider.bindToLifecycle(). Подробнее о том, как обрабатывать изменения конфигурации…

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

private lateinit var imageCapture: ImageCapture

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val cameraProviderFuture = ProcessCameraProvider.getInstance(this)

    cameraProviderFuture.addListener(
        Runnable {
            // Camera provider is now guaranteed to be available.
            val cameraProvider = cameraProviderFuture.get()

            // Set up the preview use case to display camera preview.
            val preview = Preview.Builder().build()

            // Set up the capture use case to allow users to take photos.
            imageCapture = ImageCapture.Builder()
                .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
                .build()

            // Choose the camera by requiring a lens facing.
            val cameraSelector = CameraSelector.Builder()
                .requireLensFacing(CameraSelector.LENS_FACING_FRONT)
                .build()

            // Attach use cases to the camera with the same lifecycle owner.
            val camera = cameraProvider.bindToLifecycle(
                this as LifecycleOwner, cameraSelector, preview, imageCapture
            )

            // Connect the preview use case to the previewView.
            preview.setSurfaceProvider(
                previewView.getSurfaceProvider()
            )
        },
        ContextCompat.getMainExecutor(this)
    )
}Architecture.kt

CameraX позволяет одновременно использовать по одному экземпляру Preview, VideoCapture, ImageAnalysis и ImageCapture. Кроме того,

Каждый вариант использования может работать самостоятельно. Например, приложение может записывать видео без предварительного просмотра.
Если расширения включены, гарантированно будет работать только комбинация ImageCapture и Preview. В зависимости от реализации OEM, возможно, не удастся добавить ImageAnalysis. Расширения нельзя включить для варианта использования VideoCapture. Подробную информацию вы найдете в справочной документации по расширениям.
В зависимости от возможностей камеры некоторые из них могут поддерживать комбинацию в режимах с более низким разрешением, но не могут поддерживать ту же комбинацию в некоторых режимах с более высоким разрешением.
На устройствах с аппаратным уровнем камеры FULL или ниже сочетание Preview, VideoCapture и ImageCapture или ImageAnalysis может заставить CameraX дублировать поток PRIV камеры для Preview и VideoCapture. Такое дублирование, называемое совместным использованием потока, позволяет одновременно использовать эти функции, но требует повышенной вычислительной мощности. В результате задержка может немного увеличиться, а время работы от батареи – сократиться.

Поддерживаемый уровень аппаратного обеспечения можно получить из Camera2CameraInfo. Например, следующий код проверяет, является ли задняя камера по умолчанию устройством LEVEL_3:

@androidx.annotation.OptIn(ExperimentalCamera2Interop::class)
fun isBackCameraLevel3Device(cameraProvider: ProcessCameraProvider): Boolean {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
        return CameraSelector.DEFAULT_BACK_CAMERA
            .filter(cameraProvider.availableCameraInfos)
            .firstOrNull()
            ?.let { Camera2CameraInfo.from(it) }
            ?.getCameraCharacteristic(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL) ==
            CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3
    }
    return false
}Architecture.kt

Разрешения

Приложению потребуется разрешение CAMERA. Чтобы сохранять изображения в файлы, ему также потребуется разрешение WRITE_EXTERNAL_STORAGE (кроме устройств с Android 10 или более поздней версии).

Подробнее о том, как запрашивать разрешения для приложения…

Требования

Минимальные требования к версии CameraX:

Уровень API Android 21
Компоненты архитектуры Android 1.1.1

Для действий, учитывающих жизненный цикл, используйте FragmentActivity или AppCompatActivity.

Объявление зависимостей

Чтобы добавить зависимость от CameraX, необходимо добавить в проект репозиторий Google Maven.

Откройте файл settings.gradle проекта и добавьте хранилище google(), как показано ниже.

Яркий

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Kotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Добавьте в конец блока Android следующий код:

Яркий

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Добавьте в файл build.gradle каждого модуля приложения следующий код:

Groovy

dependencies {
  // CameraX core library using the camera2 implementation
  def camerax_version = "1.7.0-rc01"
  // The following line is optional, as the core library is included indirectly by camera-camera2
  implementation "androidx.camera:camera-core:${camerax_version}"
  implementation "androidx.camera:camera-camera2:${camerax_version}"
  // If you want to additionally use the CameraX Lifecycle library
  implementation "androidx.camera:camera-lifecycle:${camerax_version}"
  // If you want to additionally use the CameraX VideoCapture library
  implementation "androidx.camera:camera-video:${camerax_version}"
  // If you want to additionally use the CameraX View class
  implementation "androidx.camera:camera-view:${camerax_version}"
  // If you want to additionally add CameraX ML Kit Vision Integration
  implementation "androidx.camera:camera-mlkit-vision:${camerax_version}"
  // If you want to additionally use the CameraX Extensions library
  implementation "androidx.camera:camera-extensions:${camerax_version}"
}

Kotlin

dependencies {
    // CameraX core library using the camera2 implementation
    val camerax_version = "1.7.0-rc01"
    // The following line is optional, as the core library is included indirectly by camera-camera2
    implementation("androidx.camera:camera-core:${camerax_version}")
    implementation("androidx.camera:camera-camera2:${camerax_version}")
    // If you want to additionally use the CameraX Lifecycle library
    implementation("androidx.camera:camera-lifecycle:${camerax_version}")
    // If you want to additionally use the CameraX VideoCapture library
    implementation("androidx.camera:camera-video:${camerax_version}")
    // If you want to additionally use the CameraX View class
    implementation("androidx.camera:camera-view:${camerax_version}")
    // If you want to additionally add CameraX ML Kit Vision Integration
    implementation("androidx.camera:camera-mlkit-vision:${camerax_version}")
    // If you want to additionally use the CameraX Extensions library
    implementation("androidx.camera:camera-extensions:${camerax_version}")
}

Подробнее о том, как настроить приложение в соответствии с этими требованиями…

Совместимость CameraX с Camera2

CameraX основана на Camera2 и предоставляет способы чтения и даже записи свойств в реализации Camera2. Подробную информацию можно найти в пакете Interop.

Чтобы узнать больше о том, как CameraX настраивает свойства Camera2, используйте Camera2CameraInfo для чтения базового CameraCharacteristics. Вы также можете записать базовые свойства Camera2 одним из двух способов:

Используйте Camera2CameraControl, чтобы задать свойства для базового элемента CaptureRequest, например режим автофокуса.
Расширьте UseCase CameraX с помощью Camera2Interop.Extender. Это позволяет задавать свойства в CaptureRequest, как и в Camera2CameraControl. Кроме того, вы можете задать дополнительные настройки, например выбрать сценарий использования камеры. Подробнее о том, как использовать варианты использования потока для повышения производительности…

В следующем примере кода показано, как оптимизировать поток для видеовызова. Используйте Camera2CameraInfo, чтобы узнать, доступен ли вариант использования потока видеовызова. Затем используйте Camera2Interop.Extender, чтобы задать способ использования базового потока.

// Set underlying Camera2 stream use case to optimize for video calls.

val videoCallStreamId =
    CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_VIDEO_CALL.toLong()

// Check available CameraInfos to find the first one that supports
// the video call stream use case.
val frontCameraInfo = cameraProvider.getAvailableCameraInfos()
    .first { cameraInfo ->
        val isVideoCallStreamingSupported = Camera2CameraInfo.from(cameraInfo)
            .getCameraCharacteristic(
                CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES
            )?.contains(videoCallStreamId)
        val isFrontFacing = (cameraInfo.getLensFacing() == 
                             CameraSelector.LENS_FACING_FRONT)
        (isVideoCallStreamingSupported == true) && isFrontFacing
    }

val cameraSelector = frontCameraInfo.cameraSelector

// Start with a Preview Builder.
val previewBuilder = Preview.Builder()
    .setTargetAspectRatio(screenAspectRatio)
    .setTargetRotation(rotation)

// Use Camera2Interop.Extender to set the video call stream use case.
Camera2Interop.Extender(previewBuilder).setStreamUseCase(videoCallStreamId)

// Bind the Preview UseCase and the corresponding CameraSelector.
val preview = previewBuilder.build()
camera = cameraProvider.bindToLifecycle(this, cameraSelector, preview)

Дополнительные ресурсы

Чтобы узнать больше о CameraX, ознакомьтесь со следующими дополнительными ресурсами.

Практическая работа

Начало работы с CameraX

Пример кода

Примеры приложений CameraX

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

Структура CameraX

Модель API

CameraController

CameraProvider

Жизненные циклы CameraX

Собственные LifecycleOwner

Примеры одновременного использования

Разрешения

Требования

Объявление зависимостей

Яркий

Kotlin

Яркий

Kotlin

Groovy

Kotlin

Совместимость CameraX с Camera2

Дополнительные ресурсы

Практическая работа

Пример кода

Архитектура CameraX