Stroke color of annotations cannot be correctly set

[cli-lilly]

dummy.pdf

Description of the bug

When I use annot.set_colors(stroke=(0, 0, 0)) to set annotations' border color to black, the fill color of the annotations are changed to black instead. The border color remains the same as the text color.

How to reproduce the bug

import pymupdf
pdf = pymupdf.open(input_pdf_path)
page = pdf[0]

text_color = (1, 0, 0)
fill_color = (191/255, 1, 1)
border_color = (0, 0, 0)

annot_rect = pymupdf.Rect(90.1, 486.73, 139.26, 499.46)

annot = page.add_freetext_annot(  
    annot_rect,  
    "AETERM",  
    fontname="Arial",  
    fontsize=10,  
    text_color=text_color,
    fill_color=fill_color,   
    border_width=1   
)  

annot.set_colors(stroke=(0, 0, 0))
annot.update()  # Save the annotation to the page
pdf.save(output_pdf_path)

Expected behavior:
The border of the annotation should be black, and the fill color should remains light blue

Actual behavior:
The fill of the annotation is set to black, while the border color is the same as the text color

PyMuPDF version

1.25.4

Operating system

Windows

Python version

3.13

[julian-smith-artifex-com]

Please add the pdf file input_pdf_path to this issue.

[cli-lilly]

Due to company policy, I am unable to provide the original PDF file. I have added a dummy pdf file instead, I think you can reproduce the bug on it

[julian-smith-artifex-com]

Actually don't worry, i think i've reproduced the problem with a blank document.

[JorjMcKie]

As per the PDF specification, FreeText annotations only support one color in their object definition (/C) which is used for the fill color. Just like e.g. Highlight annotations.
This is the reason for your phenomenon.
So using annot.set_color for FreeText will in most cases not lead to what you want.

[JorjMcKie]

FreeText annotations often have 3 different colors: fill, border and text color - which is completely beyond what PDF object definition syntax lets you do.
What is more, FreeText annots also support rich text which basically means you can specify text in HTML syntax. Here, separate colors and other text properties can be set for individual text particles.
Use the annotation's .update() method for modifying the colors ... or do it right when creating 😉.

[JorjMcKie]

I think we need to explain this better in the documentation - i.e. discourage the use of .set_colors for FreeText annots.

[cli-lilly]

I tried setting the border color to black when creating the annotation in the beginning, but it ended up being the same as the text color:

annot = page.add_freetext_annot(  
    annot_rect,  
    "AETERM",  
    fontname="Arial",  
    fontsize=10,  
    text_color=text_color,
    fill_color=fill_color,   
    border_width=1,
    border_color=border_color  
) 

Other codes remain the same and it gives:

[JorjMcKie]

Please consult the documentation:

You need to add a rich text annot to achieve your goal.

[cli-lilly]

Thanks, I will try rich text annot instead

[cli-lilly]

border color can be correctly set with richtext=True. Thank you very much

[julian-smith-artifex-com]

Reopening this until we've released some improvements in this area - to the documentation, and to raise an exception if a text annotation cannot handle the desired colors.