Home Status Documentation Quickstart User Manual Platform-specifics Developers Guide Bug list To-do list Changelog Downloads Screenshots Maps Mailing lists Archives Get RoadMap at SourceForge.net. Fast, secure and Free Open Source software downloads Wiki

RoadMap User Manual and README

February 2009

Introduction

RoadMap is an open source program that displays street maps. When a GPS receiver is available RoadMap can track the current location of the vehicle on the screen, continuously adjusting the position of the map; with appropriate map data, it can also identify the name of the current street as well as the name of the next intersection. RoadMap can be used without a GPS receiver, as a static map viewer and address finder.

RoadMap runs on various UNIX and Linux systems, but it's also ported to Windows CE, and other efforts are underway.

RoadMap is released under the GPL (see the COPYING file).

RoadMap currently support map data from several sources:

Authors

This document, as well as RoadMap as a whole, is primarily the work of Pascal Martin. Other major contributors include Steve Woodbridge, Ehud Shabtai, Paul Fox, and Danny Backx. The RoadMap "forked road" icon was designed by fmiser from the RoadMap mailing list.

About this Documentation

This documentation was written using vi (what else? :-) in the format supported by txt2tags. The txt2tags tool was used to produce the HTML version of this manual (file web/manual.html). The HTML file can be regenerated using the following command: 

        txt2tags --toc -t html -o web/manual.html -i README

The txt2tags tool is available at http://txt2tags.sourceforge.net/

Quickstart

This section describes the most basic steps you'll need to perform in order to get RoadMap running on your system. More detailed information is available in the Installation Guide section of the documentation.

To build RoadMap for a "standard" linux/unix environment, follow the following steps:

For more complete installation and configuration information, please consult the "INSTALLATION" section of the README file. The README is on the web, here:

http://roadmap.sourceforge.net/usermanual.html

Good luck, and have fun!

Full Installation Guide

Using RoadMap

Button-Left Move the map view to the left.
Button-Right Move the map view to the right.
Button-Up Move the map view up.
Button-Down Move the map view down.
+ (or = ) Zoom in: enlarge the central part of the map.
- Zoom out: show a larger area.
A Search for a specified address.
B Start the route back to the departure point.
C Bring up the roadgps GPS console.
D Show the current route's destination.
E Erase maps among those currently visible.
F Toggle full screen mode.
G Show the current GPS position.
H Hold the map view in its current position.
I Search for a specified street intersection.
J Rotate the map counterclockwise.
K Rotate the map clockwise.
L Show the last selected location.
M Enable/Disable map download.
N Create a new trip.
O Open an existing trip.
P Stop tracking the current trip.
Q Quit RoadMap.
R Set the map back to the default zoom level.
S Start tracking the current trip.
T Toggle display of the current track.
U Center the map on the GPS position (north up).
V Create new waypoint based on current GPS position.
W Set the selected street block as waypoint.
X Find an intersection.
Y Save a screenshot of the current map display.
F11 Toggle the full screen mode (same as 'F').

The current bindings that are used by the application can be printed using the "--help=keymap" option.

Note for Familiar 0.7.1 GPE users: the GPE environment has defined the button bindings in a way that makes it impossible for RoadMap to use them (the buttons are mapped to the GPE applications). In this environment it is recommended that the toolbar be enabled to replace the buttons. The joypad is still available.

Using RoadGps

RoadGps is a handy GPS console, inspired by the Garmin satellite status page, with NMEA logging capability.

The functionality of RoadGps is now included directly in roadmap, but roadgps is still available as a separate program. If configured to use gpsd, roadgps and roadmap can be active at the same time, since gpsd manages the serial port connection to the GPS unit.

If built as separate program, roadgps can be started on its own (using command line options similar to those of RoadMap), and in any case from the RoadMap's File / GPS Console menu item.

The screen shows the list of satellites, their position in the sky (north up) and the strength of the signal. It marks in reverse video the satellites being used to compute the current position. In addition, the locations of the Sun and/or Moon are shown, for general reference.

RoadGps uses a subset of the RoadMap preferences setup, but has no preferences editor of its own: configure RoadMap first, and then use RoadGps.

Configuration

This section describes the files used to configure RoadMap on the local machine. In most cases these files contain user-defined data that defines the look of the RoadMap user interface, or resources used by RoadMap.

For more information on configuring specific devices (e.g., WinCE, iPhone, XO laptop), see the PLATFORM SPECIFIC section of the documentation.

We will first describe where to find these configuration files on the different operating systems that RoadMap supports, then we will describe the content of each configuration file.

The files themselves are the same on all operating systems.

Note that this section does not cover the files describing the maps: there is a clear separation in RoadMap between the map data, which the user normally does not modify or customize, and the configuration data, which the user may want to custimize. The map files are described in a separate section.

The configuration files are stored in a set of directories to allow for a default, system-wide configuration and allow each user to customize the configuration separately. See the INSTALLATION section of the documentation for more details.

Files

The syntax of most RoadMap configuration files is similar to the X ressources file format (the exceptions are the sprites file and the trip files). Each configuration item is represented by one line of text, using the following format: 

                name ': ' value

The following configuration files are used:

preferences
User's preferences.

session
The latest context used (locations)

sprites
The definition of the graphic symbols

roadmap.toolbar (Optional)
The actions shown on the RoadMap toolbar.

roadgps.toolbar (Optional)
The actions shown on the RoadGps toolbar.

The session file contains the current state of roadmap, which is saved (if needed) when roadmap exits. The preferences file contains all of the static preference items, and can be edited by the user. The sprites file contains the graphical definition of the symbols usd by RoadMap to indicates the various locations, to draw the compass, etc..

The toolbar files define the content of the RoadMap and RoadGps toolbars. See the section CONFIGURING THE MENUS AND TOOLBAR for more information.

%A Estimated time of arrival (not yet implemented).
%B Direction of travel (bearing).
%C The name of the city for the selected or current street.
%D Distance to the destination (set only when a trip is active).
%E Next sunset time (evening), undefined in night time.
%e Next sunset time, always defined.
%F Full name (number, name, city) of the selected or current street.
%H Altitude.
%M Next sunrise time (morning), undefined in daylight time.
%m Next sunrise time, always defined.
%N Name of the selected or current street.
%P Name of the selected or current place.
%R Name of the route or list containing the selected place.
%S Speed.
%T Current time, format HH:MM.
%W Distance to the next waypoint (set only when a trip is active).
%X Directions to be followed when the next waypoint (with
directions) is reached. (set only when a trip is active).
%Y Distance to the next waypoint which includes directions, unless
the GPS is "at" that waypoint. (set only when a trip is active).
%# the street number range to the selected or current street block.
%s Total number of satellites.
%v Total number of available satellites.
%x Distance from one side of the screen to the other.
%y Distance from the top to the bottom of the screen.

Note that the time is always shown using the military format: HH:MM.

Example: "%D (%W)" shows the distance to the destination point, followed by the distance to the next waypoint (in parenthesis).

A message is evaluated, and displayed, only when all referenced %-macros have a defined value. Therefore the example above will show nothing if there is no trip active, or if there is no next waypoint. It is possible to define several alternatives, separated by the character '|': the first alternative that has been successfully evaluated will be displayed.

Example: "%D (%W)|%D" shows both distances to the destination point and to the next waypoint if both distances are defined, or else only the distance to the destination point if this distance is defined. If none of the two distance have been defined (for example when no trip is active), then no display is shown and/or no sound is produced.

Likewise, "In %Y, %X|%X" will say something like "In 0.5 miles, Turn Right", unless you're already at the point at which you should turn right. Then it will just say "Turn Right".

Another typical example is "sunset: %E|sunrise: %M", which shows the next sunset (in daylight time) or sunrise (in night time).

It is possible to "link" together parts of a string using simple or double quotes. This is used when the string specifies an external command to execute. RoadMap does not use the shell to execute commands (so to stay independent from the OS-specific shell syntax), but it does recognise the use of quotes to specify a command parameter that includes spaces. Such a parameter may be enclosed in single or double quotes. There is no difference between one quote or another, except that the parameter must be terminated with the same quote character it was started with.

Example: "flite -t 'On %N'" to specify the command flite with two parameters ("-f" and "On %N").

Menus and Toolbar

The items shown in the RoadMap and RoadGps menus and toolbars can be redefined by the user in text configuration files. Note that each program comes with a built-in menus and toolbar configuration that serves as the default, so none of these configuration files is required to be present for RoadMap or RoadGps to work. In fact, RoadMap is distributed with none of the configuration files described in this section. (Example files are provided for RoadMap, but are not installed automatically.)

It must be realized that making any change to the menus and the toolbar comes at a price: this documentation was written using the standard user interface. Modifying the user interface is likely to make this documentation even more confusing than it originally is.

The major reason for customizing the menus or the toolbar is to let the user tailor the toolbar to fill small screens (such as a PDA) with his preferred controls at the most convenient place. Using a GUI in a car or on a bike is challenging enough.

The configuration files are organized with one entity per line. An entity is either the title of a menu, the name of an action, a separator or a comment.

Each menu is described by it's title (prefixed with character '/'), followed by the list of items in that menu. The title of a menu is a user-defined string with a maximum length of 254 characters (it is recommended to select short titles made of a single word, however). There is no such title line for toolbars: all menu title lines will be silently ignored. The toolbar is organized as a single, anonymous, menu.

Each menu or toolbar item is described by its action name. A separator is described by the character '-'. There must be only one item (title, action name or separator) per line. Empty lines are authorized and lines starting with the '#' character are treated as comments.

There are two sorts of menus. All menus are available as popup menus, which are invoked either in response to an event (as specified in the preferences "Events" section), or by being invoked from a menu entry or toolbar button. In addition, menus that are specified as menubar menus will appear in the menu bar. Invoking a popup menu from another menu is how submenus are implemented in RoadMap.

The menus, popup and toolbar configuration files for roadmap are named "roadmap.menus", "roadmap.popup" and "roadmap.toolbar", respectively. The same configuration files for roadgps are named "roadgps.menus", "roadgps.popup" and "roadgps.toolbar". These files must be stored in the same places as other RoadMap configuration files.

By default, a long click of mouse button 1 will bring up the menu called "/Long Click Popup" in road{map,gps}.popup, and a right click (button 3) will bring up the menu called "/Right Click Popup". These bindings can be changed by setting "Events:Long Click" or "Events:Right Click" in the preferences.

There is a different list of possible actions for RoadMap and RoadGps. The list of valid action names can be obtained using the command line option --help=actions: 

            roadmap --help=actions
            roadgps --help=actions

The following is an example of a menus definition file for RoadMap: 

           /Right Click Popup
           preferences
           gpsconsole
           -
           quit
           /Help
           about

The following is an example of a toolbar definition file for RoadMap: 

            full
            quit
            -
            destination
            location
            gps
            hold
            -
            zoomin
            zoomout
            zoom1
            ->Help...

The last item in the toolbar file example will invoke the "Help..." menu. If the toolbar file is empty, no toolbar will be created.

It's actually possible to configure RoadMap with no on-screen buttons or menus at all. By creating an empty "roadmap.menus" file, the internal menubar menus will be suppressed. Then, configure the Long or Right Click action to invoke the "Menus..." menu. This special popup contains the same list of menus that would normally appear in the menubar. This allows full access to RoadMap commands, all via the mouse. More practically, one might wish to bind the "->Menus..." popup menu to a toolbar button -- then RoadMap could run with a toolbar, but no menubar.

It is also possible to rename the RoadMap actions, with the effect of changing the labels used in the menus and the text of the tooltips.

The translations are described in text files, one text file per program: "roadmap.actionlabels" for roadmap and "roadgps.actionlabels" for roadgps. These files should be located in the usual RoadMap configuration places.

Each action is renamed using one line of text that contains the action name, its menu label, its toolbar label and its tip label (in that order). Each of these items is separated by one special character. This separator can be any character except a letter (upper case or lower case) or a digit ('0' to '9'). Different separators can be used on different lines, but a single line must use a single separator character.

The following are examples of valid action renaming lines (from English to French, to please our Canadian friends): 

          mutevoice;Silencieux;S;Desactive la synthese vocale
          enablevoice+Volubile+V+Active la synthese vocale
          quit,Quitter,Q,Quitter l'application

(This mechanism is not intended to provide a general mechanism for the internationalization of RoadMap.)

Remember that the toolbar labels should be very short, since the toolbar has a limited size.

On-Screen Objects

RoadMap can display small images on the screen (on-screen objects) which can reflect the state of the program (e.g., which way is north, how strong is the GPS signal), and/or allow actions to be performed (e.g. zoom in, show the trip's destination). These objects may be placed anywhere on the screen, but nothing prevents them from being obscured by other popup messages and displays, so their position is usually along the sides of the screen.

The position, display, and actions associated with these objects are controlled by a "roadmap.screenobjects" file. The distributed copy of this file contains definitions for a small compass image, a map download indicator, zoom in and zoom out control points, and some arrow indicators which help point the way when following a route. The user is free to make a local copy of this file in order to add on-screen command points, and to customize the display in general.

The roadmap.screenobjects file is made of a sequence of single-line commands. The "sprites" referred to in this description are defined in the configuration file named "sprites", described in the "SPRITES FILE" section of the documentation.

N <name> Name of the object (unused, but starts
a new object)
P <x> <y> The screen position of the sprite, measured
from the top left in pixels. Negative offsets
measure from the right and from the bottom. If
the <x> or <y> value begins with a 'C', then
the remainder is an offset from the center of
the screen.
E <sprite> [text] The name of the sprite which will be drawn.
E <sprite> [text] Multiple sprites can be specified. Which
one is displayed is selected via the object's
"state" indicator. If "text" is specified, it
will be displayed with the sprite (assuming the
sprite has been defined to have text associated
with it).
- The text can be divided into multiple lines.
Line breaks are indicated by inserting a '^'.
- The text can contain %-macros, just as defined
for other text displays, in order to display
dynamic content. The '|' "alternation" symbol
is also honored. See the "CONFIGURING THE
TEXT AND VOICE MESSAGES" section of the
documentation.
S <statename> The "state" indicator which will choose among
the listed sprites. For "constant" displays,
this is optional.
A <actionname> The action which should be invoked when the
sprite is selected. Optional. The action can
be a simple action name, or, when prefixed with
"-->", the name of a popup menu which should
be invoked.
R Sprites will normally rotate, either with the
screen, or based on an angle retrieved via
the state indicator. Specifying 'R' suppresses
this by forcing rotation to the given angle.
B <x> <y> <x> <y> Optional -- the bounding box used to determine
whether a selection has taken place. (I.e.,
the size of the sprite.) Normally the bounding
box is calculated by RoadMap itself (and if
the object will rotate, the bounding box is
forced to have maximal dimensions), but
irregularly shaped sprites, combined with the
rotation of the sprite, may require that the
box be overridden. Note that the bounding box
of any text associated with the sprite is
calculated and considered separately.

The screen objects can display different sprites to indicate the state of various internaly RoadMap runtime states. These state indicators are referenced by name, and are linked to the screen object via the 'S' descriptor in the "roadmap.screenobjects" file.

The possible state indicators are as follows. Most have just two possible "return values", but some can represent more than two state values. In addition, any can optionally return an angle which can influence the display of the sprite.

get_download_enabled Indicates whether the user has enabled
map downloads.
get_GPS_reception Four possible states, indicating current GPS
performace: N/A, none, poor, and good.
zoom_reset Indicates whether zoom is at the default level.
view_mode Indicates 2D or 3D map rendering.
get_orientation Indicates whether map rotation is fixed or
dynamic. Also returns the current angle of
the map relative to north. (This is what
drives the on-screen compass object.)
get_direction_next When following a route, indicates the direction
to the next waypoint. This indication is
relative to the direction of travel -- i.e., it
points correctly if the user holding the display
is facing forward in the vehicle.
get_direction_2nd As above, but points to the waypoint after the
next.
get_direction_dest As above, but points to the final destination.

Preference Items

General.Unit
The unit system used, either "imperial" or "metric"
General.Default Zoom
The zoom level when roadmap is started.
General.Keyboard
Show (yes) or hide (no) a keyboard on the screen.
General.Icons
Show (yes) or hide (no) icons on the toolbar.
General.IconPath
The icon search path.
General.Busy Cursor Delay
Delay until mouse cursor switches to "busy"
General.Progress Bar Delay
Delay until progress bar during refresh.
General.Show Errors
Should runtime errors be reported on-screen?
General.Toolbar
Show (yes) or hide (no) the roadmap toolbar.
General.Toolbar Orientation
Choose where to position the toolbar
General.Tooltips
Show (yes) or hide (no) tooltips on menus and buttons.
General.UserPath
Directory for per-user configuration.
General.TripsPath
Directory in which trips are stored, usually per-user.
General.Sprite Scale
Sets a scaling factor for all RoadMap sprites.
Geometry.Main
Sets the size of the RoadMap main window.
Geometry.Default
Sets the default size for other RoadMap windows.
Geometry.WINDOW
Sets the size of the RoadMap window named WINDOW.
Display.Bottom Right
Defines the message on the bottom right corner.
Display.Bottom Left
Defines the message on the bottom left corner.
Display.Top Right
Defines the message on the top right corner.
Display.Top Left
Defines the message on the top left corner.
Display.Duration
The time during which a selection or message is shown.
Display.Refresh Period
Minimum interval between display refreshes.
Display.Font Size
The size of the text used for labeling.
Help.Browser
The browser program used to show the help text.
Help.Source
Whether RoadMap will find Help text on the local machine or the web.
Help.Website
If Help.Source is "web", this is the site to access for Help text.
Map.Path
The map database search path.
Map.Cache
The number of entries in RoadMap's mapping cache.
Map.Background
The color used for the background of the maps.
Map.Labels
Enable/disable the initial display of street names.
Map.DynamicOrientation
Rotate the map to match the GPS direction.
Map.Panning Percent
How far an arrow key will move the map view
Map.GPS map offset latitude
Allows tuning of GPS latitude results.
Map.GPS map offset longitude
Allows tuning of GPS longitude results.
Map.Signs
Enable/disable the map sprites and street signs.
Map.Refresh
Forces a screen refresh every time.
Map.Use Linefont
Enables use of the internal linefont.
Map.ViewMode
Select 2D (flat) or 3D (perspective) map view.
Labels.MinFeatureSize
The shortest street which may be labeled.
Labels.Color
The color used when labeling streets.
Labels.Font Size
The size of the text used for labeling.
Landmarks.Name
The filename used for storing personal landmarks
Landmarks.Color
The color used when labeling personal landmarks.
Landmarks.Font Size
The size of the text used for labeling.
Track.Name
The filename used for storing current "breadcrumb" track
Track.Initial Display
Determines whether the track is displayed when RoadMap starts.
Track.Policy
The algorithm used to decide when to store a new trackpoint
Track.Time Delta
Time interval used when Track.Policy is "Time".
Track.Distance Delta
Distance used when Track.Policy is "Distance".
Track.Autosave minutes
Number of minutes between automatic saves of the current track.
Track.Saved Track Points
Approximate number of track points saved in memory, or in a single file.
Trip.Name
The filename holding the current trip.
Trip.Show Inactive Routes
Should waypoints in unselected routes be shown.
Trip.Show Inactive Tracks
Should waypoints in unselected tracks be shown.
Trip.Connect Route Points
Should route waypoints be connected with straight lines?
Trip.Route Connect Color
The color used to connect route waypoints.
Trip.Waypoint Radius
How close does the GPS need to be to a waypoint to be "on" the waypoint.
Trip.GPS Focus Release Delay
Delay until GPS loses focus, if off-screen.
FeatureFiles.Path
List of files containing "Point of Interest" features to display on map.
Files.Make Backups
Enable/disable the creation of backup files.
GPS.Background
The background color for the RoadGps screen.
GPS.Foreground
The foreground color for the RoadGps screen.
GPS.Timeout
A timeout for detecting that the GPS link is down.
GPS.LostFixWarningTimeout
Timeout for the "lost satellite" message.
GPS.Source
The URL that gives the address of the GPS data source.
GPS.Baud
The baud rate to use if GPS.Source is a serial port
GPS.Color
The color used for the current GPS position symbol.
Destination.Color
The color used for the destination symbol.
Selected Street.Background
The color for the background of the selected street name.
Selected Street.Foreground
The color for the foreground of the selected street name.
Selected Street.Text
The format used for the selected street's display.
Console.Background
The color used for the background of the trip display.
Console.Foreground
The color used for the foreground of the trip display.
Current Street.Background
The color for the background of the current street's name.
Current Street.Foreground
The color for the foreground of the current street's name.
Current Street.Text
The text used to display the current street's name.
Voice.Current Street
The command used to announce the current street's name.
Voice.Selected Street
The command used to announce the selected street's name.
Voice.Next Intersection
The command used to announce the name of the next intersection.
Voice.Approach
Reserved for future use (approaching waypoint).

Accuracy.Confidence
The minimum rating for a street to be selected
Accuracy.GPS Position
The GPS's estimated position error (worst case)
Accuracy.GPS Speed
GPS's speed accuracy.
Accuracy.Minimum drag
The minimum movement required to initiate a drag.
Accuracy.Mouse
The size of the street or place selection search area.
Accuracy.Street
The street selection accuracy.
History.Depth
The maximum number of items in the "Find" history.
Approach.Background
Reserved for future use (approaching waypoint).

Approach.Foreground
Reserved for future use (approaching waypoint).

Approach.Text
Reserved for future use (approaching waypoint).

Download.Source
The format used to generate the URL of the source.
Download.Destination
The path of the directory where to store the downloaded map files.
Style.Use Pretty Lines
If "yes", roads are shown with all the defined pens (see schema). If "no", roads are shown with the first pen only.
Style.Pretty Lines when Dragging
If "yes", roads are shown with all the defined pens when dragging (if enabled--see above). If "no", roads are shown with the first pen only while dragging.
Style.Show Objects when Dragging
If "yes", objects are shown when dragging. If "no", objects are not shown while dragging. Objects are the sprites, text messages, etc..
Location.Position
The latest selected position.
GPS.Position
The latest received GPS position.
GPS.Direction
The latest received GPS direction.
Selection.Position
The position of the latest selection.
Address.Position
The position of the latest address used.
Trip.Name
The name of the last used trip file.
Delta.X
The horizontal map shift compare to the reference position.
Delta.Y
The vertical map shift compare to the reference position.
Delta.Rotate
The rotational shift compare to the reference direction.
General.Zoom
The current zoom level.
Focus.Rotate
Indicate if the current map focus is set to rotate.
Focus.Name
Name of the reference position where the focus should be set.
Navigation.Enable
Controls whether navigation mode is enabled.
Voice.Mute
Defines if the voice function was muted by the user.
Hold.Direction
An artefact of saving the context. Ignored.

Hold.Position
An artefact of saving the context. Ignored.

Log.Path
Last selected path for the RoadGps log files.
Events.Right Click
The name of the menu to open on a mouse right click.
Events.Long Click
The name of the menu to open on a mouse long click.

Schema Items

The schema file uses the same format as the preference file. It defines the properties of the various categories of objects that make a map. the list of categories matches the list of Tiger file's categories (see Tiger's CFCC field) that have been filtered by buildmap.

The two differences with the preferences files are that there is no pre-defined category in RoadMap: categories are defined by the maps (FIXME: this is still to be done--as a temporary hack, the categories have been hardcoded somewhere) and there is no default value.

For each category, RoadMap use the following items:

<category>.Class:
the class of object this category belongs to.
<category>.Color:
the color used when drawing the objects.
<category>.Declutter:
the zoom level from which the objects are hidden
<category>.Thickness:
the thickness used to draw lines.

RoadMap uses the following categories:

Sprites

This file defines the drawing commands used to draw the various symbols used by RoadMap:

S <name> Starts a sprite.
A <name> Defines the current sprite as an alias of
the specified sprite.
F <color> <thickness> Define the pen to be used by the subsequent
drawing commands.
X <percent> Optional scale factor for this sprite. All
components of the sprite will be adjusted.
L <x>,<y> .. Draw a line.
P <x>,<y> .. Draw a filled polygon.
C <x>,<y> <radius> Draw a circle.
D <x>,<y> <radius> Draw a disk (filled circle).
B <x>,<y> <x>,<y> Optional -- the bounding box used to determine
whether a selection has taken place, when a
a sprite is in use as an on-screen object (in
"roadmap.screenobjects"). Normally the
bounding box is calculated by RoadMap itself,
but irregularly shaped sprites, combined with
the rotation of the sprite, may require that
the box be overridden.
T <x>,<y> <s> text... Adds text to the sprite, of size 's'. "text"
can be ommitted, in cases where the sprite's
text will be provided by a screen object
definition. Text strings are fixed, with no
expansion of %-macros.
TR If the sprite has text, supply a backing
rectangle sized and positioned to match the
text.
TB If the sprite has text, supply a box outline
around the text.

The coordinates are pixel positions, relative to the sprites "hot point". The "natural" direction for the sprite, for pointing purposes is to the north. Positive X and Y values are towards the east and south, negative are towards the west and north.

The bounding box of a sprite is normally calculated internally, but can be overridden. If a sprite has text associated with it, the text forms a second, separate, bounding box. This is because the text may change shape (if it's dynamically produced), and because sprites tend to be compact, while text tends to be long and thin. Currently these bounding box outlines are only used when a sprite is referenced in "roadmap.screenobjects". The sprite's bounding box can also be overridden there.

An S command must appear before any alias or drawing command.

A sprite cannot contain both an alias command and drawing commands. In addition, if an alias command is present, it is the only command defining this sprite (i.e. an alias sprite is defined by just one S and one A command). For example: 

       S Friend
       A GreenTriangle
  
       S GreenTriangle
       F white 2
       L 0,0 7,14 0,8 -7,14
       F DarkGreen 2
       L 0,1 6,13 0,10 -6,13 0,1

A sprite alias is just another name for the referenced sprite: an alias will be visually identical to the sprite it references. An alias command can reference a sprite that is itself an alias. There is no limit to the depth of the alias chain, but circular references are illegal, and detected. Forward references are legal, i.e. the sprite referenced in an alias command can be defined later in the file.

One reason for using alias sprites is to make it simpler to redefine sprites known to RoadMap (such as "Direction" or "Destination"). The alias mechanism has a negligible fixed cost at runtime: using multiple alias levels will have no practical impact on RoadMap performances.

Trip Files

RoadMap trip data is stored in GPX format. More about the widely-used GPX data format can be found at:

http://www.topografix.com/gpx.asp

The main thing to know about this format is that a GPX file may contain one or more "routes", one or more "tracks", and one or more "landmarks".

Routes and tracks are very similar: it's most useful to think of a route as "where you want to go", and a track as "where you've been". Routes are usually "composed", either manually or using navigation software. Tracks are usually recorded, by making a note of one's GPS location periodically. (By the way, tracks don't get included into trip files automatically. If you wish to store your tracks along with your routes for a given trip, you'll need to save copies of your current track and them to the trip.)

Routes and tracks are both composed of "waypoints". To reduce confusion, RoadMap tries to use the term "waypoint" to _only_ refer to points which are contained in routes and tracks. Points that are unassociated with a specific route or track are called "landmarks". If you read the GPX documentation you'll find that everything is called a waypoint.

Waypoints simply represent a place, along with some other information about that place. For instance, a waypoint in a route might have a name, and it might also have a comment attached to it which says which way to turn when this waypoint is reached. A waypoint in a track might only contain its location and the time at which you were there. The landmarks in the trip file might represent places of interest which, while not really part of a route, are related to the trip somehow.

Here are some more details regarding how RoadMap uses the GPX format.

Waypoints (and landmarks):

<name> is used directly if available.

If no name is available, a shortened version of the <cmt> or <description> element will be used instead. If neither of these elements is available, a name will be generated.

In addition, if no <cmt> is available, the <description> element will be used as a description.

The <sym> element will be used as the sprite name, if it is set, otherwise fixed RoadMap defaults will be used for the spritename, depending on what sort of waypoint it is.

When generating a waypoint while recording a track, RoadMap will set the <ele>, <speed>, <course>, and <time> elements, as well as the "lat" and "lon" attributes. All of this data comes directly from the GPS. The <name> and <sym> elements are left unset.

Routes and Tracks:

The <name> and <desc> elements will be used and set. For tracks, the <trkseg> level of the hierarchy is ignored -- all track segments are treated as one.

The following trip file example contains just one route, which goes from the Golden Gate's bridge to 1 Market St, in san Francisco, California. It also contains the locations of some nearby pizza parlors: 

        <?xml version="1.0"?>
        <gpx version="1.1">
           <rte>
              <name>198 Richardson Ave to 1 Market St</name>
              <rtept lat="37.8003" lon="-122.44703">
                 <cmt>Head southeast from Richardson Ave</cmt>
              </rtept>
              <rtept lat="37.79879" lon="-122.4446">
                 <cmt>Bear left at Lombard St</cmt>
              </rtept>
              <rtept lat="37.79901" lon="-122.44265">
                 <cmt>Turn right at Divisadero St</cmt>
              </rtept>
              <rtept lat="37.78336" lon="-122.43948">
                 <cmt>Turn left at Geary Blvd</cmt>
              </rtept>
              <rtept lat="37.78529" lon="-122.42467">
                 <cmt>Bear right at Ofarrell St</cmt>
              </rtept>
              <rtept lat="37.78678" lon="-122.40458">
                 <cmt>Turn left at Market St</cmt>
              </rtept>
              <rtept lat="37.79444" lon="-122.39487">
                 <cmt>Arrive at destination</cmt>
              </rtept>
           </rte>
           <wpt lat="37.792612" lon="-122.393843">
              <name>Village Pizzeria</name>
           </wpt>
           <wpt lat="37.793392" lon="-122.397554">
              <name>Parkway Pizza</name>
           </wpt>
           <wpt lat="37.789001" lon="-122.394843">
              <name>Dogzilla Cafe</name>
           </wpt>
        </gpx>

In addition to the trip files, there are two other important files which are also stored in GPX format.

Personal Landmarks
Called "landmarks.gpx" by default, this contains landmarks (waypoints) which you might want to keep handy no matter what trip file you have loaded. Examples might include your home, your office, your hairdresser, etc. When writing this file, only the personal landmarks are written. When reading, only the unassociated waypoints are read -- any routes or tracks in the file are ignored.

Current Track
Contains waypoints representing where you've been -- a "breadcrumb trail", if you will. This file (called "currenttrack.gpx" by default) will only contain a single track when written. When read (on startup, to restore previous state), only the first track in the file will be read. All other routes or tracks and waypoints will be ignored (and likely lost, when the current track is saved at the end of the session). Along with the currenttrack.gpx, you may see "recenttrack.csv", and one or more "savetrack-*.gpx" files (which will include a date in their names). The "savetrack" files are archival: if the in-memory list gets too big, or if the user "clears" the current track, then excess historical trackpoints will be written to a "savetrack" file. A "savetrack" file will also be created if you manually reset the current track -- a backup of its contents is saved, for good measure. The "recenttrack.csv" file is a temporary file, used to keep RoadMap from losing any track points in the event that it dies (crashes) unexpectedly. The goal is to never lose a track point.

(These files are not stored in the same directory as the other trip files, but instead in the same directory in which the user's preferences and session file are found.)

Feature Files

Like the RoadMap trip data, feature data is stored in GPX format. Each feature file should represent a related set of points of interest, like ice cream shops, motels, campgrounds, or mountaintops. A single sprite can be associated with each file, and will be used to represent its contents on the map. Features will be labeled using the pen color specified. Either or both of the sprite and label can be suppressed by specifying the name "NONE". Feature labels and sprites can also be selectively disabled as the map is zoomed out. An example feature file specification, which uses ';' as its delimiter, might be: &/icecream.gpx;ConeSprite;darkblue;350;750 This says that the ice cream shops listed in the given file should be drawn with the ConeSprite, labeled with a "darkblue" pen, the labels should be eliminated above zoom level 350, and the sprites should disappear above zoom 750. Likewise: &/towns.gpx;NONE;black;350;350 says that towns should be labeled in black, with no sprite, up to zoom level 350. If a higher sprite declutter level is specified: &/towns.gpx;NONE;black;350;1000 then a small default sprite (with the name "PointOfInterest") will be shown, up to the higher level.

Multiple file specifications (including each file's associated (and semicolon-separated) sprite name, pen color, and declutter levels) should be separated by ',' characters.

Note that unlike the maps, which are read and cached on an as-needed basis, the feature files are read into memory in their entirety when RoadMap starts, so there is a memory penalty for using large feature files.

Configuration Examples

~/.roadmap/preferences ("factory" defaults): 

      Accuracy.GPS Speed: 4
      Accuracy.Confidence: 25
      Accuracy.Street: 150
      Accuracy.Mouse: 20
      Accuracy.Minimum Drag: 5
      Approach.Background: yellow
      Approach.Foreground: black
      Approach.Text: Approaching %N, %C|Approaching %N
      Console.Background: yellow
      Console.Foreground: black
      Current Street.Background: yellow
      Current Street.Foreground: black
      Current Street.Text: %N, %C|%N
      Destination.Color: red
      Display.Bottom Left: %S
      Display.Bottom Right: %D (%W)|%D
      Display.Top Right: In %Y, %X|%X
      Display.Duration: 10
      Display.Rotate: yes
      General.Default Zoom: 20
      General.Keyboard: no
      General.Toolbar: yes
      General.Icons: yes
      General.Unit: imperial
      Geometry.Main: 800x600
      Geometry.Preferences: 800x300
      GPS.Background: LightYellow
      GPS.Color: red
      GPS.Foreground: black
      GPS.Source: gpsd://localhost
      GPS.Timeout: 10
      History.Depth: 100
      Map.Path: ~/.roadmap,/var/lib/roadmap,/usr/lib/roadmap
      Map.Cache: 8
      Map.Background: LightYellow
      Map.Refresh: normal
      Map.Signs: yes
      Polygons.Declutter: 1300
      Selected Street.Background: yellow
      Selected Street.Foreground: black
      Selected Street.Text: %F
      Shapes.Declutter: 1300
      Voice.Approach: flite -t 'Approaching %N'
      Voice.Current Street: flite -t 'On %N'
      Voice.Next Intersection: flite -t 'Next intersection: %N'
      Voice.Selected Street: flite -t 'Selected %N'

~/.roadmap/session ("factory" defaults): 

      Delta.Rotate: 0
      Delta.Y: 0
      Delta.X: 0
      Focus.Rotate: 0
      Focus.Name: Address
      Trip.Name: default.gpx
      Hold.Direction: 0
      Hold.Position: 0,0
      Selection.Position: -122394181,37794928
      Address.Position: -122394181,37794928
      GPS.Direction: 0
      GPS.Position: 0,0
      General.Zoom: 150

Using OpenStreetMap Maps

This information is preliminary, since OSM support is work-in-progress. It does work, but may change in detail.

Building Maps

To build the TIGER map files from scratch:

  1. download some maps from the US Census bureau:

    http://www.census.gov/geo/www/tiger/tiger2006se/tgr2006se.html

    This download can be automated by using the shell script roadmap/src/rdmdownload: 

              rdmdownload <tiger-path> [<state-symbol> ..]

    (To download older versions of the maps (e.g. 2000), see the script for the options available.)

  2. Build the maps: 

              rdmgenmaps <tiger-path> maps=<map-path>

    This command processes all the Census Bureau files found in <tiger-path> and creates the map files for RoadMap in the <map-path> directory. There is one map file generated for each county. Alternately, specific counties can be built. Counties are identified by their FIPS codes (e.g. 06075 for San Francisco, CA). 

              rdmgenmaps <tiger-path> [maps=<map-path>] <county fips code> ..

    The rdmgenmaps command can also process one full state at a time: 

              rdmgenmaps <tiger-path> maps=<map-path> <two-letter state abbreviation>

    The rdmgenmaps tool is a shell script that extracts the TIGER files from the downloaded ZIP files, invokes the buildmap tool and then cleans up the TIGER files. Last, rdmgenmaps invokes the buildus tool to generate the US states and counties catalog. The main purpose of rdmgenmaps is really to keep the TIGER files in compressed form, considering their huge size..

    The buildmap tool is the worker program used by rdmgenmaps. It takes a county "FIPS" code and a TIGER file as input and produces one RoadMap .rdm map file. The option --help gives more information about the available options.

    Here is an example: 

              buildmap 01001 /tmp/TGR01001.RT1

    The buildus tool creates a catalog of maps that is used by RoadMap to combine all states and counties into a giant US map.

Map Utilities

RoadMap comes with a small set of utility programs and scripts which are used to build and maintain the map data files that roadmap uses.

buildmap
buildmap takes various input map formats as input and produces the map files used by roadmap. This program is only used to prepare the map files and is not needed when running roadmap.

buildus
buildus takes a set of roadmap map files and creates a directory file that lets roadmap choose the map(s) to display according to location or city. buildus is not needed when using roadmap -- only when preparing the maps.

rdmgenmaps
A script to simplify the generation of the maps.

dumpmap
Display the data tables from a map file. This application is used for debug purposes only and is not needed when using roadmap.

A RoadMap map file is a small database of C tables. The tables are organized in a tree fashion and each table is identified by a path. One specific set of tables (the dictionary) groups all the names that appear in the map.

dumpmap can be used to display information extracted from a map file: 
         dumpmap [--usage] [-d TABLE] [--strings] [--volume=NAME] [--search=NAME]
The name of map files must be provided after the options: dumpmap will process each provided file sequentially, according to the options that was selected.

See the "Map Format" section of the documentation for more information about the format of the maps.

RoadMap Navigation

Navigation support is work in progress.

It requires maps that have been built with a new version of buildmap (or buildmap_osm) because this new version will add a couple of tables to the map.

Navigation support needs to be compiled in, see "Building". RoadMap will show an additional menu labelled "Navigate" when this code is compiled in.

Maps for Navigation

In order to support navigation, several extensions were made to the RoadMap map format :