Annotation Files

In the February issue of EMME/2 News we have discussed in detail the interactive aspects of working with annotations (see also section III-6.4 of the EMME/2 User's Manual). In this issue, we shall have a closer look at the format of the annotation files annotx. Understanding the protocol used in these files opens the possibilities of manipulating annotation files directly with a text editor, such as modifying existing annotations, combining different annotation files into one, or splitting annotations. When the information to be included in an annotation is already available in some other format, it might also be more efficient to create an annotation file directly from this data, rather than entering it interactively on the screen.

An annotation file is an ordinary sequential text file that contains the annotation information as a sequence of simple commands. The command protocol is very similar to a plotter command language, with commands to move or draw to an address, to write a text and to change color, line pattern and text attributes. It should be noted, however, that the commands contained in an annotation file differ in format and structure from the interactive commands used when an annotation is created interactively at the screen.

A command always occupies one line in the annotation file. The first character of the line is the command character followed by the command specific parameters. The parameters consist of one or two numerical values and an optional text. The parameters are read using the usual EMME/2 free format conventions. The following table contains a list of the currently supported annotation file commands in alphabetical order:

COMMAND CMD PARAMETER 1 PARAMETER 2 TEXT

Define text direction a delta X delta Y -

Change color c color index - -

Draw to point d X-coordinate Y-coordinate -

End annotation e bit pattern - -

Change line pattern l line pattern - -

Move to point m X-coordinate Y-coordinate -

Define text size/slant s text size text slant -

Write text at position t X-coordinate Y-coordinate text

Select coord. units u 0=hardware def text size - 1=user coord.

The select coordinate units command u specifies if the following addresses are to be interpreted as user coordinates or as hardware coordinates. The command remains active until the next u command. At the beginning of an annotation, the coordinates default to hardware units. Vectors and text drawn in hardware coordinate mode may use the entire screen and appear always at the same place on the screen, independent of the current network window displayed. When user coordinate units are selected, the annotations are defined on the network plane and only the part of the annotation that is contained within the current network window is displayed on the screen. The optional second parameter "text size" can be used to indicate the default text size for texts written in user coordinate mode.

The drawing of vectors is accomplished by using the move to point and draw to point commands m and d. By default, color index 1 (white on screen/black on paper) and line pattern 1 (solid line) are used, but can be changed using the change color and change line pattern commands c and l.

A text is placed at a specified position using the t command. The address corresponds to the lower left corner of the first character written. By default, the text uses a size of 12 hardware units, no slant and is written horizontally from left to right. The text size and slant can be set by the s command. The text size is specified in hardware or user units, depending on the current coordinate system set by the last u command. The length of the text is limited to a maximum of 60 characters. The slant is defined as the tangent of the slant angle, e.g. 0 corresponds to no slant, .5 to a forward slant of about 30 degrees and -.2 to a backward slant of about 12 degrees. The text direction (or angle) can be changed with the a command. The delta-X and delta-Y parameters specify the direction along which the text is generated. In order to set the direction to an arbitrary angle , the command

a

can be used. Note that only the angle of the vector spanned by (delta-X,delta-Y) is used, but not its length - thus the units used are not important.

The command e indicates the end of an annotation file. It is usually not needed, since the end of an annotation corresponds also to the physical end of the file. An exception to this rule is the current interactively entered annotation file annot0, where the e command is used to indicate which annotations a-z have been previously superimposed. The parameter is defined as a bit pattern (bit0="a", bit1="b", ...) indicating the subset of annotations a-z which are be superimposed. Note that the e command is ignored if it appears in files other than annot0.