RoadMap is a program for Linux that displays street maps. The maps are provided by the US Census Bureau, and thus only cover the US. 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, QT/X11 or QT/QPE graphic environments. The QT environment --especially its QT/QPE version--is still experimental, the Gtk 1.2 environment is the most stable and the GTK 2.0 one has the most features.
RoadMap is at an early stage of development. At this time there are not much features implemented yet. RoadMap can merely display the map around a specified street address, identify the current street or follow a GPS device. 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. In the mean time a basic trip support is provided (waypoints and destination).
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.
The complete set of maps is available at the following URL:
http://community.zaurus.com/projects/zroadmap
The RoadMap application accepts the following command line options:
The options marked as "sticky" remain in effect the next time RoadMap is run. The use of the option actually changes the RoadMap preferences.
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 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.
Clicking on the map screen displays the name of the closest street (with the selected street block's range of address), road or freeway (if any). This display is shown for a limited amount of time (see preference "Highlight.Duration").
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 conditions for RoadMap to "lock" on a new current street: the GPS location must have gone far enough from the previous street, if any (see preference Accuracy.Street); The GPS location must be close to the street (same preference as before); the same street must be "confirmed" by multiple readings (The main reason for these conditions is to avoid locking on streets at the intersections--see Accuracy.Confirm)
RoadMap can also display 3 messages at the following corners of the map: bottom left, bottom right and top right (the top left corner is already used to show the orientation of the map). These messages can be defined by the user using RoadMap's specific format strings (see section "Configuring the RoadMap text and voice messages").
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.
On the Zaurus the buttons are mapped as follow:
| arrow buttons | scroll the map |
| middle button - left arrow | zoom in |
| middle button - right arrow | zoom out |
| '+' | zoom in. |
| '-' | zoom out. |
| 'r' | reset the zoom level. |
| 'd' | show the destination point. |
| 'l' | show the location last searched. |
| 'g' | show (and track) the current GPS position. |
| 'm' | toggle the map download mode on and off. |
| 'e' | delete maps (i.e. open the map delete dialog). |
| 'h' | hit the road (a.k.a. start a trip). |
| 'p' | pause (a.k.a. stop the current trip). |
| 'u' | U-turn (a.k.a. restart the current trip in reverse). |
| 'q' | quit roadmap. |
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 Find / Map Download menu entry. On startup the download mode is always deactivated. RoadMap shows a red "download" icone on 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 Find / 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 Find / 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.
RoadMap manages four 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), a destination point, and an arbitrary number of user-defined waypoints.
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. Thus the definition of a destination or waypoint is a two step procedure: (1) select a location, and (2) set the selected point as a waypoint or the destination point (in the Trip menu).
The location point can be entered in one of three ways:
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, suffix and type, if provided, must be among the abbreviations listed by the US Census Bureau (N for north, E for east, Blvd for boulevard, etc..). 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 Angeles
The 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 "View / Show intersection.." menu entry activates a dialog that requires 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.
A trip is made of one destination point and many user-defined waypoints. The purpose of a RoadMap trip is to describe a real-life trip and to provide the user information about the trip progress.
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. each trip support an infinite number of waypoints.
The last trip created or loaded will be reloaded the next time RoadMap starts.
A trip must have been loaded before it can be edited. There are three trip edition actions available in the "Trips" menu: set the destination point, add a waypoint or remove a waypoint. The destination point is defined using a street address by selecting the "Set Destination.." entry. A waypoint is added by highlighting a location on the map and then selecting the "Add as Waypoint" entry. Waypoints can be deleted by selecting the "Delete Waypoints.." entry, then selecting a specific waypoint and hitting the "Delete" button.
A trip that has been created or loaded can then be activated. Activating a trip defines the departure point (the current GPS location) and enable the "trip display" mode, i.e. some trip information displayed on top of the map. These trip displays include an arrow beside the GPS location symbol to indicate the direction of the next waypoint (if any) or else of the destination, as well as user configurable messages, such as distance information, at the corners of the map. (see CONFIGURATION for more information about these user configurable messages).
When a trip is active, RoadMap tracks the GPS position in realtime and updates its map accordingly. The GPS position can be shown in two modes: either North up, or GPS direction up. In the second case, the map is rotated according to the direction information received from the GPS. This dynamic rotation is in addition to the map manual rotation.
A trip can be stopped at any time and then resumed. Resuming a trip does not modify the departure point. The trip can also be resumed in reverse mode: in that case the departure point and the destination point switch roles. Note that this does not modify the trip, only the way RoadMap uses the trip information. The reverse mode makes it possible to use the same RoadMap trip on the way back.
When starting a trip, the map will rotate to match the orientation of the vehicule. This display mode is the most convenient as it matches the driver's or passenger's view. It is however possible to switch the display in the "North Up" mode by selecting the "Trips / Resume Trip (North Up)" menu entry.
The reserve trip always works in the same mode as previously selected the last time the trip was started or resumed: for example, if the "North Up" mode was selected when the trip was resumed, then the reverse trip will still use this "North Up" mode.
It 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.
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).
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.
The RoadMap configuration is stored in text files located in the following directories:
/opt/QtPalmtop/share/roadmap
/mnt/cf/QtPalmtop/share/roadmap
/mnt/card/QtPalmtop/share/roadmap
~/.roadmap (equivalent to "&" in RoadMap)
~/.roadmap/trips (equivalent to "&/trips" in RoadMap)
~/.roadmap/maps (equivalent to "&/maps" in RoadMap)
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 in the "shared" directories.
The directory ~/.roadmap/trips is used as the default location for the trip files. Note that trip files can be stored anywhere, not only in ~/.roadmap/trips.
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.
The user configuration directories are created when needed, if they do not exist.
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:
schema The definition of the geographic entities.
preferences User's preferences.
session The latest context used (locations)
sprites The definition of the graphic symbols
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 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: Route bearing (not yet implemented). D: Distance to the destination time (set only when a trip is active). S: Speed (set only when a trip is active). T: Current time, format HH:MM (set only when a trip is active). W: Distance to the next waypoint (set only when a trip is active). #: the street number range to the selected or current street block. N: the name of the selected or current street. C: the name of the city for the selected or current street. F: the full name (number, name, city) of the selected or current street.
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.
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").