Annotation Appearance Streams

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 bounding box. (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.

Starting with PSPDFKit for Web 2020.6.0, you can enable support for rendering existing appearance streams by setting PSPDFKit.Configuration#isAPStreamRendered in the configuration object passed to PSPDFKit.load():

PSPDFKit.load({
  isAPStreamRendered: annotation => {
    // Render rectangle annotations using their AP streams.
    if (annotation instanceof PSPDFKit.Annotations.RectangleAnnotation) {
      return true;
    }
    // The rest of the annotations will be rendered using their default, native appearance.
    return false;
  }
  // ...
});

When this callback is set, it’ll be used for each annotation about to be rendered. If the callback returns true, the annotation will be rendered using its appearance stream from the document instead of its default, native appearance, which is rendered when this callback isn’t set or returns false. When an annotation’s appearance has been customized (like in the square annotation with a photograph example above), this setting allows for a visual result closer to the original.

Only annotations that were present in the document when it was opened may be rendered using their AP streams, and this callback won’t be used for other annotations. If any visual property of an annotation is modified, its appearance stream will be considered invalidated, meaning it no longer reflects the annotation’s properties and therefore won’t be used — the callback won’t be used again for this annotation in this session.

Image and stamp annotations, as well as digitally signed signature form field widgets, will always be rendered using their AP streams, and this callback won’t be used for those annotations either.

Keep in mind that enabling this feature may affect performance, as each annotation appearance needs to be rendered separately. Moreover, the original appearance will still be hidden while the annotation is being resized, modified, or edited, and it may be removed completely if the annotation is modified.

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

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