A DjVu Metadata Tutorial

This tutorial illustrates how to access DjVu metadata.

Step 1: Initialization

To use DjVu SDK, you firstly include several headers.

#include "djv_document.h" // for Document class
#include "djv_page.h" // for Page class
#include "djv_annotation.h" // for Annotation/PropSet classes

using namespace Celartem;
using namespace Celartem::DjVu;

Step 2: Loading a DjVu file

Load a DjVu file using Document::create method.

AutoPtr<Document> doc = Document::create("metadata_test.djvu");

Warning

Without setting appropriate license script, decoding function (DjVuDecode feature) will stop working after 2 weeks from the its built time. See License System for more information.

Step 3: Accessing Document Level Metadata

DjVu has metadata both on the document level and on the page level. Each document can have its metadata and each page also can have its own page level metadata.
So anyway, on the step, we try to access the document level metadata:

// Obtain the document level, shared, metadata
AutoPtr<PropertySet> propSet = doc->getSharedAnnotation()->properties;

// getting "Title" of the document
// if the property is not found, the method returns an empty string.
String title = propSet->get("Title");

// enumerate all the properties
// NOTE: String::c_str() method returns UTF-8 text
AutoPtr<PropertySetIterator> it = propSet->enumProperties();
while(it->next())
{
  printf("%s=%s\n", it->getKey().c_str(), it->getValue().c_str());
}

// setting a property value
propSet->set("Title", "New Title");

// removing a property
// if the property is not found, the method does nothing
propSet->remove("Author");

// propagating the property changes to the chunks
// Without this, the changes are not reflected to the saved file
doc->updateChunks();

// save to the existing file
// Because \ref Document instance still references the original file,
// it actually locks the file and it could not be overwritten.
// disconnectFromOriginalSources method loads all the file data onto
// the memory and releases the locks to the original file
doc->getChunk()->disconnectFromOriginalSources();

// OK, now we can overwrite the original file
doc->save("metadata_test.djvu");

// Of course, we can save the \ref Document instance to other files easily
doc->save("other.djvu")

Step 4: Accessing Page Level Metadata

For the page level metadata, the process is almost same but we just load the metadata from Page method:

AutoPtr<Page> page = doc->getPages()[0];
AutoPtr<PropertySet> pagePropSet = page->getAnnotation()->properties;

Normally, for a DjVu file, we prefer the document level metadata but you can also add metadata for each page if you want to do that.