README

Luban 2





中文 | English

Luban 2（鲁班 2） —— 高效简洁的 Android 图片压缩工具库，像素级还原微信朋友圈压缩策略。

 如果你需要在线或命令行的图片压缩（PNG / JPEG / GIF / WebP / AVIF，免费，网页 / API / CLI 共用一份额度），可以看看同一系列的 LubanPNG（鲁班刨）：https://lubanpng.wizthink.cn/?utm_source=luban2&utm_medium=readme&utm_campaign=launch

 📑 目录

- 📖 项目描述
- 📊 效果与对比
  - 🔬 核心算法特性
- 📦 导入
- 💻 使用
  - ⚡ Kotlin (Coroutines)
  - ☕ Java / Builder 模式
- ☕ 捐助
- 📄 License

 📖 项目描述

目前做App开发总绕不开图片这个元素。但是随着手机拍照分辨率的提升，图片的压缩成为一个很重要的问题。单纯对图片进行裁切，压缩已经有很多文章介绍。但是裁切成多少，压缩成多少却很难控制好，裁切过头图片太小，质量压缩过头则显示效果太差。

于是自然想到App巨头"微信"会是怎么处理，Luban（鲁班）就是通过在微信朋友圈发送近100张不同分辨率图片，对比原图与微信压缩后的图片逆向推算出来的压缩算法。

因为是逆向推算，效果还没法跟微信一模一样，但是已经很接近微信朋友圈压缩后的效果，具体看以下对比！

本库是 Luban 的 Kotlin 重构版本，在升级核心算法的同时，利用 Kotlin Coroutines 和 TurboJPEG 进行了深度优化。新算法比原算法更加健壮和高效，提供更高效的异步处理和更优质的压缩效果。

 📊 效果与对比

| 图片类型 | 原图（分辨率, 大小） | Luban（分辨率, 大小） | Wechat（分辨率, 大小） |
| :--- | :--- | :--- | :--- |
| 标准拍照 | 3024×4032, 5.10MB | 1440×1920, 305KB | 1440×1920, 303KB |
| 高清大图 | 4000×6000, 12.10MB | 1440×2160, 318KB | 1440×2160, 305KB |
| 2K 截图 | 1440×3200, 2.10MB | 1440×3200, 148KB | 1440×3200, 256KB |
| 超长记录 | 1242×22080, 6.10MB | 758×13490, 290KB | 744×13129, 256KB |
| 全景横图 | 12000×5000, 8.10MB | 1440×600, 126KB | 1440×600, 123KB |
| 设计原稿 | 6000×6000, 6.90MB | 1440×1440, 263KB | 1440×1440, 279KB |

 🔬 核心算法特性

本库采用自适应统一图像压缩算法 (Adaptive Unified Image Compression)，通过原图的分辨率特征，动态应用差异化策略，实现画质与体积的最优平衡。

 智能分辨率决策

- 高清基准 (1440p)：默认以 1440px 作为短边基准，确保在现代 2K/4K 屏幕上的视觉清晰度
- 全景墙策略：自动识别超大全景图（长边 10800px），锁定长边为 1440px，保留完整视野
- 超大像素陷阱：对超过 4096万像素的超高像素图自动执行 1/4 降采样处理
- 长图内存保护：针对超长截图建立 10.24MP 像素上限，通过等比缩放防止 OOM

 自适应比特率控制

- 极小图 (3MP)：应用高压缩率，显著减少体积

 健壮性保障

- 膨胀回退：压缩后体积大于原图时，自动透传原图，确保绝不"负优化"
- 智能格式透传：保留小体积 PNG 的透明通道，大体积 PNG 自动转码为 JPEG
- 输入防御：妥善处理极端分辨率输入（0、负数、1px 等），防止崩溃

 📦 导入

确保项目的 build.gradle 或 build.gradle.kts 已配置 Maven Central 仓库：

kotlin
repositories {
    mavenCentral()
}


在模块的构建文件中添加依赖：

Kotlin DSL (build.gradle.kts):

kotlin
dependencies {
    implementation("top.zibin:luban:2.0.3")
}


Groovy (build.gradle):

groovy
dependencies {
    implementation 'top.zibin:luban:2.0.3'
}


 注意：请访问 Maven Central 查看最新版本号。

 💻 使用

 ⚡ Kotlin (Coroutines)

Luban 提供了三种 Kotlin 调用方式，从最符合 Kotlin 习惯到传统方式：

 1. DSL 风格（推荐）

最符合 Kotlin 习惯的方式是使用 DSL API：

kotlin
lifecycleScope.launch {
    val results = luban(context) {
        outputDir = File(context.cacheDir, "compressed")
        
        compress(imageUri1)
        compress(imageUri2)
        compress(imageFile1)
        compress(listOf(imageFile2, imageFile3))
        compress(listOf(imageUri3, imageUri4))
    }
    
    results.forEach { result -
        result.getOrNull()?.let { file -
            Log.d("Luban", "压缩成功: ${file.absolutePath}")
        } ?: run {
            val error = result.exceptionOrNull()
            Log.e("Luban", "压缩失败: ${error?.message}")
        }
    }
}


注意： 
- 对于 Uri 类型的压缩，如果不指定 outputDir，默认使用 context.cacheDir。对于 File 类型的压缩，必须显式设置 outputDir。
- DSL 配置是声明式的，配置顺序不影响结果。你可以先设置 outputDir 再调用 compress()，也可以先调用 compress() 再设置 outputDir。

 2. 扩展函数

你也可以使用