---
title: "Compare documents on iOS and highlight changes | Nutrient SDK"
canonical_url: "https://www.nutrient.io/guides/ios/compare-documents/"
md_url: "https://www.nutrient.io/guides/ios/compare-documents.md"
last_updated: "2026-05-15T19:10:05.020Z"
description: "Document Comparison is used to visually compare pages of different documents. It’s helpful for things such as construction plans and detailed drawings."
---

# Compare documents on iOS

Document Comparison is used to visually compare pages of different documents. It’s helpful for things such as construction plans and detailed drawings, as well as other content that requires precise placement.

This can be done in Nutrient using [`ComparisonProcessor`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonprocessor). The process of preparing documents and comparing them involves a few steps to specify how the comparison should happen.

The APIs described in this guide require the Document Comparison component to be enabled in your license.

## Changing the stroke colors

One of the most important steps of generating a comparison document is the ability to change the stroke colors, which makes it easier to see the differences between two versions of a document.

Setting a different stroke color 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.

First, create a new [`ComparisonConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration) object that allows you to customize certain aspects of the generated comparison document, described below.

The stroke colors of both versions of a document can be changed using the [`oldDocumentStrokeColor`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration/olddocumentstrokecolor) and [`newDocumentStrokeColor`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration/newdocumentstrokecolor) properties:

```swift

let configuration = ComparisonConfiguration {
    $0.oldDocumentStrokeColor =.systemOrange
    $0.newDocumentStrokeColor =.systemGreen
}

```

The table below shows how applying an orange stroke color changes the appearance of a document.

| Original document                                                                                                                                                                    | Stroked document                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |

You can also change the blend mode used to overlay the new version of a document on top of the old one by changing the [`blendMode`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration/blendmode) property.

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

## Changing the working directory

By default, the [`ComparisonProcessor`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonprocessor) will generate a comparison document in the system temporary directory. To customize this behavior, change the [`workingDirectory`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration/workingdirectory) URL of [`ComparisonConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration).

## Generating the comparison document

You can use [`ComparisonProcessor`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonprocessor) to generate a comparison document. First, initialize it with a [`ComparisonConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration), and then call the [`comparisonDocument(...)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonprocessor/comparisondocument(olddocument:pageindex:newdocument:pageindex:transform:)) function, passing the two versions of a document to be compared as arguments:

```swift

let oldDocument: Document = /* the old version of a document */
let newDocument: Document = /* the new version of a document */

let configuration = ComparisonConfiguration.default()
let processor = ComparisonProcessor(configuration: configuration)

let comparisonDocument = try processor.comparisonDocument(
    oldDocument: oldDocument,
    newDocument: oldDocument
)

```

By default, the processor will generate a comparison document using the first page of both versions of the document. If the page you want to compare has moved, or if it’s not the first page, you can specify explicit indices using extra `pageIndex` arguments:

```swift

let comparisonDocument = try processor.comparisonDocument(
    oldDocument: oldDocument,
    pageIndex: 2,
    newDocument: oldDocument,
    pageIndex: 3
)

```

If either of the passed documents is password protected, make sure to unlock it before passing it into the processor.

It’s only possible to compare one page at a time.

The below table shows how a comparison document generated from two different but similar-looking documents that previously had their stroke colors changed would look.

| Old document                                                                                                                                                                                 | New document                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |

| Comparison document                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |

## Aligning the documents

If the two versions of the document you want to compare aren’t perfectly aligned with each other, Nutrient provides a way for users to visually select two corresponding sets of landmark points in both versions of the document, and it automatically calculates a transformation matrix based on that.

To initiate the document alignment process, create a [`DocumentAlignmentViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/documentalignmentviewcontroller) with the two versions of a document and a [`ComparisonConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkit/comparisonconfiguration):

```swift

let oldDocument: Document = /* The old version of a document. */
let newDocument: Document = /* The new version of a document. */

let viewController = DocumentAlignmentViewController(
    oldDocument: oldDocument,
    newDocument: newDocument,
    configuration:.default()
)

```

You can wrap the document alignment view controller in a `UINavigationController` and customize its navigation bar button items. The document alignment process begins in the old version of the document, and then it automatically moves on to the new version once the user selects all three points in the old one.

**It’s crucial to select the same three landmark points, in the same order.** The points should be chosen such that they don’t move, relative to each other. Selecting a point that changes position will result in corrupted comparison documents. The below table shows the recommended landmark points.

| Points in the old document                                                                                                                                                                          | Points in the new document                                                                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |

Once all six points are selected, the document alignment view controller will automatically calculate a transformation matrix, try to generate a comparison document, and call one of its [delegate methods](https://www.nutrient.io/api/ios/documentation/pspdfkitui/documentalignmentviewcontrollerdelegate), depending on whether or not the generation succeeded:

```swift

func documentAlignmentViewController(_ sender: DocumentAlignmentViewController, didFinishWithComparisonDocument document: Document) {
    /* Display the comparison document. */
}

func documentAlignmentViewController(_ sender: DocumentAlignmentViewController, didFailWithError error: Error) {
    /* Show the error. */
}

```

As an alternative to implementing the delegate methods, you can subscribe to the [`comparisonDocument`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/documentalignmentviewcontroller/comparisondocument) future. The document alignment view controller will both call its delegate methods and send either a document or an error to the future.

The image below shows a comparison document aligned based on the two sets of three landmark points shown above.

## Example

Check out [`ComparisonExample.swift`](https://github.com/PSPDFKit/pspdfkit-ios-catalog/blob/master/Catalog/Examples/Components/ComparisonExample.swift) in our [Nutrient Catalog](https://www.nutrient.io/guides/ios/getting-started/example-projects.md#nutrient-catalog) example project to see the document comparison and alignment APIs in action.
---

## Related pages

- [Best practices](/guides/ios/best-practice.md)
- [Mac Catalyst PDF library](/guides/ios/catalyst.md)
- [iOS PDF bookmark SDK](/guides/ios/bookmarks.md)
- [Cordova PDF library](/guides/ios/cordova.md)
- [Contributing to Nutrient projects](/guides/ios/miscellaneous/contributing.md)
- [Discover innovative PDF SDK demos for multiple platforms](/guides/ios/demo.md)
- [Download our iOS library](/guides/ios/downloads.md)
- [iOS PDF library](/guides/ios.md)
- [iOS guides: Integrate our PDF library](/guides/ios/intro.md)
- [Ionic PDF library](/guides/ios/ionic.md)
- [visionOS buides: Integrate our PDF library](/guides/ios/intro-visionos.md)
- [iPad PDF Library](/guides/ios/ipad.md)
- [iPhone PDF library](/guides/ios/iphone.md)
- [Knowledge base](/guides/ios/kb.md)
- [Swift PDF library](/guides/ios/swift.md)
- [Troubleshooting](/guides/ios/troubleshoot.md)
- [Upgrade and migration guides](/guides/ios/upgrade.md)
- [Xamarin.iOS PDF library](/guides/ios/xamarin.md)
- [visionOS PDF library](/guides/ios/visionos.md)
- [Changelog for iOS](/guides/ios/changelog.md)