readme

A car navigation system for Unix and PocketPC.

      [[b]] the various existing RoadmMap maps.

   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).

   The buildus tool also uses popt for parsing the command line arguments:
   the option --help gives more information about the available options.

   [[8]] run make to install roadmap:

------
      cd gtk        -- or gtk2 or qt, depending on your preferences.
      make install
      cd ..
------

   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.


* A NOTE ABOUT THE ROADMAP ICONS

   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):

------
      ~/pixmaps
      /usr/local/share/pixmaps
      /usr/share/pixmaps
------


ROADMAP APPLICATIONS

   RoadMap includes the following applications:

   [roadmap]         This is the main application. It displays the map
                     and can keep track of the current GPS position.
                     Depending on which toolkit you use, this will be
                     roadmap/src/gtk/gtkroadmap, roadmap/gtk2/gtkroadmap
                     or roadmap/src/qt/qtroadmap (zroadmap on the Zaurus).

   [roadgps]         A very handy GPS console, inspired by the Garmin
                     satellite status page, with a NMEA log capability.
                     Thanks to gpsd, roadgps and roadmap can be active
                     at the same time. Depending on which toolkit you use,
                     this will be named roadmap/src/gtk/gtkroadgps,
                     roadmap/gtk2/gtkroadgps or roadmap/src/qt/qtroadgps
                     (zroadgps on the Zaurus).

   [buildmap]        A program that takes the US Census Bureau files
                     as input and produces the map files used by roadmap.
                     This application is to be run once on a desktop or
                     beefed-up laptop to prepare the map files and is not
                     needed when using roadmap.

   [buildus]         A program that takes a set of roadmap map files and
                     produce a directory file that helps roadmap choose
                     the map(s) to display according to the location or
                     city. This application is to be run once on a desktop
                     or laptop and is not needed when using roadmap.

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

   [rdmgenmaps]      A script to simplify the generation of the maps.


USING ROADMAP

* 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 specified RoadMap
   preferences item.

   The RoadMap application accepts the following command line options:
   
   [--location=<LONGITUDE,LATITUDE>] Set the location point (see menu entry
       View/Show Location..). This option is sticky (preference item
       Locations.Location=<LONGITUDE,LATITUDE>).

   [--metric] Use the metric system for all units. This option is sticky
      (preference item General.Unit = "metric").

   [--imperial] Use the imperial system for all units. This option is sticky
      (preference item General.Unit = "imperial").

   [--no-area] Do not show the polygons (parks, hospitals, malls, airports,
      etc..).

   [-geometry=<WIDTHxHEIGHT>] See option --geometry=<WIDTHxHEIGHT>.

   [--geometry=<WIDTHxHEIGHT>] Sets the geometry for the RoadMap main window.

   [--geometry:<WINDOW>=<WIDTHxHEIGHT>] Set the geometry of a specific RoadMap
      window, according to its title. --geometry:Main=<WIDTHxHEIGHT> is
      equivalent to --geometry=<WIDTHxHEIGHT>. If the window's title includes
      any space, dashes can be used in place of the spaces (the goal here is
      to be shell friendly). This option is sticky (preference item
      Geometry.<WINDOW> = <WIDTHxHEIGHT>).

   [--no-toolbar] Do not show the toolbar. This option is sticky (preference
      item General.Toolbar = "no").

   [--no-icon] Do not show any icon, i.e. keep as much space as possible
      for the map. This option is sticky (preference item General.Icons = "no").

   [--square] Show squares boundaries as grey boxes. This option is for
       debug purpose only.

   [--gps=<URL>] Use a specific GPS source. This option is not sticky: it
       overrides the preferences setting this time, but the preferences
       setting is not modified. The main use of this option is to rerun GPS
       logs created using roadgps.

   [--debug] Print all informational and debug traces.

   [--verbose] Print all informational traces.

   [--help] Show a description of all command line options.


* GETTING HELP

   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 ROADMAP DISPLAY

   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.

   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 command "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 reselected (for example by using
   the menu command Find / GPS position or the "G" toolbar button).

   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 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 vehicule 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 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").


* {VOICE} INTERFACE

   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
     make
----


* {KEY} BINDINGS

   Most 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.
*-----------------*-----------------------------------------------------*
   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.
*-----------------*-----------------------------------------------------*
   U              |     Center the map on the GPS position (north up).
*-----------------*-----------------------------------------------------*
   W              |     Set the selected street block as waypoint.
*-----------------*-----------------------------------------------------*

   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
   buttons bindings In a way that makes it impossible for RoadMap to use
   them (the button are mapped to the GPE applications). In this environment
   it is recommended to enable the toolbar to replace the buttons. the joypad
   is still available.


* ON-THE-FLY MAP DOWNLOAD

   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.