Python Pillow getpalette 怎样读取图像调色板数据

Python Pillow 中，打开图像后调用 image.getpalette("RGB")，可以读取按 RGB 分量排列的调色板列表。每三个整数组成一个颜色条目；图像没有调色板时返回 None，应先处理这个分支再切片。

它读取的是颜色查找表，不是图片里每一种颜色的出现次数。若要解释某个 P 模式像素，应把像素值当作索引，再用它定位颜色表。

官方地址：https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getpalette

getpalette 返回的是什么

在索引图中，像素位置记录索引值，调色板负责把索引解释为颜色。明确请求 "RGB" 后，列表结构是第一个条目的三个分量、第二个条目的三个分量，依此排列。因此索引 i 对应列表中从 3*i 开始的三个元素。

这种结构适合读取现有颜色表、导出条目清单或解释像素索引。它不会告诉你哪个条目最常用，也不会因为一个条目存在就证明该颜色已经被某个像素引用。

先确认当前模式与适用范围

安装 Pillow 后从 PIL 导入 Image。本文围绕现有图像读取，不要求转换或重新保存文件。先看 image.mode，而不是根据扩展名判断内部模式：同一种文件格式可以使用不同图像模式。

P 模式表示调色板索引。RGB 图像通常直接保存各颜色分量，不需要用同样方式解释像素值。getpalette 的返回类型应作为显式分支处理，不能把 None 误写成“图像没有颜色”。

接口允许通过 rawmode 选择返回形式；当前文档还支持传入 None 以沿用调色板当前模式，这一能力从 Pillow 9.1.0 加入。若下游代码固定按三个分量分组，明确指定 RGB 更容易解释，不能在选择不同返回模式后仍机械地除以三。

读取并按 RGB 三元组整理颜色表

from PIL import Image

def read_palette(path):
    # 在文件上下文内读取，离开后只返回独立的普通数据
    with Image.open(path) as image:
        mode = image.mode
        flat = image.getpalette("RGB")
        if flat is None:
            return {"mode": mode, "has_palette": False, "entries": None}
        # 明确请求 RGB 后，按三个分量组织一个表项
        if len(flat) % 3:
            raise ValueError("调色板分量数量不能组成完整 RGB 表项")
        entries = [
            tuple(flat[offset:offset + 3])
            for offset in range(0, len(flat), 3)
        ]
        return {"mode": mode, "has_palette": True, "entries": entries}

report = read_palette("indexed.png")
print("mode:", report["mode"])
print("has_palette:", report["has_palette"])
if report["entries"] is not None:
    # 仅打印前几个条目，不把条目数量当作已使用颜色数量
    print("entries:", len(report["entries"]))
    print("preview:", report["entries"][:8])

请提供一份有权限读取的 indexed.png。程序显示当前模式、是否存在调色板、条目数量及前八个条目。具体值取决于文件，本文不提供伪造运行输出。这个小函数返回的是普通字典和元组，不把依赖文件仍然打开的图像对象交给调用方。

返回值刻意区分 has_palette=False 和条目列表。这样调用方可以明确显示“无调色板”，无需从空列表猜测原因。前八项只是展示上限，不会裁剪实际返回的 entries。

处理无调色板与索引映射

如果目标是解释某个像素，而不只是导出颜色表，可在当前 P 模式下按以下方式读取左上角的索引及对应 RGB：

from PIL import Image

with Image.open("indexed.png") as image:
    # 只对当前 P 模式解释像素值为调色板索引
    if image.mode != "P":
        raise ValueError("这个示例要求当前帧为 P 模式")
    if image.width == 0 or image.height == 0:
        raise ValueError("图像没有可读取的像素")
    flat = image.getpalette("RGB")
    if flat is None:
        raise ValueError("当前图像没有调色板")
    index = image.getpixel((0, 0))
    start = index * 3
    # 对读取结果做范围处理，不用越界切片伪装成有效 RGB
    if start + 3 > len(flat):
        raise ValueError("像素索引超出当前调色板范围")
    print("index:", index)
    print("rgb:", tuple(flat[start:start + 3]))

这里把模式、表是否存在和索引范围分别处理，因为它们是不同问题。对非 P 模式直接报错，有助于避免把 RGB 元组错误地乘以三。示例读取一个像素，不会修改原图。

如调用前已把图像转换成 RGB，就不应再期待原来的索引与颜色表关系仍然可用。需要原始颜色表时，应先在原对象上记录；如果选择另建调色板，则属于另外的转换任务，不是无损地找回原表。

颜色表不能替代像素统计

透明信息也不能仅凭 RGB 三元组推出。Pillow 的图像模式与文件元数据可以表达不同的透明方式，读取颜色表与判断像素是否可见应分开设计。本文只输出颜色分量，不给 RGB 列表附加透明度保证。

统计实际使用情况需要观察像素索引或明确颜色统计口径，不能拿 len(flat)//3 代替。若图像是动画或多帧文件，还要明确所读的是哪一帧；不能把当前对象的一次读取当作整个动画的统一颜色表报告。

资源与常见问题

Image.open 采用延迟读取机制，因此应在文件上下文中完成所需访问。对于批量任务，不要让大量图像对象长期持有文件；也不要为提取一张颜色表而先把完整像素转换成庞大的 Python 列表。

读取外部图像时，保留 Pillow 的图像尺寸保护设置，并按应用入口限制文件大小和处理资源。文件不存在、无法识别或底层读取失败应按真实异常处理，不能一律返回“无调色板”。

为什么 JPEG 读到 None？

应看当前对象是否具有调色板。常见 RGB 图像不依赖索引表，None 本身是可处理的正常结果。

为什么条目多于肉眼看到的颜色？

颜色表可以包含未使用位置，多个位置也可能具有相同颜色。表的容量与像素中实际颜色数量是不同概念。

getpalette 与 getpixel 应怎样配合？

对当前 P 模式，getpixel 提供位置上的索引；getpalette 提供索引对应的颜色表。先确认模式，再按返回模式的分量数量解释条目。

读调色板时抓住三个对象即可：当前模式、索引值与颜色条目。把它们分别保存，再明确处理 None，就能得到可解释的颜色表数据。

参考资料：Pillow Image 接口；Pillow 模式与调色板概念；Pillow 文件生命周期。