Metadata Handling

In PixelLive SDK, you can also handle metadata of each images. They can be obtained by Doc::getMetadata or Image::getMetadata functions.
As an Image instance can not be modified by any functions in the library, so metadata also can not be modified directly. Metadata is also processed through Image chains. For example, if you use PhotometricTransform, it converts the colorspace of the input image and it also replaces the color profile (one of the metadata) of the input.

PixelLive Metadata Basics

In PixelLive SDK, all metadatas are stored in a DataStore instance. DataStore can store any Serializable instances and TIFF metadatas are also defined as DataArray class. Although You can access to the DataStore directly, it is little bit complicated and you had better use TIFF6 functions. TIFF6 provides functions which ease the manipulation of TIFF metadata. There are several function and several definitions in the structure.

TIFF Specifications

Almost all metadata managed in PixelLive SDK is based on TIFF 6.0 and its extensions. If you know nothing about TIFF file format, see Supported TIFF Tags.

TIFF Tags in String and in Number

There are two ways to specify a TIFF tag. For example, if you want to get ICC color profile from an Image instance, you can select one of the following two codes:

AutoPtr<DataStore> metadata = image->getMetadata();
const void *ptr;
u16 type;
size_t count;

// (1) By string
ptr = TIFF6::get(metadata, "InterColorProfile");

// (2) By tag number
ptr = TIFF6::get(metadata, 34675);

And there are also TIFF6::getTagName and TIFF6::getTagFromName functions and tag number and tag string can be converted one to the other.

Directory Structure by IFD Pointers

The metadata may contain some directory structures such as Exif IFD Pointer(34665) or other IFD pointer based TIFF tags. For these tags, you can only use the string version of TIFF6 functions. For example, the following code obtains the resolution that is managed in EXIF:

TIFF_RATIONAL xRes = TIFF6::getAsRATIONAL(metadata, "Exif IFD Pointer:XResolution");
TIFF_RATIONAL yRes = TIFF6::getAsRATIONAL(metadata, "Exif IFD Pointer:YResolution");

Almost all TIFF6 functions accepts ':' as path separator and the code above illustrates this.

TIFF6::verify

This function is very useful when checking the existance, type and count of a TIFF tag. Unlike other functions in the library, TIFF6::verify never throws any exceptions and you can use this function to check several conditions.

Existance of a tag
To check the existance of a tag, use this function like the following:

if(TIFF6::verify(metadata, "HostComputer"))
{
    // "HostComputer" is there.
}
else
{
    // No "HostComputer"
}

It can be also used with tag number instead of the tag string.

if(TIFF6::verify(metadata, 316)) // 316="HostComputer"
    ...

Type of a tag
To confirm the type of a tag, use this function like the following code:

if(TIFF6::verify(metadata, "XResolution", TIFF6::RATIONAL)
{
    // Yes, "XResolution" is in RATIONAL.
    u16 type;
    u32 count;
    const TIFF_RATIONAL& xRes = TIFF6::get(metadata, "XResolution", type, count);
}
else
{
    // The data does not comply with TIFF 6.0 spec.
}

Whole validation of a tag
To confirm the type and count of a tag, use this function like the following:

if(TIFF6::verify(metadata, "Exif IFD Pointer::DateTimeOriginal", TIFF6::ASCII, 20)
{
    // Yes, "DateTimeOriginal" is in ASCII and count is 20.
}
...

Resolution Utilities

With TIFF6::verify function, you can write metadata handling code with less try-catch blocks. Anyway, if you only want to know the resolution, you had better use MetadataUtils::getXResolution and MetadataUtils::getYResolution function. The following code illustrates how to use these functions:

TIFF_RATIONAL xRes = MetadataUtils::getXResolution(metadata, MetadataUtils::Inch);
TIFF_RATIONAL yRes = MetadataUtils::getYResolution(metadata, MetadataUtils::Inch);

Modifying TIFF Tags

You can add or modify a tag by TIFF6::set functions. The following code illustates how to modify the metadata:

u16 pageNum = 3;
TIFF6::set(metadata, "PageNumber", TIFF6::SHORT, 1, &pagenum);

If you want to modify the ASCII typed tags, the code is much simple:

TIFF6::set(metadata, "Exif IFD Pointer:ImageUniqueID", "35513A3606DA45b3895AA428DA77E2FD");

TIFF6::getAsXXX Functions

The TIFF6::get functions throw exceptions if any errors during the process. There are also exception free versions of get functions. These functions return NULL when error occurs (TIFF6::getAsString returns NullString instead).

For the information about modifying Metadata before exporting, see Modifying Metadata for Exporting Images.

Metadata other than TIFF Tags

There are also metadatas which could not be expressed in TIFF Tag style. They are usually stored as Serializable data and it may not be accessed by TIFF6 functions. For example, VFZ/PFZ defines its own metadata format and some of them do not correspond to specific TIFF tags easily. They are stored in a child DataStore named "PixelLive". The following code illustrates how to access to them:

    AutoPtr<DataStore> metadata = image->getMetadata();
    String vfzTitle = metadata->getAsString("PixelLive/TITLE", '/');
    String vfzAuthor = metadata->getAsString("PixelLive/AUTHOR", '/');
    GUID vfzGuid = metadata->getAsGUID("PixelLive/GUID", '/');

DataStore has many getAsXXX functions and usually they accept two parameters. The first one is the location of the data. The second one is the path separator. In the sample above, the location is separated by '/'. You can also change the separator for the data like the following code:

    String vfzTitle = metadata->getAsString("PixelLive|TITLE", '|');

For more information about VFZ/PFZ metadata, see VFZ Specific Metadata Support.

Modifing Metadata on Image::getMetadata

In Image::getMetadata function, an Image instance can obtain and modify a copy of the metadata from the input Image instance (by Image::getMetadata) and it finally passes it to the Image instance chained above it. The following code is almost same to the one that is used in PhotometricTransform (but error handling codes are removed to simplify the code):

virtual AutoPtr<DataStore> getMetadata() const
{
    AutoPtr<DataStore> metadata = m_image->getMetadata();
    if(m_profDst.isValid())
    {
        // We should replace color profile if it is not compatible with
        // the new photometric...
        TIFF6::set(
            metadata,
            "InterColorProfile", // 34675
            TIFF6::UNDEFINED,
            m_profDst->getRawData().getSize(),
            m_profDst->getRawData().getPtr());
    }
    else
    {
        // simply remove the profile.
        metadata->unlink("InterColorProfile");
    }
    return metadata;
}

This document is automatically generated using doxygen 1.5.4 at Fri Jun 27 18:22:54 2008.