Add movable image annotation?

[balk77]

Hi, I would like to add an image to a PDF in an annotation fashion. Freetext annots can be easily moved by the user in an appropriate PDF editor, but this cannot be used to add images. Images added through insert_image or insert_htmlbox cannot be moved unless the user edits the PDF in for instance Adobe Acrobat Pro.

When I copy paste an image (screenshot for instance) on a PDF, I can still move it. It has the subtype "Square". I seem not be able to add such subtype to the pdf.

for a in page.annots():
    print(a)

results in

{'subtype': '/Square', 'location': [231.05, 690.6986, 371.4487, 774.1989]}
{'subtype': '/FreeText', 'location': [0, 742, 100, 842]}

Here, /Square is the pasted image.

Another route I tried was add_freetext_annot with richtext=True and an <img> tag, but that only shows [image] on the PDF. See screenshot.

So, is there a way to programmatically add a movable image to a PDF?

Sample script:

import pymupdf  

pdf_path = "output.pdf"
doc = pymupdf.open(pdf_path)

value = """
<img src="example.png" width="100" height="100">
"""
page = doc[0]  

rect = pymupdf.Rect(0,0,100,100)
annot = page.add_freetext_annot(
        rect,
        str(value),
        fontsize=5,
        rotate=0,
        text_color=None,
        fill_color=None,
        align=pymupdf.TEXT_ALIGN_CENTER,
        richtext=True
        
    )

annot.update()
page = doc.reload_page(page)

for a in page.annots():
    print(a)

doc.saveIncr()
doc.close()

[JorjMcKie]

In the near future, we will support images as part of a "Stamp" annotation. It won't be part of the next version 1.25.5, but probably version 1.25.6.

[balk77]

Thanks, I will look out for rev 1.25.6 then!

[JorjMcKie]

The base library MuPDF already contains this type of support and I have a test script which will be the basis for a final API. If you are interested, I can share that script with you.

[balk77]

that would be great so I can test. Thanks!

[JorjMcKie]

Here you are.
stamp-image.zip

The way it currently works is by creating an arbitrary text-based Stamp annotation. Such annotations have a predefined width:height aspect ratio (10:38 if I remember correctly).
Then convert this into an Image-Stamp. This will modify the original annotation rectangle.

• The given rectangle is drawn in red.
• Standard (text) Stamp insertion behavior is to make a new annot rectangle of required aspect ratio and put it centered into the given rect (at max possible size).
• When converting to an image, the image is inserted at max possible size, retaining image aspect ratio, such that its left border equals the computed annot rectangle.

That's how far I am.
Opacity is supported by setting the annotation opacity.
Annotation rotation is not supported.
Let me know how this works for you.

[balk77]

It works! Thanks for the help Op ma 10 mrt 2025, 14:00 schreef Jorj X. McKie ***@***.***>:

…

Here you are. stamp-image.zip <https://github.com/user-attachments/files/19162739/stamp-image.zip> The way it currently works is by creating an arbitrary text-based Stamp annotation. Such annotations have a predefined width:height aspect ratio (10:38 if I remember correctly). Then convert this into an Image-Stamp. This will modify the original annotation rectangle. - The given rectangle is drawn in red. - Standard (text) Stamp insertion behavior is to make a new annot rectangle of required aspect ratio and put it centered into the given rect (at max possible size). - When converting to an image, the image is inserted at max possible size, retaining image aspect ratio, such that its left border equals the computed annot rectangle. That's how far I am. Opacity is supported by setting the annotation opacity. Annotation rotation is *not* supported. Let me know how this works for you. — Reply to this email directly, view it on GitHub <#4357 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACNSATQFOYVL6AC5SC24A432TWEGVAVCNFSM6AAAAABYVUA5TKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTENBUHA4TINA> . You are receiving this because you authored the thread.Message ID: ***@***.***>