The Annotator

Suppose you are an historian, studying old sketches, and you have one digitised as a bitmap picture. (Or, you might be a space scientist, studying the recent photographs of the surface of one of Jupiter's moons.) You want to annotate the picture, drawing shapes around significant features and attaching meaning to them. Annotator is designed to help you do this.

Here's a simple example. Note the picture is monochrome while the annotation marks are in colour. Some are rectangles or polygons, showing various items of interest; some are lines showing relationships. The Annotator makes use of the Amiga's Dual PlayField graphics mode to keep the annotations separate from the picture - as though you were drawing on a sheet of glass covering the picture - so keeping the picture clean. Example annotation (Best view on Amiga)

Features of Annotator

Annotator is not just a drawing program. It is not just a database. The special thing about Annotator is that it links drawn marks with a knowledge base of what those marks mean. It links

Moreover, it is designed to be easier to use than many drawing packages and to employ a more powerful, more flexible data model than many databases. Here is a brief list of some of its features:

How to use Annotator

Getting Started

1. (Installing Annotator: Download Annotator from (notyet). Then decrunch using LHA. Then install it by double-clicking on the Install- Annotator icon.)

2. Start Annotator by double-clicking on its icon, in the normal way. You are presented with an initial control screen.

3a. New picture? (To get existing one, see below.) Hit the 'New' button and you will be asked which picture you wish to annotate. Select one. A few examples have been included with the program. Your picture should normally be monochrome or few colours for best results.

3b. Existing picture? Hit the 'Get KB' button. (KB stands for 'knowledge base', since you are storing your knowledge and beliefs and interpretations along with the picture.) You will be asked for your KB file. A simple one is supplied - Execution, which shows an execution in progress with a few annotations.

4. Now start drawing, using the mouse, as follows ..

Drawing New Things

To Modify Existing Things

Semantics: What Your Marks Stand For

Your drawn marks are more than marks: they mean something. In particular, each thing usually has a name and/or a meaning. In addition there can be any number of attributes, and relationships to other things.


Items are individual things, or objects, that you wish to pick out on your picture, such as:* In drawing an item you are separating it out from its background (the picture) because it is meaningful to you.

Most items are expressed by coloured rectangles or polygons on top of the picture. To draw an item, simply press left mouse button and draw a rectangle in the time-honoured way. Then an Attributes Panel comes up into which you can fill:

There are various types of item, and you can create new types as needed. For a new KB (new picture) you are given the following types for free:

(though this list might change with new versions). They are shown at the start of the Item Type List in the KB Panel. (The other item types are special for the system's use; they have been left in view so you can gain some idea of them but I don't *think* you will come to any grief if you draw them; it's just that they won't be very useful to you at present.)

At any time you can bring up the item's Item Details Panel which presents all the details of the item, including its name, its colour and line pattern, its attributes and all things it is related to. And you can alter many of these, such as adding new attributes to it.


Attributes belong to items (and scenes) and hold values that describe your items. Think of items as nouns, and attributes and their values as adjectives. Attributes hold the 'data' of your items, for instance that the signified hanging occurred in 1471 and from this you might infer that it was part of the violent backlash against the peasant revolt.

By standard, each item starts with four attributes:

and you are invited to enter the values of these when the item is first drawn. Note, the Name and Meaning of an item are not true 'attributes', though you enter them at the same time; they cannot be got rid of though they can be made blank.

You can enter their values, or change their values, later on via the Item Details Panel - by selecting the attribute and hitting the nearby 'See' button, which brings up the Attributes Details Panel.

You can also add new attributes to the item (and get rid of unwanted ones) via the Item Details Panel - entering a name, selecting a type and hitting the 'Add' button. Note that you can do this at any time and are not, as in most databased systems, restricted to doing it at creation time. For instance, you might want to add something about the style in which the item was drawn.

To create a new Attribute Type hit the Att Types button on the KB panel and up comes the Attributes Types Panel. On the left hand side, enter a Name, select a Type of value for it and hit the Add button. The right-hand list is of names given to enumeration or ordinal types.


Relationships are used to link items together in a way that carries meaning for you. Most relationships are expressed as lines between items. The main relationship you will use will be the Normal Link.

To draw a relationship, simply:

( Oops. No line is drawn? Normally this means you haven't released over another item's line. Try again. It doesn't start drawing a line but rather draws a rectangle instead? It's drawing another item, probably because you have not pressed the mouse exactly over an item. Try again.)


Many pictures, especially of the more complex sort found in historical drawings, contain a number of scenes. Different things are happening in different parts. It is useful to link all items in that area into a scene - or into more than one.

You can draw a scene - usually a large green/red dashed rectangle - quite easily, just as you would draw an item. After that, any items that lie partly within that scene are linked to the scene by the 'Contains' relationship. There are two ways of drawing a scene:

The use of scenes is up to you, but they give a visual grouping and an automatic linking (unlike Topics, which you have to set up and link specially. More importantly, when exporting your annotation scenes are recognised as special entities.


In most annotations you will have a number of significant topics - such as death, love, money - by which you might want to index your items and scenes. The Topics facility of Annotator allows you to:

There are two ways to define Topics. One way, not really recommended, is to select the Topics Item Type and draw boxes representing them on the picture. Not recommended, cos it clutters up the picture, but you might want to do it for some reason. The recommended way is to hit the Topics button on the KB Panel to bring up the Topics Control Panel. Then you enter the name for the topic and hit the 'Add' button. You can add several in this way and then either leave the panel up or hit 'Done' button. Note that topics created in this way have no visual expression on the picture.

There are two ways to link items (and scenes) to topics. One way, not really recommended, and only relevant to topics drawn onto the picture, is to select the Topic Relationship Type and draw a relationship from the topic box to the item box. Not recommended cos if you draw the relationship in the reverse direction (from item to topic) then the link is not recognised as a true Topic link - and it is very easy to forget in which direction to draw it. The recommended way it to bring up the item's (or scene's) Item Details Panel and hit the Topics button you will find there. This presents a list of topics and checkboxes which you can hit to link or unlink the item to topics.

To highlight a topic bring up the Topics Control Panel by hitting the Topics button on the KB Panel. On this, hit the 'Hide All' button to erase all visible things from the picture (don't worry; they are still there, just invisible). Then select a topic in the list and hit the 'Show' button. All items linked to that topic will then be displayed. Select another topic and hit 'Show' and these become displayed too. To bring back all the items, hit the 'Sh' button next to the 'Curr Pic' button on the KB Panel.


When you are analysing things you often want them in groups, not one by one. You might want to see all the persons who are kneeling, because those people are likely to be paying homage. Or all who are gazing at people who are kneeling. The lists feature helps you do this.

The Lists facility allows you to create sets or lists of items etc. that are meaningful and then display them, export them, etc. For instance, you can create a set of all items later than a particular date. To see it, hit the Lists button on your KB Panel.

Up comes a rather complex panel, the Lists Panel. Don't be frightened: it's in three main parts:

But how do you create a list? This is what the rest of the panel is about.

Then, when you hit the 'DoIt' button, Annotator will go through all things in the source and apply the selection criteria to each, and all those chosen will be placed in a new list. (For those who know databases, it is a bit like the standard SQL SELECT .. FROM .. WHERE .. statement, but Annotator allows you to do joins and counts a bit more easily.)

The source can be one of:

Now that you have specified your source, you must say whether you want all the things found or to select from them:

At the bottom of the panel is the 'DoIt' button which, when you hit it, makes the new list. First thing that happens is an Item Details Panel comes up for the 'new list'. You should rename it as needed and hit 'OK'. Then at the top of the panel, select it as current list and hit 'Show them' button, to see those things selected in the list.

You can also 'Export them' as text form to a file.

Want a more complex selection? For instance, all those that are both kneeling and also being gazed at? Well, you do this step by step:


Values are the contents of attributes, and can be either Quantitative values are numeric, such as 25, 0.75, 1997, while qualitative values are non-numeric, such as labels like 'Monday' or longer text strings. At present Annotator has a wide range of value types that have been brought over from another program (the Istar knowledge based system creator) and most will probably be irrelevant to your needs at first - such things as compass directions, odds, ratios, probabilities, bayesians, proportions, etc. - though you are free to use them as you wish. In future it is planned to add more meaningful types.

A particular type of interest in most applications is the Enumerator or Ordinal value. This allows you to set up sets of discrete values like the days of the week or types of weapon ('Sword', 'Bow', 'Axe', 'Dagger'). To do this, bring up the Domains Management Panel, select type 'Enum' or 'Ordinal', give it a name (e.g. 'WeaponType') and hit the 'Add' button. Then move ove to the right hand list, enter the name for the first one (e.g. 'Sword') and hit the right hand 'Add'. Repeat for each type. The difference between Enumerator and Ordinal is that the latter has a numeric order while the former doesn't. (So, 'Very Strong', 'Strong', 'Weak' would be an ordinal while 'Sword', 'Axe', 'Bow' would form an enumerator.)

Software Features of Annotator


At present, you can only export lists.


Templates are wee knowledge bases that hold a selection of item, attribute and relationship types suited to certain types of picture. You can make up your own, either from scratch or from an existing one. They are like normal knowledge bases but lacking a picture. When you hit the 'New' button a template will be loaded to go with your picture; they are located in the Ann:Templates drawer.

Which template is loaded? Normally the one called Template.std. So you can copy any of the others to it, as you need, before starting the Annotator. Or, better, hit the Prefs button on the main control panel and you can select the file you want to act as a template.

To create your own template from scratch, you will be given a knowledge base without any user types, and you create attribute, item and relationship types in that order:

Annotator Panels

Item Details Panel

There is one of these panels for each item, scene or list, and any number can be open at a time (though like any Amiga Window, you must send-to-back or bring-to-front to find the one you want. Each gives details on one item and allows you to change things of it. It also allows you to move to related items' panels.

Item Details Panel (Best view on Amiga)

There are five main parts to the panel:

The 'See' buttons allow you to traverse to related things. Simply select the thing and hit the See button. Note that you can add attributes to, and get rid of attributes from, an item indepentently of its item type.

Relationship Instance Details Panel

This panel shows details of a relationship, that is a link between two items or other linked things. The main thing of interest is its type and the two things at either end of it. You can alter the type by hitting the wee button to left of type. Also there is a short list gadget showing attributes of the relationship, if any.

The 'Delete' button will delete the relationship, and also erase its visual graphic.

Attribute Details Panel

This panel shows details of an attribute, allowing you to set its value or change its name or meaning. You can also change its type.

Adding an Attribute

To add a new attribute to an item or anything else:


Domains are sets of values that are meaningful to you. They are what attributes of items (and relationships) are linked to as their 'type'. You can create new domains anytime you like, e.g. when adding an attribute to an item or item type. You can also create many of them at one sitting using the Domains Management Panel.

Creating a New Domain

You can create new domains while in the middle of adding an attribute and you see there is no suitable domain; merely hit the New Domain button on the Add Attribute panel. Or you can hit the Domains button on the KB Panel, which allows you to create several domains at once, say when setting up a KB, and allows fuller entry of details.

In the former case, when you hit the New Domain button, a panel comes up showing a list of Value Types, such as Integer, TextString, Probability. There are three simple steps:

And your new domain should now appear in the Domains list so you can select it.

Domains Management Panel

In the latter case, when you hit the Att Domains button, you are presented with a larger panel, with two lists. The left hand list is of currently available domains. Below it are three boxes which allow you to create new domains or modify existing ones. To create a new domain, enter Name (N) and Meaning (M) and choose Type, then hit the Add button. To update an existing domain, select it from list, make the changes to Name, Meaning or Type and hit the Update button.

The right hand of the panel holds lists of labels associated with certain types of domains called Enumerated or Ordinal types, such as days of week ('Sunday', 'Monday', etc.). You can add new labels by entering the label in the N box and hitting the Add button. (To be written properly.)

Standard List Gadgets

Many panels show a standard list gadget, which is a ListView gadget surrounded by several other ones that take action on the list. In some of the lists some buttons might not be relevant and so are missing. Also, there is a slight difference between lists of related items and other lists. The buttons are as follows:

KB Panel

There is one of these KB Panels for each Knowledge Base loaded. It allows you to do things at the whole-KB level such as saving it and also selecting the item type or relationship type since these are common to all pictures in the KB.

KB Panel (Best view on Amiga)

Written by, and copyright (c) 1997 of, Andrew Basden.

Email questions or comments would be welcome, especially if they aid exploration and enriching of the ideas. Last modified 5 June 1997. Number of visitors to these pages: Counter. Written on the Amiga and Protext.