Annotation rectangle different from the one used to set it

[jn-chrn]

Describe the bug (mandatory)

When adding an annotation to a page using page.add_circle_annot, a rectangle can be given to set its size. However, when retrieving the size of the annotation, the rectangle has a different size, namely a bit larger.

To Reproduce (mandatory)

import fitz

doc: fitz.Document = fitz.open()
doc.insert_page(0, width=50, height=50)

page: fitz.Page = list(doc.pages())[0]

rectangle = fitz.Rect(10, 10, 20, 20)
page.add_circle_annot(rect=rectangle)

(single_annot,) = page.annots()
assert single_annot.rect == rectangle  # (9.5, 9.5, 20.5, 20.5) != (10, 10, 20, 20)

Expected behavior (optional)

The rectangle that is read from the PDF should have the same size as the rectangle that is used to set the annotation.

Your configuration (mandatory)

• Operating system, potentially version and bitness

3.10.11 (main, Apr 20 2023, 19:02:41) [GCC 11.2.0]
linux

• Python version, bitness

PyMuPDF 1.21.1: Python bindings for the MuPDF 1.21.1 library.
Version date: 2022-12-13 00:00:01.
Built for Python 3.10 on linux (64-bit).

• PyMuPDF version, installation method (wheel or generated from source).
  • PyMuPDF version 1.21.1 and 1.22.3, both installed using pip (so wheel).

[JorjMcKie]

Probably no bug:
You did not provide a reproducer file. But chances are that you should first wrap the page's contents by graphics stacking commands: page.wrap_contents(), before you insert the annot.

[JorjMcKie]

Otherwise, your statement

The rectangle that is read from the PDF should have the same size as the rectangle that is used to set the annotation.

is wrong.
This

rectangle = fitz.Rect(10, 10, 20, 20)
annot=page.add_circle_annot(rect=rectangle)
print(annot.rect)

prints this: Rect(9.5, 9.5, 20.5, 20.5), which is correct, given the default line width is 1.

You can enforce things like this:

rectangle = fitz.Rect(10, 10, 20, 20)
annot = page.add_circle_annot(rect=rectangle)
annot.set_border(width=0)
annot.update()
print(annot.rect)

which prints the original rectangle.

[jn-chrn]

Sorry, I am not sure what page.wrap_contents() is supposed to fix in this context.

Also I realized I forgot some pieces of information sorry: the code I sent actually worked with PyMuPDF version 1.21.1, but does not with 1.22.3.

So the assert was not failing, and

rectangle = fitz.Rect(10, 10, 20, 20)
annot=page.add_circle_annot(rect=rectangle)
print(annot.rect)

prints Rect(10.0, 10.0, 20.0, 20.0) with version 1.21.1. Is the new behavior then expected?

Regarding your suggestion, it is a nice workaround, thanks. I am just surprised that when we draw we use the inner rectangle and when we read we get the outer one.

[JorjMcKie]

Yes, you are right: there was a change. Using this code:

print("PyMuPDF version:", fitz.version[0])
doc: fitz.Document = fitz.open()
page = doc.new_page()

rect = fitz.Rect(10, 10, 20, 20)
annot = page.add_circle_annot(rect)
print(annot.rect)
print(doc.xref_object(annot.xref))

Gives the following result in v1.21.x:

PyMuPDF version: 1.21.1
Rect(10.0, 10.0, 20.0, 20.0)
<<
  /Type /Annot
  /Subtype /Circle
  /Rect [ 10 822 20 832 ]
  /BS <<
    /W 1
  >>
  /C [ 1 0 0 ]
  /P 4 0 R
  /F 4
  /AP <<
    /N 6 0 R
  >>
  /NM (fitz-A0)
>>

But the following in v1.22.x:

PyMuPDF version: 1.22.3
Rect(9.5, 9.5, 20.5, 20.5)
<<
  /Type /Annot
  /Subtype /Circle
  /Rect [ 9.5 821.5 20.5 832.5 ]
  /BS <<
    /Type /Border
    /W 1
  >>
  /C [ 1 0 0 ]
  /P 4 0 R
  /F 4
  /RD [ .5 .5 .5 .5 ]
  /AP <<
    /N 6 0 R
  >>
  /NM (fitz-A0)
>>

This change happens in MuPDF, which now explicitely generates the /RD entry, an array of 4 numbers denoting the differences (left, top, right, bottom) of the "inner" rectangle borders from the outer one.
The 4 values .5 are computed as width / 2 as mentioned before.

[jn-chrn]

Thanks for the insights :)

when we draw [the annotation] we use the inner rectangle and when we read we get the outer one.

and these rectangles are different. Should we consider this then as expected behavior? Because this is not documented either. For me, those two should be the same. However, if the previous behavior was wrong due to the border width, then we would just adapt our code.

[JorjMcKie]

I know, this is not documented yet, unfortunately. I will take of this.
The new behaviour is correct / more complete and has been introduced with MuPDF's recent added support for cloudy annotation borders. The differentiation between inner and outer rectangle becomes especially significant here, so couldn't let be defaulted any longer.
PyMuPDF's support for cloudy annot borders will come with the next version, which will allow appearances like the following circle annotation:

In this case, the line width is not the only thing that influences the "difference rectangle" /RD, but also the presence and "intensity" of the cloud lines.

Maybe we should add a new annot property that contains that difference retangle, or rather the inner rectangle? Any opinion?

[jn-chrn]

An inner_rect property would probably be easily added, as the border width and rectangle are available. So I guess it depends on your philosophy here: for such a simple computation, do you prefer leaving it to the users, or to have it inside PyMuPDF?
For our case, it would be a nice to have for sure, but not a necessity.

[JorjMcKie]

Thanks for the feedback! Ok, we could just report the 4 /RD values, but either that or the inner rectangle are probably valueable to know.