CameraX: какво е, CameraX API и как работи камерата

Какво е CameraX?

CameraX — е библиотека от състава на Android Jetpack, пусната за първи път от Google през 2019 г. като заместник на остарялото Camera API и опростена алтернатива на сложния Camera2. Основната философия на CameraX — „пиши веднъж, работи на всички устройства". Библиотеката автоматично обработва хардуерните разлики: разположение на камерите, поддържани резолюции, ориентация на сензора и налични формати — разработчикът не трябва да пише код, специфичен за устройство.

Архитектурата на CameraX е изградена върху use cases: Preview (показване на изображение от камерата във Viewfinder), ImageCapture (снимане на снимки), ImageAnalysis (анализ на поток от кадри за ML) и VideoCapture (запис на видео). Всеки use case е независим компонент, който може да се комбинира: едновременно пускане на Preview за визьора и ImageAnalysis за ML обработка. Според Google (2026), CameraX се поддържа на 99% от Android устройствата с API 21+.

Основни възможности

CameraX предоставя автоматично превключване между предната и задната камера, поддръжка на завъртане на екрана без пресъздаване на сесия, вградено управление на жизнения цикъл чрез LifecycleOwner, свързване на use cases към един Lifecycle процес, поддръжка на Camera2 Extensions за портрет, HDR и нощен режим, както и TestableCameraX за unit тестване без реално устройство.

Use cases на CameraX

CameraX дефинира четири стандартни use case, всеки от които решава конкретна задача за работа с камерата. Use cases могат да се комбинират: най-популярните комбинации са Preview + ImageCapture за камера и Preview + ImageAnalysis за ML скенер.

Preview

Preview use case показва видео потока от камерата в PreviewView — специален View от библиотеката CameraX. PreviewView автоматично се адаптира към съотношението на страните на камерата, поддържа ScaleType (FillCenter, FitCenter) и завъртане на екрана без пресъздаване на use case. Разработчикът трябва само да свърже Preview с Lifecycle чрез ProcessCameraProvider.

ImageAnalysis

ImageAnalysis use case предава всеки кадър от камерата на обработчика за анализ: разпознаване на текст, откриване на лица, сканиране на QR кодове. Анализаторът получава кадри във формат YUV_420_888 — универсалното цветово пространство на Android. Режим на работа (BLOCKING или NON_BLOCKING) управлява опашката от кадри: BLOCKING изчаква завършването на предишния анализ, NON_BLOCKING пропуска кадри при закъснение.

ImageCapture

ImageCapture use case прави снимки от камерата с настройки на светкавица, резолюция и компресия. Поддържат се формати JPEG и RAW (на съвместими устройства). ImageCapture записва снимката асинхронно чрез OnImageCapturedCallback или директно във файл чрез ImageCapture.OutputFileOptions.

VideoCapture — запис на видео

VideoCapture use case е добавен в CameraX 1.1.0 (бета) и позволява запис на видео с резолюция до 4K при 30 FPS. Use case автоматично се синхронизира с Preview: изображението във визьора съответства на това, което се записва във файла. VideoCapture използва вътрешно MediaCodec и MediaMuxer, скривайки сложността на конфигуриране на видео кодек и MP4 контейнер.

CameraX срещу Camera2

CameraX и Camera2 — два подхода за работа с камера в Android. Camera2 — ниско ниво API, даващо пълен контрол над устройството. CameraX — високо ниво абстракция, автоматизираща типични сценарии. Изборът между тях зависи от изискванията на проекта.

Използвайте CameraX за стандартни задачи: камера в приложението, QR скенер, ML обработка на поток. Използвайте Camera2, когато се изисква ръчно управление на експозицията, RAW снимане с пълен контрол на параметрите, работа с няколко камери едновременно.

Примери за код в Kotlin

Нека разгледаме пълната конфигурация на CameraX в Android приложение, използвайки и трите основни use cases: Preview, ImageCapture и ImageAnalysis.

Конфигуриране на ProcessCameraProvider

Кодът свързва CameraX с Lifecycle на Activity чрез ProcessCameraProvider. Първо се изисква инстанция на provider, след което се създават use cases и се извършва свързване.

val cameraProviderFuture =
    ProcessCameraProvider.getInstance(this)

cameraProviderFuture.addListener({
    val cameraProvider = cameraProviderFuture.get()

    // Създаване на Preview
    val preview = Preview.Builder()
        .build()
        .also {
            it.setSurfaceProvider(
                binding.viewFinder.surfaceProvider
            )
        }

    // Създаване на ImageCapture
    val imageCapture = ImageCapture.Builder()
        .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
        .build()

    // Свързване с Lifecycle
    cameraProvider.unbindAll()
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}, ContextCompact.getMainExecutor(this))

Kotlin кодът получава ProcessCameraProvider чрез future, създава use cases Preview и ImageCapture и ги свързва с Lifecycle на текущото Activity. CameraX автоматично обработва завъртане на екрана, превключване на камери и освобождаване на ресурси при затваряне на Activity.

ImageAnalysis за ML обработка

Нека добавим ImageAnalysis use case за покадрова обработка на потока от камерата, например за интеграция с ML Kit.

val imageAnalysis = ImageAnalysis.Builder()
    .setBackpressureStrategy(
        ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
    )
    .build()

imageAnalysis.setAnalyzer(
    ContextCompact.getMainExecutor(this)
) { imageProxy ->
    // Конвертиране на YUV в Bitmap за ML Kit
    val bitmap = ImageUtils.yuvToBitmap(imageProxy)
    val inputImage = InputImage.fromBitmap(bitmap)

    // Стартиране на разпознаване на текст ML Kit
    recognizer.process(inputImage)
        .addOnSuccessListener { result ->
            // Обработка на резултата
            processTextResult(result)
        }
        .addOnCompleteListener {
            imageProxy.close()
        }
}

ImageAnalysis със стратегия KEEP_ONLY_LATEST обработва само последния наличен кадър, пропускайки остарелите, ако анализаторът не успява. Всеки кадър се конвертира от YUV в Bitmap за ML Kit, след което се стартира разпознаване на текст. Извикването на imageProxy.close() е задължително — иначе CameraX ще спре да доставя нови кадри.

CameraX Extensions

CameraX Extensions — модул, който добавя разширени режими на снимане: портретен (размазване на фона), HDR (разширен динамичен обхват), нощен режим (снимане при слаба осветеност), авторетуш (корекция на кожата) и режим „красиво лице" (beauty). Разширенията се активират само на устройства, където производителят на камерата е предоставил OEM имплементация.

Проверка и включване на разширения

Преди използване на CameraX Extensions трябва да се провери дали разширението е налично на текущото устройство. Google препоръчва проверка чрез ExtensionsManager.isExtensionAvailable.

val extensionsManager =
    ExtensionsManager.getInstance(this)

if (extensionsManager.isExtensionAvailable(
    cameraProvider,
    CameraSelector.DEFAULT_BACK_CAMERA,
    ExtensionMode.BOKEH
)) {
    // Включване на портретен режим
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}

Кодът проверява поддръжката на BOKEH (портретно) разширение чрез ExtensionsManager и го включва, ако има налична OEM имплементация. CameraX автоматично превключва настройките на камерата за портретен режим. Ако разширението не е налично, приложението продължава да работи в стандартен режим без сривове.

CameraX Extensions решават един от основните проблеми на Android разработката: фрагментацията на камерите. На различни устройства портретният режим се имплементира различно — някои използват два обектива, други — софтуерно размазване. CameraX абстрахира тази разлика: разработчикът включва BOKEH режим, а библиотеката сама определя как да го имплементира на конкретното устройство. Google поддържа списък на проверени OEM партньори: Samsung, Xiaomi, OPPO, vivo, Google Pixel.

При работа с CameraX е важно да се вземат предвид ограниченията за броя на едновременните use cases: на повечето устройства могат да се пуснат максимум 3 use case едновременно. Например Preview + ImageCapture + ImageAnalysis работят на всички съвременни устройства, но Preview + ImageCapture + VideoCapture може да не се поддържат на бюджетни модели. CameraX предоставя метода ProcessCameraProvider.checkAvailability(), който проверява съвместимостта на комбинацията от use cases преди свързване, което позволява избягване на сривове по време на изпълнение.

CameraX се интегрира с Jetpack Navigation чрез CameraXFragment или PreviewView, съвместим с Compose. За Compose се използва елементът AndroidView, в който се вгражда PreviewView. CameraX правилно обработва завъртане на екрана и промяна на конфигурацията без загуба на състоянието на сесията на камерата — достатъчно е да се посочи LifecycleOwner и библиотеката автоматично ще пресъздаде свързването на use cases при завъртане на устройството.

За тестване на CameraX без реално устройство Google предоставя TestableCameraX — библиотека, емулираща поведението на камерата в unit тестове. TestableCameraX позволява симулиране на кадри от камерата, проверка на работата на ImageAnalysis и коректност на обработката на ImageCapture без физическо устройство. Това значително ускорява CI/CD pipeline за проекти, работещи с камера.