Such complex file formats as EXIF, TIFF, JPEG-JFIF, PNG and some others contain a lot of non-image data generally referred to as metadata. ImageGear provides functionality to read the metadata during image loading, to store it with the image in memory, and modify metadata during image saving.

ImageGear for Java provides two sets of API for working with non-image data:

• General Metadata API - This set of API provides unified access to metadata of all supported image formats. Non-image data itself can be of any possible complex type and completely depends on the nature of the file format itself. ImageGear processes this complex data through a single interface and provides uniform processing that does not depend on the actual data format and varies from information fields of such simple formats as BMP and PCX, up to the complex EXIF and IPTC metadata support in such filters as TIFF and JPEG.
• Simplified Metadata API - This set of API provides access to standard tags of specific complex formats, such as TIFF, EXIF, and IPTC. It takes care of the location of particular tags in the metadata tree, decodes and encodes complex metadata values, and provides structures and enumerations for data types according to the metadata standard.

ImageGear for Java is responsible for translating this format-dependent data into a standard uniform format. As soon as an image is loaded, its metadata is accessible through ImGearPage.getMetadata method and ImGearDocument.getMetadata method objects.

You do not need to load image pixels to obtain the non-image data. Use the ImGearFileFormats.loadPageHeader method to load DIB info and metadata without loading pixel data.

Common Non-Image Data

ImageGear for Java uses its Metadata API to provide information that is common for all image file formats, such as compression of file page from which the image was loaded.

Use the ImGearMetadataHead.getCommon method to access common metadata.

Accessing Non-Image Data

ImageGear for Java uses different storage for Document level metadata and Page level metadata:

Document level metadata is only used with file formats that are capable of storing multiple pages. This metadata includes only values that are common for all pages of the image. Page level metadata is available for all file formats. It includes data that describes an image page. Different file formats use different metadata structures and tags. When saving an image to a file format that differs from the format of metadata attached to the image, the image's metadata is ignored, and default metadata is created instead.

ImageGear uses a tree structure to store format metadata. All nodes of the metadata use a common parent class: ImGearMetadataNode Class. The two following classes are derived from it:

ImGearMetadataLeaf Class can only contain data and no nested nodes; ImGearMetadataTree Class can contain the nested nodes, but cannot contain the data values. A special node of type ImGearMetadataHead Class is always present in every ImGearPage Class and ImGearDocument Class as a class instance. It cannot be attached to any metadata node, and it can only have one child. If the page or document has metadata, then a metadata tree is attached to this Head node. Otherwise, the Head does not have child nodes.

A node can be un-referenced or referenced from the one parent, but it cannot be referenced from multiple parents. The node cannot reference itself directly or indirectly. ImageGear checks this when the node is attached to another node. A metadata tree cannot be shared between multiple pages or documents.

Every metadata node has Format Field of ImGearMetadataFormats Enumeration type. This allows you to store, for example, EXIF metadata under TIFF metadata. A Format Field value of ImGearMetadataFormats.UNKNOWN can be used to indicate a custom/unknown format.

The actual data in ImGearMetadataLeaf Class uses the System.Object type. The nativeType Field of the ImGearMetadataLeaf Class object specifies the type of data that is used by a file format.

Several leaves can reference the same object. ImageGear does not check or maintain consistency between an image and the metadata attached to it. For example, if an image loaded from a TIF file is resized, ImageGear does not update ImageWidth and ImageHeight tags in the image metadata. However, when you save this image, the correct values will be written to the file.

Metadata Dictionary

ImageGear provides a metadata dictionary that stores necessary information for all known metadata tags of all supported formats.

The application can obtain an information record for any tag that is present in the dictionary, using ImGearMetadataDictionary.lookUp Method.

All tag information records implement the IImGearMetadataDictRecord Interface. This interface provides minimal information for a tag, its name. This is sufficient for most ImageGear supported formats. These formats use ImGearCommonMetadataDictRecord Structure for storing tag information. This structure only contains the tag and its name.

Dictionary records for DICOM tags contain the additional fields valueRepresentation and maxMultiplicity. ImageGear uses ImGearDICOMMetadataDictRecord Class to store DICOM tag information.

ImageGear contains an expansive set of predefined dictionary records. In addition, the dictionary allows adding new records for new or custom tags that are not present in the predefined dictionary. The dictionary also allows overwriting predefined information for a tag with a custom one. Use this ImGearMetadataDictionary.addRecord method for this.

Use the ImGearMetadataDictionary.reset method to reset the dictionary to its initial state. This method removes all records that were added by the addRecord method, and leaves only predefined records.

The metadata dictionary only affects the General Metadata API. It does not affect the Simplified Metadata API.

Updating File Metadata without Updating its Pixel Data

There are cases when an application needs to update the metadata of an image file while leaving its pixel data unchanged. For example, if the image is compressed using a Lossy compression scheme, this avoids degradation of image quality.

Use ImGearFileFormats.updatePageMetadata Method to update metadata in an image file without changing its pixel data.

Currently, the method only supports updating metadata in the DICOM file format.