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

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

Структура CameraX

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

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

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

Модель API

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

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

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

CameraController

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

Kotlin

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

Java

PreviewView previewView = viewBinding.previewView;
LifecycleCameraController cameraController = new LifecycleCameraController(baseContext);
cameraController.bindToLifecycle(this);
cameraController.setCameraSelector(CameraSelector.DEFAULT_BACK_CAMERA);
previewView.setController(cameraController);

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

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

CameraProvider

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

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

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

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

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

Kotlin

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

Java

Preview preview = new Preview.Builder().build();
PreviewView viewFinder = findViewById(R.id.view_finder);

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

// PreviewView creates a surface provider, using a Surface from a different
// kind of view will require you to implement your own surface provider.
preview.previewSurfaceProvider = viewFinder.getSurfaceProvider();

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

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

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

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

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

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

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

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

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

В приведенном ниже фрагменте кода показано, как создать простой пользовательский LifecycleOwner:

Kotlin

class CustomLifecycle : LifecycleOwner {
    private val lifecycleRegistry: LifecycleRegistry

    init {
        lifecycleRegistry = LifecycleRegistry(this);
        lifecycleRegistry.markState(Lifecycle.State.CREATED)
    }
    ...
    fun doOnResume() {
        lifecycleRegistry.markState(State.RESUMED)
    }
    ...
    override fun getLifecycle(): Lifecycle {
        return lifecycleRegistry
    }
}

Java

public class CustomLifecycle implements LifecycleOwner {
    private LifecycleRegistry lifecycleRegistry;
    public CustomLifecycle() {
        lifecycleRegistry = new LifecycleRegistry(this);
        lifecycleRegistry.markState(Lifecycle.State.CREATED);
    }
   ...
   public void doOnResume() {
        lifecycleRegistry.markState(State.RESUMED);
    }
   ...
    public Lifecycle getLifecycle() {
        return lifecycleRegistry;
    }
}

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

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

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

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

Kotlin

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

Java

private ImageCapture imageCapture;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    PreviewView previewView = findViewById(R.id.previewView);

    ListenableFuture<ProcessCameraProvider> cameraProviderFuture =
            ProcessCameraProvider.getInstance(this);

    cameraProviderFuture.addListener(() -> {
        try {
            // Camera provider is now guaranteed to be available
            ProcessCameraProvider cameraProvider = cameraProviderFuture.get();

            // Set up the view finder use case to display camera preview
            Preview preview = new Preview.Builder().build();

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

            // Choose the camera by requiring a lens facing
            CameraSelector cameraSelector = new CameraSelector.Builder()
                    .requireLensFacing(lensFacing)
                    .build();

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

            // Connect the preview use case to the previewView
            preview.setSurfaceProvider(
                    previewView.getSurfaceProvider());
        } catch (InterruptedException | ExecutionException e) {
            // Currently no exceptions thrown. cameraProviderFuture.get()
            // shouldn't block since the listener is being called, so no need to
            // handle InterruptedException.
        }
    }, ContextCompat.getMainExecutor(this));
}

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

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

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

Kotlin

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

Java

@androidx.annotation.OptIn(markerClass = ExperimentalCamera2Interop.class)
Boolean isBackCameraLevel3Device(ProcessCameraProvider cameraProvider) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
        List\<CameraInfo\> filteredCameraInfos = CameraSelector.DEFAULT_BACK_CAMERA
                .filter(cameraProvider.getAvailableCameraInfos());
        if (!filteredCameraInfos.isEmpty()) {
            return Objects.equals(
                Camera2CameraInfo.from(filteredCameraInfos.get(0)).getCameraCharacteristic(
                        CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL),
                CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3);
        }
    }
    return false;
}

Разрешения

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

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

Требования

Для CameraX действуют следующие минимальные требования к версии:

  • Android API уровня 21
  • Android Architecture Components 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 каждого модуля приложения следующий код:

Классный 

dependencies {
  // CameraX core library using the camera2 implementation
  def camerax_version = "1.7.0-alpha03"
  // 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}"
}

Котлин 

dependencies {
    // CameraX core library using the camera2 implementation
    val camerax_version = "1.7.0-alpha03"
    // 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 одним из двух способов:

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

Kotlin

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

Java

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

Long 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.
List<CameraInfo> cameraInfos = cameraProvider.getAvailableCameraInfos();
CameraInfo frontCameraInfo = null;
for (cameraInfo in cameraInfos) {
    Long[] availableStreamUseCases = Camera2CameraInfo.from(cameraInfo)
        .getCameraCharacteristic(
            CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES
        );
    boolean isVideoCallStreamingSupported = Arrays.List(availableStreamUseCases)
                .contains(videoCallStreamId);
    boolean isFrontFacing = (cameraInfo.getLensFacing() ==
                             CameraSelector.LENS_FACING_FRONT);

    if (isVideoCallStreamingSupported && isFrontFacing) {
        frontCameraInfo = cameraInfo;
    }
}

if (frontCameraInfo == null) {
    // Handle case where video call streaming is not supported.
}

CameraSelector cameraSelector = frontCameraInfo.getCameraSelector();

// Start with a Preview Builder.
Preview.Builder 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.
Preview preview = previewBuilder.build()
Camera camera = cameraProvider.bindToLifecycle(this, cameraSelector, preview)

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

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

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

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

    • Пример кода

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

    •