
PyPNG 的 png.Writer.write() 要求 RGB 图像的每一行必须是扁平化的 1D 列表(如 [R,G,B,R,G,B,...]),而非嵌套元组列表(如 [(R,G,B), (R,G,B), ...]),否则会触发 ProtocolError。本文解析其数据格式规范、提供可运行示例,并指出官方文档关键位置。
pypng 的 `png.writer.write()` 要求 rgb 图像的每一行必须是扁平化的 1d 列表(如 `[r,g,b,r,g,b,...]`),而非嵌套元组列表(如 `[(r,g,b), (r,g,b), ...]`),否则会触发 protocolerror。本文解析其数据格式规范、提供可运行示例,并指出官方文档关键位置。
PyPNG 是一个轻量、纯 Python 实现的 PNG 编解码库,并未过时(截至 2024 年 7 月最新版为 0.2024.7.10,托管于 GitLab),但其文档组织方式易导致初学者误解——核心问题不在于 API 过时或错误,而在于对输入数据结构的严格约定未被直观传达。
✅ 正确的数据格式要求
当创建 RGB 图像(greyscale=False, bitdepth=8)时,writer.write(stream, rows) 中的 rows 必须是一个可迭代对象(如列表),其中每个元素代表图像的一行(row),且该行本身必须是长度为 width × channels 的一维整数列表:
- 对于 RGB 图像:
channels = 3→ 每行应含width × 3个整数(范围 0–255); - 顺序为:
[R₀, G₀, B₀, R₁, G₁, B₁, ..., R_{w−1}, G_{w−1}, B_{w−1}]; - ❌ 错误格式:
[(0,0,0), (255,128,64), ...](嵌套元组)→ 触发ProtocolError: Expected 30 values but got 10 values, in row 0(10 像素 × 3 通道 = 30 值,但只传了 10 个元组); - ✅ 正确格式:
[0,0,0,255,128,64,...](展平后的一维列表)。
? 示例:生成 10×10 全黑 RGB PNG
import png
# 创建 Writer:10×10 RGB 图像,8-bit
writer = png.Writer(size=(10, 10), greyscale=False, bitdepth=8)
# ✅ 正确构造 rows:每行是长度为 30 的 list(10 像素 × 3 通道)
rows = []
for _ in range(10): # 10 行
row = [0, 0, 0] * 10 # 黑色像素重复 10 次 → [0,0,0,0,0,0,...]
rows.append(row)
# 写入文件
with open("black_10x10.png", "wb") as f:
writer.write(f, rows)
? 如何将 [(R,G,B), ...] 自动展平?
若你已有类似 getRowsAsRGB() 返回的嵌套结构(如 [[ (0,0,0), (255,0,0), ... ], [...]]),需显式展平:
def flatten_rgb_rows(rgb_rows):
"""将 [[(R,G,B), ...], ...] 转为 [[R,G,B,R,G,B,...], ...]"""
flattened = []
for row in rgb_rows:
flat_row = []
for r, g, b in row:
flat_row.extend([r, g, b])
flattened.append(flat_row)
return flattened
# 使用示例
nested = [[(0,0,0), (255,0,0), (0,255,0)] for _ in range(3)] # 3×3 绿/红/黑条纹
flat_rows = flatten_rgb_rows(nested) # → [[0,0,0,255,0,0,0,255,0], ...]
? 提示:文档中 “More Colour” 示例 使用
itertools.chain.from_iterable实现高效展平,推荐在大数据量场景使用:from itertools import chain flat_row = list(chain.from_iterable(pixel for pixel in nested_row))
⚠️ 注意事项与最佳实践
-
不要依赖
size参数自动推导行长度:Writer不校验每行实际长度,仅按width × channels预期值校验 —— 行长错误会在write()时立即报错; -
bitdepth 与数值范围强相关:
bitdepth=8要求所有值 ∈[0, 255];若用bitdepth=16,则需0–65535,且每个值需拆为两个字节(PyPNG 会自动处理); -
Alpha 通道需显式启用:添加
alpha=True后,每像素变为 4 值(RGBA),行长度变为width × 4; - 文档查阅建议:优先访问权威文档源 —— drj11.gitlab.io/pypng,而非 PyPI 页面链接(后者常滞后);重点精读 Colour 和 More Colour 章节。
掌握这一“扁平化行数据”范式,即可稳定使用 PyPNG 完成各类 RGB 图像生成任务,无需怀疑库本身是否异常 —— 它只是严谨,而非刁难。










