feat(imageprocessing): add ThumbnailGenerator, blurhash and cache support

- Add ThumbnailGenerator for efficient thumbnail creation
- Add blurhash module for image placeholders
- Add cache module for image caching
- Add ImageProcessingModule DI
- Add Base64ImageUtils

Author: crim50n

core/imageprocessing/build.gradle.kts

@@ -11,4 +11,5 @@ dependencies {
     implementation(libs.koin.core)
     implementation(libs.koin.android)
     implementation(libs.rx.kotlin)
+    implementation(libs.blurhash)
 }

core/imageprocessing/src/main/java/dev/minios/pdaiv1/core/imageprocessing/ThumbnailGenerator.kt

@@ -0,0 +1,175 @@
+package dev.minios.pdaiv1.core.imageprocessing
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import dev.minios.pdaiv1.core.imageprocessing.cache.ImageCacheManager
+import dev.minios.pdaiv1.core.imageprocessing.utils.base64ToBitmap
+import dev.minios.pdaiv1.core.imageprocessing.utils.base64ToThumbnailBitmap
+import io.reactivex.rxjava3.core.Scheduler
+import io.reactivex.rxjava3.core.Single
+import java.io.File
+
+/**
+ * Generates thumbnail images from Base64 encoded images or files.
+ * Uses ImageCacheManager for caching.
+ */
+class ThumbnailGenerator(
+    private val processingScheduler: Scheduler,
+    private val imageCacheManager: ImageCacheManager,
+    private val fallbackBitmap: Bitmap,
+) {
+
+    /**
+     * Generates a thumbnail from a file path.
+     * First checks cache, then generates if not found.
+     * Uses inSampleSize decoding for memory efficiency.
+     */
+    fun generateFromFile(
+        id: String,
+        filePath: String,
+        targetSize: Int = ImageCacheManager.THUMBNAIL_SIZE,
+    ): Single<Bitmap> = Single
+        .defer {
+            // Check cache first
+            val cached = imageCacheManager.getThumbnail(id)
+            if (cached != null) {
+                return@defer Single.just(cached)
+            }
+
+            // Generate thumbnail from file with subsampled decoding
+            Single.fromCallable {
+                val file = File(filePath)
+                if (!file.exists()) {
+                    return@fromCallable fallbackBitmap
+                }
+
+                // First decode bounds only
+                val options = BitmapFactory.Options().apply {
+                    inJustDecodeBounds = true
+                }
+                BitmapFactory.decodeFile(filePath, options)
+
+                // Calculate inSampleSize
+                options.inSampleSize = calculateInSampleSize(options, targetSize, targetSize)
+                options.inJustDecodeBounds = false
+
+                // Decode with inSampleSize
+                val subsampledBitmap = BitmapFactory.decodeFile(filePath, options)
+                    ?: return@fromCallable fallbackBitmap
+
+                // Final scale to exact target size if needed
+                val thumbnail = createThumbnail(subsampledBitmap, targetSize)
+
+                // Cache the thumbnail
+                imageCacheManager.putThumbnail(id, thumbnail)
+
+                // Recycle intermediate bitmap if different from result
+                if (subsampledBitmap != thumbnail && !subsampledBitmap.isRecycled) {
+                    subsampledBitmap.recycle()
+                }
+
+                thumbnail
+            }
+        }
+        .onErrorReturnItem(fallbackBitmap)
+        .subscribeOn(processingScheduler)
+
+    /**
+     * Generates a thumbnail from base64 string.
+     * First checks cache, then generates if not found.
+     * Uses inSampleSize decoding for memory efficiency.
+     */
+    fun generate(
+        id: String,
+        base64ImageString: String,
+        targetSize: Int = ImageCacheManager.THUMBNAIL_SIZE,
+    ): Single<Bitmap> = Single
+        .defer {
+            // Check cache first
+            val cached = imageCacheManager.getThumbnail(id)
+            if (cached != null) {
+                return@defer Single.just(cached)
+            }
+
+            // Generate thumbnail with subsampled decoding
+            Single.fromCallable {
+                // Decode with inSampleSize for memory efficiency
+                val subsampledBitmap = base64ToThumbnailBitmap(base64ImageString, targetSize)
+
+                // Final scale to exact target size if needed
+                val thumbnail = createThumbnail(subsampledBitmap, targetSize)
+
+                // Cache the thumbnail
+                imageCacheManager.putThumbnail(id, thumbnail)
+
+                // Recycle intermediate bitmap if different from result
+                if (subsampledBitmap != thumbnail && !subsampledBitmap.isRecycled) {
+                    subsampledBitmap.recycle()
+                }
+
+                thumbnail
+            }
+        }
+        .onErrorReturnItem(fallbackBitmap)
+        .subscribeOn(processingScheduler)
+
+    /**
+     * Gets or generates a full-size image from base64.
+     */
+    fun getFullImage(
+        id: String,
+        base64ImageString: String,
+    ): Single<Bitmap> = Single
+        .defer {
+            // Check cache first
+            val cached = imageCacheManager.getFullImage(id)
+            if (cached != null) {
+                return@defer Single.just(cached)
+            }
+
+            // Load full image
+            Single.fromCallable {
+                val bitmap = base64ToBitmap(base64ImageString)
+                imageCacheManager.putFullImage(id, bitmap)
+                bitmap
+            }
+        }
+        .onErrorReturnItem(fallbackBitmap)
+        .subscribeOn(processingScheduler)
+
+    private fun calculateInSampleSize(options: BitmapFactory.Options, reqWidth: Int, reqHeight: Int): Int {
+        val (height: Int, width: Int) = options.run { outHeight to outWidth }
+        var inSampleSize = 1
+
+        if (height > reqHeight || width > reqWidth) {
+            val halfHeight: Int = height / 2
+            val halfWidth: Int = width / 2
+
+            while (halfHeight / inSampleSize >= reqHeight && halfWidth / inSampleSize >= reqWidth) {
+                inSampleSize *= 2
+            }
+        }
+
+        return inSampleSize
+    }
+
+    private fun createThumbnail(source: Bitmap, targetSize: Int): Bitmap {
+        if (source.width <= targetSize && source.height <= targetSize) {
+            return source
+        }
+
+        val aspectRatio = source.width.toFloat() / source.height.toFloat()
+        val targetWidth: Int
+        val targetHeight: Int
+
+        if (aspectRatio > 1) {
+            targetWidth = targetSize
+            targetHeight = (targetSize / aspectRatio).toInt()
+        } else {
+            targetHeight = targetSize
+            targetWidth = (targetSize * aspectRatio).toInt()
+        }
+
+        return Bitmap.createScaledBitmap(source, targetWidth, targetHeight, true)
+    }
+}

core/imageprocessing/src/main/java/dev/minios/pdaiv1/core/imageprocessing/blurhash/BlurHashDecoder.kt

@@ -0,0 +1,69 @@
+package dev.minios.pdaiv1.core.imageprocessing.blurhash
+
+import android.graphics.Bitmap
+import com.vanniktech.blurhash.BlurHash
+import io.reactivex.rxjava3.core.Scheduler
+import io.reactivex.rxjava3.core.Single
+
+/**
+ * Decodes BlurHash strings to Bitmap images for placeholders.
+ */
+class BlurHashDecoder(
+    private val processingScheduler: Scheduler,
+    private val fallbackBitmap: Bitmap,
+) {
+
+    /**
+     * Decodes a BlurHash string to a Bitmap synchronously.
+     * Use for inline Composable rendering.
+     */
+    fun decodeSync(
+        hash: String,
+        width: Int = DEFAULT_SIZE,
+        height: Int = DEFAULT_SIZE,
+    ): Bitmap? {
+        if (hash.isBlank()) return null
+        return try {
+            BlurHash.decode(hash, width, height)
+        } catch (e: Exception) {
+            null
+        }
+    }
+
+    /**
+     * Decodes a BlurHash string to a Bitmap.
+     * @param hash The BlurHash string to decode
+     * @param width Target width of the decoded bitmap
+     * @param height Target height of the decoded bitmap
+     * @return Single emitting the decoded Bitmap
+     */
+    fun decode(
+        hash: String,
+        width: Int = DEFAULT_SIZE,
+        height: Int = DEFAULT_SIZE,
+    ): Single<Bitmap> = Single
+        .fromCallable {
+            if (hash.isBlank()) {
+                return@fromCallable fallbackBitmap
+            }
+            BlurHash.decode(hash, width, height) ?: fallbackBitmap
+        }
+        .onErrorReturnItem(fallbackBitmap)
+        .subscribeOn(processingScheduler)
+
+    companion object {
+        const val DEFAULT_SIZE = 32 // Small size for blur placeholder
+
+        /**
+         * Static decode for simple use cases without dependency injection.
+         */
+        fun decodeStatic(hash: String, width: Int = DEFAULT_SIZE, height: Int = DEFAULT_SIZE): Bitmap? {
+            if (hash.isBlank()) return null
+            return try {
+                BlurHash.decode(hash, width, height)
+            } catch (e: Exception) {
+                null
+            }
+        }
+    }
+}

core/imageprocessing/src/main/java/dev/minios/pdaiv1/core/imageprocessing/blurhash/BlurHashEncoder.kt

@@ -0,0 +1,47 @@
+package dev.minios.pdaiv1.core.imageprocessing.blurhash
+
+import android.graphics.Bitmap
+import com.vanniktech.blurhash.BlurHash
+import io.reactivex.rxjava3.core.Scheduler
+import io.reactivex.rxjava3.core.Single
+
+/**
+ * Encodes Bitmap images to BlurHash strings for progressive loading placeholders.
+ */
+class BlurHashEncoder(
+    private val processingScheduler: Scheduler,
+) {
+
+    /**
+     * Encodes a bitmap to a BlurHash string synchronously.
+     * Use this for inline processing where async is not needed.
+     */
+    fun encodeSync(
+        bitmap: Bitmap,
+        componentX: Int = DEFAULT_COMPONENT_X,
+        componentY: Int = DEFAULT_COMPONENT_Y,
+    ): String = BlurHash.encode(bitmap, componentX, componentY) ?: ""
+
+    /**
+     * Encodes a bitmap to a BlurHash string.
+     * @param bitmap The source bitmap to encode
+     * @param componentX Horizontal components (1-9), higher = more detail
+     * @param componentY Vertical components (1-9), higher = more detail
+     * @return Single emitting the BlurHash string
+     */
+    fun encode(
+        bitmap: Bitmap,
+        componentX: Int = DEFAULT_COMPONENT_X,
+        componentY: Int = DEFAULT_COMPONENT_Y,
+    ): Single<String> = Single
+        .fromCallable {
+            BlurHash.encode(bitmap, componentX, componentY)
+                ?: throw IllegalStateException("Failed to encode BlurHash")
+        }
+        .subscribeOn(processingScheduler)
+
+    companion object {
+        const val DEFAULT_COMPONENT_X = 4
+        const val DEFAULT_COMPONENT_Y = 3
+    }
+}

core/imageprocessing/src/main/java/dev/minios/pdaiv1/core/imageprocessing/cache/ImageCacheManager.kt

@@ -0,0 +1,71 @@
+package dev.minios.pdaiv1.core.imageprocessing.cache
+
+import android.graphics.Bitmap
+import android.util.LruCache
+
+/**
+ * Manages dual-layer image caching for gallery:
+ * - Thumbnail cache: stores small preview images (256x256)
+ * - Full image cache: stores full resolution images for viewing
+ */
+class ImageCacheManager(
+    thumbnailCacheSize: Int = DEFAULT_THUMBNAIL_CACHE_SIZE,
+    fullImageCacheSize: Int = DEFAULT_FULL_IMAGE_CACHE_SIZE,
+) {
+
+    private val thumbnailCache = object : LruCache<String, Bitmap>(thumbnailCacheSize) {
+        override fun sizeOf(key: String, bitmap: Bitmap): Int {
+            return bitmap.byteCount / 1024 // Size in KB
+        }
+    }
+
+    private val fullImageCache = object : LruCache<String, Bitmap>(fullImageCacheSize) {
+        override fun sizeOf(key: String, bitmap: Bitmap): Int {
+            return bitmap.byteCount / 1024 // Size in KB
+        }
+    }
+
+    fun getThumbnail(id: String): Bitmap? = thumbnailCache.get(id)
+
+    fun putThumbnail(id: String, bitmap: Bitmap) {
+        thumbnailCache.put(id, bitmap)
+    }
+
+    fun getFullImage(id: String): Bitmap? = fullImageCache.get(id)
+
+    fun putFullImage(id: String, bitmap: Bitmap) {
+        fullImageCache.put(id, bitmap)
+    }
+
+    fun removeThumbnail(id: String) {
+        thumbnailCache.remove(id)
+    }
+
+    fun removeFullImage(id: String) {
+        fullImageCache.remove(id)
+    }
+
+    fun clearThumbnails() {
+        thumbnailCache.evictAll()
+    }
+
+    fun clearFullImages() {
+        fullImageCache.evictAll()
+    }
+
+    fun clear() {
+        clearThumbnails()
+        clearFullImages()
+    }
+
+    companion object {
+        const val THUMBNAIL_SIZE = 256 // px
+
+        // Cache size in KB (about 2500 thumbnails of ~50KB each = ~125MB)
+        // Increased for smoother gallery scrolling like Immich
+        private const val DEFAULT_THUMBNAIL_CACHE_SIZE = 125_000
+
+        // Cache size in KB (about 10 full images of ~5MB each = ~50MB)
+        private const val DEFAULT_FULL_IMAGE_CACHE_SIZE = 50_000
+    }
+}