Image Annotations (Custom Stamps)

Image annotations allow you to add images to PDF pages. By default, users can move, resize, and delete these images. If you need to add annotations like drawings and arrows onto a JPEG or PNG image, see our guide on image documents.

An image annotation is an annotation that simply displays an appearance stream and has no specific properties. Appearance streams can contain bitmap images or complex vector drawing data. PSPDFKit supports both. Unlike bitmap image annotations, vector image annotations allow transparency and high-resolution zooming. For more on this topic, please refer to our Use Vector Stamps Instead of Blurry Shapes and What Are Appearance Streams? blog posts.

Image annotations are represented using the StampAnnotation class. An image annotation can be thought of as a custom stamp. Properties of the stamp — like the title and the stamp type — are specific to standard stamps and custom text stamps and should not be used with image annotations.

Here’s how to programmatically add a vector image annotation, which may also be referred to as a vector stamp:

// Create a stamp annotation. You'll need to specify the annotation's page, bounding box in PDF coordinates, and custom subject.
val imageAnnotation = StampAnnotation(pageIndex, RectF(300f, 500f, 500f, 300f), "Stamp with custom AP stream")

// Create an appearance stream generator from a PDF containing a vector logo stored in assets.
imageAnnotation.appearanceStreamGenerator = AssetAppearanceStreamGenerator("PSPDFKit Logo.pdf")

// Add the newly created annotation to the document.
document.getAnnotationProvider().addAnnotationToPage(imageAnnotation)
// Create a stamp annotation. You'll need to specify the annotation's page, bounding box in PDF coordinates, and custom subject.
StampAnnotation imageAnnotation = new StampAnnotation(pageIndex, new RectF(300f, 500f, 500f, 300f), "Stamp with custom AP stream");

// Create an appearance stream generator from a PDF containing a vector logo stored in assets.
imageAnnotation.setAppearanceStreamGenerator(new AssetAppearanceStreamGenerator("PSPDFKit Logo.pdf"));

// Add the newly created annotation to the document.
document.getAnnotationProvider().addAnnotationToPage(imageAnnotation);

For a complete example, take a look at AnnotationCreationActivity inside the Catalog app, which shows how to create vector image annotations programmatically using an appearance stream generator.

You can also refer to our Default Stamp Annotations guide, which illustrates how to customize the default stamp annotations available in the stamp picker dialog.

ℹ️ Note: Make sure the bounding box of the vector stamp annotations you create matches the aspect ratio of the source document exactly. Otherwise, you might encounter some distortion when rotating vector stamps that have mismatched bounding boxes.