使用fitz与OpenCV转换PDF为图像时输出近乎全黑图像的原因排查

• 数据类型错误：代码中使用np.int8解析像素数据是核心问题。图像RGB像素值范围是0-255的无符号整数，而np.int8是有符号类型（范围-128到127），超过127的像素值会被转换为负数，导致OpenCV保存时识别为异常值，最终生成全黑图片。
  修复：将np.int8改为np.uint8。
• 路径转义问题：Windows系统下路径中的反斜杠\会被当作转义字符（比如\m可能被解析为特殊字符），可能导致PDF文件无法正确读取。
  修复：使用原始字符串定义路径，或者将反斜杠改为双反斜杠：

  filename = r'sample_pdf\muscle model\Invoice of muscle model from HealthLink.pdf'
  # 或者
  filename = 'sample_pdf\\muscle model\\Invoice of muscle model from HealthLink.pdf'
  

• 可选优化：fitz的get_pixmap默认已经是RGB格式，colorspace='RGB'可以省略；另外可以直接使用pix.save('test.png')跳过OpenCV的转换步骤，更简洁可靠。

修复后的完整代码：

import fitz
import cv2
import numpy as np

# 使用原始字符串避免路径转义
filename = r'sample_pdf\muscle model\Invoice of muscle model from HealthLink.pdf'

doc = fitz.Document(filename)
page1 = doc[0]
pix = page1.get_pixmap(annots=False)
# 改用无符号8位整数解析像素数据
bytes = np.frombuffer(pix.samples, dtype=np.uint8) 
img_rgb = bytes.reshape(pix.height, pix.width, pix.n)
img_bgr = img_rgb[:,:,::-1]
cv2.imwrite('test.png', img_bgr)

doc.close()

或者更简洁的版本（跳过OpenCV直接保存）：

import fitz

filename = r'sample_pdf\muscle model\Invoice of muscle model from HealthLink.pdf'
doc = fitz.Document(filename)
page1 = doc[0]
pix = page1.get_pixmap(annots=False)
pix.save('test.png')
doc.close()

内容的提问来源于stack exchange，提问作者Kong Ting Chau