manual.html

A car navigation system for Unix and PocketPC.

<li>Compile the map building tools:<pre>      cd roadmap-&lt;version&gt;/src
      make build</pre></li>
<li>Compile roadmap for the GTK, GTK2 or the QT
toolkit:<pre>      make DESKTOP=GTK    -- if using the GTK 1.2 toolkit

      make DESKTOP=GTK2   -- if using the GTK 2.0 toolkit

      make DESKTOP=GPE    -- if using GPE with the GTK 2.0 toolkit

      make DESKTOP=QT     -- if using the QT toolkit

      make DESKTOP=QPE    -- if using the QT/QPE toolkit</pre><p>If you want
to build all three versions of RoadMap (GTK, GTK2 and QT), just
type:</p><pre>      make       -- This replaces steps 3 and 4.</pre><p><b>Note
for QT users</b>: the RoadMap QT module is built with QT3 by default, but
requires the QT2 compatibility headers.</p><p><b>Note for developpers</b>:
using the option MODE=DEBUG causes RoadMap to be compiled in debug
mode.</p></li>
<li>download some maps from the US Census
bureau:<p><a href="http://www.census.gov/geo/www/tiger/tiger2002/tgr2002.html">http://www.census.gov/geo/www/tiger/tiger2002/tgr2002.html</a></p><p>This
download can be automated by using the shell script
roadmap/src/rdmdownload:</p><pre>      rdmgenmaps &lt;tiger-path&gt; [&lt;state-symbol&gt; ..]</pre><p><b>CAUTION</b>:
the command above downloads the tiger 2002 files. to download the tiger 2000
files, use the <b>format</b>
option:</p><pre>      rdmgenmaps &lt;tiger-path&gt; format=2000 [&lt;state-symbol&gt; ..]</pre></li>
<li>download the list of counties from the US Census
bureau:<p><a href="http://www.census.gov/geo/tigerline/app_a02.txt">http://www.census.gov/geo/tigerline/app_a02.txt</a></p><p>(A
version of app_a02.txt is also provided in directory src.)</p></li>
<li>Build the
maps:<pre>      rdmgenmaps &lt;tiger-path&gt; [maps=&lt;map-path&gt;]</pre><p>This
command processes all the Census Bureau files found in <i>tiger-path</i> and
creates the map files for RoadMap in the <i>map-path</i> directory. There is
one map file generated for each
county.</p><pre>      rdmgenmaps &lt;tiger-path&gt; [maps=&lt;map-path&gt;] &lt;county&gt; ..</pre><p>This
other command processes only the listed counties. The county shall be
identified by its FIPS (e.g. 06075 for San francisco,
CA).</p><p><b>CAUTION</b>: the description above assumes the tiger 2002
format. use the option <b>format=2000</b> to convert tiger 2000 files. For
example:</p><pre>      rdmgenmaps &lt;tiger-path&gt; format=2000 [maps=&lt;map-path&gt;]</pre><p>The
rdmgemaps 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, rdmgemaps invokes the buildus tool to generate the US states
&amp; counties catalog. The main purpose of rdmgemaps is really to keep the
TIGER files in compressed form, considering their huge size..</p><p>The
<b>buildmap</b> tool takes a county &quot;FIPS&quot; and a TIGER file as input
and produces one RoadMap .rdm map file. The tool uses the popt library for
parsing the command line arguments: the option --help gives more information
about the available options.</p><p>Here is an
example:</p><pre>      buildmap 01001 /tmp/TGR01001.RT1</pre><p>The
<b>buildus</b> tool creates a catalog of maps that is used by RoadMap to
combine all states &amp; counties into a giant US map. It looks
for:</p><ol style="list-style-type: lower-alpha">
<li>the file AllSt.txt and</li>
<li>the various existing RoadmMap maps.</li>
</ol><p>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).</p><p>The buildus tool also uses popt for parsing the command line
arguments: the option --help gives more information about the available
options.</p></li>
<li>run make to install
roadmap:<pre>      cd gtk        -- or gtk2 or qt, depending on your preferences.
      make install
      cd ..</pre><p>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.</p></li>
</ol><h2><a id="id.s3.6" name="id.s3.6">3.6 </a>A NOTE ABOUT THE ROADMAP
ICONS<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>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.</p><p>A make script
builds all the necessary files using the ImageMagick package. The icon files
are built (or installed) when building (or installing) RoadMap.</p><p>The PNG
icon files must be installed in one of the following directories (the order
below reflects the search order):</p><pre>      ~/pixmaps
      /usr/local/share/pixmaps
      /usr/share/pixmaps</pre><h1><a id="id.s4" name="id.s4">4 </a>ROADMAP
APPLICATIONS<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h1>
<p>RoadMap includes the following applications:</p><dl compact>
<dt><b>roadmap</b></dt>
<dd>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).</dd>
<dt><b>roadgps</b></dt>
<dd>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).</dd>
<dt><b>buildmap</b></dt>
<dd>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.</dd>
<dt><b>buildus</b></dt>
<dd>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.</dd>
<dt><b>dumpmap</b></dt>
<dd>Display the data tables from a map file. This application is used for
debug purposes only and is not needed when using roadmap.</dd>
<dt><b>rdmgenmaps</b></dt>
<dd>A script to simplify the generation of the maps.</dd>
</dl><h1><a id="id.s5" name="id.s5">5 </a>USING
ROADMAP<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h1>
<h2><a id="id.s5.1" name="id.s5.1">5.1 </a>COMMAND LINE
<a id="options" name="options">OPTIONS</a><a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>The options marked as &quot;sticky&quot; remain in effect the next time
RoadMap is run. The use of the option actually changes the specified RoadMap
preferences item.</p><p>The RoadMap application accepts the following command
line options:</p><dl compact>
<dt><b>--location=<i>LONGITUDE,LATITUDE</i></b></dt>
<dd>Set the location point (see menu entry View/Show Location..). This option
is sticky (preference item Locations.Location=<i>LONGITUDE,LATITUDE</i>).</dd>
<dt><b>--metric</b></dt>
<dd>Use the metric system for all units. This option is sticky (preference
item General.Unit = &quot;metric&quot;).</dd>
<dt><b>--imperial</b></dt>
<dd>Use the imperial system for all units. This option is sticky (preference
item General.Unit = &quot;imperial&quot;).</dd>
<dt><b>--no-area</b></dt>
<dd>Do not show the polygons (parks, hospitals, malls, airports, etc..).</dd>
<dt><b>-geometry=<i>WIDTHxHEIGHT</i></b></dt>
<dd>See option --geometry=<i>WIDTHxHEIGHT</i>.</dd>
<dt><b>--geometry=<i>WIDTHxHEIGHT</i></b></dt>
<dd>Sets the geometry for the RoadMap main window.</dd>
<dt><b>--geometry:<i>WINDOW</i>=<i>WIDTHxHEIGHT</i></b></dt>
<dd>Set the geometry of a specific RoadMap window, according to its title.
--geometry:Main=<i>WIDTHxHEIGHT</i> is equivalent to
--geometry=<i>WIDTHxHEIGHT</i>. 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.<i>WINDOW</i> =
<i>WIDTHxHEIGHT</i>).</dd>
<dt><b>--no-toolbar</b></dt>
<dd>Do not show the toolbar. This option is sticky (preference item
General.Toolbar = &quot;no&quot;).</dd>
<dt><b>--no-icon</b></dt>
<dd>Do not show any icon, i.e. keep as much space as possible for the map.
This option is sticky (preference item General.Icons = &quot;no&quot;).</dd>
<dt><b>--square</b></dt>
<dd>Show squares boundaries as grey boxes. This option is for debug purpose
only.</dd>
<dt><b>--gps=<i>URL</i></b></dt>
<dd>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.</dd>
<dt><b>--debug</b></dt>
<dd>Print all informational and debug traces.</dd>
<dt><b>--verbose</b></dt>
<dd>Print all informational traces.</dd>
<dt><b>--help</b></dt>
<dd>Show a description of all command line options.</dd>
</dl><h2><a id="id.s5.2" name="id.s5.2">5.2 </a>GETTING
HELP<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>The main RoadMap window includes a &quot;Help&quot; 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
&quot;dillo&quot;, but this default can be changed in the user's preferences
(see section PREFERENCE ITEMS).</p><h2><a id="id.s5.3" name="id.s5.3">5.3
</a>THE ROADMAP
DISPLAY<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>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.</p><p>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 &quot;Managing Trips&quot;
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.</p><p>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
&quot;freezes&quot; 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 &quot;G&quot; toolbar button).</p><p>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 &quot;Highlight.Duration&quot;).</p><p>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 &quot;lock&quot; 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 &quot;locked&quot;
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.</p><p>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 &quot;Configuring the RoadMap
text and voice messages&quot;).</p><h2><a id="id.s5.4" name="id.s5.4">5.4
</a><a id="voice" name="voice">VOICE</a>
INTERFACE<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>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 &quot;tell&quot; 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&quot; 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.</p><p>It is possible to mute the
RoadMap's voice, using the File / Mute Voice item from the menu bar. The voice