Send comments on this topic. | Back to Introduction - All Topics | Help Version 15.12.21
Implementing Annotations
Note: This topic is for Document/Medical only. Annotations are based on vectored drawing functions and are associated with bitmaps as an overlay of the displayed image. LEADTOOLS supports a number of annotation types, including lines, rectangles, hotspots, redact objects, polygons, and containers. A container is a specialized annotation object that lets you position and groups other annotation objects, including other container objects. Support for the various annotation objects is provided by the annotation object classes, which are named using a format of AnnXXXXObject where XXXX is the type of object. For a full list of available annotation object classes, refer to Types Of Annotation Objects. LEADTOOLS maintains annotations separately from bitmaps. Your application code is responsible for maintaining the relationships between images and annotations. For example, the annotation example that ships with LEADTOOLS, creates an annotation file that has the same name as its associated image file, but with a different extension. When the image file is loaded, the program looks for an associated annotation file and loads it as well.

Prior to version 14.5, annotations could be saved using the AnnCodecs.Save method in one of three formats:

Prior to version 14.5, the Native format was the preferred format for storing annotation files. In version 14.5, there is a new text-based format for annotations - AnnCodecsFormat.Xml. This is a text-based format for storing LEAD annotations that follows the XML (Extensible Markup Language) format. The Xml format is replacing the Native format as the preferred format for storing annotations.

There are many advantages of using the Xml format:

  • Unlike the Native format, the Xml format is both forward- and backward-compatible.
  • It is human readable.
  • Files using the Xml format can be easily modified using a standard text editor (i.e. notepad.exe).
  • Files using the Xml format can be easily parsed using any standard XML parser.
  • Files using the Xml format can be used with any of the growing number of utilities that work with XML.

Non-automated Annotations Non-automated annotations allow you to customize the creation of and interaction with annotations to suit your own needs. When programming non-automated annotations, it is important to remember:

  • You must provide any menus or dialogs you wish to use for entering annotation data.
  • You must also provide your own means of drawing and interacting with the annotations.
  • No hyperlink activation is provided for non-automated annotations. In addition to providing the code for entering hyperlink type and associated parameters, you must also provide the code for accessing the default web browser and calling any programs to be run through a hyperlink.
For tutorials on creating a non-automated annotation program, see Implementing a Non-automated Annotation Program and Using Non-automated Annotations in Run Mode.

Automated Annotations

Automated annotations require an automation object to be associated with a RasterImageViewer. This automation object lets you maintain default properties for all objects. For example, you can use it to set the default font and the default line width. Keep in mind, however, that scaling factors affect the appearance of these default measurements. The values are set based on the scaling factors that are in effect at the time you create the object. Features associated with automated annotations are:

  • Automated annotation menus that appear when you right-click in design mode.
  • Automated drawing that lets you use the left mouse button to draw annotations in design mode.
  • The annotation toolbar that lets you select the annotation tool to draw.
  • Programmatical handling (by LEADTOOLS) of the activation of hyperlinks and audio annotations.
  • The ability to undo/redo a number of user actions that were executed using the automated annotations functions.
The user interface for the automated annotations has several options that allow you to control the behavior of the annotation objects, including options that allow you to select whether you want to do the following:
  • Use Rotate Control Points
  • Use New Rubber Stamp Pictures
  • Maintain Aspect Ratio
  • Use New Group Edit Designer
  • Use XP Style Toolbar
  • Calibrate a ruler
For more information, refer to New Annotation Features of Version 14.5. For a tutorial on creating an automated annotation program, see Working With Automated Annotations. Annotation Classes The following paragraphs provide a brief introduction to the major classes that are used to implement support for annotations. The AnnAutomationObject class defines all the properties needed to automate an annotation object. You create an instance of this class and fill it up with the properties you want and then you add it to the Objects collection. At any time, you can enumerate the Objects collection and add or remove or modify any properties you want. The CreateDefaultObjects method creates the default AnnAutomationObject objects for the default annotation objects. LEADTOOLS will create the automation properties for the default annotation objects. You can change any property behavior by overriding members of this class or deriving your own. For information regarding default text strings used throughout the user interface in the automated mode, including information on how to override them, refer to Localization of LEADTOOLS for .NET Annotations Automation. Use the CreateDefaultObjects method to create the default automation annotation objects, and the CreateDefaultObjectContextMenu method to create the context menu associated with a certain id. You should call the CreateToolBar method after you finish setting up the automation objects in Objects or CreateDefaultObjects. After calling this method, a ToolBar is created and you can add it to your form. Use the FindObject method to find the AnnAutomationObject associated with a certain id. For a tutorial on creating user automation objects, refer to the Implement User-Defined Objects With LEADTOOLS Annotations. The AnnAutomationManager class holds the collection of all AnnAutomation objects in the application as well the annotation toolbar. Cursor, keyboard, context sensitive menus, property dialogs and various other user interface options and settings are stored here as well. An automated annotation application usually creates one AnnAutomationManager object per application. When working with annotations, the background color (the color that fills the interior) of many objects can be changed by changing the object's "brush", and line characteristics can be changed by changing the object's "pen". For more information, refer to Changing Annotation Automation Background Colors. Support for annotation brushes is provided by the AnnBrush and its derived classes, while support for annotation pens is provided by the AnnPen class. The AnnCodecs class handles loading and saving operations. The following methods let you load annotations from a file or save them to a file: The AnnContainer class represents an annotation container, a rectangular area that holds annotation objects. The container is responsible for maintaining these objects as well as drawing them upon request. The AnnDesigner class is the base class for all the designers in the annotation toolkit. An AnnDesigner derived class controls the user interface functionality involved in drawing, editing or running an object. This class provides the basic functionality common to all the designers such as hooking into a container, clipping the mouse cursor, etc. You assign an AnnContainer object to the Container member and a RasterImageViewer object to the Owner member of a designer. Then based on the exact designer functionality, it will hook into the various mouse events to draw a new, edit an existing (by moving, resizing, etc.) or run (if the container is in Run user mode) an AnnObject. The AnnDesigner classes provide the following methods as appropriate:
  • Cancel
  • DoubleClick
  • End
  • EndClipCursor
  • EndWorking
  • GetLogicalAnnPoint
  • HookContainer
  • MouseDown
  • MouseMove
  • MouseUp
  • Move
  • MoveControlPoint
  • MoveName
  • OnAfterDrawingObjects
  • OnDraw
  • OnEdit
  • OnRun
  • Start
  • StartClipCursor
  • StartWorking
  • Working
The AnnDrawable class is the base class for all annotation objects used in the Annotations class library. This class holds common drawing information shared by all annotation objects in the Annotations class library. You can query the properties of this class to easily figure out if a certain class supports pen, brush or font and quickly change them. For example, the Properties dialogs used in the automation mode do just that to test whether to display the pen options. The AnnPrinter class supports printing of an RasterImage and a AnnContainer. The AnnPrinter class derives from RasterImagePrinter to make the process of printing an AnnContainer on top of an RasterImage easier. Printing using the .NET framework involves adding a handler to the PrintPage event. In that event handler, you set up a new instance of the AnnPrinter class, set up its properties as desired, and then call the Print method passing it the RasterImage to print, the image page number, the AnnContainer containing the annotations objects to be printed and the PrintPageEventArgs object obtained through your PrintPageEventHandler. The AnnTransformer class is an Annotation support class which provides functionality for converting annotation points, rectangles, lengths, etc. from one coordinate system to another. This class derives from the Transformer class and provides extra functionality to deal with annotation-specific objects. The units of measure are taken into consideration and transformed objects retain the same units as the originals. Events Use the following events to adapt your application: Annotation Object Names You can use annotation object names to differentiate between multiple objects in a container. LEADTOOLS does not use the object name in any special way and the value has no special meaning. For information on using annotation object names, refer to Annotation Object Names. Annotation Interfaces LEADTOOLS provides several interfaces for use with the various annotation objects in automation mode. In automation mode the annotation framework uses the appropriate interfaces to display dialogs, with the appropriate tabs, for the annotation objects. The IAnnPictureObject interface supports standard picture properties used by annotation objects from those classes that implement this interface. The IAnnPrimarySecondaryPictureObject interface supports standard primary and secondary picture properties used by annotation objects from those classes that implement this interface. The IAnnProtractorObject interface is used by the annotation framework to draw a protractor. The protractor annotation object consists of two rulers joined at a point to create an angle. The IAnnRulerObject interface is used by the annotation framework to draw a ruler. The IAnnTextObject interface is used by the annotation framework to draw a text string. User Interface, Automation Mode For information regarding default text strings used throughout the user interface in the automated mode, including information on how to override them, refer to Localization of LEADTOOLS for .NET Annotations Automation. The following methods and properties support Windows clipboard operations: The following methods let you group or ungroup annotation objects: The AnnNewGroupEditDesigner class extends AnnRectangleEditDesigner class to provide functionality for editing an AnnGroupObject annotation object on an annotation container. This class has improved resizing and rotate functionality over the AnnGroupEditDesigner class. For more information on grouping and ungrouping, refer to Grouping and Ungrouping Annotation Objects. The LEADTOOLS annotation features include an Undo engine for undoing annotation automation operations. The AnnAutomation.UndoCapacity property specifies the number of operations that can be undone. The default is 10 actions. LEADTOOLS provides a number of methods and properties for handling undo capabilities in non-automated operations. For more information, refer to Undoing Automation Operations. Use the UserMode property to get or set the current user mode. AnnUserMode.Design is for creating objects; AnnUserMode.Run mode is for viewing them. Switching the user mode toRun automatically hides the automation ToolBar . Setting the user mode toDesign displays the ToolBar. The UserModeChanged event is fired whenever the UserMode property is changed. The following properties and methods let you create and customize the interface used in automation mode: For a tutorial on creating an automated annotation program, see Working With Automated Annotations.