Comparison

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

All of this can be done with PSPDFKit using the APIs on PdfProcessorTask. 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 PdfProcessorTask 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 any 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 Comparison 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 the 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():

Copy
1
2
3
4
5
6
val pageIndex = 0
val orange = 0xffa500
val task = PdfProcessorTask.fromDocument(document)
task.changeStrokeColorOnPage(pageIndex, orange) 

PdfProcessor.processDocument(task, outputFile)
Copy
1
2
3
4
5
6
int pageIndex = 0;
int orange = 0xffa500;
PdfProcessorTask task = PdfProcessorTask.fromDocument(document);
task.changeStrokeColorOnPage(pageIndex, orange);

PdfProcessor.processDocument(task, outputFile);

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 Comparison 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(PagePdf, int, BlendMode) for merging. This method will merge the given page object onto the specified destination page of the currently processed document. Additionally, you can specify a transformation that should be applied before merging and choose the desired blend mode that should be used:

Copy
1
2
3
4
5
6
7
8
9
10
// First document for comparison with strokes colored to green.
val greenDocument: PdfDocument = ...
// Second document for comparison with strokes colored to red.
val redDocument: PdfDocument = ...

val destinationPageIndex = 0
val task = PdfProcessorTask.fromDocument(greenDocument)
task.mergePage(PagePdf(context, redDocument), destinationPageIndex, BlendMode.DARKEN)

PdfProcessor.processDocument(task, outputFile)
Copy
1
2
3
4
5
6
7
8
9
10
// First document for comparison with green strokes.
PdfDocument greenDocument = ...;
// Second document for comparison with red strokes.
PdfDocument redDocument = ...;

int destinationPageIndex = 0;
PdfProcessorTask task = PdfProcessorTask.fromDocument(greenDocument);
task.mergePage(new PagePdf(context, redDocument), destinationPageIndex, BlendMode.DARKEN);

PdfProcessor.processDocument(task, outputFile);

This is the result of the above logic comparing two different but similar looking document pages that had their stroke colors previously 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.

Examples

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 DocumentComparisonExample.kt in the Catalog app.