Custom Image Stamp Annotations on iOS

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 bitmap image annotation:

// Create `Document`.
let document = Document(url: documentURL)

// Create a new annotation.
let imageAnnotation = StampAnnotation()

// Set the image. PSPDFKit will store this as an appearance stream behind the scenes.
imageAnnotation.image = UIImage(named: "PSPDFKit Logo.jpg")

// Set the bounding box.
imageAnnotation.boundingBox = CGRect(x: 180, y: 150, width: 444, height: 500)

// Add the newly created annotation to the document.
document.add(annotations: [imageAnnotation])

// Create `PSPDFDocument`.
PSPDFDocument *document = [[PSPDFDocument alloc] initWithURL:documentURL];

// Create a new annotation.
PSPDFStampAnnotation *imageAnnotation = [[PSPDFStampAnnotation alloc] init];

// Set the image. PSPDFKit will store this as an appearance stream behind the scenes.
imageAnnotation.image = [UIImage imageNamed: @"PSPDFKit Logo.jpg"];

// Set the bounding box.
imageAnnotation.boundingBox = { .origin.x = 180.f, .origin.y = 150.f, .size.height = 444.f, .size.width = 500.f };

// Add the newly created annotation to the document.
[document addAnnotations:@[imageAnnotation] options:nil];

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

// Create `Document`.
let document = Document(url: documentURL)

// Create the URL of the appearance stream that uses a PDF file.
let samplesURL = Bundle.main.resourceURL?.appendingPathComponent("Samples")
let logoURL = samplesURL!.appendingPathComponent("PSPDFKit Logo.pdf")

// Create a new stamp annotation using the appearance stream generator.
let vectorImageAnnotation = StampAnnotation()

// Set the appearance stream.
vectorImageAnnotation.appearanceStreamGenerator = FileAppearanceStreamGenerator(fileURL: logoURL)

// Set the bounding box.
vectorImageAnnotation.boundingBox = CGRect(x: 180, y: 150, width: 444, height: 500)

// Add the newly created annotation to the document.
document.add(annotations: [vectorImageAnnotation])

// Create `PSPDFDocument`.
PSPDFDocument *document = [[PSPDFDocument alloc] initWithURL:documentURL];

// Create the URL of the appearance stream that uses a PDF file.
NSURL *samplesURL = [NSBundle.mainBundle.resourceURL URLByAppendingPathComponent:@"Samples"];
NSURL *logoURL = [samplesURL URLByAppendingPathComponent:@"PSPDFKit Logo.pdf"];

// Create a new stamp annotation using the appearance stream generator.
PSPDFStampAnnotation *vectorImageAnnotation = [[PSPDFStampAnnotation alloc] init];

// Set the appearance stream.
vectorImageAnnotation.appearanceStreamGenerator = [[PSPDFFileAppearanceStreamGenerator alloc] initWithFileURL:logoURL];

// Set the bounding box.
vectorImageAnnotation.boundingBox = CGRectMake(180.f, 150.f, 444.f, 500.f);

// Add the newly created annotation to the document.
[document addAnnotations:@[vectorImageAnnotation] options:nil];

Take a look at AddVectorStampAnnotationProgrammaticallyExample inside the Catalog app, as it shows how to create vector image annotations programmatically.

You can also refer to the Default Stamp Annotations section of the Stamp Annotations Configuration 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.