readme

A car navigation system for Unix and PocketPC.

    [Selected Street.Text] The format used for the selected street's display.

         <<Format:>> RoadMap format string

         <<Default:>> %F

    [Console.Background] The color used for the background of the trip display.

         <<Format:>> color

         <<Default:>> yellow

    [Console.Foreground] The color used for the foreground of the trip display.

         <<Format:>> color

         <<Default:>> black

    [Current Street.Background] The color for the background of the current
         street's name.

         <<Format:>> color

         <<Default:>> DarkSeaGreen4

    [Current Street.Foreground] The color for the foreground of the current
         street's name.

         <<Format:>> color

         <<Default:>> white

    [Current Street.Text] The text used to display the current street's name.

         <<Format:>> color

         <<Default:>> black <(I would recommend using white--see above)>

         <<Default:>> %N, %C|%N

    [Voice.Current Street] The command used to announce the current street's
         name.

         <<Format:>> RoadMap format string

         <<Default:>> flite -t 'On %N'

    [Voice.Selected Street] The command used to announce the selected street's
         name.

         <<Format:>> RoadMap format string

         <<Default:>> flite -t '%N'

    [Voice.Next Intersection] The command used to announce the name of the
           next intersection.

         <<Format:>> RoadMap format string

         <<Default:>> flite -t 'Next intersection: %N'

    [Voice.Approach] Reserved for future use (approaching waypoint).

    [Accuracy.Confidence] The minimum rating for a street to be selected

         <<Format:>> integer, range 0 .. 1024

         <<Default:>> 25

         <<Comment:>> RoadMap uses fuzzy logic to identify what street
                  the vehicule is on. This value if a minimum fuzzy result
                  for RoadMap to select any street. This helps not selecting
                  whatever street is near by when off-road. This also speeds
                  up the identification process by filtering out unlikely
                  matches.

    [Accuracy.GPS Position] The GPS's estimated position error (worst case)

         <<Format:>> integer

         <<Default:>> 300

         <<Comment:>> the unit depends on the selected unit system (feet or
                  meter). The default shown being tuned for feet. This default
                  accuracy can be adjusted to the actual GPS estimate if a
                  Garmin GPS receiver is used.

    [Accuracy.GPS Speed] GPS's speed accuracy.

         <<Format:>> integer

         <<Default:>> 4

         <<Comment:>> the unit depends on the selected unit system (ft/s or
                  m/s).

    [Accuracy.Mouse] The size of the street selection search area.

         <<Format:>> number of pixels

         <<Default:>> 20

         <<Comment:>> on a mouse click, RoadMap defines the street search area
                  as the rectangle delimited by the two points
                  (x-accuracy, y-accuracy) and (x+accuracy, y+accuracy).
                  Limiting the search to this area speeds up the process,
                  compared to searching in the whole screen area.

    [Accuracy.Street] The street selection accuracy.

         <<Format:>> integer (using the current unit system).

         <<Default:>> 150

         <<Comment:>> This is the maximum distance to a street for the
                  navigation logic. If a street is at a distance greater than
                  this value, then RoadMap will never consider this street
                  when searching which street the vehicule is on.

    [History.Depth] The maximum number of items in the <<find>> history.

         <<Format:>> integer

         <<Default:>> 100

    [Approach.Background] Reserved for future use (approaching waypoint).

    [Approach.Foreground] Reserved for future use (approaching waypoint).

    [Approach.Text] Reserved for future use (approaching waypoint).

    [Download.Source] The format used to generate the URL of the source.

         <<Format:>> printf() format, which must include the sequence "%05d".

         <<Default:>> /usr/local/share/roadmap/usc%05d.rdm

         <<Comment:>> this item is either a full path name (starting with a '/')
                  or an URL (such as "file://[...]" or "http://[...]").

    [Download.Destination] The path of the directory where to store the
         downloaded map files.

         <<Format:>> string

         <<Default:>> &/maps

         <<Comment:>> this item must be either a full path name or start with
                  '~' (user home directory) or '&' (RoadMap user's directory).


* SESSION ITEMS

    [Location.Position] The latest selected position.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

         <<Comment:>> the name of this item is kind of silly, to be changed.

         <<Command line option:>> --location=<LONGITUDE>,<LATITUDE>

    [GPS.Position] The latest received GPS position.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

    [GPS.Direction] The latest received GPS direction.

         <<Format:>> degrees

         <<Default:>> 0

    [Selection.Position] The position of the latest selection.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

    [Address.Position] The position of the latest address used.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

    [Trip.Name] The name of the last used trip file.

         <<Format:>> string

         <<Default:>> default
         
    [Delta.X] The horizontal map shift compare to the reference position.

         <<Format:>> number of pixels

         <<Default:>> 0

    [Delta.Y] The vertical map shift compare to the reference position.

         <<Format:>> number of pixels

         <<Default:>> 0

    [Delta.Rotate] The rotational shift compare to the reference direction.

         <<Format:>> degrees.

         <<Default:>> 0

    [General.Zoom] The current zoom level.

         <<Format:>> number

         <<Default:>> see the default zoom preference item.

    [Focus.Rotate] Indicate if the current map focus is set to rotate.

         <<Format:>> boolean (1 or 0)

         <<Default:>> 0

    [Focus.Name] Name of the reference position where the focus should be set.

         <<Format:>> either "GPS", "Location" or "Address"

         <<Default:>> "Location"

    [Hold.Direction] An artefact of saving the context. Ignored.

    [Hold.Position] An artefact of saving the context. Ignored.

 (*) NOTE: the default position values match 1 Market St, San Francisco, CA.


* SCHEMA ITEMS

     The schema file uses the same format as the preference file. It defines
     the properties of the various categories of objects that make a map.
     the list of categories matches the list of Tiger file's categories
     (see Tiger's CFCC field) that have been filtered by buildmap.

     The two differences with the preferences files are that there is no
     pre-defined category in RoadMap: categories are defined by the maps
     (FIXME: this is still to be done--as a temporary hack, the categories
     have been hardcoded somewhere) and there is no default value.

     For each category, RoadMap use the following items:

     [<category>.Class:] the class of object this category belongs to.

         <<Format:>> Road, Feature or Area.

         <<Comment:>> Road and Feature categories are searched in the "line"
                  table of the map files and drawn as lines. The Road
                  category is searched when a street name is looked for.
                  The Area objects are drawn separatly, as polygons.

     [<category>.Color:] the color used when drawing the objects.

         <<Format:>> color

     [<category>.Declutter:] the zoom level from which the objects are hidden

         <<Format:>> integer

         <<Comment:>> the definition of this item is rather obscure. To be fixed.

     [<category>.Thickness:] the thickness used to draw lines.

         <<Format:>> number of pixels


   RoadMap uses the following categories:

         * Freeways

         * Ramps

         * Highways

         * Streets

         * Trails

         * Rivers

         * Shore

         * Hospitals

         * Malls

         * Airports

         * Stations

         * Lakes

         * Parks

         * Sea


* SPRITES FILE

     This file defines the drawing commands used to draw the various symbols
     used by RoadMap:

         GPS (indicates the current GPS position and direction),
         Position (indicates the currently selected location),
         Destination,
         Highlight (marks the endpoints of a selected street block) and
         Compass (used to indicates the direction of the North pole).

     The sprites file is made of a sequence of single-line commands:

*------------------------------+---------------------------------------------+
|        S <name>              | Starts a sprite.
*------------------------------+---------------------------------------------+
|        F <color> <thickness> | Define the pen to be used by the subsequent
|                              | drawing commands.
*------------------------------+---------------------------------------------+
|        L <x>,<y> ..          | Draw a line.
*------------------------------+---------------------------------------------+
|        P <x>,<y> ..          | Draw a filled polygon.
*------------------------------+---------------------------------------------+
|        C <x>,<y> <radius>    | Draw a circle.
*------------------------------+---------------------------------------------+
|        D <x>,<y> <radius>    | Draw a disk (f