第 16 章：THMB 区段
Directory Tag： THMB · 作用范围： 全局 · 必须性： 可选 · 允许 Codec： RAW8
THMB（Thumbnail）保存用于资产卡片、文件列表、选择器和网页首屏的轻量 PNG 缩略图。它的
目标是让调用方在不读取 VOX0、不解析 PRVW GLB、也不初始化 3D 渲染器的情况下快速显示一个
可信度明确的视觉占位。
THMB 不是权威数据。它不参与 Source Hash，不得用于编辑、体素拾取、几何校验或反推 VOX0。
缩略图缺失、损坏、过期或读取器不支持时，资产仍可按正常 VFP 路径打开、验证和编辑。
16.1 Directory 约束
每个活动 generation 最多只能有一个 THMB。若存在，它必须是全局 RAW8 区段：
| 字段 | 必须值 | 说明 |
|---|---|---|
tag | THMB | ASCII 四字符 tag |
codec | 0（RAW8） | 不允许以 VFP RLE8 编码 PNG 字节 |
chunkId | -1 | 缩略图属于整个资产，不属于某个空间 Chunk |
flags | 0 | flags 不表达图片编码或尺寸 |
rawLength | 等于 length | RAW8 原样存放 |
crc32 | PNG 载荷的 CRC32 | 先由 Directory 校验 |
THMB 是可安全忽略的可选区段。旧读取器可以忽略未知 tag；新读取器则应在需要缩略图时按目录
offset 选择性读取它，避免为了一个小图加载整个 VFP。
16.2 PNG Payload
Payload 是完整 PNG 文件字节流，没有 VFP 私有 Header，也不需要额外的 MIME 字段。最小结构为：
PNG signature (8 B)
IHDR (必须且唯一)
IDAT (一个或多个)
IEND (必须且唯一)
合规 THMB 必须满足：
| PNG 字段 | 规则 |
|---|---|
| PNG signature | 必须为 89 50 4E 47 0D 0A 1A 0A |
IHDR.bitDepth | 必须为 8 |
IHDR.colorType | 必须为 6（RGBA） |
IHDR.compressionMethod | 必须为 0 |
IHDR.filterMethod | 必须为 0 |
IHDR.interlaceMethod | 必须为 0（不隔行） |
IHDR.width / height | 必须相等，且都在 64..1024 |
标准不规定具体相机、材质、背景、光照或抗锯齿算法。这些属于编译器的展示策略，不改变资产
语义。VoxelKit Compiler 的默认输出为 256 × 256 RGBA PNG，使用等轴视角和透明背景。
Writer 可选择 thumbnail_background="#RRGGBB" 写入不透明背景；#RRGGBB 应规范化为大写，
transparent 表示完全透明。背景只影响 PNG 展示，不参与 Source Hash，也不能改变体素资产语义。
16.3 读取流程
缩略图读取只需要容器级安全检查和 THMB 本身，不需要恢复全部体素：
读取 Header / 最后一个 Footer
↓
读取并校验 DIR0 CRC
↓
查找唯一 THMB[-1] 目录项
↓
按 offset / length 范围读取并校验 payload CRC
↓
校验 PNG signature 与 IHDR
↓
返回原始 PNG 字节和 width / height
读取器应把“没有 THMB”视为正常的可选缓存缺失，而不是整个文件损坏。可将结果建模为
undefined / None，或返回明确的 thumbnail_unavailable 状态；只有调用方把缩略图设为
业务强制资源时，才应将该状态提升为用户可见错误。
16.4 安全与资源限制
PNG 是外部不可信数据。读取器至少应在交给图像解码器前执行以下限制：
- Directory 中的
length不得超过产品的预览载荷上限； - 必须先确认
offset + length位于活动 DIR0 前的文件范围内； - 必须通过 Directory payload CRC，再检查 PNG signature 和 IHDR；
width × height必须使用溢出安全乘法，并限制在1024²；- 不支持动画、调色板索引、灰度、JPEG、WebP 或隔行 PNG 时，必须安全拒绝或忽略该缓存；
- 不得因
THMB错误跳过VOX0的正式验证，也不得把缩略图用于内容审核或作品真实性判定。
PNG 解码失败只影响预览功能。除非产品明确规定“缩略图必须存在”，否则应隐藏缩略图并继续展示 文件名、META 信息或模型正式预览入口。
16.5 与 PRVW 的关系
PRVW 与 THMB 都是派生预览，但解决的问题不同：
| 对比 | THMB | PRVW |
|---|---|---|
| 载荷 | 小型 RGBA PNG | 通用 3D GLB 预览 |
| 典型用途 | 文件列表、选择器、资产卡片 | 无体素渲染器时的 3D 兼容展示 |
| 首次读取成本 | 只读一个小 PNG 区段 | 读取并交给 GLB / glTF 管线 |
| 是否可编辑 / 验证 | 否 | 否 |
| 缺失后的处理 | 隐藏缩略图 | 回退到体素渲染或隐藏 3D 预览 |
资产可以同时携带二者，也可以只携带其中之一。客户端不应因为已存在 PRVW 就跳过 THMB：
文件库通常优先选择 THMB，用户进入模型详情后再按需加载 PRVW 或权威体素。
16.6 Writer 建议
Writer 生成 THMB 时应：
- 先完成
VOX0、PAL0与 Source Hash 的权威写入； - 从权威体素或其已验证的派生面生成缩略图；
- 写入符合本章约束的完整 PNG；
- 为目录项计算 CRC32，并设置 Header
featureFlags的0x80提示位； - 可在
META.cache.thumbnail中记录format、width、height、background等展示提示；background推荐为transparent或规范化的#RRGGBB； - 在编辑导致权威体素或调色板变化后，重建或删除旧
THMB。
META.cache.thumbnail 只是提示。读取器必须以 PNG IHDR 和 Directory 为准，不能信任元数据中
的尺寸来分配内存或定位图片。
本章总结
THMB 提供了一个低成本、跨平台、可选择性读取的资产缩略图路径。它改善文件浏览体验，但始终是
可丢弃的缓存：资产的真实性和可编辑性仍只由 META、PAL0、CHIX 与 VOX0 决定。