# Simplify image annotation with Android SDK While it has always been possible to annotate images in Nutrient, doing so previously required some extra code. You had to convert an image to PDF, be sure to update the annotation tools and user interface (UI) to only show relevant options, and extract the image data back when a save occurred. In [Nutrient Android SDK 4.6](https://www.nutrient.io/blog/pspdfkit-android-4-6/), we introduced a new class, [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/), to make this process much simpler. All you need to do is pass your image source to the [`ImageDocumentLoader`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document-loader/) or [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/), and we handle the rest. To make use inside [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/) even simpler, we provide a prebuilt configuration that adjusts the UI so that it works great for images. Furthermore, image documents remain fully editable, even after saving them back to the original image file. Take a look at `ImageDocumentExample` in the Catalog app or read our [announcement blog post](https://www.nutrient.io/blog/image-documents/) to learn how you can annotate PNG, JPEG, and TIFF images just like a PDF with Image Documents. This feature requires the [Image Documents](https://www.nutrient.io/sdk/features-list/) component to be enabled in your license. If you need to use an image as an annotation in another document, see our guide on [image annotations](https://www.nutrient.io/guides/android/annotations/image-annotations.md). ## Loading image documents [`ImageDocumentLoader`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document-loader/) provides several static methods that can be used to load [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/) instances from either a [`Uri`](http://developer.android.com/reference/android/net/Uri.html) or a [`DocumentSource`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-document-source/). Supported image document formats are JPEG, PNG, and TIFF. Just like with PDF documents, image documents can be loaded from [various sources](https://www.nutrient.io/guides/android/basics/using-activity.md#launching-from-a-uri-using-the-static-methods), including the local file system, Android content providers, or the app’s assets. Here’s how to load an image document from the app’s assets directory: ### KOTLIN ```kotlin val uri = Uri.parse("file:///android_asset/image.png") val imageDocument: ImageDocument = ImageDocumentLoader.openDocument(context, uri) ``` ### JAVA ```java final Uri uri = Uri.parse("file:///android_asset/image.png"); final ImageDocument imageDocument = ImageDocumentLoader.openDocument(context, uri); ``` ### Loading into an activity Image documents can be shown and used inside a [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/), just like normal [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/)s. To launch [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/) with an image document, you can use the static [`showImage()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/show-image.html) method of [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/), which will load the image document for display inside the activity. To simplify creation of a suitable [`PdfActivityConfiguration`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.configuration.activity/-pdf-activity-configuration/) when displaying image documents, you can use [`getDefaultImageDocumentActivityConfiguration()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document-loader/get-default-image-document-activity-configuration.html) on [`ImageDocumentLoader`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document-loader/), which will provide the recommended settings: ### KOTLIN ```kotlin val config: PdfActivityConfiguration = ImageDocumentLoader.getDefaultImageDocumentActivityConfiguration(context) PdfActivity.showImage(context, Uri.fromFile(image), config) ``` ### JAVA ```java final PdfActivityConfiguration config = ImageDocumentLoader.getDefaultImageDocumentActivityConfiguration(context); PdfActivity.showImage(context, Uri.fromFile(image), config); ``` If you want to launch a custom subclass of [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/) or need to specify additional [`Intent`](https://developer.android.com/reference/android/content/Intent) options, you can create an [`Intent`] for image document viewing using static methods on [`PdfActivityIntentBuilder`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity-intent-builder/) — for example, [`fromImageUri()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity-intent-builder/from-image-uri.html). ### Loading into a fragment #### PdfFragment You can also load image documents into a [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/) instance using the static [`newImageInstance()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/new-image-instance.html) methods on [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/): ### KOTLIN ```kotlin val uri = Uri.parse("file:///android_asset/image.png") val config = ImageDocumentLoader.getDefaultImageDocumentConfiguration() val fragment = PdfFragment.newImageInstance(uri, config) supportFragmentManager.beginTransaction().replace(R.id.container, fragment).commit() ``` ### JAVA ```java final Uri uri = Uri.parse("file:///android_asset/image.png"); final PdfConfiguration config = ImageDocumentLoader.getDefaultImageDocumentConfiguration(); final PdfFragment fragment = PdfFragment.newImageInstance(uri, config); getSupportFragmentManager().beginTransaction().replace(R.id.container, fragment).commit(); ``` Like with the activity, you can create a recommended [`PdfConfiguration`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.configuration/-pdf-configuration/-builder/) instance for displaying image documents inside [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/) using the static helper methods on [`ImageDocumentLoader`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document-loader/). #### PdfUiFragment When loading an image in a [`PdfUiFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-ui-fragment/), you need to use [`PdfUiFragmentBuilder#fromImageUri()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-ui-fragment-builder/from-image-uri.html) to create the [`PdfUiFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-ui-fragment/): ### KOTLIN ```kotlin val uri = Uri.parse("file:///android_asset/image.png") val config: PdfActivityConfiguration = ImageDocumentLoader.getDefaultImageDocumentActivityConfiguration(context) val fragment = PdfUiFragmentBuilder.fromImageUri(this, uri).configuration(config).build(); supportFragmentManager.beginTransaction().replace(R.id.container, fragment).commit() ``` ### JAVA ```java final Uri uri = Uri.parse("file:///android_asset/image.png"); final PdfActivityConfiguration config = ImageDocumentLoader.getDefaultImageDocumentActivityConfiguration(context); final PdfUiFragment fragment = PdfUiFragmentBuilder.fromImageUri(this, uri).configuration(config).build(); getSupportFragmentManager().beginTransaction().replace(R.id.container, fragment).commit(); ``` ## Coordinate system The coordinate system of image documents is very similar to the one used for PDF documents. The zero point is at the bottom left, and it’s sized to match the image that was opened.![Annotation creator dialog](@/assets/guides/android/annotations/image-coordinates.png) ## Annotation types Although you can technically use any annotation type with [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/), 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, don’t make sense for an [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/) because there will be no selectable text in the document. When using the preconfigured configuration instances returned by [`ImageDocumentLoader`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document-loader/), these impractical annotation tools will be automatically disabled. ## Saving Saving has been designed to be transparent, i.e. to make [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/) instances behave just like [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/) instances. You can use any of the save methods on [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/), which will handle saving all changes back to the original image file. By default, image documents will stay editable after saving. If you don’t need to retain editability, you can strip all document metadata in the saved image file, which will also reduce the final file size. To control how the backing image is saved, the [`ImageDocument#saveIfModified(metadata)`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/save-if-modified.html) method provides a parameter. - `metadata: false` — When saving, all the (visible) changes are 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. - `metadata: true` — This saves all changes to the original image as described above, 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 [`ImageDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-image-document/), the saved changes will then be editable. Be aware that using this option to save will increase the size of the images: ### KOTLIN ```kotlin val imageDocument: ImageDocument // By default, the image document is saved so that it stays editable. imageDocument.saveIfModified() // You can also strip all metadata, saving the image as non-editable. val saveMetadata = false imageDocument.saveIfModified(saveMetadata) ``` ### JAVA ```java final ImageDocument imageDocument; // By default, the image document is saved so that it stays editable. imageDocument.saveIfModified(); // You can also strip all metadata, saving the image as non-editable. final boolean saveMetadata = false; imageDocument.saveIfModified(saveMetadata); ``` ### Saving inside an activity By default, PSPDFKit will auto-save image documents whenever the activity is closed or put into the background. You can find out more about auto-saving in our [Annotation-Saving Mechanism](https://www.nutrient.io/guides/android/annotations/annotation-saving-mechanism.md) guide. If you want to manually save the image document, you can directly call the [`save()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/save.html) method on the used [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/) instance: ### MYACTIVITY.KT ```kt // This will forward the save operation to the `ImageDocument` instance. pdfFragment.save() ``` ### MYACTIVITY.JAVA ```java // This will forward the save operation to the `ImageDocument` instance. getPdfFragment.save(); ``` If you want to receive save completion callbacks of image document-saving operations, you can register a [`DocumentListener`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/) instance using [`addDocumentListener()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/add-document-listener.html) on [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/). --- ## Related pages - [Enhance your image annotation experience](/guides/android/features/image-document-standard.md)