RetinaForge — iOS 自动化切图工具箱

RetinaForge 是一个用于 iOS 开发的自动化图片处理工具，主要功能包括：

• 批量多线程转换任意倍率 Retina 图片：在 @1x、@2x、@3x 之间自由缩放转换。
• 自动同步更新 Xcode Assets 配置：转换完成后自动修改 .imageset/Contents.json，确保 Xcode 资源引用正确无误。
• 极限体积优化：支持 PNG 无损压缩（最高等级 9）、剔除 ICC 色彩配置文件、智能还原索引色（P 模式），有效降低 App 打包体积。

简而言之：一条命令搞定整个 Assets.xcassets 目录的图片倍率转换和 JSON 配置同步。

# 进入项目目录
cd iOS-AssetFlow

# 创建 Python 虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate      # macOS / Linux
# .venv\Scripts\activate       # Windows

# 安装依赖
pip install Pillow tqdm

注意：项目中已存在 .venv 虚拟环境，直接使用 source .venv/bin/activate 激活即可。

python retina_forge.py <目标文件夹路径> [选项]

• <目标文件夹路径>：指向包含 .imageset 的目录，通常是 Assets.xcassets。

将目录下所有 *@3x.png 缩放为 *@2x.png，并自动更新 Contents.json。

python retina_forge.py ./Assets.xcassets

将所有 *@3x.png 缩放为标准无后缀的 *.png（1x 图）。

python retina_forge.py ./Assets.xcassets --to-scale 1

默认情况下已存在的目标文件会被跳过。加上 --force 可强制重新生成。

python retina_forge.py ./Assets.xcassets --force

覆盖前自动将旧文件备份为 .bak。

python retina_forge.py ./Assets.xcassets --force --backup

仅查看会处理哪些文件，对磁盘零破坏，适合批量操作前核对。

python retina_forge.py ./Assets.xcassets --dry-run

将已有的 *@2x.png 降级切出 *.png（1x）。

python retina_forge.py ./Assets.xcassets --from-scale 2 --to-scale 1

开启 Pillow 极限体积优化 + 最高压缩等级，显著降低打包体积。

python retina_forge.py ./Assets.xcassets --optimize --compress 9 --force

脚本根据 iOS 命名规范自动计算输出文件名，支持大小写兼容（@2x / @2X）：

icon@3x.png  →  icon@2x.png   （3x → 2x）
icon@3x.png  →  icon.png      （3x → 1x）
icon@2x.png  →  icon.png      （2x → 1x）

每次转换成功后，脚本会自动找到同级目录下的 Contents.json，更新对应 scale 槽位的 filename 字段。如果槽位不存在则自动创建。

示例更新前：

{
  "images": [
    { "idiom": "universal", "scale": "2x" }
  ],
  "info": { "author": "xcode", "version": 1 }
}

更新后（假设转换了 icon@2x.png）：

{
  "images": [
    { "idiom": "universal", "scale": "2x", "filename": "icon@2x.png" }
  ],
  "info": { "author": "xcode", "version": 1 }
}

• 透明通道保护：自动处理 P/LA/PA/M 等模式的透明度，避免缩放后变黑。
• 智能色彩还原：如果原图是高效的索引色（P 模式），缩放后通过自适应量化还原为 PNG-8；如果原图没有透明通道，转回 RGB 以节省 Alpha 通道体积。
• ICC 配置剔除：彻底移除色彩配置文件，节省数 KB 到数十 KB 空间。

使用 ThreadPoolExecutor 进行并发处理，默认并发数为 CPU 核心数。配合 tqdm 显示实时进度条。

1. 始终在 .imageset 子目录下运行：确保脚本能找到 Contents.json 文件。例如传入 ./Assets.xcassets 而非某个具体的 .imageset 目录。
2. 建议先 Dry Run：首次使用前先用 --dry-run 预览，确认映射关系无误后再正式执行。
3. 大项目建议备份：处理重要项目前建议先 git commit 或手动备份。
4. --optimize 会显著增加耗时：仅在最终发布前使用，开发阶段不建议开启。
5. 仅支持 PNG 格式：脚本扫描 *.png 文件，不支持 JPG/SVG 等其他格式。