Rotate PDF Annotations Using JavaScript

PSPDFKit supports rotating certain types of annotations. This guide discusses the user interface (UI) 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.

User Interface

When an annotation is selected, PSPDFKit shows the rotation knob for supported annotation types. At an angle of zero degrees, the rotation knob appears below the annotation. The knob rotates as the annotation is rotated.

To rotate an annotation in the UI, drag the rotation handle and rotate the annotation.

Annotation rotation handle

Rotating Annotations Programmatically

This section explains how to rotate annotations programmatically.

Conventions

Annotation rotation is the counterclockwise 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 an 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 Conversion guide to learn more.

Rotatable Annotation Types

You can freely rotate the following annotation types:

  • Text

  • Stamp

You can rotate image and widget annotations in 90-degree steps.

Getting Rotation

The angle of an annotation can be read by calling the get("rotation") method on the annotation.

Setting Rotation

To change an annotation’s rotation, use the PSPDFKit.Annotations.rotate method. This method takes two parameters:

  1. The annotation object that you want to rotate.

  2. The angle by which you want to rotate the annotation. This is an integer value.

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. The PSPDFKit.Annotations.rotate method automatically updates the bounding box.

Compatibility

The PDF specification (version 2.0) doesn’t 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 (A). If that document is opened in another PDF reader (B), until the annotations are edited, they’ll 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 doesn’t understand all the annotation properties used by the first app, this regenerated appearance may not match the original.

Text Annotations

Adobe Acrobat has limited support for text annotation rotation. It appears to mainly support rotation in steps of 90 degrees to counteract page rotation. Page rotation isn’t something you typically have to worry about when using PSPDFKit because of our normalized page coordinate spaces.

Text annotations rotated to angles that aren’t multiples of 90 degrees shouldn’t 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.

Image Annotations

When you rotate an image annotation in Adobe Acrobat that you previously rotated in PSPDFKit, the image inside the annotation is rendered incorrectly, as a black X. Opening the same document later in PSPDFKit shows the same black X instead of the image.

Standard Stamps

A standard stamp is a StampAnnotation that displays text or an image that’s 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

PSPDFKit can create custom text stamps by setting the title and subtitle of a StampAnnotation. These properties aren’t part of the PDF specification. As such, other PDF readers have no ability to regenerate the appearance of such an annotation if one is edited.

Adobe Acrobat will correctly show and resize custom text stamp 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 doesn’t store appearance streams at all, while XFDF does store appearance streams for stamp and image annotations but not for text annotations. 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.