规范写完之后,两个同事各写一版解码器,读同一个文件。一个人说宽是九十六,另一个人说宽是三十九万三千二百二十四,两个人用的还是同一份规范。查了半天,问题在宽高字段的读法:一个按两字节小端读,另一个把它当成四字节,把后面的高度也拼了进去。

这是纸面规范和可运行实现之间的典型落差。字段表写得再清楚,只要没有一份真实文件、一个真实的往返测试,实现者就会在边界上做出不同解释。所以这一篇不继续讲设计,直接按上一篇的 PXIF 写代码:量化、编码、解码,然后在本机跑一遍,拿真实字节数和逐像素比对结果说话。

所有代码只用 Python 标准库,没有第三方依赖,也不调用系统里的图像库。演示脚本放在临时目录,没有进仓库。跑出来的文件我会把头部十六进制贴出来,逐字段对一遍,确认它和规范完全一致。

现象真实原因第一步查什么
两个解码器读同一文件,宽高不同字段宽度或字节序理解不一致,把相邻字段拼进了同一个整数按偏移逐字段打印原始字节,和规范表对照
解码时读越界,异常抛在下一行数据上RLE 没有按行宽计数,把控制字节当成像素继续读统计每行解出的像素单元数,确认等于层宽
往返后颜色整体错位调色板条目按三字节读,实际写了四字节,索引全偏核对 flags 的 alpha 位与调色板实际步长
编码后文件比原图还大渐变区域平均游程很短,控制字节的开销超过省下的像素统计每行平均游程长度,再决定是否开 RLE
逐像素比对失败,但肉眼看不出差别把量化误差当成了编码错误,比较对象不是同一张图先和量化后的索引图比,再和原图比误差
渐进层显示出来位置不对层宽高与实际行数据不一致,取样时下标越界或错行检查每层头部的宽高和该层实际解出的行数
改了元数据之后像素全乱data_offset 没有跟着元数据长度重算校验两个偏移是否指向合法位置,是否互相重叠

把规范翻成结构体

第一步是让头部只有一种读法。用标准库的 struct 定义固定格式,一次解出十一个字段,避免手写偏移时数错字节。格式串里的类型顺序必须和规范完全对应:四个字符的 magic、四个单字节字段、四个双字节字段、两个四字节字段。

import struct

HDR = struct.Struct("<4sBBBBHHHHII")
assert HDR.size == 24

MAGIC = b"PXIF"
VERSION = 1
F_INDEXED = 1 << 0
F_ALPHA = 1 << 1
F_PROGRESSIVE = 1 << 2
F_RLE = 1 << 3

magic, ver, flags, depth, reserved, w, h, npal, nmeta, data_off, meta_off = HDR.unpack_from(data, 0)

解析完先做四道检查:magic 匹配、版本认识、flags 无未知位、位深为八。四道都过,才读调色板和元数据。任何一道不过就抛带错误码的异常,不要「尽力解析」,结构错了之后偏移已经没有意义。

错误码要分开,这是排查效率的关键。magic 错说明文件根本不是这个格式;版本错说明是未来文件;flags 错说明能力位不认识;偏移错说明文件被截断或写入端算错。把这些混成一个「文件损坏」,线上只能靠猜。

解码器不要相信头部里的计数。调色板条数、元数据条数、层数都要和文件实际长度对照,超过上限直接拒绝。这是解析不可信输入的基本要求,和格式设计无关。

索引色量化:中位切分怎么切

索引色的第一步是把真彩色压到最多二百五十六种颜色。最简单的做法是均匀切分,每个通道切六档,得到二百一十六种颜色。它的问题是分配太平均:一张以蓝色为主的图,大部分颜色落在用不到的色块上,真正需要的渐变反而被切得很粗。

中位切分换了个思路:把所有像素当成一个盒子,每次挑出通道跨度最大的盒子,按该通道排序,从中间切成两半,直到盒子数量达到目标。每个盒子最后取平均色作为调色板条目,盒子里所有像素都映射到这个条目。颜色分布密的地方会被切得更细,分布稀的地方合并得更狠。

def median_cut(pixels, max_colors):
    boxes = [list(range(len(pixels)))]
    while len(boxes) < max_colors:
        best = None
        for bi, box in enumerate(boxes):
            if len(box) < 2:
                continue
            for ch in range(3):
                vals = [pixels[i][ch] for i in box]
                span = max(vals) - min(vals)
                if best is None or span > best[0]:
                    best = (span, bi, ch)
        if best is None or best[0] == 0:
            break
        _, bi, ch = best
        box = boxes.pop(bi)
        box.sort(key=lambda i: pixels[i][ch])
        mid = len(box) // 2
        boxes.append(box[:mid])
        boxes.append(box[mid:])

    palette = []
    for box in boxes:
        n = len(box)
        palette.append((
            sum(pixels[i][0] for i in box) // n,
            sum(pixels[i][1] for i in box) // n,
            sum(pixels[i][2] for i in box) // n,
            sum(pixels[i][3] for i in box) // n,
        ))
    return palette

这段实现只在 RGB 三个通道上找切分点,alpha 不参与切分,最后取平均。原因很简单:alpha 的分布和颜色分布不是一回事,把四个通道一起算跨度,会让透明边缘把颜色盒子切碎。代价是半透明区域的颜色会被平均得比较糙,边缘可能出现轻微的色偏。

最近色查找是另一个性能点。每个像素都要和二百五十六个条目算距离,一张七千像素的图就是一百七十多万次运算,还能接受;四百万像素的图就是十亿次,纯 Python 会跑到分钟级。演示里按通道高位做了缓存,把重复颜色折叠掉,实际项目应换成 kd 树或 C 库。

按行 RLE:控制字节怎么定

规范里已经定了规则:控制字节最高位为零表示字面量,后面跟「值加一」个像素单元;最高位为一表示重复,后面跟一个单元,重复「低七位加一」次。编码时按行扫,先看当前值和后面是否连续相同,连续两个以上就走重复,否则攒字面量,直到遇到重复或攒满一百二十八个。

def rle_row(units):
    out = bytearray()
    i, n = 0, len(units)
    while i < n:
        j = i + 1
        while j < n and units[j] == units[i] and j - i < 128:
            j += 1
        if j - i >= 2:
            out.append(0x80 | (j - i - 1))
            out.extend(units[i])
            i = j
        else:
            k = i
            while k < n and (k + 1 >= n or units[k + 1] != units[k]) and k - i < 128:
                k += 1
            if k == i:
                k += 1
            out.append(k - i - 1)
            for t in range(i, k):
                out.extend(units[t])
            i = k
    return bytes(out)

这段代码有个容易写错的地方:判断字面量能延伸到哪里。条件是「下一个不等于当前」并且「没有攒满」,遇到连续相同就停下,让下一轮处理重复。条件写成大于等于,会把重复串的第一个也吞掉,压缩率掉一点但解码仍正确;边界处理错,就会多读一个单元,行宽超过层宽。

解码端要反过来做,并且必须用层宽做上限。读到控制字节,算出这一段的单元数,先检查「已解出的数量加这一段」是否超过层宽,超过就报错,不要继续读。没有这个检查,一个损坏的文件可以让解码器一直读到文件末尾,把后面的层头当成像素。

渐进层:三层怎么排

渐进层按八、四、一三个分母生成。每一层先用最近邻从原图取样,得到十二乘九、二十四乘十八、九十六乘七十二三张索引图,再各自按行做 RLE。层头固定五字节:一字节分母、两字节宽、两字节高,后面直接跟这一层的行数据。

scales = [8, 4, 1]
payload.append(len(scales))
for s in scales:
    lw, lh = max(1, width // s), max(1, height // s)
    payload.append(s)
    payload.extend(struct.pack("<HH", lw, lh))
    for y in range(lh):
        src_y = min(height - 1, y * s)
        row = [bytes((indices[src_y * width + min(width - 1, x * s)],))
               for x in range(lw)]
        payload.extend(rle_row(row) if use_rle else b"".join(row))

三层的像素单元总数是一百零八加四百三十二加六千九百一十二,等于七千四百五十二,比单层多了百分之八。这是渐进的第一笔开销,还没算每行 RLE 的控制字节。换来的是解码端读完第一层就能先画一个十二乘九的缩略图,用户不用盯着空白等整张图。

取样用最近邻而不是平均,是刻意的。低分辨率层的用途是占位和轮廓,不是最终画质;用平均会让边缘变软,而且在纯 Python 里要遍历更多像素。真正好看的那一层在最后,前面两层糊一点无所谓。

渐进层的宽高必须和实际行数据一致。写入端如果按向下取整算宽高,却在取样时用了向上取整的循环,解码端会少读或多读一行,后面的层全部错位。这种错误不会在编码时报,只会在解码时表现成花屏。

编码器:两个偏移要一次算对

把前面几块拼起来,顺序是:先算调色板字节、元数据字节,再算两个偏移,最后拼头部和负载。调色板紧跟在头部之后,所以元数据偏移等于二十四加调色板长度;像素偏移等于元数据偏移加元数据长度。两个偏移都从文件开头算,不是相对上一段。

编码器的执行顺序
量化出调色板
逐层取样
按行 RLE
算两个偏移
拼字节写文件
meta_offset = HDR.size + len(palette_blob)
data_offset = meta_offset + len(meta_blob)
header = HDR.pack(MAGIC, VERSION, flags, 8, 0,
                  width, height, len(palette), len(metas),
                  data_offset, meta_offset)
blob = header + bytes(palette_blob) + bytes(meta_blob) + bytes(payload)

写入前要做范围检查:宽高必须在一到六五五三五之间,调色板不超过二百五十六,键名只能是 ASCII 小写字母、数字、下划线和短横线,值长度不超过六五五三五,元数据条数不超过六五五三五。这些检查放在编码端,比放在解码端更早暴露问题,因为编码端手里有原始数据,能给出更清楚的错误信息。

还有一个顺序细节:元数据块里的值是用 UTF-8 编码后的字节长度,不是字符数。四个中文字的「封面占位」是十二字节,写长度时要写十二,写四就会截断。这个错误在纯英文环境里测不出来,一上中文就出问题。

实际跑一遍:文件有多大

示例图是九十六乘七十二的合成图:渐变背景、带 alpha 渐变的圆形切口、纯色矩形和一条水平线,共六千九百一十二像素,调色板二百五十六色,元数据四条。本机 Python 3.15.0 直接运行,输出如下。

format      = PXIF v1
image       = 96x72  pixels=6912
palette     = 256 colors (RGBA)
header      = 24 bytes, data_offset=1134, meta_bytes=86
pxif size   = 4266 bytes  payload=3132
raw RGBA    = 27648 bytes  ratio=6.48:1
raw index   = 6912 bytes  ratio=1.62:1
layer scale=1/8  12x9   first_row[:8]=[21, 21, 95, 100, 80, 81, 53, 58]
layer scale=1/4  24x18  first_row[:8]=[21, 21, 21, 95, 95, 193, 100, 101]
layer scale=1/1  96x72  first_row[:8]=[21, 21, 21, 21, 21, 21, 21, 21]
roundtrip vs quantized source: mismatch=0 / 6912
quantization vs original: max_channel_err=118 rmse=8.484
meta: [('title', '示例图'), ('author', '科设文档'), ('created', '2026-11-06'), ('note', '合成图,非照片')]
flags=0x0f  indexed=True alpha=True progressive=True rle=True
hex head: 50 58 49 46 01 0f 08 00 60 00 48 00 00 01 04 00 6e 04 00 00 18 04 00 00

文件四千二百六十六字节。调色板一千零二十四字节,元数据八十六字节,头部二十四字节,剩三千一百三十二字节是像素负载。和未压缩的 RGBA 比是六点四八比一,和未压缩的索引位图比是一点六二比一。后一个更重要:索引色已把每像素压到一字节,压缩器只需和六千九百一十二字节较劲。

头部十六进制对一遍:前四字节 50 58 49 46 即 PXIF;版本 01;flags 是 0f,四个位全开;位深 08;保留 00;宽 60 00 是九十六;高 48 00 是七十二;调色板计数 00 01 是二百五十六;元数据条数 04 00 是四;像素偏移 6e 04 00 00 是一千一百三十四;元数据偏移 18 04 00 00 是一千零四十八。

验算一下偏移:二十四加一千零二十四等于一千零四十八,正好是元数据偏移;一千零四十八加八十六等于一千一百三十四,正好是像素偏移。两个数字和规范算法完全对上,说明编码器的拼装没有错位。

解码回来:逐像素比对

解码器按相反顺序走:读头部、跳过调色板前的字节、读指定条数的调色板、按元数据偏移读键值块、按像素偏移读层。每一层解开后得到一张索引图,最后一层的索引图通过调色板查表,变回 RGBA 像素。

def decode_pxif(path):
    data = open(path, "rb").read()
    magic, ver, flags, depth, reserved, w, h, npal, nmeta, off, moff = HDR.unpack_from(data, 0)
    assert magic == MAGIC and ver == VERSION
    palette, pos = [], HDR.size
    for _ in range(npal):
        r, g, b, a = data[pos:pos + 4]
        palette.append((r, g, b, a))
        pos += 4
    pos = off
    nlayers = data[pos]; pos += 1
    layers = []
    for _ in range(nlayers):
        s = data[pos]; pos += 1
        lw, lh = struct.unpack_from("<HH", data, pos); pos += 4
        rows = []
        for y in range(lh):
            row, pos = unrle_row(data, pos, lw, 1)
            rows.append([r[0] for r in row])
        layers.append((s, lw, lh, rows))
    return layers, palette

比对时分两步,不能混在一起。第一步拿解码后的像素和「量化后的源图」比,也就是调色板查表之后的索引图。这一步比的是编码和解码有没有错,理论上必须完全一致。第二步拿它和原始合成图比,这一步比的是量化误差,允许有差别。

实际结果是:对量化源图的比对,六千九百一十二个像素里零个不一致;对原始图的量化误差,单通道最大差一百一十八,均方根误差八点四八四。前者为零说明编解码闭环正确,后者不为零说明索引色的有损是真实存在的。

最大误差一百一十八出在圆形切口的 alpha 渐变上:alpha 从零连续变到二百五十五,二百五十六色分不出这么细的层次,只能就近取一个,边缘于是有台阶。这不是解码 bug,是索引色的上限。

四种开关组合的体积账

同一张图,把渐进和 RLE 两个开关分别开关,得到四组结果。数字都是本机实际编码出来的,不是估算。

渐进RLE文件字节像素负载说明
开开42663132示例图使用的组合
开关86027468三层原始索引,逐层展开
关开37222588单层加 RLE,体积最小
关关80526918单层原始索引,六字节层头加像素

RLE 在单层上把六千九百一十八压到二千五百八十八,省了约百分之六十三;渐进打开后,三层总共七千四百六十八,压到三千一百三十二,省了约百分之五十八。渐进本身让文件从三千七百二十二涨到四千二百六十六,多了五百四十四字节,涨幅约百分之十五。这就是「更早看到内容」的价格。

作为参照,zlib 压同一份索引字节是七百五十字节,加上头部和调色板约一千七百九十八字节,手写 RLE 比它差二点四倍。原因很直接:RLE 只吃连续相同的像素,渐变上相邻像素几乎都不同,控制字节成了纯开销;DEFLATE 还会找重复子串和做熵编码。

所以这个格式的真实定位是「结构清晰、可跳读、元数据和像素同体」,不是「压缩比优秀」。如果目标是体积,索引字节后面直接接 zlib 流会比手写 RLE 好得多,代价是随机访问和流式解码变难。选哪条路,取决于你更在意体积还是解析自由度。

边界与代价

第一笔代价是有损。二百五十六色对图标、图表、截图够用,对照片就是明显的色块和渐变断层,误差八点四八四已经超过很多场景的容忍线。要保真,得走直接色路径或者提高调色板容量,两者都会把文件变大。

第二笔代价是 RLE 的最坏情况。一行如果是交替的两种索引,每个像素都要单独一个控制字节,体积翻倍。编码器可以逐行试算、选小的方式,再在行头加标记;v1 没留这个位,只能整个文件开关 RLE。

第三笔代价是性能。整条实现用 Python 列表存像素,七千像素很轻松,四百万像素会慢到不可用。真要上生产,至少要换成字节数组、按块处理、把量化抽样化,或者把热点用 C 扩展重写。Python 适合验证规范,不适合批量转码。

第四笔代价是健壮性。v1 没有校验和,只有结构检查,一个被翻转的像素字节会安静地解出一张颜色错误的图。要检测内容损坏,得在元数据里放哈希,或者等 v2 加校验块。对外接收文件时,还要限制尺寸、调色板条数、元数据条数和每层行数,防止构造文件把内存吃光。

解码时每读一段都要先检查剩余字节数。RLE 的重复次数最多一百二十八,字面量也最多一百二十八,但不检查边界的话,一个伪造的控制字节可以让解码器连续越过层边界,读到任意位置。

最后还有一块没有实测:规范里定义了直接色和十位深,这两条路径本机没有实现,也没有跑过往返测试,标记为未实测。写进规范是为了让格式定义完整,不代表可以直接上线。要支持它们,得补编码器、解码器、边界检查和一组新的测试用例。

当天能自己验证的五个练习

  1. 把示例图的宽高改成奇数,比如九十七乘七十一,跑一遍编码和解码,检查最后一层宽高和取样下标是否仍然对齐。
  2. 把 RLE 的重复上限从一百二十八改成六十四,重新编码,记录文件变大多少,理解控制字节密度和游程长度的关系。
  3. 关掉 alpha 位、把调色板改成三字节,重新跑往返,确认解码端的步长也跟着改,观察颜色是否错位。
  4. 故意把 data_offset 改大十个字节,用解码器打开,记录它报的是哪一类错误,是否会在读层头时越界。
  5. 用一张真实照片跑量化,记录不同调色板数量下的均方根误差和文件大小,画出两条曲线。

小结

三句话:规范只有落到真实的字节和往返测试里才算成立,头部字段宽度、偏移算法、RLE 行边界是最容易分叉的三处;索引色量化把每像素从四字节压到一字节,但有损,误差要用均方根而不是肉眼判断;RLE 和渐进都是拿体积换别的东西,RLE 换解码简单,渐进换首屏体验,两个开关都要按图的内容决定。

自定义格式讲到这里,实现和验证都跑通了。下一篇回到日常工程:不造格式,只做优化。列表页的图为什么加载慢、尺寸和像素密度怎么配、有损参数怎么定、渐进和懒加载怎么用、格式回退和缓存怎么排,最后给一张可以直接照着做的决策表。