add_freetext_annot is drawing text outside the annotation box

[apalermo01]

Description of the bug

I originally put this issue is sioyek here but I think this is an issue with pymupdf itself.

Annotations generated using add_freetext_annot sometimes appear invisible until one of its properties is changed in a pdf viewer.

How to reproduce the bug

I set up this script that reproduces the issue:

import fitz

pdf_path = "/home/alex/Documents/tutorial.pdf"
output_path =  "/home/alex/Documents/output.pdf"

doc = fitz.open(pdf_path)
page = doc[0]

rect = fitz.Rect(100, 100, 200, 150)
annot = page.add_freetext_annot(rect, "Test Annotation from minimal example")
annot.set_border(width=1, dashes=(3,3))
annot.set_opacity(0.5)
annot.set_colors(stroke=(1, 0, 0), fill=(0.9, 0.9, 0.9))
# annot.update()

rect = fitz.Rect(200, 200, 300, 300)
annot2 = page.add_freetext_annot(rect, "Test Annotation from minimal example pt 2")
annot2.set_border(width=1, dashes=(3,3))
annot2.set_opacity(0.5)
annot2.set_colors(stroke=(1, 0, 0), fill=(0.9, 0.9, 0.9))
annot2.update()

print("annot 1 AP:")
print(annot._getAP())
print("annot 2 AP:")
print(annot2._getAP())

doc.save(output_path)

annot appears on the page when I open the file in okular, but annot2 appears invisible. When I go in okular, select the annotation, and change any of its properties, it appears. I attached a video demonstrating this:

pymupdf_issue_20250126.mp4

Here are the appearance strings that we printed when I ran this:

annot 1 AP:
b'/H gs\n[3 3]0 d\n1 0 0 rg\n0 G\n1 w\n100 642 100 50 re\nf\n100.5 642.5 99 49 re\nS\n101 643 98 48 re\nW\nn\nq\n1 0 -0 1 100 642 cm\nBT\n0 g\n2 52.4 Td\n0 -13.200001 Td\n/Helv 11 Tf\n(Test Annotation ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(from minimal ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(example) Tj\nET\nQ\n'
annot 2 AP:
b'q\n/H gs\n[3 3] 0 d\n\n0 0 100 100 re\nW\nn\nBT\n0 g\n2 102.399997 Td\n0 -13.200001 Td\n/Helv 11 Tf\n(Test Annotation ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(from minimal ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(example pt 2) Tj\nET\nQ\n'

I'm pretty unfamiliar with this library, so I threw these at chatGPT and the suggestion that it gave was that the text is initially being drawn outside the bounding box.

Additionally, when I call annot.update(), both annotations are invisible. Here are the appearance strings:

annot 1 AP:
b'q\n/H gs\n[3 3] 0 d\n\n0 0 100 50 re\nW\nn\nBT\n0 g\n2 52.4 Td\n0 -13.200001 Td\n/Helv 11 Tf\n(Test Annotation ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(from minimal ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(example) Tj\nET\nQ\n'
annot 2 AP:
b'q\n/H gs\n[3 3] 0 d\n\n0 0 100 100 re\nW\nn\nBT\n0 g\n2 102.399997 Td\n0 -13.200001 Td\n/Helv 11 Tf\n(Test Annotation ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(from minimal ) Tj\n0 -13.200001 Td\n/Helv 11 Tf\n(example pt 2) Tj\nET\nQ\n'

If anyone has an idea of what the issue might be I'm happy to try a fix myself, but I will have to ask for a bit of guidance on where to look since I've never touched this library before.

PyMuPDF version

1.25.2

Operating system

Linux

Python version

3.13

[JorjMcKie]

This is a bug that started showing up after MuPDF also supported the callout format of this annotation type.
This new feature has changed the format command stream of freetext annotations, and PyMuPDF still needs to adapt its code to avoid interfering with it.

[julian-smith-artifex-com]

Fixed in PyMuPDF-1.25.3.