PSPDFKit supports rotating certain types of annotations. This guide discusses the user interface PSPDFKit provides for annotation rotation, the API that can be used to read and set rotation, and the compatibility that can be expected with other PDF readers.
When an annotation is selected, PSPDFKit shows the rotation knob for supported annotation types. At an angle of zero degrees, the rotation knob appears above the annotation. The knob rotates as the annotation is rotated.
Disabling Annotation Rotation
You can disable annotation rotation completely with the
Annotation rotation is the clockwise angle of the annotation relative to the page, in degrees. Rotation values are integers, which means the highest precision possible is 1 degree. Rotation angles should be between 0 and 359. Setting a value outside this range will result in the value being wrapped around to lie within that range.
While PDF pages can be rotated in the underlying PDF, PSPDFKit exposes a normalized (non-rotated) coordinate space for each page. This means if an annotation appears the right way up, it will have a rotation of 0, even if the content on the page may appear sideways or upside-down. See our Coordinate Space Conversions guide to learn more.
Rotatable Annotation Types
The angle of an annotation can be read using
The bounding box of an annotation is the rectangle that encloses the annotation’s contents. The edges of the bounding box are parallel to the edge of the page. If an annotation has a rotation that isn’t a multiple of 90 degrees, the bounding box will be larger than the actual size of the annotation contents.
To change an annotation’s rotation, use
setRotation(int rotation, boolean adjustBounds). You must specify whether the bounding box should be updated to preserve the apparent content size after the rotation change. If the annotation is already visible, you should pass
true to update the bounding box. In some cases, it may be useful to set the rotation without updating the bounding box — for example, if you already know the correct final bounding box when deserializing an annotation.
The PDF specification (version 2.0) does not define behavior for annotation rotation.
Rotation compatibility between PDF readers is mostly achieved using appearance streams. An appearance stream is a series of PDF drawing commands that can be attached to an annotation.
As an example, consider annotations are added to a document in a PDF reader (let’s call it A). If that document is opened in another PDF reader (B), until the annotations are edited, they will appear in B exactly the same as they appeared in A. This is achieved by rendering the appearance stream. However, if the second reader app edits an annotation, then the appearance stream usually needs to be regenerated. If the second reader app does not understand all the annotation properties used by the first app, this regenerated appearance may not match the original.
Text annotations are represented as
FreeTextAnnotations in PSPDFKit.
Apple Preview doesn’t support rotated text annotations. The appearance will be regenerated without rotation if the annotation is edited.
Adobe Acrobat has limited support for text annotation rotation. It appears to mainly support rotation in steps of 90 degrees in order to counteract page rotation. (Page rotation is not something you typically have to worry about when using PSPDFKit because of our normalized page coordinate spaces.)
Text annotations rotated to angles that are not multiples of 90 degrees should not be considered compatible with Adobe Acrobat. Acrobat is expected to show rotated text annotations correctly. However, it displays strange behavior when trying to edit such an annotation, and it doesn’t show a rotation knob to adjust the angle.
Apple Preview doesn’t allow stamps to be rotated or edited in any way. This is good for compatibility because it ensures the existing rotated appearance of any stamp will be preserved.
Stamp compatibility with Adobe Acrobat varies by stamp type.
An image annotation is a
StampAnnotation with a
Adobe Acrobat will correctly show rotated image annotations. It shows a rotation knob, and rotation works correctly. PSPDFKit is able to reopen documents with images rotated by Acrobat and continue editing the rotation.
A standard stamp is a
StampAnnotation that displays text or an image that is predefined by the PDF software. Standard stamps include those displaying text such as Approved and Confidential, as well as those showing a green checkmark or red cross image.
Adobe Acrobat has good support for rotating standard stamps.
While the exact appearance generated for these stamps differs slightly between PSPDFKit and Adobe Acrobat, both sides understand the standard types, so if a stamp created with one of these is edited by the other, the appearance will change slightly, but the text, color, and rotation will be preserved. The size may be altered when applying rotation with Acrobat, but the user is able to adjust the size again to restore the original size.
Custom Text Stamps and Vector Image Annotations
PSPDFKit can create custom text stamps by setting the
subtitle of a
StampAnnotation. These properties are not part of the PDF specification. As such, other PDF readers have no capability to regenerate the appearance of such an annotation if one is edited.
A vector image annotation, also known as a vector stamp, is purely a container for an appearance stream. You create a vector image annotation by creating a
StampAnnotation with no stamp type or title and then setting its
appearanceStreamGenerator. If the appearance stream of a vector image was regenerated, there would be nothing left except an empty box. If PSPDFKit detects an annotation is a vector image and that annotation is resized or rotated, PSPDFKit will preserve the appearance stream by applying a transform to the annotation.
Since the title and subtitle properties are “off spec,” as far as Adobe Acrobat is concerned, there’s no difference between a custom text stamp and a vector image annotation.
Adobe Acrobat will correctly show and resize these annotations that were created and rotated by PSPDFKit. Acrobat will show a rotation knob, but if that knob is used to adjust the angle, then Acrobat will discard the original appearance and replace it with a black cross in a white box.
Instant JSON and XFDF
Instant JSON and XFDF do not store appearance streams. As such, storing annotations with rotation is generally not recommended when using these data formats, although the rotated appearance will be correctly replicated if the document is always opened by PSPDFKit.