pyhanko.pdf_utils.images module

Utilities for embedding bitmap image data into PDF files.

The image data handling is done by Pillow.


Note that also here we only support a subset of what the PDF standard provides for. Most RGB and grayscale images (with or without transparency) that can be read by PIL/Pillow can be used without issue. PNG images with an indexed palette backed by one of these colour spaces can also be used.

Currently there is no support for CMYK images or (direct) support for embedding JPEG-encoded image data as such, but these features may be added later.

pyhanko.pdf_utils.images.pil_image(img: PIL.Image.Image, writer: pyhanko.pdf_utils.writer.BasePdfFileWriter)

This function writes a PIL/Pillow Image object to a PDF file writer, as an image XObject.

  • img – A Pillow Image object

  • writer – A PDF file writer


A reference to the image XObject written.

class pyhanko.pdf_utils.images.PdfImage(image: Union[PIL.Image.Image, str], writer: Optional[pyhanko.pdf_utils.writer.BasePdfFileWriter] = None, resources: Optional[pyhanko.pdf_utils.content.PdfResources] = None, name: Optional[str] = None, opacity=None, box: Optional[pyhanko.pdf_utils.layout.BoxConstraints] = None)

Bases: pyhanko.pdf_utils.content.PdfContent

Wrapper class that implements the PdfContent interface for image objects.


Instances of this class are reusable, in the sense that the implementation is aware of changes to the associated writer object. This allows the same image to be embedded into multiple files without instantiating a new PdfImage every time.

property image_ref

Return a reference to the image XObject associated with this PdfImage instance. If no such reference is available, it will be created using pil_image(), and the result will be cached until the writer attribute changes (see set_writer()).


An indirect reference to an image XObject.

render() → bytes

Compile the content to graphics operators.