Support for adding an image to a page?

[robyoung]

Does pypdf support adding an image to a page? I can find how to list existing images on a page and even to replace one but I can't seem to find a method to add a new image. I would be willing to contribute such a method if that would be welcome.

[pubpub-zz]

Adding an image to a page can be done in 2 steps:
A) Convert the image to a pdf page using pillow
B) merge the created page with a transformation (scaling and translation) using merge_with_transformation()

Maybe an improvement could be to build the transformation matrix from the image size(from the pdf) the page size and destination position and size in percentage of destination page
Can you try this?

[robyoung]

Thanks, your pointers gave me some good places to start but I don't think I'm quite there yet.

I could not find any method called merge_with_transformation but I did find an example on merge with rotation which seems to do roughly what you describe. With it I can successfully add an image to a page but it has some oddities. Below is the test code that I have put together. With approach1 I get a merged page with the image appended to the content stream. However, rest of the PDF is completely re-written so I lose all the document metadata. With approach2 I retain the document metadata but the page is updated to have an array of two content streams, one being the original and one being my image. In both cases a clipping rectangle is added and there are two stacked transformation matrices added which seems totally sensible for most cases.

So, my questions:

1. Can I retain the document metadata while keeping the page content as a single stream?
2. Can I omit the clipping rectangle and merge the two transformation matrices?

from PIL import Image
from pypdf import PdfReader, PdfWriter, Transformation


def approach1():
    base_pdf = PdfReader("base.pdf")

    horsey = Image.open("horsey.jpg")
    horsey.save("horsey.pdf")
    horsey_pdf = PdfReader("horsey.pdf")

    horsey_page = horsey_pdf.pages[0]

    transformation = Transformation().rotate(45)
    horsey_page.add_transformation(transformation)

    base_page = base_pdf.pages[0]
    base_page.merge_page(horsey_page)

    updated_pdf = PdfWriter()
    updated_pdf.add_page(base_page)
    updated_pdf.write("approach1.pdf")


def approach2():
    base_pdf = PdfReader("base.pdf")

    horsey = Image.open("horsey.jpg")
    horsey.save("horsey.pdf")
    horsey_pdf = PdfReader("horsey.pdf")

    horsey_page = horsey_pdf.pages[0]

    transformation = Transformation().rotate(45)
    horsey_page.add_transformation(transformation)

    updated_pdf = PdfWriter()
    updated_pdf.clone_document_from_reader(base_pdf)

    base_page = updated_pdf.pages[0]
    base_page.merge_page(horsey_page)

    updated_pdf.write("approach2.pdf")


if __name__ == "__main__":
    approach1()
    approach2()

edited to fix some grammar

[stefan6419846]

By the way, the method mentioned by @pubpub-zz most likely is https://pypdf.readthedocs.io/en/stable/modules/PageObject.html#pypdf._page.PageObject.merge_transformed_page.

[pubpub-zz]

sorry for mistake in method name, I did not had easy access to web.

for your question, I recommend to work on the PdfWriter straight:
(draft code to be adjusted)

import pypdf
from io import BytesIO

w = pypdf.PdfWriter(clone_from="base.pdf")

horsey = Image.open("horsey.jpg")
horsey_pdf = BytesIO()
horsey.save(horsey_pdf)

horsey_page = horsey_pdf.pages[0]

transformation = pypdf.Transformation().rotate(45)
horsey_page.add_transformation(transformation)

for p in w.pages:
    p.merge_page(horsey_page)
    p.compress_content_streams()  # if you really want to condense the contentstream

w.write("approach3.pdf")

There is no issue to have a contentstream as an array (it is part of the standard)
Clipping areas are recommended to ignore all data out of the expected area. You should use the existing function to keep things simple.