How to enable rotation of annotations

[bjhowie]

I have a loop that iterates through each annotation on a page and calls a function which modifies both the object dictionary and appearance stream, as per the below example.

for annot in page.annots():
    if annot.type[0]==4:
        annot.update()
        rotate_rect_annot(annot,angle)

The result is that the code gets stuck in an infinite loop, looping over the same annotations over and over. Modifying the object or appearance stream obviously messes with the page.annots() generator. Is there a way to avoid this?

Another thing that is unexpected is that unless i call annot.update() before calling my function, i get a MuPDF error when attempting to update the appearance stream "xref not a stream object".

I'm using v1.16.18

[JorjMcKie]

what does function rotate_rect_annot do? Can you give me the code?
The annots() generator iterator is very simple and uses annot.next until it gets None. So I have to assume for the moment that something in your function is interfering with this ...
I also am puzzled how something can destroy the appearance object of the annot: it is a different xref than that of the annot itself.
Also the appearnace stream for rectangles (type 4) is one of the most simple ones and basically consists of one line x0 y0 x1 y1 re.

[bjhowie]

Jorj,

Function definition below:

def rotate_rect_annot(annot,ang):
    """
    Rotates the annotation by the specified angle.
    'update' should be called on the annotation before rotation, but not after

    Parameters
    ----------
    annot : fitz.annot
        The annotation to be rotated
    ang : int/float
        The angle the annotation is to be roatetd by in degrees

    Returns
    -------
    None.

    """
    page=annot.parent
    doc=page.parent
    page_tf=page._getTransformation()
    
    arect=annot.rect
    lw=annot.border["width"]
    lc=annot.colors["stroke"]
    fill=annot.colors["fill"]
    B,D=arect.width,arect.height

    m=fitz.Matrix(ang)
    m.invert()

    BBox=fitz.Rect(arect.x0-0.5*lw,arect.y0-0.5*lw,arect.x1+0.5*lw,arect.y1+0.5*lw)
    BBox.transform(page_tf)
    
    #Edit annot rect
    b=sp.box(arect.x0,arect.y0,arect.x1,arect.y1)
    b=spa.rotate(b,ang)
    overall_bounding_rect=fitz.Rect(b.bounds)
    annot.setRect(overall_bounding_rect)
    
    #Edit PDF Info
    obdict=get_xref_dictionary(doc,annot.xref)
    obdict["/Rotation"]=int(ang)
    AP_xref=obdict["/AP"]["/N"].idnum # Get Appearance stream xref

    apdict=get_xref_dictionary(doc,AP_xref)
    apdict["/Matrix"]=[m.a,m.b,m.c,m.d,m.e,m.f]   
    apdict["/BBox"]=[BBox.x0,BBox.y0,BBox.x1,BBox.y1]

    newob=dict_to_PDFdict(obdict)
    #Update appearance dict
    doc.updateObject(annot.xref, newob,page)

    newap=dict_to_PDFdict(apdict)
    doc.updateObject(AP_xref, newap,page)

    #Create appearance stream and update
    aps=appearance_stream()
    aps.set_line_width(lw)
    aps.set_line_colour(lc)
    aps.set_fill_colour(fill)
    aps.draw_rectangle(BBox.x0,BBox.y0,B,D) 

    doc._updateStream(AP_xref, aps.to_bytes(), new=False)

The function get_xref_dictionary calls doc._getXrefString(xref) then parses the returned dictionary into a python dictionary. dict_to_PDFdict converts back to a PDF dictionary.

[JorjMcKie]

Easy thing first:

Another thing that is unexpected is that unless i call annot.update() before calling my function, i get a MuPDF error when attempting to update the appearance stream "xref not a stream object".

Even if you keep the same xref for AP/N there in fact will be allocated a new object, but with the same xref number. So you need to specify new=True in updateStream. This also should be the cause for the unexpected reaction WRT to the sequence of update and rectangle modification.

Well, that function is definitely quite complex! What you are in fact doing is replacing the annot definition (including its /AP) by new, same-numbered objects.
The next method of annots is provided by MuPDF, which is based on an internal array of all annotations. MuPDF creates when the page is loaded! This should be the reason, why you get an infinite loop: MuPDF does not know about what you did.
Hence I think you cannot use the annots() iterator in your case, nor the next method.

Question is what you could do instead.
I saw you are already using the page parameter of updateObject which obviosly has not the desried effect (refreshing that internal annots array). There also exists Page.refresh() which calls the same function.
Another option would be to reload the page each time after such update. Which would require you to reposition yourself behind the last updated annotation. Could be achieved by checking its xref, skipping everything already done.
Reloading a page goes like this: page = doc.reload_page(page). It destroys the page, then loads it again.
I created it to make sure annotation updates are reflected in the page's pixmap. Was required because of my feature extensions in that area (freetext and others), which bypass / replace the corresponding MuPDF code.

[bjhowie]

Thanks, that all makes sense. I'll try putting the reload_page call after the last updated annotation to prevent the annotation array from being updated mid-way through.

Yes, i've gone down a bit of a rabbit hole i never intended to in creating that function. I'm trying to replicate the annotation rotation functionality of the commercial PDF writer that we use (Bluebeam Revu) so that i can save data back to the source PDF after processing it.

Thanks for the help! I'll let you know how it goes.

[JorjMcKie]

I should have mentioned one more thing:
The update() method among other things invokes MuPDF's update function. This guy rebuilds the appearance stream. Which of course destroys anything you had ben doing with it.
There is a set of annot modifications, for which no update() is needed - among them changes to the rectangle.
You are building a set of new onjects and streams yourself: (1) annot object, (2) /AP/N object and its stream.
So you should not need annot.update() at all.
You are, however, on yourself when it comes to other changes: colors, opacity, dashing, blendmode, line end symbols, ... They are all reflected in the AP/N stream (as well). So you either rebuild all that too, or loose it.
Extended annot features in PyMuPDF exist for a handfull of annot types. They work becasue I first invoke MuPDF annot update and then apply my changes on the outcome.
In the long run, I probably will take your idea and make it an enhancement.

Could you please share a before / after status of your annotation rotation? I hope I can extract the necessary logic from it. The /Rotate PDF key is undocumented in the PDF specs. MuPDF does support it for one annot type: FreeText, but only for angles 0, 90, 270.

For a general support of this, there must be a way to not changing the /AP/N stream, but instead work with a rotation matrix in the object definition of /AP/N.

[bjhowie]

So moving the page refresh to the end of the annotation updates resolved the infinite loop problem, unfortunately it turns out my rotation function isn't working as well as it had been in my initial tests. Annotation appearance is a bit off. I'll have to keep playing around with it and let you know. There's an algorithm given in the PDF guide (CL 12.5.5) but it doesn't make a whole lot of sense to me. From what i can understand, I agree that there should be a particular transformation matrix that avoids the need to alter the appearance stream directly. I might take a step back and look into this in more detail.

I was aware that the annot.update() function overwrites the appearance stream so was using the rotate_rect_annot function as a replacement for the annot.update() function, for rectangles with a non-zero rotation. For my purposes, i don't really need dashing, blendmode etc. but looking over the PDF guide it seems they would be relatively easy to implement (at least for my specific use case) in the appearance_stream class i made. It would certainly be a lot of work to generalise this to all annotation types though.

I haven't found a lot of PDF readers that support annotation rotations, and i'm sure the ones that do, implement it in an inconsistent, incompatible way. But Bluebeam Revu has become pretty much become the industry standard in building/construction now (at least in my country) so I am adopting the approach they have used.

[bjhowie]

So I think i've figured it out. By shifting the appearance stream bounding box back to (0,0), then rotating it, then shifting it to the location of the annotation rectangle I don't need to modify BBox or the appearance stream itself.

    rect_cent=((rect.x1-rect.x0)/2, (rect.y1-rect.y0)/2)
    bbox_cent=((BBox[2]-BBox[0])/2, (BBox[3]-BBox[1])/2)
    
    m=fitz.Matrix(1, 0, 0, 1, -bbox_cent[0], -bbox_cent[1]) #Move to 0,0
    m.concat(m,fitz.Matrix(-ang)) #Rotate
    m.concat(m,fitz.Matrix(1, 0, 0, 1, rect_cent[0], rect_cent[1])) #Move to centre of Rect
    
    apdict["/Matrix"]=[m.a,m.b,m.c,m.d,m.e,m.f]

Annoyingly, when i update the appearance stream object the appearance stream seems to get deleted. Any idea why this might be the case? I've got around it for now by caching the stream before updating the object, then forcing it back in afterwards.

    #Update appearance dict
    newap=dict_to_PDFdict(apdict) #convert python dict to PDF dict
    apstream=doc._getXrefStream(AP_xref) #cache stream
    doc.updateObject(AP_xref, newap,ud_page) #Update appearance object
    doc._updateStream(AP_xref, apstream, new=True) #Force stream back in

[JorjMcKie]

I have described the reason here:

The update() method among other things invokes MuPDF's update function. This guy rebuilds the appearance stream. Which of course destroys anything you had ben doing with it.
There is a set of annot modifications, for which no update() is needed - among them changes to the rectangle.

In update(), the invoked MuPDF function simply recreates an annotation appearance according to its capabilities. Which means, you must not invoke it after you have done your stuff.
My extensions therefore do exactly this: invoke MuPDF, then apply added functionality to its outcome.

It seems your approach results in a modification of the annot.rect, right? I am trying to develop an algorithm which preserves the annot rectangle - which may be unnecessary, or what do you think?

[JorjMcKie]

If I can drop the restriction that the resulting rotated annotation must not exceed the original rectangle borders, then my algorithm already delivers this:

The black border is the original rect.
This is achieved by the same steps you did.
Technically

1. the /Matrix of the /AP/N is replaced by the rotation matrix
2. the annot.rect is replaced by the rectangle of quad annot.rect.quad rotated around its center point.

If you think we could go with this, then I am done and would include the new functionality in the next version.

[JorjMcKie]

Another question I have:

How do you service the crazy guy who comes along and wants to undo (or in general change) a rotation? Would you be able to do that?

[bjhowie]

So to be clear, doc.updateObject also recreates the appearance of the annotation?

The annot.rect will certainly need to get bigger as part of any rotation operation. The operations you've outlined are correct. The final translation operation i was doing to move the transformed BBox to the location of annot.rect was unnecessary. I've copied my final rotate_rect_annot function below. It seems to be working in all the tests i've run on it.

def rotate_rect_annot(annot,ang,refresh_page=False):
    """
    Rotates the annotation by the specified angle.
    'update' should not be called on the annotation after calling this function

    Parameters
    ----------
    annot : fitz.annot
        The annotation to be rotated
    ang : int/float
        The angle the annotation is to be roatetd by in degrees
    refresh_page: Bool
        Whether the page should be refreshed after the annotation and apppearance objects are updated

    Returns
    -------
    None.

    """
    page=annot.parent
    doc=page.parent
    ud_page=page if refresh_page else None
    
    arect=annot.rect

    #Edit annot rect
    b=sp.box(arect.x0,arect.y0,arect.x1,arect.y1)
    b=spa.rotate(b,ang)
    overall_bounding_rect=fitz.Rect(b.bounds)
    annot.setRect(overall_bounding_rect)
    
    #Edit PDF Info
    obdict=get_xref_dictionary(doc,annot.xref)
    obdict["/Rotation"]=int(ang)
    AP_xref=obdict["/AP"]["/N"].idnum # Get Appearance stream xref

    apdict=get_xref_dictionary(doc,AP_xref)   
    BBox=apdict["/BBox"]

    bbox_cent=((BBox[2]-BBox[0])/2,(BBox[3]-BBox[1])/2)
    
    m=fitz.Matrix(1, 0, 0, 1, -bbox_cent[0], -bbox_cent[1]) #Move to 0,0
    m.concat(m,fitz.Matrix(-ang)) #Rotate
    apdict["/Matrix"]=[m.a,m.b,m.c,m.d,m.e,m.f]
    
    #Update annotation object
    newob=dict_to_PDFdict(obdict)
    doc.updateObject(annot.xref, newob, ud_page)
    
    #Update appearance object
    newap=dict_to_PDFdict(apdict)
    apstream=doc._getXrefStream(AP_xref) #Cache appearance stream as the next operation deletes it
    doc.updateObject(AP_xref, newap,ud_page)
    doc._updateStream(AP_xref, apstream, new=True)

Rotations passed to fitz.Matrix seem to be anti-clockwise, whereas Revu uses clockwise rotations, hence either the angle passed to the matrix or the angle in the /Rotation dictionary entry need to be negative. I presume your intent is only to implement the matrix rotation, as /Rotation is reader-specific? It could be good to have a PyMuPDF function to add/edit custom dictionary entries for reader-specific functionality. I notice Revu seems to also use custom dictionary entries for annotation opacity.

I had considered how to go about rotating an already rotated annotation. Perhaps you could use the appearance BBox to get the un-rotated rectangle geometry (though it may need adjusting for stroke width), then reposition it to the current annot.rect location before proceeding with the rotation operation. I don't think there anything stopping BBox from being much larger than the drawn graphics so this wouldn't be foolproof, but should work 99% of the time. Otherwise i think you'd need to read the 're' operation from the appearance stream directly.

In terms of being able to read the rotation of an existing annotation, you should be able to back-calculate the rotation angle from the appearance matrix and expose it with annot.rotation or something similar, otherwise you could just expose the appearance /Matrix directly.

[JorjMcKie]

So to be clear, doc.updateObject also recreates the appearance of the annotation?

No, that was a misunderstanding. only the anoot.update() method does that.

fitz.Matrix seem to be anti-clockwise

Yes, by design so in MuPDF.

move the transformed BBox to the location of annot.rect was unnecessary

I agree and let me add: also dangerous:
There is more than one way to set up an annot appearance. The appearance BBox might be specified with "absolute" / "abstract" coordinates and the appearance matrix overtakes all the mapping.
So in case of a 'Square' annotation you may have BBox[0 0 1 1], 0 0 1 1 re, while /Matrix[a 0 0 d e f] controls scaling in x and y direction via a and d, and e/f take care of translation.
MuPDF (currently) chooses an approach to let BBox equal annot.rect for /Square, /Circle and some others (not all types!). The matrix in MuPDF is always the identity, the only exception being 'FreeText', where text rotation is reflected in it. In the latter case, we always have BBox[0 0 w h], where width and height equal either the rect original's, or are reversed in cases 90°, 270°.

In terms of being able to read the rotation of an existing annotation, you should be able to back-calculate the rotation angle from the appearance matrix and expose it with annot.rotation or something similar, otherwise you could just expose the appearance /Matrix directly.

Agreed, there will be new attributes and methods to deal with the AP/N:

• attributes for BBox and Matrix
• methods to set both values - actually relevant only is setting the matrix.

So overall I envision this:

• Annot.rotation is the value of /Rotate in the annot object
• Annot.setRotation and Annot.update(..., rotate=n) modify this value - for a subset of annot types only (no text markers for example)
• Annot.apn_bbox / Annot.apn_matrix are BBox, rresp. Matrix in the AP/N (nomenclature still under consideration 🤔 - maybe apnMatrix and setAPNMatrix?).
• Annot.set_apn_bbox(), Annot.set_apn_matrix() modify the values.

As pointed out, there is no generally reliable way to back-calculate the original annot.rect. So I must leave recovery of the original rectangle to the user and his knowledge of the special situation ...

[JorjMcKie]

Implemented by v1.17.1 which is currently being uploaded to PyPI.