#1460·pdfcpu

`CreateImageStreamDict` corrupts white/gray images with transparency

Author: phipspCreated Aug 12, 2026Updated Aug 12, 2026
Labelsinvestigate

When model.CreateImageStreamDict builds an image object from a decoded image, it detects white/gray images as grayscale and stores them as DeviceGray plus SMask. That encoding is fine in itself, but the gray values written are wrong: the gray channel ends up being a byte-for-byte copy of the alpha channel, so the visible color is destroyed.

I stumbled over this bug while using model.CreateImageStreamDict from the API, but it can also be reproduced using images update. I know it's a known limitation from the docs ("allows for image replacement as long as there is no softmask or alpha channel involved") but I wondered if it might still be worth fixing for API users.

Example: a white logo with soft transparent edges turns into a gray blob.

bash
pdfcpu import white.pdf white.png                        # control, correct
pdfcpu images update white.pdf white.png corrupt.pdf 4   # replace Im0 with the SAME png
pdfcpu images list white.pdf corrupt.pdf

white.pdf renders to:

Image

while corrupt.pdf renders to:

Image

Version: v0.15.0. OS: ubuntu:24.04

Image

white.pdf corrupt.pdf