Global 360 Annotation Specification, Version 1.00.06

This document describes the proposed annotation extension developed for TIFF 6.0 by Global 360 to provide information for creating and reading annotation data. This document

·         Defines annotation data and lists available annotation marks.

·         Describes the format of annotation data that is stored in TIFF 6.0 files.

·         Explains the annotation mark attribute structure.

·         Discusses named blocks and defines the annotation named block structures.

·         Defines each type of annotation mark and summarizes the associated attributes and named blocks.

Alternative Implementation

An alternative way to create annotation data is available in all versions of the Imaging for Windowsâproduct:

 

·         Imaging for Windows 95

·         Imaging for Windows 98

·         Imaging for Windows NT 4.0

·         Imaging for Windows Professional Edition

 

Each version of Imaging for Windows includes ActiveX (OLE) controls that provide a higher-level interface to the creation of annotation data. In particular, the Image Edit control and the Image Annotation Tool Button control include properties, methods, and events that enable application engineers to implement programmatic generation of annotations. ActiveX methods are callable from many programming environments, including Visual Basic and Visual C++.

Annotation Data

Annotation data is stored information about simple drawings or notations. These drawings or notations are referred to as annotation marks. The following types of annotation marks are available.

 

Attach-a-note

Image reference

Filled rectangle

Straight line

Form

Typed text

Freehand line

Text from file

Hollow rectangle

Text stamp

Image embedded

OCR region

Note: The OCR region annotation type is available with Imaging for Windows Professional Edition only.

 

Processing of Annotation Data in TIFF Image Files

Annotation data is included as part of a TIFF image page. It is accessed using a private tag in the page image file directory (IFD), as follows:

 

                      Tag ID = 32932 (decimal)

                      Tag Data Type = BYTE

                      Tag Data Count = size of annotation data

                      Tag Val/Offset = file offset to annotation data

Annotation Data File Format

The data associated with an annotation tag in a TIFF file consists of zero or more blocks of default data, followed by the data necessary to describe each annotation mark. Default data consists of default named blocks, designated Type 2 data. Annotation mark data consists of an attribute structure, designated Type 5 data, followed by one or more named blocks, designated Type 6 data.

 

The annotation data itself consists of a 4-byte header, which is not currently used (reserved for future use). The header should be skipped on read and written as zeros. Note, however, that it is included in the TIFF tag's Data Count field. The header is followed by four bytes in Intel order that specify size of INTs and UINTs and byte ordering:

 

4 bytes  0 = Intel 16-bit  (least-significant byte to most-significant byte and two-byte INTs and UINTs)
1 = Intel 32-bit      (least-significant byte to most-significant byte and four-byte INTs and UINTs)

                               

                                 

 

Default data and mark data follow:

 

4 bytes   =  type of data (integer 2, 5, or 6, as explained below)

4 bytes   =  size of data (not including named block data)

Variable data follows, depending on the data type.

                                

Supported Data Types

The following data types are supported:

 

                             

 Type  = 2 

A default named block.

Data in this block will be part of each newly-created mark.

Data consists of the following named block structure:

8 bytes  =  name of named block

4 bytes  =  size (n) of named block

4 bytes  =  reserved. Only present and necessary with  Intel 16-bit format. Skip on read and write as zeros.

n bytes  =  named block data
Type  =  5  

The attribute structure of the next annotation mark.

This type also implies the end of the previous mark’s data,
  erefore the beginning of an annotation mark.

Data consists of the attribute structure.

  Must be followed by one or more named blocks of type 6.
Type  =  6

A named block that is part of the preceding annotation mark.

Data consists of the following named block structure:

8 bytes  =  name of named block

4 bytes  =  size (n) of named block data

 bytes  =  reserved. Only present and necessary with  Intel 16-bit format. 

Skip on read and write as zeros.

n bytes  =  named block data

                 

Annotation Mark Attributes

All annotation marks have a set of attributes associated with them. Attributes that do not apply are ignored.

Attribute Structure

typedef struct tagOIAN_MARK_ATTRIBUTES{

UINT uType;                                   // The type of the mark.
                                                                // 1 = Image embedded
                                                                // 2 = Image reference
                                                                // 3 = Straight line
                                                                // 4 = Freehand line
                                                                // 5 = Hollow rectangle
                                                                // 6 = Filled rectangle
                                                                // 7 = Typed text
                                                                // 8 = Text from file
                                                                // 9 = Text stamp
                                                                //10 = Attach-a-Note
                                                                //12 = Form
                                                                //13 = OCR region

LRECT lrBounds;                             // Rectangle in FULLSIZE units; equivalent to type RECT.
                                                                // Can be a rectangle or two points.

RGBQUAD rgbColor1;                             // The main color; for example, the color of all lines,
                                                                // all rectangles, and standalone text.

RGBQUAD rgbColor2;                             // The secondary color; for example, the color of the text of
                                                                // an Attach-a-Note.

BOOL bHighlighting;                     // TRUE ¾ The mark is drawn highlighted. Highlighting
                                                                // performs the same function as a highlighting marker on a
                                                                // piece of paper. Valid only for lines, rectangles, and
                                                                // freehand.

BOOL bTransparent;                      // TRUE ¾ The mark is drawn transparent. A transparent
                                                                // mark does not draw white pixels. That is, transparent
                                                                // replaces white pixels with whatever is behind those pixels.
                                                                // Available only for images.

UINT uLineSize;                             // The width of the line in pixels.

UINT uReserved1;                        // Reserved; must be set to 0.

UINT uReserved2;                        // Reserved; must be set to 0.

LOGFONT lfFont;                    // The font information for the text, consisting of standard
                                                                // font attributes of font size, name, style, effects, and
                                                                // background color.

DWORD bReserved3;                        // Reserved; must be set to 0.

time_t Time;                                    // The time that the mark was first saved, in seconds, from
                                                                // 00:00:00 1-1-1970 GMT. Every annotation mark has
                                                                // time as one of its attributes. If you do not set the time before
                                                                // the file is saved, the time is set to the date and time that the
                                                                // save was initiated. This time is in the form returned by the
                                                                // "time" C call, which is the number of seconds since
                                                                // midnight 00:00:00 on 1-1-1970 GMT. If necessary, refer
                                                                // to your C documentation for a more detailed description.

BOOL bVisible;                                // TRUE ¾ The mark is currently set to be visible.
                                                                // Annotation marks can be visible or hidden.

DWORD dwReserved4;                // Reserved; must be set to 0x0FF83F.

long lReserved[10];                      // Must be set to 0.

}OIAN_MARK_ATTRIBUTES;

 

Note: The OCR region annotation type is available with Imaging for Windows Professional Edition only.

Annotation Named Blocks

A named block can be used to hold any data for any purpose; for example, named blocks can be used to store

·         Internal mark data

·         Public mark data

·         Group information

·         Selection operations criteria

·         Access control data

 

A named block is a block of data that is referenced by an 8-byte name. The data is structured as follows:

 

8 bytes  =  name of named block

4 bytes  =  size (n) in bytes, of named block data

4 bytes  =  reserved. Only present and necessary with Intel 16-bit format.
                   Skip on read and write as zeros.

n bytes  =  named block data

Named Block Conventions

·         The name of a named block is case sensitive; for example, ABC is not the same as aBc.

·         The named block name is left-justified and padded with nulls to eight bytes. All eight bytes are used and compared regardless of content.

·         All annotation marks allow any number of named blocks to be associated with them. Each named block is associated with one and only one structure. A mark cannot have multiple blocks with the same name.

·         All names beginning with Oi (Oixxxxxx) are reserved.

Reserved Named Blocks

The reserved named blocks defined for annotation marks and their associated structures and usage are as follows:

 

Named Block

Associated Structure

Usage

OiAnoDat              For lines:

AN_POINTS

List coordinates for lines and freehand marks.

                                For images:

AN_NEW_ROTATE_STRUCT

Hold scaling and resolution information for image marks.

OiFilNam

AN_NAME_STRUCT

Hold file name for image marks.

OiDIB

AN_IMAGE_STRUCT

Store DIB data.

OiGroup (required)

STR

Create sets of marks (required).

OiIndex (required)

STR

Assign unique number, originating at 0, for each mark. To facilitate easy application control, the next available number is generated by incrementing by 1 the number just assigned and storing it in the default OiIndex mark.

OiAnText

OIAN_TEXTPRIVDATA

Display text annotation marks.

OiHypLnk

HYPERLINK_NB

Turn mark into a hyperlink.

 

Note: The Hyperlink annotation type is available with Imaging for Windows Professional Edition (read/write) and Imaging for Windows 98 (read only).

Named Block Structures

The structures used by annotation named blocks are as follows:

 

Structure

Definition

 

AN_POINTS

 

 

typedef struct tagAnPoints{

    int nMaxPoints;                // The maximum number of points; must
                                                // be equal to the value of nPoints.

    int nPoints;                       // The current number of points.

    POINT ptPoint[1];            // Points marking the beginning and
                                                // ending of the line segment(s); in
                                                // FULLSIZE (not scaled) coordinates
                                                // relative to the upper left corner
                                                // of lrBounds in
                                                // OIAN_MARK_ATTRIBUTES.

} AN_POINTS;

 

AN_NEW_ROTATE_STRUCT

 

typedef struct tagAnNewRotateStruct{

    int rotation;                       // 1=Original
                                                // 2=Rotate right (90 degrees clockwise)
                                                // 3=Flip (180 degrees clockwise)
                                                // 4=Rotate left (270 degrees clockwise)

                                                // 5=Vertical mirror (reflected around a
                                                // vertical line)

                                                // 6=Vertical mirror + Rotate right
                                                // 7=Vertical mirror + Flip
                                                // 8=Vertical mirror + Rotate left

    int scale;                            // Set to 1000.

    int nHRes;                         // Set to value of nOrigHRes.

    int nVRes;                         // Set to value of nOrigVRes.

    int nOrigHRes;               // Resolution of image mark in DPI.

    int nOrigVRes;                // Resolution of image mark in DPI.

    BOOL bReserved1;          // Set to 0.

    BOOL bReserved2;          // Set to 0.

    int nReserved[6];

}AN_NEW_ROTATE_STRUCT;

 

AN_NAME_STRUCT

 

typedef struct tagAnNameStruct{

    char name[1];                    // A character string designating the
                                                // filename; terminated with a NULL.

}AN_NAME_STRUCT;

 

AN_IMAGE_STRUCT

typedef struct tagAnImageStruct{

    BYTE dibInfo[1];              // Standard DIB.

}AN_IMAGE_STRUCT;

 

STR

 

Character string.

For OiIndex, a 10-character string holding a unique number, left-justified and padded with nulls.

For OiGroup, a null-terminated string giving the name of the group that the mark belongs to; the default is [Untitled]\0.

 

OIAN_TEXTPRIVDATA

 

typedef struct tagOiAnTextPrivData{

    int        nCurrentOrientation;          // Angle of text baseline to image
                                                                // in tenths of a degree; valid
                                                                // values are 0, 900, 1800, 2700.

    UINT   uReserved1;                         // Always 1000 when writing;
                                                                // ignore when reading.

    UINT   uCreationScale;                   // Always 72000 divided by
                                                                // the vertical resolution of the
                                                                // base image when writing;
                                                                // Used to modify the
                                                                // Attributes.lfFont.lfHeight
                                                                // variable for display.

    UINT   uAnoTextLength;               // 64K byte limit (32K for multi-
                                                                // byte data) for Attach-a-Note,
                                                                // typed text, text from file;
                                                                // 255 byte limit for text stamp.

    char      szAnoText[1];                     // Text string for text mark types.

}OIAN_TEXTPRIVDATA;

HYPERLINK_NB

int           nVersion;               // The version number of this data.

int           nLinkSize;              // The size of the link string in bytes.

char        szLinkString;         // The variable length multi-byte

                                                // name string.

int           nLocationSize;      // The size of the location string.

char        szLocationString;// The variable length multi-byte

                                                // location string.

int           nWorkDirSize;      // The size of the working directory string.

char        szWorkDirString;// The variable length multi-byte

                                                // working directory string.

int           nFlags;                   // One or more of the following flags

                                                // OR’ed together:

                                                // 1 = Can remove hyperlink from mark.

                                                // 2 = Hyperlink refers to this document.

 

 

Note: The Hyperlink annotation type is available with Imaging for Windows Professional Edition (read/write) and Imaging for Windows 98 (read only).

Annotation Marks

There can be any number of annotation marks on an image, and any number of named blocks on a mark. Every mark must be at least five pixels in from the edge of the image.

 

The following alphabetical listing of supported annotation mark types defines each mark and specifies its attributes and named blocks.  Note that all mark types require the uType, lrBounds, and bVisible attribute.

Attach-a-Note

Definition

A colored rectangle that contains text.

Attributes

rgbColor1, rgbColor2, lfFont

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               OIAN_TEXTPRIVDATA

Filled Rectangle

Definition

A rectangle with a filled center.

Attributes

rgbColor1, bHighlighting

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               Not used

Form

Definition

A black and white image included by indirect reference. Only one form mark is allowed per image. It is placed on top of the base image before all other marks. If the image is not found at display time, an error is returned.

Attributes

bTransparent (must be set)

Named Blocks and Associated Structures

OiAnoDat              AN_NEW_ROTATE_STRUCT

OiFilNam                AN_NAME_STRUCT

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               Not used

Freehand Line

Definition

A series of lines such that the starting point of line n+1 is the same as the ending point of line n.

Attributes

rgbColor1, bHighlighting, uLineSize

Named Blocks and Associated Structures

OiAnoDat              AN_POINTS

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               Not used

Hollow Rectangle

Definition

A rectangle with a center that is not filled.

Attributes

rgbColor1, bHighlighting, uLineSize

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               Not used

Image Embedded

Definition

An embedded image.

Attributes

bTransparent

Named Blocks and Associated Stuctures

OiAnoDat              AN_NEW_ROTATE_STRUCT

OiFilNam                AN_NAME_STRUCT

OiDIB                     AN_IMAGE_STRUCT

OiGroup STR

OiIndex                  STR

OiAnText               Not used

Image Reference

Definition

An image included by reference. If the image is not found at display time, an error is returned.

Attributes

bTransparent

Named Blocks and Associated Structures

OiAnoDat              AN_NEW_ROTATE_STRUCT

OiFilNam                AN_NAME_STRUCT

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               Not used

 

Note:  To reference images at different locations on different PCs, you can use the following technique to specify the image filename. For example, to reference c:\oi\bw.tif, first define a section in the win.ini file called [O/i ImagePath], with an entry such as x=c:\oi\, where x is an integer from 1 to 9. After this setting is defined, use the filename x:bw.tif to access c:\oi\bw.tif. The path specified for x (c:\oi\) concatenates with what follows after the colon in the filename (bw.tif) to produce c:\oi\bw.tif.

Straight Line

Definition

A line with a defined starting and ending point.

Attributes

rgbColor1, bHighlighting, uLineSize

Named Blocks and Associated Structures

OiAnoDat              AN_POINTS

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               Not used

Typed Text

Definition

A series of characters entered from the keyboard.

Attributes

rgbColor1, lfFont

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               OIAN_TEXTPRIVDATA

Text From File

Definition

Text supplied from a file. The file format is Text Only, which is only ASCII with carriage returns, line feeds, and tabs.

Attributes

rgbColor1, lfFont

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               OIAN_TEXTPRIVDATA

Text Stamp

Definition

Text that contains a pre-defined string which may include, for example, the date and/or time when the mark was applied.

Attributes

rgbColor1, lfFont

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               OIAN_TEXTPRIVDATA

OCR region

Definition

An rectangular region in which to perform OCR.

Attributes

rgbColor1, lfFont

Named Blocks and Associated Structures

OiAnoDat              Not used

OiFilNam                Not used

OiDIB                     Not used

OiGroup STR

OiIndex                  STR

OiAnText               OIAN_TEXTPRIVDATA

                                (This will contain a sequential

                                number string).

 

Note: The OCR region annotation type is available with Imaging for Windows Professional Edition only.