readme

A car navigation system for Unix and PocketPC.

                               ---------
    RoadMap - a street navigation system using the US Census maps and GPS
                               ---------
                Pascal Martin ([e-mail])
                               ---------
                             November 2003



INTRODUCTION

   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 vehicule 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 the Digital Charts
   of the Words (DCW), a set of world-wide maps produced by the US Department of
   Defense. 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.

   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 GTK 1.2 environment is being phased out (due to its old age). The
   most stable environment is the GTK 2.0 one (this is the one used for
   developping RoadMap). The GPE support is and optional extension of the
   GTK 2.0 environment and is still very experimental (i.e. untested).

   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. A basic trip support is
   provided (waypoints and destination). RoadMap detects what is the next
   waypoint, provides a direction arrow and show the distance to this
   waypoint (and/or to the destination).

   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.


ABOUT THIS DOCUMENTATION

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


INSTALLATION

* DEPENDENCIES

   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 communicates with the GPS receiver through gpsd, a GPS
   communication daemon for UNIX. Therefore gpsd is required for RoadMap
   to take advantage of a GPS receiver. However gpsd is not required when
   building RoadMap, and RoadMap can run without gpsd as a static map viewer
   or address finder. In addition, gpsd may run on a remote computer
   accessible through a TCP/IP network: in this case the remote computer
   will be tacked by RoadMap, not the local one..

   RoadMap uses either GTK, GTK2 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 uses the ImageMagick package to generate the PNG files for some
   icons of its toolbar. ImageMagick is only required for building RoadMap,
   it is not necessary when running RoadMap.

   RoadMap uses flite (festival lite) to generate voice messages. See
   section "VOICE INTERFACE" for more information.

   RoadMap uses aptconvert to format the documentation (see previous section).

   Support for a "Point of Interest" feature is in the way, where the plan
   is to store the points in a SQLite database. RoadMap is not at this time
   dependent on SQLite, even while using SQLite will be an option in the
   future.

* DOWNLOADING

   RoadMap can be downloaded from the RoadMap web site:

         * {{http://roadmap.digitalomaha.net/download.html}}

   RoadMap is distributed with the map of San Francisco as an example of
   map. The complete set of maps is available on the following web site:
   
         * {{http://roadmap.digitalomaha.net/maps.html}}

   The 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 huges and the bandwidth is expensive.
   
   If you do need the complete set, please drop an email to the author.
   Roadmap comes either as a set of sources, or as a set of binary files,
   depending on which distribution you downloaded. RoadMap comes in three
   distribution formats:

      * a binary tarball with executables for Linux/i686.

      * a set of .ipk packages for Linux/armv4l (Linux/Familiar).

      * a source tarball.

   The arm and i686 executables use the same map files. Please note that
   the map files are dependent on the computer's endianess: map files
   built on a Mac (PowerPC CPU) would not be compatible with an Intel or
   (small endian) ARM computer.

   Note: the main GTK RoadMap executables (roadmap and roadgps) are
   built as "gtkroadmap" and "gtkroadgps", while the QT equivalent are
   built as "qtroadmap" and qtroadgps" to avoid a clash. These executables
   are installed under their "standard" names using symbolic links, so
   that only one version can be installed at a time (the reason is to
   share one roadmap.menu file..).

   A version of RoadMap for the Sharp Zaurus is available at
   {{http://community.zaurus.com/projects/zroadmap/}}


* INSTALLING FROM THE BINARY TARBALL

   The binary distribution contains three sets of files: the directory
   src/gtk contains the executable files for Debian GNU/Linux (kernel 2.4)
   and the directory src contains the example map datafiles.

   RoadMap can be installed by running the "make install" command from
   one of the graphical toolkit directories (gtk2, gtk or qt). This
   installs the associated set of RoadMap executables and all configuration
   files (but not the maps!).


* INSTALLING FROM THE FAMILIAR PACKAGE

   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.digitalomaha.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
   
           * /mnt/hda/share/roadmap or

           * /mnt/card/share/roadmap.

   (This can be changed using 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.


* INSTALLING FROM THE SOURCE TARBALL

   It is also possible to rebuild RoadMap and the map files from scratch
   from the source distribution:

   [[1]] Install the development libraries for GTK+ 1.2, GTK+ 2.0 or Qt.

   [[2]] Install the RoadMap's tarball:

----
      tar xzvf <tarball>
----

   [[3]] Compile the map building tools:

----
      cd roadmap-<version>/src
      make build
----

   [[4]] Compile roadmap for the GTK, GTK2 or the QT toolkit:

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

      If you want to build all three versions of RoadMap (GTK, GTK2
      and QT), just type:

----
      make       -- This replaces steps 3 and 4.
----

      <<Note for QT users>>: the RoadMap QT module is built with QT3 by
      default, but requires the QT2 compatibility headers.

      <<Note for developpers>>: using the option MODE=DEBUG causes RoadMap
      to be compiled in debug mode.

   [[5]] download some maps from the US Census bureau:

         {{http://www.census.gov/geo/www/tiger/tiger2002/tgr2002.html}}

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

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

   <<CAUTION>>: the command above downloads the tiger 2002 files. to download
   the tiger 2000 files, use the <<format>> option:

----
      rdmgenmaps <tiger-path> format=2000 [<state-symbol> ..]
----

   [[6]] download the list of counties from the US Census bureau:

         {{http://www.census.gov/geo/tigerline/app_a02.txt}}

      (A version of app_a02.txt is also provided in directory src.)

   [[7]] Build the maps:

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

   This command processes all the Census Bureau files found in <tiger-path>
   and creates the map files for RoadMap in the <map-path> directory. There
   is one map file generated for each county.

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

   This other command processes only the listed counties. The county
   shall be identified by its FIPS (e.g. 06075 for San francisco, CA).

   <<CAUTION>>: the description above assumes the tiger 2002 format. use
   the option <<format=2000>> to convert tiger 2000 files. For example:

----
      rdmgenmaps <tiger-path> format=2000 [maps=<map-path>]
----


   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 & counties catalog. The main purpose of rdmgemaps 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 tool uses the popt library for
   parsing the command line arguments: 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 & counties into a giant US map. It looks for:

      [[a]] the file AllSt.txt and