自动批量无损压缩贴图尺寸，做性能优化 | Batch lossless texture compression & performance optimization for game assets
一个工具搞定所有纹理优化场景：本地图片批量压缩、3D 资产 zip 包贴图优化、UE 编辑器内纹理降级。支持 4K→2K→1K 一键转换，最高节省 93% 显存/包体。
One tool for all texture optimization needs: batch compress local images, optimize textures inside 3D asset zip files, and downscale textures inside Unreal Engine. Convert 4K→2K→1K in one command, saving up to 93% VRAM/package size.
| 问题 | 传统做法 | 本工具 |
|---|---|---|
| 4K 贴图太大占显存 | 手动一张张改尺寸 | 一行命令批量压缩，保持目录结构 |
| Tripo/Meshy 等 AI 模型贴图过大 | 手动解压→改图→重打包 | 自动处理 zip 包，解压压缩重打包一条龙 |
| UE 里纹理太多不好管 | 一个个资产改 MaxTextureSize | 批量设置，无损可逆，一键恢复 |
| 法线/金属度贴图 sRGB 设错 | 手动检查修正 | 自动识别纹理类型，设置正确压缩格式 |
关键词 / Keywords: texture compression texture optimization image resize ImageMagick 批量贴图压缩 性能优化 Unreal Engine UE5 PBR game assets Tripo zip texture 无损压缩 显存优化
- 功能特性 / Features
- 快速开始 / Quick Start
- 使用方式 / Usage
- 参数说明 / Parameters
- 常见问题 / FAQ
- 安全说明 / Security
- License
- ✅ 两种运行模式：命令行（文件级压缩）+ UE Python（编辑器内优化）
- ✅ 批量压缩：支持文件夹递归、zip 包内贴图
- ✅ 无损缩放：使用 ImageMagick 高质量 Lanczos 缩放算法，只缩小不放大
- ✅ 增量处理：已存在的输出文件自动跳过，中断可续
- ✅ 格式广泛：PNG, JPG, TGA, BMP, WebP, TIFF
- ✅ UE 智能识别：自动识别 Normal/Metallic/Roughness 等纹理类型，设置正确压缩格式
- ✅ 无损可逆：UE MaxTextureSize 模式随时可恢复原始尺寸
- ✅ 零配置：开箱即用，参数按需调整
- ✅ 防命令注入：subprocess 使用参数列表调用，无
shell=True - ✅ 防 Zip Slip：zip 解压前逐文件校验路径，防止目录穿越攻击
- ✅ 文件头校验：魔术字节验证图片真实性，防止伪装文件触发 ImageMagick 漏洞
- ✅ 路径隐私保护：日志默认只打印相对路径，不暴露完整本地目录结构
- ✅ 终端注入防护：输出文件名经过净化，移除控制字符
- Python 3.8+
- ImageMagick 7.x（命令行压缩需要，UE 模式不需要）
- 下载：https://imagemagick.org/script/download.php
- Windows 安装时勾选 "Add to PATH"
# 克隆或下载本仓库
git clone https://github.com/JemmaBone/texture-optimizer.git
cd texture-optimizer
# 验证 ImageMagick
magick --version# 压缩文件夹内所有图片到 2048px
python texture_optimizer.py compress --src ./textures --size 2048
# 压缩 Tripo/3D 资产 zip 包内的贴图到 1024px
python texture_optimizer.py compress-zip --src ./models --size 1024批量压缩文件夹内的所有图片，保持目录结构不变。
# 基本用法
python texture_optimizer.py compress --src ./textures --size 2048
# 指定输出目录和质量
python texture_optimizer.py compress --src ./textures --out ./compressed --size 1024 --quality 90
# 不递归子目录
python texture_optimizer.py compress --src ./textures --size 2048 --no-recursive
# 指定 ImageMagick 路径（如果不在 PATH 中）
python texture_optimizer.py compress --src ./textures --size 2048 --magick "C:\Program Files\ImageMagick-7\magick.exe"输出示例：
ImageMagick: Version: ImageMagick 7.1.2 Q16-HDRI x64
============================================================
Folder batch compression
Source : ./textures
Output : ./textures_compressed
Size : 2048px max side
Quality: 85
Images : 156
============================================================
[1/156] ✓ character/basecolor.png (72%)
[2/156] ✓ character/normal.png (68%)
...
[156/156] ✓ props/metalness.png (75%)
============================================================
Done!
Processed: 156/156
Skipped : 0 (already exist)
Original : 245.3 MB
Compressed: 68.7 MB
Saved : 72%
============================================================
批量压缩 zip 包内的所有贴图（保持 zip 结构不变）。 适用于 Tripo、Meshy、3D 扫描资产等打包好的模型文件。
# 基本用法
python texture_optimizer.py compress-zip --src ./models --size 1024
# 指定输出目录
python texture_optimizer.py compress-zip --src ./models --out ./models_2k --size 2048
# 自定义质量
python texture_optimizer.py compress-zip --src ./models --size 1024 --quality 90输出示例：
ImageMagick: Version: ImageMagick 7.1.2 Q16-HDRI x64
============================================================
Zip batch texture compression
Source : ./models
Output : ./models_compressed
Size : 1024px max side
Quality: 85
Zips : 32
============================================================
[1/32] 📦 retro_monitor.zip
✓ 4/4 textures, 12.5MB → 3.2MB (74%)
[2/32] 📦 office_chair.zip
✓ 3/3 textures, 8.7MB → 2.1MB (76%)
...
[32/32] 📦 old_radio.zip
✓ 4/4 textures, 15.3MB → 3.8MB (75%)
============================================================
Done!
Zips processed: 32/32
Skipped : 0
Textures : 128/128 resized
Original : 384.6 MB
Compressed : 98.3 MB
Saved : 74%
============================================================
在 Unreal Engine Python 控制台中运行，对内容浏览器中的纹理资产批量优化。
优点：无损可逆，原图不变，只是设置最大显示尺寸。想调回去随时改。
# 1. 导入模块
import sys
sys.path.append(r"<本仓库的本地路径>")
import texture_optimizer as topt
# 2. 先看看当前纹理尺寸分布
topt.list_texture_sizes("/Game/YourFolder")
# 3. 一键综合优化（推荐）
# - 自动识别 Normal/Metallic/Roughness 等类型，设置正确压缩格式
# - 设置 MaxTextureSize 到 2048
topt.batch_optimize("/Game/YourFolder", max_size=2048)
# 4. 或者只改尺寸
topt.batch_set_max_size("/Game/YourFolder", max_size=1024)
# 5. 恢复原始尺寸
topt.batch_reset_size("/Game/YourFolder")UE 模式功能对照表：
| 函数 | 功能 | 可逆？ |
|---|---|---|
list_texture_sizes() |
统计纹理尺寸分布 | - |
batch_set_max_size() |
批量设置 MaxTextureSize | ✅ 可逆 |
batch_set_compression() |
自动识别纹理类型，设置压缩格式 + sRGB | ✅ 可逆 |
batch_optimize() |
上面两个的组合（推荐） | ✅ 可逆 |
batch_reset_size() |
恢复原始尺寸 | - |
| 参数 | 默认值 | 说明 |
|---|---|---|
--size |
2048 |
目标最大边长（像素）。保持宽高比，只缩小不放大 |
--quality |
85 |
JPEG/PNG 质量 1-100。85 基本无损，75 体积更小 |
--magick |
magick |
ImageMagick 路径。默认从 PATH 找，也可用 $MAGICK 环境变量 |
| 参数 | 默认值 | 说明 |
|---|---|---|
--src |
(必填) | 源图片文件夹 |
--out |
<src>_compressed |
输出文件夹 |
--no-recursive |
关闭 | 不递归子目录 |
| 参数 | 默认值 | 说明 |
|---|---|---|
--src |
(必填) | 源 zip 文件所在文件夹 |
--out |
<src>_compressed |
输出文件夹 |
| 目标尺寸 | 相对 4K 节省 | 推荐场景 |
|---|---|---|
| 4096 (4K) | 0% | 主角、特写道具、高质量渲染 |
| 2048 (2K) | 75% | 大部分游戏道具、次世代场景（推荐） |
| 1024 (1K) | 93.75% | 远景道具、小物件、手游、独立游戏 |
| 512 | 98.4% | 极小道具、LOD 远距离、像素风 |
💡 建议：先用 2048 试一下，大多数情况下肉眼几乎看不出区别，但显存直接砍到 1/4。
Q: 压缩后画质损失大吗？
A: 4K→2K 在正常观察距离下人眼基本看不出区别。ImageMagick 用的是高质量 Lanczos 缩放算法。quality=85 的 JPEG 也属于感知无损范围。
Q: 支持哪些图片格式？
A: PNG, JPG/JPEG, TGA, BMP, WebP, TIFF。如果有其他格式需求可以提 issue。
Q: zip 压缩会破坏其他文件吗？
A: 不会。只压缩图片，其他文件（FBX、OBJ、材质文件等）原样保留，zip 结构完全不变。
Q: 能处理嵌套 zip 吗？
A: 目前只处理单层 zip（zip 里面直接是贴图）。如果有嵌套需要先解压再处理。
Q: UE 模式和命令行模式有什么区别？
A:
- 命令行模式：真正修改文件，体积变小，适合提交版本控制、打包前优化
- UE 模式：只改资产设置，原图不变，无损可逆，适合项目内快速调整
Q: Tripo 模型怎么用？
A: 用
compress-zip模式，把 Tripo 导出的 FBX zip 直接丢进去：python texture_optimizer.py compress-zip --src ./tripo_models --size 1024
| 防护措施 | 说明 |
|---|---|
| 防命令注入 | subprocess 使用参数列表调用，无 shell=True，文件名不会被解析为 shell 命令 |
| 防 Zip Slip | zip 解压前逐文件校验路径，防止 ../ 目录穿越写入系统任意位置 |
| 文件头校验 | 魔术字节验证图片真实性（PNG/JPG/BMP/WebP/TIFF），防止伪装文件 |
| 路径隐私 | 日志默认打印相对路径/目录名，不暴露完整本地路径结构 |
| 终端注入防护 | 输出文件名经过净化，移除控制字符 |
- 只处理来源可信的图片和 zip 文件
- 保持 ImageMagick 为最新稳定版（旧版可能存在图片解析漏洞）
- 如遇可疑 zip 包，工具会自动拦截并报告不安全路径
- 如需最快速度且信任源文件，可用
--no-validate跳过文件头校验（不推荐）
- TGA 格式无标准魔术字节，无法通过文件头校验，仅依赖后缀名判断
- 本工具纯本地运行，无网络功能，不存在远程攻击面
- 不处理可执行文件，仅处理图片格式
MIT