Жизненный цикл улучшения медиаконтента в режиме Bitmap

Media Enhancement API – это решение на основе ИИ, которое работает на устройстве, обеспечивает низкую задержку и конфиденциальность, а также использует аппаратное ускорение, чтобы улучшать качество медиаконтента, не увеличивая размер APK-файла. Подробнее о возможностях улучшения медиаконтента…

Статический режим Bitmap (EnhancementMode.BITMAP) предназначен для обработки статических декодированных изображений.

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

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

  1. Настройте параметры. Создайте объект EnhancementOptions, убедившись, что для enhancementMode задано значение EnhancementMode.BITMAP.
  2. Создание сеанса. Используйте созданную ранее оболочку createSessionAsync, чтобы создать EnhancementSession. Это тяжелый объект, поэтому создавайте его только при необходимости.
  3. Обработка изображения. Вызовите сеанс, входное растровое изображение и нужные параметры.
  4. Обработка результата. Функция приостановки возвращает новый улучшенный объект Bitmap в случае успеха или выдает исключение в случае неудачи.
  5. Завершение сеанса. По окончании работы вызовите session.release(), чтобы освободить ресурсы графического процессора.

EnhancementSession – это тяжеловесный объект контекста, который поддерживает постоянный конвейер памяти графического или нейронного процессора. Он выделяет выделенную видеопамять (VRAM) и собственные системные дескрипторы. Чтобы избежать утечек памяти и сбоев в работе OutOfMemoryError, придерживайтесь следующих принципов:

  1. Отложенное создание экземпляра. Не создавайте сеанс, пока пользователь не инициирует действие по улучшению.
  2. Повторное использование. При обработке нескольких изображений с одинаковыми конфигурациями (размерами и параметрами с переключателями) используйте один и тот же экземпляр сеанса.
  3. Быстрое завершение. Вызывайте session.release() сразу после завершения визуальных задач, чтобы освободить общие аппаратные ресурсы.

Инициализация движка улучшения

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

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

class MediaSetupViewModel(application: Application) : AndroidViewModel(application) {
    private val enhancementClient = Enhancement.getClient(application)
    fun initializeEnhancementEngine() {
        viewModelScope.launch {
            try {
                // 1. Verify hardware capability.
                val isSupported = enhancementClient.isDeviceSupportedAsync()
                if (!isSupported) {
                    notifyUiDeviceIncompatible()
                    return@launch
                }
                // 2. Verify and download the Google Play services ML modules.
                val isInstalled = enhancementClient.isModuleInstalledAsync()
                if (!isInstalled) {
                    notifyUiDownloadingModels()
                    enhancementClient.installModule(installStatusCallback).await()
                }
                notifyUiEngineReady()
            } catch (e: Exception) {

                // Handle potential errors during session creation or image processing.
                handleInitializationError(e)
            }
        }
    }
}

Создание оболочек для сеанса и обработки битовой карты

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

// Wraps the task-based createSession callback into a suspending function.
suspend fun EnhancementClient.createSessionAsync(
    options: EnhancementOptions,
    executor: Executor
): EnhancementSession = withContext(Dispatchers.Main) {
    suspendCancellableCoroutine { continuation ->

        // EnhancementSessionCallback handles session success or failure.
        val callback = object : EnhancementSessionCallback {
            override fun onSessionCreated(session: EnhancementSession) {
                continuation.resume(session)
            }
            override fun onSessionCreationFailed(status: Status) {
                continuation.resumeWithException(
                    Exception("Session creation failed: ${status.statusMessage} (${status.statusCode})")
                )
            }
            override fun onSessionDestroyed() {}
            override fun onSessionDisconnected(status: Status) {}
        }

        // Handles errors during the initial request trigger.
        this@createSessionAsync.createSession(options, callback).addOnFailureListener(executor) { e ->
            if (continuation.isActive) {
                continuation.resumeWithException(e)
            }
        }
    }
}

// Wraps this process in a suspending function for cleaner execution.
suspend fun EnhancementSession.processBitmapAsync(
    bitmap: Bitmap,
    options: EnhancementOptions
): Bitmap = suspendCancellableCoroutine { continuation ->

    // EnhancementCallback returns the processed bitmap or an error code.
    val callback = object : EnhancementCallback {
        override fun onBitmapProcessed(enhancedBitmap: Bitmap) {
            continuation.resume(enhancedBitmap)
        }
        override fun onError(statusCode: Int) {
            continuation.resumeWithException(
                Exception("Bitmap processing failed with status code: $statusCode")
            )
        }
        override fun onSurfaceProcessed(timestamp: Long) {}
        override fun onCancelled(statusCode: Int) {}
    }
    this.process(bitmap, options, callback)
}

Выполните конвейер битовых карт в ViewModel.

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

// Define a data class to hold image information.
data class ImageInfo(val bitmap: Bitmap)
// Define a UI state class to hold loading status, errors, and enhanced image.
data class EnhancementUiState(
    val isLoading: Boolean = false,
    val enhancementError: String? = null,
    val enhancedImage: ImageInfo? = null
)

class EnhancementViewModel(application: Application) : AndroidViewModel(application) {

    // Backing field for UI state, initialized with default values.
    private val _uiState = MutableStateFlow(EnhancementUiState())
    // Publicly exposed UI state flow for observation.
    val uiState: StateFlow<EnhancementUiState> = _uiState.asStateFlow()

    // Initialize client to interact with the Media Enhancement service.
    private val enhancementClient: EnhancementClient = Enhancement.getClient(application)

    // Single-thread executor for processing background enhancement tasks.
    private val enhancementExecutor = Executors.newSingleThreadExecutor()

    // Track session state to enable reuse across multiple processing calls.
    private var enhancementSession: EnhancementSession? = null
    private var sessionOptions: EnhancementOptions? = null

    // Primary function to trigger the enhancement workflow for a provided bitmap.
    fun enhanceImage(bitmap: Bitmap) {
        viewModelScope.launch(Dispatchers.IO) {
            _uiState.update { it.copy(isLoading = true, enhancementError = null) }
            try {
                // Define enhancement options (for example, enable upscale, tonemapping) based
                // on bitmap dimensions.
                val options = EnhancementOptions(
                    bitmap.width,
                    bitmap.height,
                    EnhancementMode.BITMAP,
                    isTonemappingEnabled = true,
                    isDeblurAndDenoisePhotoEnabled = true,
                    isUpscalePhotoEnabled = false,
                )
                // 1. Establish the session lazily on demand. A session is configured for
                // specific input dimensions, so replace it when the bitmap size changes.
                if (enhancementSession == null ||
                    sessionOptions?.width != options.width ||
                    sessionOptions?.height != options.height
                ) {
                    enhancementSession?.release()
                    enhancementSession = null
                    enhancementSession = enhancementClient.createSessionAsync(options, enhancementExecutor)
                    sessionOptions = options
                }
                val session = enhancementSession ?: throw IllegalStateException("Session unavailable.")
                // 2. Dispatch image through the neural pipeline.
                val enhancedBitmap = session.processBitmapAsync(bitmap, options)
                // 3. Render output to UI.
                _uiState.update {
                    it.copy(enhancedImage = ImageInfo(bitmap = enhancedBitmap))
                }
            } catch (e: Exception) {
                _uiState.update { it.copy(enhancementError = e.message) }
            } finally {

                // Ensure loading state is reset regardless of the outcome.
                _uiState.update { it.copy(isLoading = false) }
            }
        }
    }
    override fun onCleared() {
        // 4. Critical: Release native GPU hardware resources.
        enhancementSession?.release()
        enhancementSession = null
        enhancementExecutor.shutdown()
        super.onCleared()
    }
}

Прогрессивная загрузка изображений в медленных сетях

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

Когда использовать этот шаблон

Этот шаблон подходит, если выполняются все следующие условия:

  • Устройство поддерживается. isDeviceSupportedAsync() возвращает true. Для работы API требуется Android 11 (уровень API 30) или более поздней версии. API оптимизирован для устройств премиум-уровня.
  • Изображение показывается в большем размере, чем оно было скачано. Например, маленькое изображение показывается в полноэкранном режиме. Если изображение остается в размере значка, масштабирование не дает видимых преимуществ.
  • Модуль улучшения уже установлен. isModuleInstalledAsync() возвращает true. При установке модуля файлы модели скачиваются по сети. Если у пользователя медленное подключение, не начинайте установку.

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

Реализация шаблона

Шаблон работает следующим образом:

  1. Показывать изображение с низким разрешением. Изображение небольшого размера показывается сразу после скачивания.
  2. Улучшение в фоновом режиме. Если движок улучшения готов, обработайте изображение в режиме Bitmap с включенным повышением разрешения и восстановлением резкости.
  3. Заменить результат. Замените отображаемое изображение улучшенным растровым. Короткое перекрестное затухание делает замену менее заметной.

Приведенный ниже класс ProgressiveImageEnhancer обрабатывает по одному изображению за раз и повторно использует один сеанс для изображений одного размера. Если улучшить изображение не удается, enhance() возвращает null, чтобы приложение продолжало показывать изображение с низким разрешением. Класс использует оболочки createSessionAsync и processBitmapAsync, определенные в разделе Создание оболочек для сеанса и обработки битовых карт.

Установите модуль заранее, как описано в разделе Инициализация модуля улучшения. Если isDeviceSupportedAsync() и isModuleInstalledAsync() возвращают true, вызовите enhance().

class ProgressiveImageEnhancer(
    private val enhancementClient: EnhancementClient,
    private val executor: Executor,
) {
    // Callers can request enhancements concurrently, but they all share one
    // session, so process one image at a time.
    private val mutex = Mutex()
    private var session: EnhancementSession? = null
    private var sessionOptions: EnhancementOptions? = null

    // Enhancement is optional for this pattern, so return null instead of
    // throwing. The caller can keep the low-resolution image without extra
    // error handling.
    suspend fun enhance(lowResBitmap: Bitmap): Bitmap? = mutex.withLock {
        val options = EnhancementOptions(
            width = lowResBitmap.width,
            height = lowResBitmap.height,
            enhancementMode = EnhancementMode.BITMAP,
            isDeblurAndDenoisePhotoEnabled = true,
            isUpscalePhotoEnabled = true,
        )
        try {
            getOrCreateSession(options).processBitmapAsync(lowResBitmap, options)
        } catch (e: CancellationException) {
            // A cancelled request (for example, the user scrolled away) isn't
            // an enhancement failure, so let the caller's scope handle it.
            throw e
        } catch (e: Exception) {
            null
        }
    }

    // Sessions are expensive to create and are configured for specific input
    // dimensions, so reuse the current one until the image size changes.
    private suspend fun getOrCreateSession(options: EnhancementOptions): EnhancementSession {
        val currentSession = session
        val currentOptions = sessionOptions
        if (currentSession != null &&
            currentOptions != null &&
            currentOptions.width == options.width &&
            currentOptions.height == options.height
        ) {
            return currentSession
        }
        releaseSession()
        return enhancementClient.createSessionAsync(options, executor).also {
            session = it
            sessionOptions = options
        }
    }

    // A session holds GPU memory until it's released, so free it as soon as
    // the images it enhances are no longer on screen. Taking the lock first
    // waits for any in-progress enhancement, so a session that's still being
    // created isn't leaked.
    suspend fun release() = mutex.withLock { releaseSession() }

    private fun releaseSession() {
        session?.release()
        session = null
        sessionOptions = null
    }
}

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

  • Запрашивайте один и тот же размер. В EnhancementSession используются фиксированные размеры входных данных. Запрашивайте изображения с низким разрешением одного размера, чтобы приложение могло повторно использовать один сеанс для разных изображений.
  • Кешируйте улучшенные результаты. Сохраняйте улучшенные битовые карты в кеше изображений, чтобы приложению не приходилось обрабатывать их повторно. Если включить масштабирование, улучшенная битовая карта будет больше исходной. Размер вашего кэша для больших растровых изображений.