Appearance Streams for Annotations on iOS

An annotation or form element in a PDF can specify an appearance stream, which allows the annotation to be rendered differently than its default annotation rendering. Each appearance stream is a self-contained PDF object that will be rendered inside the annotation rectangle. (See also: What Are Appearance Streams?)

Most appearance streams are just a visual representation of an annotation’s properties. This helps third-party PDF viewers that may be unable to directly generate a visual representation of those properties; these viewers can render the appearance stream instead. Appearance streams also ensure that the annotations in a document are displayed exactly as they were created in the source PDF editor, without subtle differences that could occur if the third-party PDF viewer had to recreate the annotations from raw annotation data.

However, sometimes appearance streams contain surprises. For example, square annotations may have an appearance stream with a photograph. There are a lot of edge cases out there, so one cannot disable appearance stream rendering and assume the annotation will look the same or even close to it.

ℹ️ Note: If you’re using Document Engine, please note that appearance stream rendering only works for documents uploaded after upgrading to 2020.3.0.

Changing an annotation will remove existing appearance streams and rerender them using the PSPDFKit drawing engine. Some exceptions apply, such as stamp annotations containing an image or signature form elements.

PSPDFKit allows you to define custom appearance streams on any annotation type by setting the Annotation’s appearanceStreamGenerator property.

Checking If an Annotation Includes an Appearance Stream

The hasAppearanceStream property indicates if the annotation has an appearance stream attached.

To remove an appearance stream, set the dirty property to true.

Appearance Stream Generator

We provide basic implementations of the AppearanceStreamGenerating interface:

• FileAppearanceStreamGenerator is an appearance stream generator that takes an NSURL to any PDF file and returns it as the appearance stream.

• DrawingContextAppearanceStreamGenerator generates an appearance stream from the result of calling Annotation.draw(context:options:). This is the default.

Annotation with an Appearance Stream Generator

It’s easy to set up an annotation to show a custom appearance stream. This is typically done with stamp annotations because they have few other properties. A stamp annotation used this way is usually called an image annotation. To learn more, see our guide on image annotations.

ℹ️ Note: Syncing appearance streams is currently not supported by PSPDFKit Instant.