Comparison is a feature for visually comparing pages of different documents. It is helpful for various kinds of documents: constructions plans, detailed drawings, and other content that requires precise placement.

All of this can be done with PSPDFKit using the APIs on Processor.Configuration. The process of preparing documents and comparing them involves a few steps to specify how the comparison should happen. First of all, you create a new Processor.Configuration from an existing document. Then apply the changes needed to compare documents, which are explained in the sections below. And finally, a document where all the changes and comparisons are visible will be created and saved to a specified location.

ℹ️ Note: Using these APIs will require the Comparison component to be enabled in your license.

Change the Stroke Color of Pages

One of the more helpful parts of the Comparison feature is the ability to change the stroke color of pages, making it easier to see differences on pages when you have multiple documents that mostly look the same. Setting a different stroke color for documents is usually the first step when trying to compare documents, as this will enable you to make any differences between pages more obvious.

This will only affect stroke objects in the PDF, and it will leave the color of other elements, such as text or images, unchanged.

The stroke color of a page can be changed via changeStrokeColorOnPage(at:to:):

let document: Document = // Document whose stroke color should be changed.
let configuration = Processor.Configuration(document: document)!
configuration.changeStrokeColorOnPage(at: 0, to: .orange)

let processor = Processor(configuration: configuration, securityOptions: nil)
let destinationURL: URL = // URL for the new document with the changed stroke color.
do {
    try processor.write(toFileURL: destinationURL)
} catch {
    // handle error
PSPDFDocument *document = // Document whose stroke color should be changed.
PSPDFProcessorConfiguration *configuration = [[PSPDFProcessorConfiguration alloc] initWithDocument:document];
[configuration changeStrokeColorOnPageAtIndex:0 toColor:UIColor.orangeColor];

PSPDFProcessor *processor = [[PSPDFProcessor alloc] initWithConfiguration:configuration securityOptions:nil];
NSURL *destinationURL = // URL for the new document with the changed stroke color.
[processor writeToFileURL:destinationURL error:&error];

The outcome of changing the stroke color of a PDF page to a specific color will look something like the images below.

Original Document
Orange Stroke Color

Merge Pages of Documents

The essential part of the Comparison feature is merging the pages of two (or more) documents.

Be sure to configure the document pages by changing the stroke color and setting a blend mode accordingly. This way, it’s easier to make out differences on the pages. For example, comparing one document with a green stroke color and another one with a red stroke color and using a darkening blend mode works pretty well. Additionally, all the changes can easily be seen at a glance.

Trying out various stroke colors and blend modes will result in different looking comparisons, and you can make sure the final result fits your needs.

You can use mergePage(from:password:sourcePageIndex:destinationPageIndex:transform:blendMode:) for merging. This method will merge the specified page at sourcePageIndex from the passed document and into the destinationPageIndex of the current document of Processor.Configuration. Additionally, you can specify the transform that should be applied when merging and choose how the pages should be merged via a blend mode. If the passed document is encrypted, you can also specify the password to make sure it will be unlocked:

let greenDocument: Document = // First document for comparison.
let redDocument: Document = // Second document for comparison.

let configuration = Processor.Configuration(document: greenDocument)!
configuration.mergePage(from: redDocument, password: nil, sourcePageIndex: 0, destinationPageIndex: 0, transform: .identity, blendMode: .darken)

let processor = Processor(configuration: configuration, securityOptions: nil)
let mergedDocumentURL: URL = // URL for the document with merged pages.
do {
    try processor.write(toFileURL: mergedDocumentURL)
} catch {
    // handle error
PSPDFDocument *greenDocument =  // First document for comparison.
PSPDFDocument *redDocument = // Second document for comparison.

PSPDFProcessorConfiguration *configuration = [[PSPDFProcessorConfiguration alloc] initWithDocument:greenDocument];
[configuration mergePageFromDocument:redDocument password:nil sourcePageIndex:0 destinationPageIndex:0 transform:CGAffineTransformIdentity blendMode:kCGBlendModeDarken];

PSPDFProcessor *processor = [[PSPDFProcessor alloc] initWithConfiguration:configuration securityOptions:nil];
NSURL *mergedDocumentURL = // URL for the document with merged pages.
[processor writeToFileURL:mergedDocumentURL error:&error];

This is the result of the above logic comparing two different but similar looking document pages that previously had their stroke colors changed.

Page with green stroke color
Page with red stroke color
Merged Pages

Comparison currently only allows merging single pages, and it requires both pages to have the same dimensions.


There are also a few runnable examples in our example projects that show the available Comparison API in action. These examples can be found in PSPDFKit Catalog at ComparisonExample.swift and PSCComparisonExample.m, and they provide code for Swift and Objective-C example use cases, respectively.