October 2007
RoadMap is an open source program for UNIX 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; 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.
Most of the maps are provided by the US Census Bureau, which only cover the US. RoadMap now includes a preliminary support for two other formats: the Digital Charts of the Words (DCW), a set of world-wide maps produced by the US Department of Defense, and the Canadian RNF (Road Network File) maps. The DCW contains only major highways and freeways, for some parts or the world (mostly Europe and japan) and their accuracy does not allow any reliable car navigation. The RNF files contain road data, but currently no water features or municipality information.
RoadMap is released under the GPL (see the COPYING file). The US Census Bureau's data is public domain. The DCW data is mostly public domain, but some administrative boundary data is copyright of ESRI (http://www.esri.com/). As no administrative data is incorporated in the RoadMap map files, all the RoadMap map files are in the public domain.
RoadMap uses a binary file format for representing the maps that is compact enough to allow the storage of many maps on a Compact Flash or MultiMedia card. The map of Los Angeles county takes a little more than 10 Mbytes of flash space. RoadMap comes with a set of tools to convert the US Census bureau data into its own map format.
RoadMap has been designed to be usable on both a desktop or laptop computer, or on a PDA such as the iPAQ from HP (formely from COMPAQ) or the Sharp Zaurus.
In its current version, RoadMap can work with either the GTK+ 1.2, GTK 2.0, GPE, QT/X11 or QT/QPE graphic environments. The QT environment --especially its QT/QPE version--is mostly used for the Zaurus port (but could probably be used with OPIE). RoadMap is configured for using QT3 by default, but the QT2 compatibility headers must be installed (the QT2-style coding has been kept because of the Zaurus QPE environment). The most stable environment is the GTK 2.0 one (this is the one used for developing RoadMap). The GPE support is and optional extension of the GTK 2.0 environment and is still very experimental (i.e. untested). GTK 1.2 is still interesting because it's quite a bit more efficient when running on limited hardware than is GTK 2.0.
RoadMap is also available on Windows CE (i.e. Pocket PC). As gpsd does not exist on Windows, the Windows version directly listens to the GPS serial port.
RoadMap is at an early stage of development. At this time all the features have not been implemented yet. RoadMap can display the map around a specified street address, track a GPS position and identify the current street and the next intersection. Trip support is provided (waypoints, route following, and general landmarks). Large sets of "Point of Interest" features also can be displayed on the map.
The plan for the future is to implement some navigation features similar to those found in commercial car navigation systems, and to port RoadMap to as many environment as possible.
This document, as well as RoadMap as a whole, is primarily the work of Pascal Martin. Other major contributors include Steve Woodbridge, Ehud Shabtai, and Paul Fox.
This documentation was written using vi (what else? :-) in the format supported by aptconvert. The aptconvert 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:
aptconvert -toc web/manual.html README
The aptconvert tool is available at http://www.xmlmind.com/aptconvert.html.
RoadMap communicates with a GPS receiver using the NMEA 0183 protocol. RoadMap has been tested with a Garmin 38. The GPS receiver must be configured with the datum set to either NAD83 or WGS 84.
RoadMap can connect directly to the GPS receiver using a serial port (or an emulated serial port in the case of USB receivers), but RoadMap usually communicates with the GPS receiver through gpsd, a GPS communication daemon for UNIX. Going through the intermediate daemon insulates RoadMap from some of the GPS configuration, and lets more than one program (namely RoadMap and RoadGps) use the GPS device at once. It also allows RoadMap to use a GPS device which is connected to a different computer. The most typical setup is to have gpsd on the same computer, in which case the GPS source should be set as "gpsd://localhost".
gpsd is not required when building RoadMap, and RoadMap can run without gpsd as a static map viewer or address finder.
RoadMap usually uses one flavor or another of GTK or QT for its user interface. One of these toolkits must be installed. RoadMap can be built for QT/QPE, but the RoadMap makefile for QT must be modified.
RoadMap optionally uses flite (festival lite) to generate voice messages. See section "VOICE INTERFACE" for more information.
RoadMap uses the expat library to load GPX trip and landmark files. RoadMap can be built without expat, with some loss of functionality, by changing config.mk to say: EXPAT = NO. (On Debian or Ubuntu linux systems, use "apt-get install libexpat1-dev" to install the expat library.)
Likewise, RoadMap can sometimes use the agg library to render anti- aliased maps and street label text. If you don't have agg, RoadMap will label with a (relatively crude) built-in font. To use agg, you need to change the default "AGG = NO" in config.mk to choose one of the options listed there. Unfortunately those options ("rgb565", "rgba32", "bgra32", "rgb24", "bgr24") cannot currently be auto-detected, so there may be some trial-and-error involved to get the setting right. See the comments in config.mk for more tips. RoadMap requires version 2.4 or later of the agg library -- 2.3 is incompatible. If your linux distribution includes 2.3, make sure that if you install 2.4 as well, that RoadMap finds both headers and libraries from 2.4. Note: currently (as of August, 2006) the agg support is only available if you're using the GTK2 build of roadmap. (On Debian or Ubuntu linux systems, use "apt-get install libagg-dev" to install the agg library.)
The "buildmap" program uses the shapelib library to decode the "shapefile" format). Currently, most of the maps used by RoadMap are not in that format, but some are: Canadian provinces, state boundaries, and the Digital Charts of the World. If only US maps from the census bureau are used, or if only pre-built maps are used, then there is no need for shapelib: set SHAPEFILES = NO in config.mk. (On Debian or Ubuntu linux systems, use "apt-get install libshp-dev" to install the shapefile library.)
RoadMap uses "aptconvert" to format the documentation (see previous section) into HTML format. Since this is an uncommon tool, a pre-converted copy of manual.html is provided in the RoadMap tarball.
RoadMap can use the "convert" program from the ImageMagick package to generate the PNG versions of some of the icons on its toolbar. Pre-built copies of these PNG files are distributed, so ImageMagick is optional, and in any case is only required for building RoadMap, it is not necessary when running RoadMap.
The port of RoadMap on Windows is recent, not fully complete and has not been tested thoroughly, so problems are to be expected. Thank you for your understanding.
The port to Windows was implemented by Ehud Shabtai (eshabtai@gmail.com).
RoadMap is only available for PocketPC 2002 and later at that time. There is no support yet for Windows XP, 2000 or 2003. This is because the WIN32 API is not the same on all Windows platforms: to the extend of our knowledge, RoadMap might not compile, and should not run, on Windows XP.
RoadMap use the WIN32 API exclusively, and no specific graphic library is required.
There is UNIX Makefile support for building the WinCE version of RoadMap using the arm-wince-mingw32ce cross-compiler toolchain, available from http://cegcc.sourceforge.net, but support in the code for the toolchain is incomplete. Working versions have all come from real Microsoft tools.
Maps cannot be built under Windows (buildmap and buildus have not been ported yet). Maps built under Linux can be used on PocketPC systems, however.
The flite software is available under Windows: a PocketPC 2002 (ARM) binary is available on the RoadMap project's SourceForge web site. The flite.exe binary must be installed in the same folder as the roadmap.exe binary.
The gpsd software is not available on Windows. Note that network access to a remote gpsd is possible (the remote computer must run UNIX).
Instead of a local gpsd, RoadMap can uses a Windows serial port and the GPS source should then be specified as "COM1:", "COM2":, etc...
The roadmap and roadgps programs cannot run simultaneously when configured for the serial port. The "GPS Console" menu item of roadmap does not work in that configuration. The GPS console built into RoadMap doesn't have this restriction, of course.
Only NMEA-capable GPS devices are supported, unless a remote gpsd is used.
Downloading maps on the fly is not available on Windows, due to the lack of gzip and tar tools on PocketPC.
The screenshots feature of RoadMap is not available on Windows or GTK
The full-screen mode of RoadMap is not available on Windows or GTK.
RoadMap is to be installed in a few different directories, where each directory contains a specific type of file: commands, configuration files, icons and maps.
Before you install RoadMap, you must choose what installation directories to use for these files. Some of these choices are already made for you when you install a pre-built package (such as the Familiar ipk package), or are assigned default values in the makefiles (source package). This section describes the whole thing, regardless of how you install RoadMap. It also provides some information about the standard locations in the most common cases.
RoadMap supports lists of directories, instead of a single location, for each type of files. That does not mean you must install the RoadMap files in every of these directories, only that you can install the files in any of these directories.
One reason for RoadMap to support a list of directories is to define a default system-wide configuration, and at the same time to allow a specific user to install their own setup. Another reason (for the map files on a PDA) is to let the users choose the type of hardware storage that is convenient for them.
Directory pathnames in most RoadMap path lists (on UNIX -- these are not yet implemented in the Windows code) can include several "shortcut" characters:
Map.Path: /etc/roadmap,&/maps/...
and ~/.roadmap/maps/moremaps/foo and ~/.roadmap/maps/.secret/bar are both actual directories, then the final list of paths used when looking for maps will be:
/etc/roadmap will not be searched for subdirectories, because it was not specified with a trailing "/...", and nothing below ~/.roadmap/maps/.secret will be searched, because ".secret" is "hidden" in the traditional UNIX sense. The subdirectory search will follow symlinks.
This feature can be used, for instance, to help keep maps of a single region together, by letting them be more easily put into separate directories. If a subdirectory may come and go while RoadMap is running, e.g. if it's on removeable media, then it should be named specifically in the preferences -- list of subdirectories is only enumerated at startup.
The RoadMap programs should be installed in a standard executable directory. This is an easy one: the only requirement is that this directory must appear in the PATH variable (either you choose an existing directory or you add your own).
RoadMap comes with some critical configuration files (files sprites, preferences, etc..). RoadMap supports these files to be in a few different places, which list cannot be changed in the user preferences since it is used to load the preferences themselves. The list can, however, be changed using the "--config=..." commandline option.
On most UNIX systems this list is:
These directories are searched sequentially: any configuration item found in one directory overrides all the same items found in the directories listed before. In other words, the configuration is loaded in the following order:
1- /usr/share/roadmap (installation defaults)
2- /usr/local/share/roadmap (local site defaults)
3- /etc/roadmap (local machine defaults)
4- ROADMAP_CONFIG_DIR, chosen at compile time
5- ~/.roadmap (current user configuration)
The directory ~/.roadmap contains the user configuration: any user change to the configuration is written there. The items in the user configuration take precedence over the "default" configuration as defined in the "shared" directories. This directory can be referred to with the shorthand '&' in other parts of the roadmap config.
The directory ~/.roadmap usually has two subdirectories: trips and maps. "Usually", because while the directory ~/.roadmap/trips is used as the default location for the trip files, it can be changed with the General.TripsPath setting. Note that trip files can be stored anywhere, not only in that directory -- they're just more convenient for selection when stored there..
The directory ~/.roadmap/maps contains map files specific for this user. As a general rule, it is not recommended for each user to have their own copy of the maps, as these maps take a lot of space. This directory can be used however when maps are downloaded on the fly, as shared maps are usually not writable for users. The local rules can be established so that either all users download maps into the shared repository, or else each user manages his own maps. On a PDA or on a personal desktop systems the first solution makes the more sense, but for public access computers (such as computers at an University) the second solution might be the most convenient.
These user configuration directories are created when needed, if they do not exist.
Althrough the Sharp Zaurus is a Linux (i.e. UNIX) PDA, it's setup is somewhat unusual, and the location of the configuration files is different.
The rational for the selected setup, which is typical of a PDA, is to try to make RoadMap an auto-installed option when sliding in the proper memory card. So the locations for files always include the Zaurus mount points for the CompactFlash or SD cards.
The configuration directories on the Sharp Zaurus PDA are:
Like the Zaurus, Windows CE based computers are usually of the PDA type, so the same approach as for the Zaurus is used here, i.e. we make it possible to install all RoadMap files in a memory card.
The configuration directories on Windows CE are:
As Windows CE does not really have the concept of a user directory, RoadMap will automatically add to the list the directory where its executable stands.
RoadMap (GTK version) needs some icons. These icons must be placed in the operating system's standard locations. On UNIX, this usually is:
This list can be changed using the General.IconPath setting.
RoadMap needs some map files to serve any useful purpose.
The location for these map files can be redefined in the user preferences (item Map.Path). The maps are a problem of their own, since they may require a huge space (up to 1.8 G Bytes for the full set). It is recommended to share these maps between users. Because these maps are architecture-dependent you should be careful, however, not to share them on a network (this could also be very inefficient, as this could saturate the network and the RoadMap performances would be severely impacted).
Maps can be located in any directory mentioned in the Map.Path preferences setting. The index file, usdir.rdm, must also be in one of those directories.
RoadMap will only consult a single usdir.rdm file at a time. The first usdir.rdm index file read by RoadMap must index any and all maps you might wish to view. This means that if you've built a subset of the maps, with a corresponding usdir.rdm file (using "buildus"), then when you build more maps, you can't create and install a second usdir.rdm file and expect RoadMap to use them both. A new usdir.rdm must be built which indexes all of the maps.
RoadMap will only read the index file once, even if a newer version becomes available. RoadMap must be restarted in order to take advantage of a new usdir.rdm index file. In contrast, new map files can be added to the Map.Path directories, and RoadMap will find them as needed. This means that maps kept on removeable storage devices can be used fairly easily. [ The one caveat when introducing replacement maps is that RoadMap will only try and find a map when it really needs to. RoadMap will keep a number of maps open, for easy access -- the number is controlled by "Map.Cache". You may have to visit that many other maps before RoadMap will need to reopen a map file which you've visited before but subsequently replaced. ]
(The map search paths referred to below may be changed using the "--maps=..." commandline option.)
By default, RoadMap is built to search for the following directories on most UNIX systems:
(Note that releases prior to 1.1.0 did not search subdirectories.)
RoadMap also searches in /usr/local/share/roadmap and /usr/share/roadmap, but this is in violation of the FHS filesystem standard, since these maps are not architecture-independent.
The Zaurus is a special case again, as the default path on these systems is:
The two last directories are located on a memory card, as this would be the only reasonable place where to install the maps considering their size.
The architecture-dependent nature of the map files is not an issue with a PDA, as these machines tend to be used standalone and not to rely on network access.
On Windows CE the default map search path is:
RoadMap can be downloaded from the RoadMap web site:
A quick way to get a feel for RoadMap is to download and install the contents of this tar file, which contains the US state boundary outlines, the detailed map of San Francisco, and a minimal directory file which will let RoadMap use them.
The complete set of maps is available here:
The full RoadMap directory file (usdir.rdm) must be downloaded first, as RoadMap will not work without it.
Please refrain from downloading all the US states at once, as the map files are huge and the bandwidth is expensive.
It is recommended to install the maps in one of the default directories (see previous section). You may also install the maps in any directory, assumed you set Map.Path accordingly in the RoadMap preferences.
Previously, RoadMap came either as a set of sources, or as a set of binary files. This is no longer the case -- it is not hard to build, and there are choices to be made when building, so the source tarball is all that is currently available.
If available at all, the RoadMap familiar distribution contains one .ipk package file. This package contains the RoadMap executables (roadmap and roadgps) as well as the configuration files for a GTK 2.0 setup (such as the Familiar 0.7.2 GPE image). This package does not contain the map files or the map index file.
If RoadMap is available from your feed:
ipkg install roadmap
If you downloaded the ipk files on the iPAQ:
ipkg install roadmap_X.Y.Z_arm.ipk
RoadMap is useless without maps. The maps can be downloaded from the web site (http://roadmap.sourceforge.net/maps.html or mirrors) or generated from the US Census Bureau's files (see later).
It is strongly recommended you install the maps on a CompactFlash or SD/MMC card, and not on the iPAQ internal flash. The reason is that the maps are way too big to be installed on the iPAQ flash. As configured, RoadMap will look for the maps either in
(This can be changed using the Map.Path item in the RoadMap preferences dialog.)
The set of maps for California represents more that 100 Mbyte of data, the whole US about 1.6 Gbyte. Unless you are the lucky owner of a large capacity CompactFlash, you will have to install a subset. A capacity of 128 Mbyte is enough in most cases, 64 Mbyte might be enough if you do not travel far from home.
To build the maps yourself, you need the Linux/i686 binary or the source tarball. See the next section for more details.
It is also possible to rebuild RoadMap and the map files from scratch from the source distribution:
tar xzvf <tarball>
Simply typing "make" will build the default selection in config.mk. (GNU make is required.)
Note for QT users: the RoadMap QT module is built with QT3 by default, but requires the QT2 compatibility headers.
The complete list of options for building RoadMap is as follow. These can all be modified by editing config.mk.
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.)
http://www.census.gov/geo/tigerline/app_a02.txt
(A world-extended version of app_a02.txt is provided in directory src, so you should probably skip this step.)
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. (To build older versions of the maps (e.g. 2000), see the script source for the "format=2000" option.) Alternatively, specific counties can be built. The county shall be identified by its FIPS (e.g. 06075 for San francisco, CA).
rdmgenmaps <tiger-path> [maps=<map-path>] <county> ..
The rdmgenmaps command can also process one full state at a time:
rdmgenmaps <tiger-path> maps=<map-path> state=<state-id>
where the state-id is the two first digit of the FIPS (such as 06 for california).
The rdmgenmaps tool is a shell script that extract 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 takes a county "FIPS" 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. It looks for:
This is not a problem if the catalog references a map file that does not exists: this way it is possible to store locally only a small portion of the US maps. This is useful when using a PDA with limited storage space (like the iPAQ).
make install
This last step installs the RoadMap executables. These executables and the maps should have been generated at their proper location in steps 3 to 8. The install is not required for running RoadMap: the programs and build tools) can run from the local directory as well.
RoadMap can be built from sources for Windows CE on a Windows XP or 2000 computer. The Embedded Visual C++ tool version 3 or 4 is required. These tools can be downloaded for free from the Microsoft web site, see:
http://msdn.microsoft.com/embedded
Note that not all RoadMap programs can be built on Windows. More specifically, the tools used to build the maps are available only on UNIX. However the maps available from the RoadMap web site do work with the Windows version of RoadMap.
The directory src/win32/wince_env contains a workspace file (Roadmap.vcw) that must be used to build roadmap and roadgps.
The cross compiler for the Familiar/Linux target requires some additional make options: LDFLAGS, OPTIONS, CC, AR, STRIP and X11LDFLAGS. For example:
LDFLAGS="-Xlinker -rpath-link -Xlinker /usr/local/arm/3.3.2/arm-linux/lib:/usr/local/arm/3.3.2/lib -L/usr/local/arm/3.3.2/lib" STRIP=arm-linux-strip CC=arm-linux-gcc AR=arm-linux-ar CC=arm-linux-gcc AR=arm-linux-ar STRIP=arm-linux-strip OPTIONS="-march=armv4 -mtune=xscale" X11LDFLAGS="-lXinerama"
In addition a few environment variables must be defined or modified:
PKG_CONFIG_PATH must be set to the right tool (for example: /usr/local/arm/3.3.2/lib/pkgconfig).
The PATH variable must contains the cross compiler directory (for example: /usr/local/arm/3.3.2/bin).
The RoadMap toolbar uses road signs as icons. These icons come with the application (in directory src/icons). The icon source set is made of a mix of PNG and XPM files. The final icon files must all be PNG.
A make script builds all the necessary files using the ImageMagick package. The icon files are built (or installed) when building (or installing) RoadMap.
The PNG icon files must be installed in one of the following directories (the order below reflects the search order):
~/.roadmap/pixmaps
/usr/local/share/pixmaps
/usr/share/pixmapsThis section describes the most common problems encountered when installing RoadMap:
RoadMap includes the following applications:
The options marked as "sticky" remain in effect the next time RoadMap is run. The use of the option actually changes the specified RoadMap preferences item.
The RoadMap application accepts the following command line options:
The main RoadMap window includes a "Help" menu. This help can be used to display various topics from this document. The help text is actually an HTML version of this file, shown using a web brower. The default browser is "dillo", but this default can be changed in the user's preferences (see section PREFERENCE ITEMS).
The main RoadMap window shows the menu, the toolbar and the map's canvas. The toolbar is optional: all the commands are also available from the menu bar or from the keyboard or iPAQ buttons.
When RoadMap starts, the map view reflects the previous session's mode If no session data is found, RoadMap tracks the current GPS position. It is possible to select another mode: show the current destination point (see the section "Managing Trips" below), show a specific location, track the GPS position with the north shown up, track the GPS position with the direction of movement shown up, etc.
When RoadMap is in GPS tracking mode, the map view will reflect the movement of the car so that the GPS sprite will remains at the predefined position (usually the center, but it is possible to move the position of the GPS sprite using the arrow keys). The map can be held to its current position: the "hold" button freezes the map view to its current location, but updates will continue, so that, for example, one should see the GPS sprite move away from the map's center. The hold mode make it easy to select streets and read street names while on the road. To come back to the original map view, this view must be re-selected (for example by using the menu command Find / GPS position or the "G" toolbar button).
RoadMap indicates the current street a few seconds after the GPS position reached the street. This display is also shown for a limited time. There are several criteria used by RoadMap to "lock" on a street: the distance to the street (the closest the better, not more than the value set with Accuracy.Street), the direction of the street compare to the direction of the vehicle or if the street is connected to the current "locked" street. RoadMap uses fuzzy logic to combine these criteria into one single value. None of the fuzzyfied values for the distance and direction may be below the value set by Accuracy.Confidence, or else the street is not selected. The final fuzzy value must also be above the same limit. RoadMap then selects the street with the highest fuzzy value.
RoadMap can also display four messages at each of the corners of the map: the message at top left will be shifted to leave room for the compass, which shows map orientation. These messages can be defined by the user using RoadMap's specific format strings (see section "Configuring the RoadMap text and voice messages").
RoadMap uses mostly one mouse button (the left button on a 3 button mouse). This is because RoadMap is designed for a PDA, where pens are used.
A short mouse click (or pen tap) on the map screen displays information (i.e., name, address range, etc, as appropriate) about the closest waypoint, landmark, street, road or freeway. This display is shown for a limited amount of time (see preference "Highlight.Duration"). Whether or not one of those map features is near enough to be selected, the clicked/tapped point will be remembered as the current "Selection", for the purposes of adding new waypoints or landmarks.
A long mouse click or pen tap (with no accompanying motion) will bring up a popup menu (see preference item "Events.Long Click").
Dragging the mouse with the button down, or dragging the pen on the screen, moves the map display according to the movements of the mouse or pen.
Dragging a map display is a CPU-intensive action, so a few "Style" preference items can be used to limit the amount of drawing to be performed while doing it.
A few additional actions are specific to the mouse devices, with no pen equivalent: the mouse's right button and wheel.
A popup menu can be attached to the mouse's right button (see preference item "Events.Right Click"). The menu iteself must be defined in the file roadmap.popup (see section CONFIGURING THE MENUS AND TOOLBAR).
Mouse wheel actions will trigger a zoom in and out of the map display, depending on the direction of the wheel movement.
If the flite program has been installed, or if RoadMap was configured for an available speech application, RoadMap will complement the screen information with an audio one: Roadmap will "tell" the name of the street on the audio output device. As a general rule, RoadMap tries not to repeat the same message again, as frequent audio messages tend to border on the irritating side. Thus if the same street is selected more than once, the screen information will be displayed each time, but the voice messge will be provided only once. As voice messages tend to take a significant time to be produced, RoadMap memorizes the latest message requested while the current message was produced and will "air" it after the current message has been completed. Only one message is stored that way, the last requested one: any message generated in between is ignored.
It is possible to mute the RoadMap's voice, using the File / Mute Voice item from the menu bar. The voice can be enabled later using the File / Enable Voice item.
Please note that it is possible to rebuild flite with a better voice than the default one. The flite source is available at the CMU web site:
http://www.speech.cs.cmu.edu/flite/
The flite README file describes how to regenerate flite using another voice. Here is an example, courtesy of Scot Wilcoxon:
cd flite
make clean # to remove old executable files
./configure --with-vox=cmu_us_kal16
makeMost of the RoadMap commands are available from the keyboard (so to answer requests from my loyal Zaurus fans :). In fact, the button and key bindings are common to all ports, but some buttons might not exist on some platforms.
Please note that all the button and key bindings are case insensitive, i.e. the same binding applies to 'A' and 'a' (as well as to "Button-Left" and "button-left"--whatever it means).
On a desktop or laptop (or on the Zaurus), the keyboard keys are mapped as follow:
| 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. |
| + | Zoom in: enlarge the central part of the map. |
| - | Zoom out: show a larger area. |
| A | Show a specified address. |
| B | Start the trip back to the departure point. |
| D | Show the destination point. |
| E | Erase maps among those currently visible. |
| F | Toggle the full screen mode. |
| G | Show the GPS position. |
| H | Hold the map view in its current position. |
| I | Show 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). |
| 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 are printed after the options help information when the --help option is used.
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.
Map downloading is being rewritten: future versions will download rdx files from the RoadMap web site (or from a user specified site).
Today's PDA have a limited storage space, which must be shared with MP3 and other files. As the RoadMap maps can take up to 1.6 GB, most PDA users will want to install only the few maps they need. The on-the-fly download feature of RoadMap helps the user to select visually which maps to download or remove. RoadMap is capable of downloading compressed maps: gzip, bzip2 or lzop compressed files are automatically recognized and uncompressed after transfer.
The map download is available in a special RoadMap mode, which can be activated and deactivated using the Map Download menu entry. On startup the download mode is always deactivated. RoadMap shows a red "download" icon in the right top corner of the map screen to indicate that the download mode has been activated.
In the download mode, if a map is not found by the display engine, the user will be asked for the permission to download the file from the configured source (as defined in the preference item "Download.Source"). The destination directory can also be configured (using the preferences item "Download.Destination"). Both the source and the destination file name can be edited manually before each download.
RoadMap is designed to support multiple download protocols. The protocol is selected depending on the source string, as much as possible using the well-known URL syntax. Two protocols are available: a local file copy (the source is either a full path or a "file://*" URL) and the HTTP protocol (the source is a "http://*" URL). The local file copy protocol can be useful in some cases, for example when mounting the map server's disk using nfs or smbfs.
If the suffix of the downloaded file matches a well-known compressed files suffix, RoadMap will invoke the appropriate tool to uncompress the file. The compression tools supported are gzip (.gz suffix), bzip2 (.bz2 suffix) and lzop (.lzo suffix). This feature makes it possible to store compressed maps on the server side. Using compressed files may reduce by a factor of two the time it takes to download the map, depending on the compression tool used, the specific map's content, etc.. Note that maps are always stored uncompressed: because RoadMap maps the file in memory, compressed file cannot be used by RoadMap.
If the user cancels the download of a specific map, RoadMap will not request the same download again for the remainder of the session. This means that RoadMap will request the same maps again if stopped and then restarted. This was done because there is at this time no way for the user to change his mind and re-request the download of a cancelled map. This is a part of the user interface that is likely to change in the future.
RoadMap also provides a dialog for deleting maps, activated through the "Delete Maps.." menu entry. The dialog shows the number of map files stored locally, the total size of the local maps and the list of maps currently visible on the RoadMap screen. The proper way for selecting maps to delete is to view an area you do not need anymore, hit the "Delete Maps.." entry, then select a specific county and hit the Delete button. The county will immediately disappear from the map screen and the dialog gets updated (i.e. the map statistics and the map list will reflect the latest delete action). Several counties can be deleted this way before the dialog is closed (button "Done").
Note that a deleted map is automatically added to the "cancel download" list, so that RoadMap will not request for this map again. As such, it is not a problem to delete maps while the download mode is active. If you need to download again a map that was deleted, just restart RoadMap.
A typical use of the download feature is to preload the maps you need before you go on a trip. Activate the download mode and select the destination address: RoadMap will request the download on the map that covers this destination. Zoom out the display to force the download of adjacent counties, if required. Repeat for each place you are likely to go to. Use the arrow keys or buttons to "fly over" the roads you are going to travel on. If you missed a map, and you did set a public map web server, it should be possible to download maps from an hotel's Internet access. Of course, if you are (rich and) lucky enough to have an Internet connection while on the road, the download feature can also be used at any time.
Here is a typical setup using the HTTP protocol:
1- Install the individual map files, gzip-compressed, in a "maps" subdirectory of the web server directory tree. Say the web server is named "desktop".
2- Set the preference Download.Source to http://desktop/maps/usc%05d.rdm.gz
3- Set the preference Download.Destination to /var/lib/roadmap
4- Make sure the preference Map.Path does include the directory /var/lib/roadmap.
RoadMap manages several types of points: a location point (selected using a street address or the mouse), the GPS position (updated automatically if a GPS fix is available), and an arbitrary number of user-defined waypoints, which may appear as part of a route or a track.
One can select which one of these locations serves as the center of the map. The GPS and waypoints positions are special cases: see the section on trip management.
The location point is really a buffer for the selection of a street block. Once selected, the point can be defined as a (new) waypoint or as the destination, by using it to establish a new trip. Thus the definition of a destination or waypoint is a two step procedure: (1) select a location, and (2) use the selected point to create a waypoint or a new route (in the Trip menu).
The location point can be entered in one of three ways: - by clicking on a location on the map, - by entering a valid USPS address (street number, name, city and state names) in the dialog launched by the "Show Location.." menu entry, - by specifying the intersection of two streets in the dialog launched by the "Show intersection.." menu entry.
More details are provided in the following sections.
Street names are used in the two dialogs used to select a specific location: the address and intersection dialogs. These dialogs follow the same rules regarding the format of the names.
When entering a street name, the street prefix and suffix, if provided, must be among the abbreviations listed by the US Census Bureau (N for north, SW for southwest, etc..). The "type" part of the name (i.e. "Rd", "St", "Pl") can be given using either the Census Bureau abbreviation, or by spelling it out in full (i.e., "Road", "Street", "Place"). In almost all cases, the US Census Bureau conventions follow the usual abbreviations, so there is no need to worry here. In addition, any of these fields is optional: not providing them only makes the search less selective. If several matches are found, RoadMap shows a list of all matching streets and lets the user select the appropriate one.
The exact format of the data expected by RoadMap as a complete street name is as follow:
[prefix ' '] name [[' ' suffix] ' ' type]
The name itself may include space characters. Potential conflicts are resolved by excluding the prefix, suffix and type fields from the name only when a match is found with the valid set for that county. As such, the following names would work OK in any circumstances:
N Rio del Sol St --> RoadMap detects both a prefix and a type.
Rio del Sol St --> RoadMap detects the type, no valid prefix.
N Rio del Sol --> RoadMap detects the prefix, no valid type.
Rio del Sol --> RoadMap detects no valid prefix or type.Lets go through an example: we will search for 100 East Washington Boulevard in Los Angeles, California. The name of the street should be typed as follow:
e washington blvd
The 'e' stands for "east", 'blvd' stands for boulevard, according to the US Census Bureau documentation. Note that RoadMap is not case sensitive.
The result is a single match, so RoadMap shows the location immediately without any additional question. However it is possible to omit either the prefix, street type, or both, with the effect of broadening the search. Let say we entered:
washington blvd
Now RoadMap display a dialog that lists 3 matches:
Washington Blvd, Los Angeles
W Washington Blvd, Los Angeles
E Washington Blvd, Los AngelesThe first item in the list is shown selected, and RoadMap displays a new location in the map display. In fact, each time the user selects one address in the list, RoadMap displays the corresponding map location. When the user hits the OK button, this simply confirms the current choice as the final one.
Note that not providing a prefix, suffix or street type does broaden the search, but the street name must always be provided in full: at that time RoadMap provides only an exact street names search. Thus providing "wash" instead of "washington" only triggers the error message "No street with that name could be found".
It is possible not to specify the street number part of an address: in that case, all street blocks matching the street and city names will be listed. Be careful, that might make a long list, and RoadMap has a limit of 256 items per list (matching items beyond the 256th one are discarded).
It is also possible to specify an approximate city search: if the city name is prefixed with a character '?', then the name of the city is used to find the county, but is not used in the street match: the idea is to list all similar addresses around (i.e. in the county). This is useful when one is not sure of the city name, or only knows the name of a city nearby.
The "Intersection.." menu entry activates a dialog that asks for two street names and a state name. RoadMap will search within the given state for all intersections between streets that match the street names provided. This search may take a few seconds, especially if the maps must be read from disk.
In the (likely) case where multiple intersections have been found, RoadMap displays a list that shows the name of the city and the name of the county where each intersection is located. This selection list follows the same rules as the address selection list described in the previous sections.
The "Position.." menu entry activates a dialog that asks for a longitude / latitude position. The format for the longitude and latitude must conform to the ISO 6709-1983 standard (with some extensions).
The format for longitude is:
[+-EW][d]dd[mm[ss]][.ffffff][EW]
The format for latitude is:
[+-NS]dd[mm[ss]][.ffffff][NS]
Where "[d]dd" or "dd" stands for the degrees, "mm" stands for the minutes, "ss" stands for the seconds and "ffffff" stands for the fractional part (either fraction of degrees, minutes or seconds, depending on the context).
The main extensions compare to ISO 6709 are as follow:
RoadMap supports an infinite number of trips: each trip context is saved in a trip file. One trip at a time can be edited or activated. A saved trip can be reloaded from the trip file, of course.
The last trip created or loaded will be reloaded the next time RoadMap starts. If the name of the trip has been specifically set by the user, it will appear in the titlebar of the RoadMap window.
A trip is a (usually small, but unlimited) collection of landmarks, routes, and tracks which (usually) have some relationship to one another.
Routes are sequences of waypoints that (usually!) lead you somewhere you want to go. Tracks are sequences of recorded waypoints that show you where you've been. Although one doesn't usually do so, a track can be followed just as a route can be followed.
Trip landmarks are waypoints that aren't in a route or a track. They're just (presumably) interesting all by themselves. (The trip's landmarks are distinct from another set of landmarks known as your "Personal Landmarks". The "personal landmarks" are displayed on the map no matter which trip is loaded.) Landmarks and waypoints are sometimes just referred to as "Places".
One end of a route is the starting point, and the other is the destination. Comments attached to the route's waypoints are used to give directions from one waypoint to the next. Routes can be reversed, in order to traverse them backwards (but the comments don't get rewritten). Reversing a route will not change the trip file -- the reversal is completely internal to RoadMap.
When you load a trip (or when you start RoadMap, and the last trip you used is automatically re-loaded), you'll be presented with a menu of routes to choose from. (That is, if the trip contains more than one. If there's only one, it will be selected automatically.)
While you might choose to name your trips with a ".gpx" suffix, as a reminder of what format they're stored in, this is entirely optional. File suffix doesn't matter.
Note that although tracks and routes are conceptually separate, either type can be selected at this point, and any of the operations under the "Routes" menu can be applied to either.
One of the buttons in this "Manage Routes" dialog is "None", which is a quick way of not selecting any route at all.
If you're starting a "fresh" trip, you'll likely start by creating a route. Choose a place that will be part of the route -- a waypoint, a landmark, a street address, a geographic location -- and then use the "Create New Route" menu entry to begin constructing your route. This will create an unnamed route with only one waypoint -- your destination.
A route with only one waypoint isn't very interesting, so you'll want to select more points along the route. To select a new place, you can a) click (or tap) on the street where you wish to go, b) use the "Find" menu items "Address...", "Intersection...", or "Position..." to locate it, or c) choose another, previously created place from the route, the trip landmarks, or the personal landmarks. After locating your new waypoint, use the "Add as waypoint" menu item to add each to the route. You'll have choices of where to add (at the beginning, at the end, or as a midpoint of the nearest route segment), as well as a chance to add it as a landmark, to either the trip's list, or your personal list. Continue adding waypoints to your route.
(If you do much route creation, you should create a toolbar button for the "addroutewaypoint" command. Then, the easy way to create a route is to first create a trivial route between the two endpoints as described above, and then points on the map and add them with your toolbar button. The route will "snap" into place through each new point you add.)
Note that waypoints are always copied. So if you choose an existing waypoint or landmark to use as a route waypoint, you'll end up with a new waypoint, not just a second reference to an existing waypoint.
You can give your new route points names as you go, or wait until later and use the "Route Waypoints..." menu item to go back to the list, and select the ones you wish to rename or to which you wish to add comments. Waypoint deletion can be done here as well.
It is also possible to delete, edit, or move waypoints and landmarks by directly selecting them with the mouse. Use a short click to select the place of interest -- its identifying information will be shown along the bottom of the screen. Then use the appropriate menu command to delete, edit, or move the selection. These commands are most readily accessed via the "long click" menu. If doing a move, you'll select the place, then choose the "Move place" command, then click or tap at the new desired location.
Your route doesn't yet have a name. That's fine -- routes and tracks can be unnamed. If there's only one route in a trip file, it's no big deal, but if there's more than one, you might want to give them names to help keep them straight. You do this (you can also add descriptive text) from the "Manage Current Routes" menu item. This is also where you'd select a different route to work with. If your trip has tracks, they'll appear hear as well. Be careful with delete! There's no undo command. Note that in addition to having no name, multiple routes can have the same name. This will not confuse RoadMap, though it may confuse the user.
Another, perhaps less convenient, method of creating a route, is to base it on a track that you (or someone else) has already travelled. While it's possible to simply select a track and follow it as one would follow a route, there are usually too many trackpoints showing up and obscuring the actual roads. It's better to create a route from the track using the "Simplify Route" command. (Remember that all of the route commands apply to tracks as well.) If simplification was successful (i.e., if any waypoints could be eliminated) a new route will be created and selected. It will be named after the original, with "Simple ..." prepended to to the original name. (If it had a name -- otherwise the result is unnamed as well.)
One advantage of using the popular GPX format is that routes and landmarks can be obtained from other sources. Not only are some GPS management programs converting to use GPX directly, but there are many "something-else-to-GPX" conversion programs available. There are many such programs listed at: http://www.topografix.com/gpx_resources.asp
One of the best, and most complete, of these conversion programs is gpsbabel, available here: http://www.gpsbabel.org/
There's also an online front-end to gpsbabel, here: http://www.gpsvisualizer.com/gpsbabel/
Gpsbabel will convert from most popular GPS data formats, and can talk directly to many GPS devices without involving their vendor's "support software" at all. [ RoadMap is particularly indebted to gpsbabel, since much of the code which supports RoadMap's GPX input and output came directly from gpsbabel. ]
One handy source of route and waypoint data these days is Google Maps. Google directions and waypoints can be converted directly to GPX format by the GMapToGPX bookmarklet: http://www.elsewhere.org/GMapToGPX/
gpsbabel can do this too, somewhat more indirectly -- the following script shows how:
#!/bin/sh
function usage()
{
echo usage: $0 "from address" "to address" >&2
exit 1
}
if [ $# != 2 ]
then
usage
fi
from="$1"
to="$2"
# the gpsbabel line simplifies: the "error=xxx" value is in miles,
# and signifies how far any single point must be from the straight
# line connecting its neighbors in order to not be discarded.
wget -O - "http://maps.google.com/maps?q=$from to $to&output=js" \
2>/dev/null |
sed -e 's/<b>//g' -e 's/<\/b>//g' |
gpsbabel -r -i google -f - -x simplify,error=0.05 -o gpx -F -The above script shows how one might use gpsbabel to simplify a route or track rather than doing it with the Simplify command inside RoadMap. Using gpsbabel might give better results, since it currently uses a different (and more expensive) algorithm than does RoadMap.
Once you have a have a data in GPX format, it's simply a matter of loading that that data with "Open Trip", or merging it into another of your existing trips with "Merge Trip".
Sometimes one doesn't really want to follow a route at all -- all you want to do is set a goal, and be kept informed of how far away it is, and in which direction. (This might be useful for geocaching, for instance.) That's what the "Quick Destination" menu entry is for. Select where you want to go (a waypoint, a street address, an intersection, or latitude/longitude spot), and as you move around, the display will continously display the distance and direction to that point.
A route that has been created or loaded can then be activated. Activating a route defines the departure point (the current GPS location) and enables the "trip display" mode: extra status information will appear on the map. This will include an arrow beside the GPS location symbol to indicate the direction of the next waypoint, as well as user configurable messages, such as distance information, the directions to the next waypoint (if any are present in the waypoint's comments), its distance, etc. The messages will display at the corners of the map. (see CONFIGURATION for more information about these user configurable messages).
If the route's waypoint contains comments (from the "cmt" element of the GPX file), these will be displayed as directions which should be followed when that waypoint is reached. The directions displayed will be from the next waypoint which has directions, i.e. there may intervening waypoints that do not have comments.
A waypoint is "attained" by entering within its "vicinity". This radius is set in the user's' trip preferences (125 ft, by default). When entering the vicinity circle, the GPS directional arrow will immediately begin pointing at the next waypoint in the list. On-screen directions will not be updated (i.e., to describe the next turn, rather than the current turn) until one leaves the waypoint vicinity. In addition, RoadMap honors a larger circle, at twice the size of the waypoint vicinity. If one enters this circle and then leaves it (without ever entering the inner "vicinity-sized" circle), then Roadmap will see if the next route segment is closer than the last route segment, and if so will assume that the user is on track to the next. The directional pointer and on-screen directions will be updated, even though the waypoint was never "quite" attained. This helps accomodate small map errors, or large roundabout or interchange intersections where the actual waypoint may be unreachable.
A route can be stopped at any time and then resumed. When a route is resumed, the waypoint chosen as the "next" to be visited is chosen by searching for the route segment that is closest (in geometrical terms) to the GPS location. The route can also be resumed in reverse mode: in that case the departure point and the destination point switch roles. The reverse mode makes it possible to use the same RoadMap route on the way back, though as noted previously, any comments on the waypoints that give directions will be unchanged. This can be a bit confusing sometimes!
When a route is active, RoadMap tracks the GPS position in realtime and updates the map accordingly. The GPS position can be shown in two modes: either North up or GPS direction up depending on the "Map.DynamicOrientation" preference item. In the second case, the map is rotated according to the direction information received from the GPS, and is convenient as it matches the driver's or passenger's view. (This dynamic rotation is in addition to the map manual rotation.) Some people find it disconcerting, however, and will wish to retain "North up" mode.
Unless specifically disabled in preferences, the GPS track followed by the user will be continuously recorded by RoadMap. By default this "breadcrumb trail" will be displayed on the map, but this can be suppressed with the "Show/Hide Track" toggle command. Whether the track is displayed initially is also configurable.
The frequency at which points for the track are recorded is determined by several settings in preferences:
Normally the recorded track will be saved in the configured filename. The default for this file is "currenttrack.gpx". If one wishes to record tracks, but never save them to disk, set the filename to the special value "NONE".
RoadMap can interface with the outside world through separate driver applications. A driver can:
The objects reported to RoadMap have the following attributes:
All drivers must be listed in the text file ~/.roadmap/drivers. This file contains one line per driver, with the following syntax:
<name> : <command>
The command may have any number of parameters (or none). The program must be specially designed to interact with RoadMap: do not just use any program as a RoadMap driver.
Once a driver has been declared in the drivers file, it can be enabled or disabled by changing the Drivers.driver preference item. By default, all newly declared drivers are disabled. A disabled driver is known to RoadMap, but is not started. Multiple drivers can be enabled at the same time, however some drivers may not be designed to be started more than once.
RoadMap comes with 3 drivers:
These three drivers were designed so each can be started more than once: the option --driver=name replaces the default driver's name (repectively Ghost, Friends and Kismet) with the specified name. This changes the category of the driver's preferences items as well. It is thus possible for RoadMap to interact with multiple friends servers or kismet scanners.
For example, the following drivers file declares 2 ghost drivers:
Ghost1: rdmghost --driver=Ghost1
Ghost2: rdmghost --driver=Ghost2It is possible to edit the roadmap's preferences (select File/Preferences from the menu bar). Most preference items take effect only when roadmap start, so quitting roadmap is usually required. Editing the roadmap preferences requires a keyboard to be available. One way to configure the iPAQ preferences is to run roadmap from the iPAQ, redirected to the desktop's or laptop's X server.
The RoadGps tool can be started on its own (using command line options similar to those of RoadMap), or from the RoadMap's File / GPS Console menu item.
RoadMap itself now contains a fairly complete version of RoadGps, so the separate RoadGps executable may not be necessary.
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 those satellites used to compute the current position.
More importantly, RoadGps allows to log all the NMEA sentences received. RoadGps rotates through up to 127 log files. The log file are created in /var/tmp, with the name formatted as: "roadgps-%d.log" (where %d represents an integer in the range 1..127).
This log file can be replayed in RoadMap using the --gps option with an absolute file name as an argument. For example:
roadmap --gps=/var/tmp/roadgps-1.log
When RoadGps starts, the logging function is off. Whenever the logging function is turned on a new log file is created (if the logging function was already on, the current log file is closed and a new one is created).
RoadGps uses a subset of the RoadMap preferences setup, but has no preferences editor of its own: configure RoadMap first, and then use RoadGps.
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.
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 for more details.
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:
The session file contains the state of roadmap, which is saved (if needed) when roadmap exits. The preferences file contains all the preferences items, and can be edited by the user. The schema file describes the geographic entities that are shown on the map; it should normally not be modified by the users. 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.
The RoadMap configuration also contains the map class files. Each class file describes the organization of one set of map files showing the same list of layers (roads, topography, water feature, etc...).
The class files are stored in a skin subdirectory. It is possible to install multiple sets of class files by creating multiple skin subdirectories and then select the active skin in the user preference. The default skin is named, well, default.
The class files are described in more details in the MAP FORMAT section.
(Note that the class files replace the old schema file, which is no longer used.)
The RoadMap text displays and voice messages can be configured by the user using format strings in the preferences. The format strings contain static and dynamic parts. The dynamic parts (or "%-macros") are specified using the character '%' followed by one character that denotes a predefined RoadMap variable.
| 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: | the 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: | the name of the selected or current street. |
| P: | the name of the selected or current place. |
| R: | the 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").
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 roadmap,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=actionsThe following is an example of a menus definition file for RoadMap:
/Right Click Popup
preferences
gpsconsole
-
quit
/Help
aboutThe 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. Why one would want to rename actions? Some poor souls have expressed their disapproval of this author's choice of labels and help texts. More seriously, some small screens do require short labels, while longer labels are better on large screens. Since one size does not fit all, we let you, the user, have the last say on this matter.
The renaming mechanism is based on the same actions as the menus and toolbar customization (see above).
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 the separator must stay the same until the end of the line.
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'applicationRemember that the toolbar labels should be very short, since the toolbar has a limited size.
Please note that, contrary to the example above, this renaming is not intended to provide a general mechanism for the internationalization of RoadMap. This would be a very crude translation mechanism, as it is very incomplete (for example, dialogs are not translated).
In fact, this renaming mechanism is likely to conflict with a future internationalization effort, and might be removed in later releases.
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 ' 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. |
Some RoadMap configuration items define colors to be used. As a general rule a color must be described in a way that is suitable for the target graphic system.
In the case of X11, that means either a color name (as defined in the /etc/X11/rgb.txt) or a color definition: #rrggbb where rr, gg and bb are hexadecimal values (for example: #FFFFFF is white, #000000 is black).
Note that the #rrggbb format is broadly supported, even on target systems that do not support named colors.
Default: imperial
Format: integer
Default: 60
Format: boolean
Default: yes
Format: boolean
Default: yes
Command line option: --no-icon
Format: a comma-separated list of directory paths.
Default: see the ICON FILES section of this document.
Comment: the hardcoded default includes the usual linux system pixmap directories used for storing application icons. A "pixmaps" subdirectory of the user's .roadmap directory, and the system roadmap config directory, will also be searched.
Format: integer (milliseconds)
Default: 300
Comment: when displaying maps that cover a large area, or on a slow computer, it may be helpful to have an on-screen indication of how long the refresh will take. The value is the delay until the progress bar appears. Use '0' to disable the progress bar.
Format: boolean
Default: yes
Command line option: --no-toolbar
Comment: in some case (GTK2) it may be necessary to suppress or minimize the toolbar if a very small screen is needed, because the size of the toolbar may dicate the minimum size of the screen. The toolbar can also be eliminated by creating an empty "roadmap.toolbar" file.
Format: "Top", "Bottom", "Left" or "Right"
Default: system default toolbar position (usually on top).
Format: boolean
Default: yes
Comment: Tooltips may not work well on a touchscreen device.
Format: a directory path, usually starting with '~'
Default: ~/.roadmap
Comment: This directory can be referred to in other RoadMap path specifications using the shortcut '&'.
Format: a directory path
Default: &/trips, i.e. in ~/.roadmap/trips
Comment: Trips files can be stored anywhere, but in some places RoadMap makes it easier if they're stored here. New trips, unnamed by the users will be stored here.
Format: integer (percentage)
Default: 100
Format: WIDTHxHEIGHT
Default: 800x600
Format: WIDTHxHEIGHT
Default: 300x200
Format: WIDTHxHEIGHT
Default: the value of Geometry.Default
Format: RoadMap format string
Default: %D (%W)|%D
Format: RoadMap format string
Default: %S
Format: RoadMap format string
Default: In %Y, %X|%X");
Format: RoadMap format string
Default: empty
Format: number of seconds.
Default: 10
Comment: the selection is only removed when the map is redrawn.
Format: integer (milliseconds)
Default: 200
Format: integer (pixels)
Comment: Currently only honored if either the internal "linefont", or AGG, is being used.
Format: a program name, with or without path.
Default: dillo
Format: a format string, with one '%s' for the help URL.
Default: %s
Format: a comma-separated list of directory paths.
Default: empty string (i.e. RoadMap uses the hardcoded default)
Comment: the hardcoded default also includes the directories /usr/local/share/roadmap and /usr/share/roadmap, for compatibility purposes. These two directories were the standard locations for the maps in previous versions of RoadMap. Maps can be located in any directory mentioned in this path. RoadMap will only consult a single usdir.rdm file at a time, even if more than one is present in the Map.Path directories.
Format: integer
Default: 8
Comment: This value controls how many maps RoadMap will keep "open" at once, for faster access.
Format: color
Default: LightYellow
Format: boolean
Default: yes
Comment: chooses whether streets are labeled at startup. They can still be toggled by command.
Format: boolean
Default: off
Comment: chooses whether the map will initially show north, or the direction of travel, towards the top of the screen. Can be toggled by command as well.
Format: integer
Default: 0
Comment: offset (millionths of a degree) applied to GPS results
Format: integer
Default: 0
Comment: offset (millionths of a degree) applied to GPS results
Format: boolean
Default: yes
Comment: use only in special cases (very small screens)
Format: enumeration (normal / forced)
Default: normal
Format: enumeration (off / labels / signs / all)
Default: labels
Comment: The internal line font may be preferable to the system font since it can draw at angles, and since its size can be easily scaled. It is not very pretty, however.
Format: integer (in pixels)
Default: 25
Format: color
Default: Black
Format: integer (pixels)
Comment: Currently only honored if either the internal "linefont", or AGG, is being used.
Format: pathname, including & and ~ shortcuts
Default: landmarks.gpx, in the '&' (~/.roadmap) directory.
Format: color
Default: dark red
Format: integer (pixels)
Comment: Currently only honored if either the internal "linefont", or AGG, is being used.
Format: pathname, including & and ~ shortcuts
Default: currenttrack.gpx, in the '&' (~/.roadmap) directory.
Comment: The file is in stored in GPX format.
Format: enumeration (on, off)
Default: on
Comment: The display can still be toggled by command.
Format: enumeration ("off", "Deviation", "Distance", "Time")
Default: off
Comment: When "off", no track is recorded. When set to "Time", a new trackpoint is stored after "Track.Time Delta" time has passed since the last point was recorded. Shen set to "Distance Delta", a new point is stored when the user has moved Track.Distance from the last point. "Deviation" is the optimal setting: call the most recent three points A, B, and C. Point B is dropped if the distance from A to B and then to C is approximately equal to the distance directly from A to C.
Format: integer (seconds)
Default: 15
Format: integer (with units)
Default: 100 m
Format: integer
Default: 1000
Format: integer
Default: 1000
Comment: After "Track.Autosave minutes", if there are 25% more points in the current track than this number, then 75% are saved to an archive file, and the remainder are still kept in memory and displayed on the map.
Format: pathname, including & and ~ shortcuts
Default: SavedTrip.gpx, in the '&/trips' (~/.roadmap/trips) directory, but usually chosen by the user.
Comment: The file is in stored in GPX format.
Format: boolean
Default: yes
Comment: Can still be toggled by command.
Format: boolean
Default: no
Comment: Can still be toggled by command.
Format: boolean
Default: yes
Comment: C