C++从零实现PNG(zlib压缩)写入：libpng过滤器值错误排查

问题核心 #

Windows图像查看器对PNG格式容错性较高，能忽略部分小错误，但OpenCV依赖的libpng对格式规范要求严格。你碰到的bad adaptive filter value错误，本质是过滤器字节的位置、格式或关联数据不符合PNG标准，哪怕你用的是合法的None过滤器（值为0）。

具体排查点 #

• 检查每行过滤器字节的添加是否正确
  PNG规范要求每一行（包括第一行）的第一个字节必须是过滤器类型（0-4），之后才是该行像素数据。要确认：

  1. 没有漏掉任何一行的过滤器字节0
  2. 过滤器字节未被计入像素数据长度——比如一行像素为N字节，过滤后该行总长度应为1+N字节

• 核对过滤后数据的总长度
  计算总字节数：(1 + 每行像素字节数) × 图像高度，与你传入zlib压缩的实际数据长度对比。如果长度不匹配，libpng会将像素数据误判为过滤器字节，自然触发非法值错误。

• 验证IDAT压缩数据的完整性
  虽然CRC校验正常，但要确认zlib压缩的是完整的过滤后数据，无截断或多余字节。可将IDAT的压缩数据解压，与原始过滤后数据逐字节对比——解压后数据若有缺失或冗余，必然会打乱过滤器解析逻辑。

• 确认IHDR参数与实际数据匹配
  检查IHDR块中的宽度、高度、位深度、颜色类型，必须与实际像素数据完全对应。比如RGB图像（3字节/像素），每行像素字节数应为宽度×3，加上过滤器字节后每行总长度为1 + 宽度×3字节。若IHDR参数与实际数据不匹配，libpng会计算错误的扫描行边界，导致过滤器字节位置错位。

• 检查过滤器字节的实际值
  不要默认过滤器字节就是0，用十六进制编辑器打开生成的PNG，解压IDAT数据后查看每行开头字节，确认均为0x00。可能因字节序错误、数据溢出等问题，过滤器字节变成了大于4的非法值。

测试小技巧 #

• 生成2x2的极小测试图像，用十六进制编辑器直接查看解压后的IDAT数据，逐行核对过滤器字节与像素数据，更容易定位错误位置。
• 用标准工具（如Photoshop）生成同参数的PNG，解压其IDAT数据，与你生成的过滤后数据做字节级对比，差异点即为问题所在。

内容的提问来源于stack exchange，提问作者Jonny_92