Kim - Kotlin Image Metadata

Kim is a Kotlin Multiplatform library for reading and writing image metadata.

This lib is used in production by my online EXIF Viewer, Thumbnail Fixer Pro, Quick Metadata Remover and PixelSafe.

Features

• JPG: Read & Write EXIF, IPTC & XMP
• PNG: Read & Write eXIf chunk & XMP
  • Also read the compressed zxIf chunk variant and non-standard EXIF & IPTC from tEXt/zTXt chunks
• WebP: Read & Write EXIF & XMP
• HEIC / AVIF: Read EXIF & XMP
  • Support for animated AVIF files (AV1 Image Sequence)
• MOV / MP4: Read EXIF & XMP
  • Includes the MakerNote and thumbnail of Fujifilm videos and the display resolution of the video track
• JXL: Read & Write EXIF & XMP of uncompressed files
• TIFF / RAW: Read EXIF & XMP
  • Full support for Adobe DNG, Canon CR2, Canon CR3 & Fujifilm RAF
  • Support for Nikon NEF, Sony ARW & Panasonic RW2
  • API for preview image extraction of DNG, CR2, CR3, RAF, NEF, ARW, RW2 & ORF
• MakerNote reading for Canon, Nikon, Sony, Fujifilm, Apple, Olympus, Panasonic, Pentax, Ricoh, Samsung, Sigma and Leica cameras, including the sub-directories with camera settings, white balance, AF, flash and lens data, the camera-encrypted Nikon data and the model specific Canon CameraInfo and CustomFunctions records
• GIF: Read & Write XMP
• Handling of XMP content through XMP Core for Kotlin Multiplatform
• Convenient Kim.update() API to perform updates to the relevant places
  • JPG: Lossless rotation by modifying only one byte (where present)
• Kim.deleteMetadata() API to remove all metadata, keeping the ICC profile

Installation

implementation("de.stefan-oltmann:kim:<VERSION>")

For the targets wasmJs & js you also need to specify this:

implementation(npm("pako", "2.1.0"))

Sample usages

Read metadata

Kim.readMetadata() takes kotlin.ByteArray on all platforms and depending on the platform also kotlinx.io.files.Path, kotlinx.io.Source (for usage with Ktor) & ByteReadChannel, java.io.File, java.io.InputStream, NSData (iOS) and String paths.

val bytes: ByteArray = loadBytes()

val metadata = Kim.readMetadata(bytes)

/* MediaMetadata has a proper toString() similar to the output of ExifTool */
println(metadata)

val orientation = metadata.findShortValue(TiffTag.TIFF_TAG_ORIENTATION)

println("Orientation: $orientation")

val takenDate = metadata.findStringValue(ExifTag.EXIF_TAG_DATE_TIME_ORIGINAL)

println("Taken date: $takenDate")

For streaming sources, Kim.readMetadata() also takes a ByteReader, so the file does not have to be loaded into memory:

val byteReader = JvmInputStreamByteReader(inputFile.inputStream(), inputFile.length())

val metadata = Kim.readMetadata(byteReader)

Some tools write XMP or EXIF as APP1 segments behind the JPEG image data. By default the read stops at the image data. Pass readTrailerMetadata = true to also report that content:

val metadata = Kim.readMetadata(bytes, readTrailerMetadata = true)

Create high level summary object

This creates an instance of MetadataSummary. It contains the following:

• Media format
• Image size, oriented size & megapixel count
• Orientation
• Date taken
• GPS coordinates & location shown
• Camera make & model
• Lens make & model
• ISO, Exposure time, F-Number, Focal length
• Film simulation (Fujifilm specific)
• Image title & description
• Rating
• XMP:pick flag
• Keywords
• Faces (XMP-mwg-rs regions, used by Picasa and others)
• Persons in image
• EXIF thumbnail size & bytes

val bytes: ByteArray = loadBytes()

val summary = Kim.readMetadata(bytes).convertToSummary()

Extract metadata bytes

Kim.extractMetadataBytes() determines the file type from the file header and returns the raw metadata bytes. Cloud services can not reliably tell the mime type, so this can be used to upload the metadata alongside the image.

val result = Kim.extractMetadataBytes(byteReader)

/* The detected media format, or NULL when it could not be determined. */
val mediaFormat: MediaFormat? = result.first

/* The raw metadata bytes to upload to the cloud service. */
val metadataBytes: ByteArray = result.second

Extract preview image

Kim.extractPreviewImage() extracts the embedded preview image of DNG, CR2, CR3, RAF, NEF, ARW, RW2 & ORF files as JPEG bytes.

val previewBytes: ByteArray? = Kim.extractPreviewImage(byteReader)

if (previewBytes != null)
    println("Preview image has ${previewBytes.size} bytes.")

Change orientation using low level API

val inputFile = File("myphoto.jpg")
val outputFile = File("myphoto_changed.jpg")

val metadata = Kim.readMetadata(inputFile)

val outputSet: TiffOutputSet = metadata.exif?.createOutputSet() ?: TiffOutputSet()

val rootDirectory = outputSet.getOrCreateRootDirectory()

rootDirectory.removeField(TiffTag.TIFF_TAG_ORIENTATION)
rootDirectory.add(TiffTag.TIFF_TAG_ORIENTATION, 8)

OutputStreamByteWriter(outputFile.outputStream()).use { outputStreamByteWriter ->

    JpegRewriter.updateExifMetadata(
        byteReader = JvmInputStreamByteReader(inputFile.inputStream(), inputFile.length()),
        byteWriter = outputStreamByteWriter,
        outputSet = outputSet
    )
}

See the example project for more details.

Update metadata using Kim.update () API

Kim.update() applies the given updates to all formats that can represent them, so EXIF, IPTC and XMP are updated simultaneously in one call. The metadata storages duplicate the same logical values. Updating only one of them would let the copies drift apart, which is why partial updates do not exist.

val bytes: ByteArray = loadBytes()

/* A single update: */
val rotatedBytes = Kim.update(
    bytes = bytes,
    update = MetadataUpdate.Orientation(TiffOrientation.ROTATE_RIGHT)
)

/* Multiple updates in one call: */
val updatedBytes = Kim.update(
    bytes = bytes,
    updates = setOf(
        MetadataUpdate.Orientation(TiffOrientation.ROTATE_RIGHT),
        MetadataUpdate.TakenDate(timestamp),
        MetadataUpdate.Title("My title"),
        MetadataUpdate.Keywords(setOf("hello", "test"))
    )
)

The supported update types are:

Update	Sets
MetadataUpdate.Orientation	Rotation (JPG supports a lossless single-byte swap)
MetadataUpdate.TakenDate	Date taken
MetadataUpdate.GpsCoordinates	GPS coordinates
MetadataUpdate.LocationShown	Location shown
MetadataUpdate.GpsCoordinatesAndLocationShown	GPS coordinates and location
MetadataUpdate.Title	Title
MetadataUpdate.Description	Description
MetadataUpdate.Flagged	The XMP:pick flag
MetadataUpdate.Rating	Star rating
MetadataUpdate.Keywords	Keywords
MetadataUpdate.Faces	Faces (XMP-mwg-rs regions)
MetadataUpdate.Persons	Persons in image

An update call without any updates is rejected with an ImageWriteException.

See AbstractUpdaterTest for more samples.

Streaming update

The update can stream the file from a ByteReader to a ByteWriter. The image data of JPEG, PNG, GIF and JPEG XL files with split codestream boxes (jxlp) is streamed in bounded chunks. WebP files buffer their chunks in memory, and JPEG XL files with a single codestream box (jxlc) buffer the codestream, because the metadata is stored behind the image data. A single-update overload exists for both the byte array and the streaming variant.

val byteReader = JvmInputStreamByteReader(inputFile.inputStream(), inputFile.length())

OutputStreamByteWriter(outputFile.outputStream()).use { outputStreamByteWriter ->

    Kim.update(
        byteReader = byteReader,
        byteWriter = outputStreamByteWriter,
        updates = setOf(MetadataUpdate.Orientation(TiffOrientation.ROTATE_RIGHT))
    )
}

Delete metadata using Kim.deleteMetadata () API

Kim.deleteMetadata() removes all metadata of a file, but keeps the ICC chunks, because they would change how the image is displayed.

• JPG: removes EXIF, XMP, IPTC & comment segments
• PNG: removes the eXIf chunk (including its compressed zxIf variant), all text chunks & the tIME chunk
• WebP: removes EXIF & XMP chunks and clears the VP8X metadata flags
• JXL: removes Exif & xml boxes
• GIF: removes the XMP application extension & comment extensions

val bytes: ByteArray = loadBytes()

val newBytes = Kim.deleteMetadata(bytes)

Like Kim.update(), deleteMetadata() also offers a streaming overload that writes to a ByteWriter without loading the file into memory for the formats listed in the Streaming update section:

Kim.deleteMetadata(
    byteReader = byteReader,
    byteWriter = byteWriter
)

Update thumbnail using Kim.updateThumbnail () API

val bytes: ByteArray = loadBytes()
val thumbnailBytes: ByteArray = loadThumbnailBytes()

val newBytes = Kim.updateThumbnail(
    bytes = bytes,
    thumbnailBytes = thumbnailBytes
)

Using Java

See the Java example project how to use Kim in Java projects.

Limitations

• Does not read the image size and orientation for HEIC, AVIF & JPEG XL.
• JPEG: Metadata that does not fit into a single segment (~64 KB) is written interoperably, following ExifTool as the reference implementation: oversized XMP uses Adobe Extended XMP (main packet plus GUID-referenced extension segments), oversized IPTC is split across multiple APP13 segments exactly like Photoshop does.
• Updates buffer the file content in memory for WebP files and for JPEG XL files with a single codestream box (jxlc). JPEG, PNG, GIF and JPEG XL files with split codestream boxes (jxlp) are streamed in bounded chunks.
• Does not read brotli compressed metadata of JPEG XL due to missing brotli KMP libs.
• The MakerNotes of GoPro cameras and the undocumented records of the oldest Canon and Sony models are not interpreted.
• There is right now no convenient tooling for GeoTiff like there is for GPS.
• PDF files are detected by the format detection, but their metadata is not parsed.
• Videos: QuickTime ilst tags (title, keywords as written by Apple tools) and the QuickTime GPS tag are not read yet; such videos report the XMP packet, the display resolution and - when present - the Fujifilm metadata only.

Regarding HEIC & AVIF metadata

In the processing of HEIC and AVIF files, we handle them as standard ISOBMFF-based files, adhering rigorously to the EIC/ISO 14496-12 specification. To preempt potential legal issues, we intentionally omit certain boxes outlined in the HEIC specification, notably the image size ("ispe") and image rotation ("irot") boxes. This approach extends to AVIF images, as they repurpose the same boxes.

Android: GPS metadata requires the ACCESS_MEDIA_LOCATION permission

On Android 10 (API 29) and above the platform only hands out the GPS coordinates of media files when the app holds the ACCESS_MEDIA_LOCATION permission. Without it the GPS tags of photos that are read through a ContentResolver stream come back empty or corrupted, which is easy to mistake for a library bug. This is platform behavior - Kim cannot bypass it.

Declare the permission in your manifest and request it at runtime like other dangerous permissions if your app needs GPS metadata:

<uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION"/>

Contributions

Contributions to Kim are welcome! If you encounter any issues, have suggestions for improvements, or would like to contribute new features, please feel free to submit a pull request.

Acknowledgements

• JetBrains for making Kotlin.
• Apache Software Foundation for making Apache Commons Imaging.
• Drew Noakes for making metadata-extractor.
• Phil Harvey for making ExifTool.
• Unsplash for providing test images.

License

This code is under the Apache License 2.0.

See the NOTICE.txt file for required notices and attributions.