You can easily render associated annotation data for your thumbnails by simply connecting ThumbnailXpress to an instance of NotateXpress. If an image has annotation data (such as text, lines, shapes, etc.), ThumbnailXpress will call on NotateXpress to include the annotations in the thumbnail rendering.

Connecting ThumbnailXpress to NotateXpress

The first step in rendering annotations in your thumbnails is to connect your instance of ThumbnailXpress to an instance of NotateXpress. You do this by passing the NotateXpress.InstanceHandle property to the ThumbnailXpress.NotateXpressInstance property.

For example, if you had an instance of ThumbnailXpress named thumbnailXpress, and an instance of NotateXpress named notateXpress, you would do this:

thumbnailXpress.NotateXpressInstance = notateXpress.InstanceHandle;

If you don't do anything else, ThumbnailXpress will automatically render internal image annotation data that NotateXpress supports (NotateXpress, Imaging for Windows, and XFDF formats).

If, however, you need to render annotations stored in external files, you'll need to teach ThumbnailXpress how to find the data using annotation search rules.

Annotation Search Rules

Instead of telling ThumbnailXpress where to find annotation data for each individual image that it needs to thumbnail, ThumbnailXpress allows you to give it a list of rules that define where it should search for annotation data. This special annotation rules list is kept in the ThumbnailXpress.AnnotationSearchOrder property.

As an image is being thumbnailed, ThumbnailXpress will iterate through its rules list to find associated annotation data. The first rule that succeeds will be used as the source of annotation data for that particular image (if no rule succeeds, then ThumbnailXpress concludes that the image does not have associated annotations and renders a thumbnail without any associated annotations). The entire process repeats when ThumbnailXpress moves on to thumbnail the next image - the search for annotations starts over, and the first rule on the list that returns annotation data "wins."

By default, any new instance of ThumbnailXpress will have pre-loaded this list with three rules:

1. If the image being thumbnailed contains internal Imaging for Windows (WANG) annotation data, use that annotation data.
2. If the image being thumbnailed contains internal NotateXpress annotation data, use that annotation data.
3. If the image being thumbnailed contains internal XFDF (PDF) annotation data, use that annotation data.

This allows you to render internal annotations by simply connecting ThumbnailXpress to NotateXpress.

But if you were to clear the rules list and set it up manually yourself, here's how you would do it:

thumbnailXpress.AnnotationSearchOrder.Clear();
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.ImagingForWindows));
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.NotateXpress));
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.Xfdf));

Or, if you know you only internally need annotation data of a particular type (let's say PDF), you could redefine the search rules to only look for this particular type of annotation data:

thumbnailXpress.AnnotationSearchOrder.Clear();
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.Xfdf));

Setting Up ThumbnailXpress to Render Annotations Stored in External Files

Where the annotation search rules really become important is when your image annotation data is stored externally to the image file. In this case, you must provide a custom set of annotation search rules to ThumbnailXpress in order to teach it how to find your external annotation data.

Before explaining how you do this, it's important to understand that ThumbnailXpress does impose a few requirements on your annotation files:

1. An external annotation file must be located in the same directory as its associated image
2. An external annotation filename must be named similarly to its associated image (the extension may be different, or it may contain an additional name prefix or suffix, but nothing more)
3. An external annotation file must contain annotation data of one of the following types:
   • NotateXpress
   • NotateXpress XML
   • XFDF
   • TMS Sequoia

With that in mind, you define external annotation search rules by constructing new instances of the ExternalAnnotationSearchRule class. An instance of this class must specify the external annotation type, whether the annotation file is named with a prefix or suffix, and whether the annotation file does or does not include the extension of its associated image file. The following examples illustrate how this works (consult the API documentation for details).

Example 1 - Using external annotation files using a .nxp extension

Imagine you have a variety of JPEG files with associated NotateXpress annotation data stored in a file of the same name except the ".jpg" extension has been replaced with ".nxp", like so:

• Form1.jpg
• Form1.nxp
• Form2.jpg
• Form2.nxp
• Form3.jpg
• Form3.nxp

You can "teach" ThumbnailXpress to use the Form1.nxp annotation data with the Form1.jpg file, the Form2.nxp annotation data with the Form2.jpg file, etc., by setting up the following annotation search rule:

thumbnailXpress.AnnotationSearchOrder.Add(
    new ExternalAnnotationSearchRule(
        ExternalAnnotationType.NotateXpress, //the type of annotation
        null, //no prefix is added to the annotation filename
        ".nxp", //the annotation file ends with ".nxp"
        false)); //but the annotation file does not include the original ".jpg" extension

With one line of code, you have "taught" ThumbnailXpress where it should look for external annotation data. As long as the .nxp files are present, they will be used to render the annotations.

Example 2 - Using only external annotations (ignoring internal annotations)

In the example above, we added a rule that allowed ThumbnailXpress to use annotation data stored in external .nxp files.

Now imagine that our directory contains the following files:

• Form1.tiff - an image with internal annotations
• Form1.nxp - a completely different set of annotations in an external file
• Form2.jpg
• Form2.nxp

In this case, we have a TIFF file with its own internal annotations, as well as a similarly-named external annotation file. The question is, which one will ThumbnailXpress use for its annotation data?

Since any new instance of ThumbnailXpress will automatically add internal annotation search rules to the search list by default, if we only add an external annotation rule to the list, then we have essentially told ThumbnailXpress: "I'd like you to look for annotations in this external file, but only if you don't find any internal annotations." So, in the example above, when ThumbnailXpress is rendering Form1.tiff, it will find its internal annotation data and use it; the external annotation data in Form1.nxp will not be used.

If what you really want is for ThumbnailXpress to ignore internal annotation data and always use external annotations, you should first clear the annotation search rules:

thumbnailXpress.AnnotationSearchOrder.Clear();
thumbnailXpress.AnnotationSearchOrder.Add(new ExternalAnnotationSearchRule(...));
...

Example 3 - A variety of annotations

Imagine you have a variety of image and annotation files, like so:

• building.jpg
• building.jpg.xml - external NotateXpress XML annotations for Form2.jpg
• house.png
• xfdf-house.png - external XFDF annotations for house.png
• logo.gif
• logo.annotations - external NotateXpress annotations for logo.gif
• Form.tiff - an image with internal NXP annotations, which we want
• WangAnnotations.tiff - a document with internal Imaging for Windows annotations
• Example.pdf - a document with internal XFDF annotations, which we want

And let's also imagine that you do not want internal Imaging for Windows annotations to ever be rendered.

In this case, here is one way you could set up the ThumbnailXpress annotation search rules:

//First, clear the pre-defined internal annotation search rules
//(because, for this example, we want to be more selective with which internal
//annotation types are allowed)
thumbnailXpress.AnnotationSearchOrder.Clear();

//Allow internal NXP
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.NotateXpress));

//Allow internal XFDF
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.Xfdf));

//.xml for NXP XML annotation files
thumbnailXpress.AnnotationSearchOrder.Add(
    new ExternalAnnotationSearchRule(
        ExternalAnnotationType.NotateXpressXml, //the type of annotation
        null, //no prefix is added to the annotation filename
        ".xml", //the annotation file ends with ".nxp"
        true)); //the original image file extension is part of the annotation filename

//"xfdf-" prefix for XFDF annotation files
thumbnailXpress.AnnotationSearchOrder.Add(
    new ExternalAnnotationSearchRule(
        ExternalAnnotationType.Xfdf, //the type of annotation
        "xfdf-", //the annotation filename begins with an "xfdf-" prefix
        null, //no suffix is added to the annotation filename
        true)); //the original image file extension is part of the annotation filename

//.annotations for NXP annotation files
thumbnailXpress.AnnotationSearchOrder.Add(
    new ExternalAnnotationSearchRule(
        ExternalAnnotationType.NotateXpress, //the type of annotation
        null, //no prefix is added to the annotation filename
        ".annotations", //a ".annotations" suffix is added to the annotation filename
        false)); //the original image file extension is not part of the annotation filename

This effectively amounts to saying to ThumbnailXpress:

• Don't use your default search rules, which include all internal annotation types
• Use these instead:
  1. Try to use internal NXP annotations
  2. If you can't do that, try to use internal XFDF annotations
  3. If you can't do that, try to use external NotateXpress XML annotations stored in a file of the same name with an additional ".xml" extension
  4. If you can't do that, try to use external XFDF annotations stored in a file of the same name with an additional "xfdf-" prefix
  5. If you can't do that, try to use external NotateXpress annotations stored in a file of the same name but whose extension has been changed to ".annotations"

Summary

If you only need ThumbnailXpress to render annotation data embedded in the image file itself, you simply need to connect your instance of ThumbnailXpress to an instance of NotateXpress. But if you want more control over where ThumbnailXpress should look to find associated annotation data for an image (particularly if you are using external annotation data), you'll need to "teach" ThumbnailXpress where it should search for associated annotation data by customizing the annotation search rules.

©2018. Accusoft Corporation. All Rights Reserved.