Annotate Images (Image Documents)

Image Documents

While it has always been possible to annotate images in PSPDFKit, doing so previously required some extra code. You had to convert the image to PDF, be sure to update the annotation tools and UI to show only relevant options, and extract the image data back when a save occurred.

In PSPDFKit 7.3 for iOS, we introduced a new class, PSPDFImageDocument, to make this process much simpler. All you need to do is pass your image to PSPDFImageDocument and we handle the rest. We even simplified the PDF controller configuration by providing a pre-built configuration that adjusts the UI so that it works great for images. And to make editing these images more powerful, we introduced a system in [PSPDFKit 7.6 for iOS]((/blog/2018/pspdfkit-ios-7-6/) where the changes made to an image document by PSPDFViewController (or by directly using the document object) remain editable even after saving. Take a look at AnnotateImagesExample in the Catalog app or read our announcement blog post to learn how you can annotate PNG and JPG just like PDF with Image Documents.

ℹ️ Note: This feature requires the Image Documents component to be enabled in your license.

PSPDFImageDocument is a subclass of PSPDFDocument that can be initialized with an image file. Although it has capabilities similar to its parent class, you should keep the following conditions in mind.

Image Formats and Size

You can initialize a PSPDFImageDocument using a local image file URL. PSPDFImageDocument supports the JPEG and PNG file formats. The compression quality when encoding to JPEG can be controlled using PSPDFImageDocument.compressionQuality.

We also enforce a maximum size of image that can be opened by PSPDFImageDocument. If an image’s area is larger than the area defined by PSPDFRenderSizeLimit, the image is not opened, as converting it to a bitmap would consume too much RAM.

Annotation Types

Although you can technically use any annotation type with PSPDFImageDocument, we recommend disabling certain annotation tools when working with image documents. For example, text selection- or text extraction-based annotations, such as highlight and underline annotations, do not make sense for a PSPDFImageDocument because there will be no selectable text in the document.

We recommend initializing your PSPDFViewController with the PSPDFConfiguration.imageConfiguration preset. This will automatically disable annotation types that are not relevant for image files:

1
let controller = PSPDFViewController(document: imageDocument, configuration: PSPDFConfiguration.image)
Copy
1
PSPDFViewController *controller = [[PSPDFViewController alloc] initWithDocument:imageDocument configuration:PSPDFConfiguration.imageConfiguration];

Customize the UI

We also recommend only exposing relevant UI elements to your users. For example, you can disable the document editing feature to disallow adding new pages to an image document. Here’s a basic UI customization for a PSPDFViewController presenting a PSPDFImageDocument:

Copy
1
2
3
4
5
6
let rightItems = [controller.annotationButtonItem, controller.activityButtonItem, controller.searchButtonItem]
let leftItems = [controller.outlineButtonItem, controller.brightnessButtonItem]
controller.navigationItem.setRightBarButtonItems(rightItems, for: .document, animated: false)
controller.navigationItem.setLeftBarButtonItems(leftItems, for: .document, animated: false)

controller.navigationItem.leftItemsSupplementBackButton = true
Copy
1
2
3
4
5
6
NSArray<UIBarButtonItem *> *rightItems = @[controller.annotationButtonItem, controller.activityButtonItem, controller.searchButtonItem];
NSArray<UIBarButtonItem *> *leftItems = @[controller.outlineButtonItem, controller.brightnessButtonItem];
[controller.navigationItem setLeftBarButtonItems:rightItems forViewMode:PSPDFViewModeDocument animated:NO];
[controller.navigationItem setLeftBarButtonItems:leftItems forViewMode:PSPDFViewModeDocument animated:NO];

controller.navigationItem.leftItemsSupplementBackButton = YES;

See AnnotateImagesExample from PSPDFCatalog for more details.

Saving

To control how the backing image is saved by PSPDFImageDocument, use the imageSaveMode property. This property has two valid values: PSPDFImageSaveModeFlatten and PSPDFImageSaveModeFlattenAndEmbed.

  • PSPDFImageSaveModeFlatten — When a PSPDFImageDocument is saved, all the (visible) changes are just saved back to the original image as is, and reopening this image will show these changes, but they will not be editable. When saving with this mode, any previously saved metadata in the document is removed as well.

  • PSPDFImageSaveModeFlattenAndEmbed — This performs everything PSPDFImageSaveModeFlatten does, but it also saves all the modifications as part of the image’s metadata. When an image saved using this mode is opened with a regular image viewer, all the changes made will be displayed on the original image. However, when an image is opened with PSPDFImageDocument, the saved changes will then be editable. Please be aware that using this option to save will increase the size of the images.

PSPDFImageDocument also supports serialization and deserialization via the NSSecureCoding protocol. If you need to preserve editing abilities for an image document between application launches, you can simply archive and unarchive it using the standard iOS serialization APIs.

ℹ️ Note: For the save mode to take effect, it must be changed before a save is performed.