SPluzh/zbrush-spotlight-extractor

# zbrush-spotlight-extractor 一个 Python 工具，用于从 ZBrush Spotlight (`.zsl`) 文件中提取嵌入的纹理，并将它们保存为标准的 PNG 图像。 ## 什么是 .zsl 文件？ ZBrush Spotlight 是内置于 ZBrush 的纹理管理系统。当保存 Spotlight 会话时，ZBrush 会将所有已加载的纹理序列化为一个专有的扩展名为 `.zsl` 的二进制容器。每个纹理都以压缩的平面通道格式存储——而不是作为标准图像文件——这使得普通的图像查看器或转换器无法访问它。 **zbrush-spotlight-extractor** 对该格式进行了逆向工程，并从原始二进制数据中重建出像素级完美的 PNG 图像。 ## 功能 - 查找 `.zsl` 容器中所有嵌入的图像块 - 解压 ZBrush 的倒序 PackBits RLE 格式 - 从数据块级别的 BGRA 平面数据中重建完整的 RGBA 图像 - 从容器元数据中恢复原始源文件名 - 将 PNG 保存到输入文件旁边的 `_extracted/` 文件夹中 - 内含 Windows 拖放批处理脚本 ## 用法 ### 简单方法：预编译可执行文件 (Windows) 使用该工具最简单的方法是从 [Releases](https://github.com/SPluzh/zbrush-spotlight-extractor/releases) 页面下载独立的 **`zsltoimg.exe`**： 1. **拖放：** 只需从文件资源管理器中拖动任何 `.zsl` 文件，并将其放到 `zsltoimg.exe` 上。它会自动将所有纹理提取到源文件旁边的文件夹中，并显示完成日志。 2. **命令行：** 在终端中运行该可执行文件： zsltoimg.exe ## 工作原理 ### 1. 容器解析 `.zsl` 文件使用 LSZ (Pixologic Serialization) 二进制格式。`zslformat.find_image_blocks()` 扫描原始字节以查找类型为 `0x06` 的标记 (`\x01\x03\x80\x01\x00\x06\x00`)；`zslformat.parse_block_header()` 提取宽度、高度和数据块布局。 ### 2. RLE 解压 每个压缩数据块都使用倒序的 PackBits 算法： - 控制字节 `n < 128` → 将下一个字节精确重复 **n** 次 - 控制字节 `n = 128` → 无操作，跳过 - 控制字节 `n > 128` → 按原义复制接下来的 **256 − n** 个字节 ### 3. 平面通道重组 ZBrush 以**数据块级别的平面 BGRA 格式**存储像素数据：每个数据块包含 32 768 个像素，分为四个相等的平面——蓝、绿、红、Alpha——按此顺序排列。该工具： 1. 从每个数据块中提取 B/G/R/A 切片 2. 将同一通道的所有切片连接成全局平面 3. 反转 Alpha 通道 (`255 − value`)，将 ZBrush 的透明度蒙版转换为标准 PNG 不透明度 4. 将各个平面交错为 RGBA 像素数据并保存为 PNG 有关详细的技术分析，请参阅 [`zsl_specification.md`](zsl_specification.md)。 ## 许可证 MIT

标签：3D图形, Python, ZBrush, 云资产清单, 图像处理, 文件解析, 无后门, 纹理提取, 逆向工具, 逆向工程