Tour 7:  Annotating Maps for Programmers

This is an advanced topic! Most users never need to worry about Meta tags.

Skip to the [ next tour 8 ] 

Advanced Topic: Annotating Maps for Programmers

When viewing a map, press F8 to display the Waypoint Editor. The Waypoint Editor is automatically shown after adding a waypoint using the F2 key.

The status line of the Waypoint Editor shows the current cursor position 'line: column'.

The format for a Waypoint is:

A waypoint file can be as simple as a list of map coordinates followed by text that you would like displayed at the coordinate. For example:

will display the text 'Utah State Capitol' at the front steps of the capitol:

A variety of other annotations features can be added using Meta Tags:

• Lines that connect waypoint locations: line styles and colors
• Symbols: draw scaled boxes, lines, arrows over map images
• Text location, size, style and colors

In addition, you can use the waypoint file to:

• Set the title displayed on the 'All Topo Maps' program
• Set the {Measurement Spike} location
• Automatically Center the viewer over a map location

The location may be entered in any reasonable format.

All characters after the semicolon ';' are included as the Waypoint Comment. You may place file note lines anywhere in the waypoint file by placing a ';' as the first non-space character on the line.

After you manually edit Waypoints in the Waypoint Editor, you should select the Reannotate menu option to reload the Waypoints onto the map surface.

2000 Waypoints can be read from a Waypoint File and displayed at once.

You can use the Jump button, or right-mouse-click 'Jump To This Waypoint' to move the map to center a location in the Waypoint Editor on the screen.

You can convert all of the <locations> in a Waypoint file to other coordinate formats using the 'Convert' menu option.

Coordinate Entry

You may enter coordinates in the Waypoint Editor using Decimal Degrees, Degrees Decimal Minutes (GPS Style), Degrees Minutes Seconds or UTM:

You may include degree, minute and second symbols (° " ') or you may leave them off.

UTM coordinates must have a ‘Z’ or ‘Zone’ before the zone number.

All Topo Maps allows a great degree of flexibility when entering map coordinates, however be sure to include the minus sign (or compass direction) for longitudes:

but NOT

Latitude may be listed first or second:

or

But, be careful, if the coordinates are ambiguous, longitude (the X or East-West coordinate) will be assumed to be first unless the direction is explicitly listed as NSEW:

Degree, Minute, Seconds marks and commas may be included or omitted:

or

Compass direction may be indicated by NSEW or sign:

or

Waypoint Comments

Any text may be placed after a semi-colon ‘;’:

If you do not place a semi-colon at the end of the coordinate:

the coordinate will be annotated with the default style set by the coordinate display box

To only display the marker symbol (no text), include a semi-colon without any text:

If you would like to place a multiple line comment at a location, use the pipe symbol '|' to start a new line. (The pipe symbol, is typically found as the uppercase backslash key '\' on your keyboard.) For example:

will place a three line comment on the map:

Jumping To A Waypoint

Once a Waypoint is entered into the Waypoint Editor, you can instantly jump to it.

Place the Waypoint Editor’s text cursor on the desired waypoint line, then right-click and select ‘Jump to This Waypoint’ (or press Alt-J). The correct map will be displayed, and the selected waypoint will be centered on the display.

<Meta> Tag Commands In Waypoint Files

Meta commands (much like the commands used to write HTML code for the web) may be included in waypoint files. Meta tags are always enclosed within '<' '>' brackets and consist of a Meta command and optional arguments.

Jump to [ Meta Tag Errors ] [ <Title... ] [ <Auto... ] [ <Href... ] [ <Meas... ] [ <@... ] [ <@Slide> ] [ <Font... ] [ <Position... ] [ <Line... ] [ <Symbol... ] [ <+><-> ]

Meta commands (much like the commands used to write HTML code for the web) may be included in waypoint files. Meta tags are always enclosed within '<' '>' brackets and consist of a Meta command and optional arguments.

Most of the tags and the arguments may be abbreviated with just a few characters. This greatly speeds up annotation entry.

For example: The 'Font' command may be abbreviated with just a single 'F'.

When you make changes to the waypoint file, using the waypoint editor, the map annotations are not automatically updated. You must press the Reannotate button on the toolbar, or right-click 'Reannotate' to load any changes onto the map surface:

Waypoint files are read sequentially from their beginning to end. As each 'coordinate; text' pair is encountered it is displayed with the fonts, lines, and symbols selected by the <Meta> tags.

There are four types of waypoint file Meta tags:

• Hyper link to web, file or multimedia content
• Center location on screen
• Set viewer Title
• Set Measurement Spike location
• Set the defaults styles to the current style
• Restore the factory default styles
• Save all settings
• Restore all settings

• Font Name
• Font Size
• Text Color and Background Color
• Text Position around coordinate

• Text Position around coordinate
• Text Offset from coordinate

• Line ON/OFF
• Line Style
• Line Color and Background Color
• Line Width

• Symbol Type
• Symbol Color
• Symbol fill Color
• Symbol Width and Height (in Meters, Miles or Feet), minimum Marker size in pixels
• Symbol Direction (in Compass bearing)
• Symbol Line Width

Meta Tag Errors

The system logger is updated with descriptions of any errors that occur while All Topo Maps looks at and interprets waypoint coordinates and Meta tags. You may display the System Information Logger by selecting the main map window menu option: 'View: System Information Logger'.

will display:

System Meta Commands

Title <Title "Use This Title>

The Title command will place the specified text as the caption of All Topo Maps. The title must be enclosed by quotes. For example:

places 'I Like All Topo Maps" as the form name:

Autojump <Auto "40 44 11.9 N 111 47 40.2 W">

After a waypoint file containing an Auto tag is loaded, the specified location is centered on the screen. If multiple Auto tags are encountered within the waypoint file, then only the last valid tag in the file is used.

The location must be enclosed by quotes. Any measurement format supported by the waypoint editor for coordinate entry may be used.

AutoJump is only evaluated when a waypoint file is read from the disk (not on a reannoation)

For example:

will center the Utah State Capitol building on the screen:

Hyper-Links in Meta Files <Href "location">

Any waypoint coordinate can include a hyper-link to a web site, picture file, audio/visual clip or other multimedia source. To add a link to a coordinate add the <H …> command. It is customary to also change the font to underlined as an indication to users that a link exists. For example:

generates this map:

Right clicking near the coordinate shows:

and the user may then select to Open the link. Any link registered with the operating system is supported.

Measurement Spike Location <M "location">
<MeasurementSpike "40 44 11.9 N 111 47 40.2 W">

Use the Spike tag to place the measurement spike at the passed location. The location must exist in the loaded map set. Any measurement format supported by the waypoint editor for coordinate entry may be used.

For example:

will set the Measurement Spike to the Utah State Capitol building.

The spike location meta tag is only evaluated when a waypoint file is read from the disk.

Setting/Restoring the Default Symbol Style
<@ SetDef> <@ GetDef> <@ ClrDef>

Use the <@ SetDef> command to save the current Line, Symbol and Text styles as the default values. The <@ GetDef> command will revert back to the saved style. The <@ ClrDef> Meta tag will restore the default symbol style to the factory defaults:

For example these waypoint entries:

result in this map display:

Slide Show <@Slide>

Place the <@Slide> tag on any line with a valid coordinate to use the coordinate as a destination slide. The tag can not have a space between the @ and Slide.

Once one or more slides are defined, use the keypad ‘*’ key to show the first slide in a waypoint file and the keypad ‘+’ and ‘-‘ keys to loop through the slides.

Annotation Text Font <Font ...>

The Text Font command accepts these arguments in any order:

Text Colors may be any of the following predefined colors:

Specify the background color (the color that fills the box behind the text) by placing an underscore before the color name. All colors may be abbreviated by using the first three characters of their name:

The Font Name may be any available font, it must be enclosed in quotes, and not surprisingly it must be spelled correctly. If you share your waypoint files with others, use fonts which are widely available, the operating system will substitute fonts freely if it does not have the correct face.

These keywords are accepted for font styles:

You can specify multiple style keywords within a command, NORM or NORMAL will clear Bold, Italic and Underlined. For example:

will generate:

The text position around the coordinate location may be specified as:

or abbreviated:

See the <Position ...> tag for additional text positioning capabilities and examples.

Changing the Position of Text Annotations <Position ...>

Use the <Position> Meta tag to change the position of text annotations about the map coordinate they are referencing. You may specify both a compass position and a distance in screen or printer pixels to move away from the coordinate. The Meta tag:

sets the annotation on the North West side of the coordinate, removed 10 pixels.

The text position around the coordinate location may be specified as:

or abbreviated:

For example:

generates these annotations (on the Salmon River in Idaho):

Connecting Coordinates with Lines <Line ...>

You can connect successive map coordinates with lines to indicate paths or boundaries. The lines can be solid, colored and any width. The Line command accepts these arguments in any order:

Style may be any of the following:

or abbreviated:

If you specify a line type other than Solid, the line width is forced to 1 (this is a limitation of the operating system.)

Lines are drawn only if both the map coordinate and the previous map coordinate have lines enabled.

For example, to draw a triangle around the Utah State Capitol using Red, White and Blue solid lines 2 pixels wide, with the text 'Utah is Not Square!' centered above the top vertex, you might use these commands:

Changing the Coordinate Symbols <Symbol ...>

At each coordinate, a symbol is displayed. The default symbol is a small dot, centered over the coordinate location on the map

The allowable arguments to the Symbol tag are:

Color and Background Color

The color and background colors are the same as text colors. The first three characters of the color names serve as abbreviations, add a leading underscore to any color to set the background color:

Marker Dots

For each symbol style, including None, a small marker dot is placed at the map coordinate. The marker dot is placed in addition to any symbol. You may change the size of the marker dot using the M= tag. For example:

generates:

Styles

The following styles are supported:

Setting the X=, Y= and L= Values

The X, Y symbol dimensions are set by the X= and Y= arguments. The default units are Meters, scaling is provided by adding units to the number. For example:

X=1.25Mi

results in a 1.25 Mile X dimension, while

Y=1050.1Ft

results in a 1,050.1 foot dimension and

Y=300yards

results in a 300 yard dimension.

Acceptable abbreviations must immediately follow the measurement (without any spaces) and include:

Yards: any word starting with ya or yd

Feet: any word starting with fe or ft

Miles: any word starting with mi

Rotation

Rotation is expressed as degrees clockwise from North. (The same as compass measurements.)

You may enter line and arrow lengths with X offset from the base coordinate, Y offset from the base coordinate and Rotation about the coordinate. For example, the first coordinate below, specifies the Cartesian offset of the blue line's endpoint from it's base map coordinate, while the second line is specified as a length at a compass bearing:

Symbol Style Examples:

None: <S None> 44 23 31.5 N 116 9 51.7 W; Hill Top

or: <S None M=0> 44 23 31.5 N 116 9 51.7 W; Hill Top

Arrow: The arrow symbol is exactly the same as Line.

Triangle:
<S Tria L=0.25Mil R=0 W=2 Red> 44 23 31.5 N 116 9 51.7 W; Hill Top

rotate the point with R=:
<S Tria L=0.25Mil R=45 W=2 Red> 44 23 31.5 N 116 9 51.7 W; Hill Top

Circle:
<S Cir L=0.25Mil R=45 W=2 LtG> 44 23 31.5 N 116 9 51.7 W; Hill Top

Ellipse: Ellipses do not rotate.

rotated: <S RC X=0.25Mi Y=0.5Mi R=25 W=2 Blu> 44 23 31.5 N 116 9 51.7 W; Hill Top

rotated to face SSW (112.5 deg):

Saving and Restoring Styles <+> & <->

Often, you would like to change the display attributes for a single map coordinate, then return to using the same styles that were in use before the change. It might be difficult to track down all of the styles that are currently used, so a simple way to save and restore style is included.

Use the <+> Meta command to save all styles, then make the desired style changes draw the annotations and finally use <-> to restore the styles to the previous values.

For example, we can turn this series of points:

into:

Saves and Restores may be nested up to 15 levels deep.

[ Continue to Next Tour Page ]

[ All Topo Home ] [ Up ] [ Tour1 ] [ Tour2 ] [ Tour3 ] [ Tour4 ] [ Tour5 ] [ Tour6 ] [ Tour7 ] [ Tour8 ] [ Tour9 ] [ GPSTour ] [ BigTopo Tour ]