使用PDFBox替换PDF图片时如何保留图片蒙版？

在使用Python结合JPype调用PDFBox替换PDF图片时，带软蒙版（soft mask）或模板蒙版（stencil image）的图片会出现蒙版丢失、图片损坏的问题，哪怕直接提取原图片再替换回去也会出现这个情况。以下是具体的解决思路和修改后的代码：

原问题代码 #

for page in pages:
    resources = page.getResources()
    if resources:
        pageImages = resources.getXObjectNames()
        for c in pageImages:
            imageObj = resources.getXObject(c)
            if isinstance(imageObj, PDImageXObject):
                bImage = imageObj.getImage()
                suffix = str(imageObj.getSuffix())
                tmp = tempfile.NamedTemporaryFile(suffix="." + suffix, mode="wb")
                out = FileOutputStream(tmp.name)
                if bImage.getColorModel().hasAlpha():
                    target = BufferedImage(bImage.getWidth(), bImage.getHeight(), BufferedImage.TYPE_INT_RGB)
                    g = target.createGraphics()
                    g.fillRect(0, 0, bImage.getWidth(), bImage.getHeight())
                    g.drawImage(bImage, 0, 0, None)
                    g.dispose()
                    ImageIOUtil.writeImage(target, suffix, out)
                else:
                    ImageIOUtil.writeImage(bImage, suffix, out)
                
                newImage = PDImageXObject.createFromFile(tmp.name, pdf)
                resources.put(c, newImage)
                tmp.close()

解决方法 #

核心是在替换图片时，将原图片的蒙版信息同步到新创建的PDImageXObject中：

1. 获取原图片的蒙版对象：通过imageObj.getSoftMask()获取软蒙版；如果是模板蒙版，可检查原图片COS对象的COSName.SMASK项是否为PDFormXObject类型来处理。
2. 将蒙版绑定到新图片：
   • 若PDFBox的PDImageXObject提供了setSoftMask公开方法，直接调用传入原蒙版对象即可；
   • 若无法调用公开方法，可直接操作COS字典设置蒙版属性，这是更通用的方式，因为PDF蒙版本质存储在图片对象的COS字典SMask项中。

修改后的代码 #

# 导入COSName，根据JPype的导入路径调整
from org.apache.pdfbox.cos import COSName

for page in pages:
    resources = page.getResources()
    if resources:
        pageImages = resources.getXObjectNames()
        for c in pageImages:
            imageObj = resources.getXObject(c)
            if isinstance(imageObj, PDImageXObject):
                # 1. 保存原图片的蒙版信息
                original_soft_mask = imageObj.getSoftMask()
                # 若需处理模板蒙版，可额外获取：
                # original_cos_obj = imageObj.getCOSObject()
                # original_mask = original_cos_obj.getItem(COSName.SMASK)
                
                bImage = imageObj.getImage()
                suffix = str(imageObj.getSuffix())
                tmp = tempfile.NamedTemporaryFile(suffix="." + suffix, mode="wb")
                out = FileOutputStream(tmp.name)
                if bImage.getColorModel().hasAlpha():
                    target = BufferedImage(bImage.getWidth(), bImage.getHeight(), BufferedImage.TYPE_INT_RGB)
                    g = target.createGraphics()
                    g.fillRect(0, 0, bImage.getWidth(), bImage.getHeight())
                    g.drawImage(bImage, 0, 0, None)
                    g.dispose()
                    ImageIOUtil.writeImage(target, suffix, out)
                else:
                    ImageIOUtil.writeImage(bImage, suffix, out)
                
                newImage = PDImageXObject.createFromFile(tmp.name, pdf)
                
                # 2. 将原蒙版绑定到新图片
                if original_soft_mask is not None:
                    # 优先使用公开方法
                    if hasattr(newImage, "setSoftMask"):
                        newImage.setSoftMask(original_soft_mask)
                    # 公开方法不可用时，直接操作COS字典
                    else:
                        newImage.getCOSObject().setItem(COSName.SMASK, original_soft_mask.getCOSObject())
                
                # 处理模板蒙版的逻辑（按需添加）
                # if original_mask is not None and isinstance(original_mask, PDFormXObject):
                #     newImage.getCOSObject().setItem(COSName.SMASK, original_mask.getCOSObject())
                
                resources.put(c, newImage)
                tmp.close()

说明 #

• 直接操作COS字典的方式兼容性更强，不受PDFBox版本中方法可见性的影响；
• 模板蒙版本质是PDFormXObject，处理逻辑和软蒙版一致，只需判断类型后同步COS对象即可；
• 替换时建议同步原图片的其他属性（如颜色空间、分辨率），避免出现额外显示问题。

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