trunk/doc/CONFIGURATION.txt

                           Routino : Configuration
                           =======================


   New in version 1.4 of Routino are the use of configuration files to
   allow more information to be provided to the programs at run-time. The
   configuration files that are used are:
     * Tagging transformation rules for the planetsplitter program.
     * Routing profiles for the router program.
     * Output translations for the router program.

   In keeping with the nature of the input and output files the
   configuration files are also XML files. Each of the files uses a custom
   defined XML schema and an XSD file is provided for each of them.


Tag Transformation Rules
------------------------

   The default name of the tagging transformation rules XML configuration
   file is tagging.xml in the same directory as the generated database
   files. Other filenames can be specified on the command line using the
   --tagging option. When processing the input it is possible to have a
   different set of tagging rules for each file; for example different
   rules for different countries.

   The tagging rules allow modifying the highway tags in the source file
   so that the routing can be performed on a simpler set of tags. This
   removes the special case tagging rules from the source code into the
   configuration file where they can be easily modified. Part of the
   provided tagging.xml file showing the rules for motorway_link and
   motorway highway types.

<?xml version="1.0" encoding="utf-8"?>
<routino-tagging>

  <way>

    <if k="highway" v="motorway_link">
      <set v="motorway"/>
    </if>

    <if k="highway" v="motorway">
      <output k="highway"/>

      <output k="motorbike"  v="yes"/>
      <output k="motorcar"   v="yes"/>
      <output k="goods"      v="yes"/>
      <output k="hgv"        v="yes"/>
      <output k="psv"        v="yes"/>

      <output k="paved"      v="yes"/>
      <output k="multilane"  v="yes"/>
      <output k="oneway"     v="yes"/>
    </if>
...
  <way>

</routino-tagging>

   The rules all have the same format; an if element for matching the
   input and some set or output elements to either change the input tags
   or create an output tag. The k and v attributes have the same meaning
   as the attributes with the same names in the OSM XML file - the tag key
   and tag value.

   An if rule that has both k and v specified is only applied if a tag
   exists in the input that matches both. An if rule that has only the k
   attribute is applied if a tag with that key exists and an if rule that
   has only the v attribute is applied to all tags with that value.

   For the set and output elements the tag that is created in the input or
   output tag set uses the k and v attributes specified. If one or both
   are not specified then the original ones are used.


Routing Profiles
----------------

   The default name of the routing profiles XML configuration file is
   profiles.xml in the same directory as the database files. Other
   filenames can be specified on the command line using the --tagging
   option.

   The purpose of this configuration file is to allow easy modification of
   the routing parameters so that they do not all need to be specified on
   the command line. In versions of Routino before version 1.4 the default
   routing parameters (preferred highways, preferred speeds etc) were
   contained in the source code, now they are in a configuration file.
   When calculating a route the --profile option selects the named profile
   from the configuration file.

   Part of the provided profiles.xml file showing the parameters for
   transport on foot is shown below:

<?xml version="1.0" encoding="UTF-8" ?>
<routino-profiles>

  <profile name="foot" transport="foot">
    <speeds>
...
      <speed highway="cycleway"      kph="4" />
      <speed highway="path"          kph="4" />
      <speed highway="steps"         kph="4" />
    </speeds>
    <preferences>
...
      <preference highway="cycleway"      percent="95" />
      <preference highway="path"          percent="100" />
      <preference highway="steps"         percent="80" />
    </preferences>
    <properties>
      <property type="paved"      percent="50" />
      <property type="multilane"  percent="25" />
      <property type="bridge"     percent="50" />
      <property type="tunnel"     percent="50" />
    </properties>
    <restrictions>
      <oneway obey="0" />
      <weight limit="0.0" />
      <height limit="0.0" />
      <width  limit="0.0" />
      <length limit="0.0" />
    </restrictions>
  </profile>
  <profile name="horse" transport="horse">
...
  </profile>
...
</routino-profiles>


Output Translations
-------------------

   The default name of the output translations XML configuration file is
   translations.xml in the same directory as the database files. Other
   filenames can be specified on the command line using the --translations
   option.

   The generated HTML and GPX output files (described in the next section)
   are created using the fragments of text that are defined in this file.
   Additional languages can be added to the file and are selected using
   the --language option to the router. If no language is specified the
   first one in the file is used.

   Part of the provided translations.xml file showing some of the English
   language (en) translations is shown below:

<?xml version="1.0" encoding="utf-8"?>
<routino-translations>

  <language lang="en">
...
    <turn direction="-4" string="Very sharp left" />
    <turn direction="-3" string="Sharp left" />
    <turn direction="-2" string="Left" />
...
    <heading direction="-4" string="South" />
    <heading direction="-3" string="South-West" />
    <heading direction="-2" string="West" />
...
    <route type="shortest" string="Shortest" />
    <route type="quickest" string="Quickest" />
    <output-html>
...
    </output-html>
    <output-gpx>
...
    </output-gpx>
  </language>
</routino-translations>


--------

Copyright 2010 Andrew M. Bishop.
1	Routino : Configuration
2	=======================
3
4
5	New in version 1.4 of Routino are the use of configuration files to
6	allow more information to be provided to the programs at run-time. The
7	configuration files that are used are:
8	* Tagging transformation rules for the planetsplitter program.
9	* Routing profiles for the router program.
10	* Output translations for the router program.
11
12	In keeping with the nature of the input and output files the
13	configuration files are also XML files. Each of the files uses a custom
14	defined XML schema and an XSD file is provided for each of them.
15
16
17	Tag Transformation Rules
18	------------------------
19
20	The default name of the tagging transformation rules XML configuration
21	file is tagging.xml in the same directory as the generated database
22	files. Other filenames can be specified on the command line using the
23	--tagging option. When processing the input it is possible to have a
24	different set of tagging rules for each file; for example different
25	rules for different countries.
26
27	The tagging rules allow modifying the highway tags in the source file
28	so that the routing can be performed on a simpler set of tags. This
29	removes the special case tagging rules from the source code into the
30	configuration file where they can be easily modified. Part of the
31	provided tagging.xml file showing the rules for motorway_link and
32	motorway highway types.
33
34	<?xml version="1.0" encoding="utf-8"?>
35	<routino-tagging>
36
37	<way>
38
39	<if k="highway" v="motorway_link">
40	<set v="motorway"/>
41	</if>
42
43	<if k="highway" v="motorway">
44	<output k="highway"/>
45
46	<output k="motorbike" v="yes"/>
47	<output k="motorcar" v="yes"/>
48	<output k="goods" v="yes"/>
49	<output k="hgv" v="yes"/>
50	<output k="psv" v="yes"/>
51
52	<output k="paved" v="yes"/>
53	<output k="multilane" v="yes"/>
54	<output k="oneway" v="yes"/>
55	</if>
56	...
57	<way>
58
59	</routino-tagging>
60
61	The rules all have the same format; an if element for matching the
62	input and some set or output elements to either change the input tags
63	or create an output tag. The k and v attributes have the same meaning
64	as the attributes with the same names in the OSM XML file - the tag key
65	and tag value.
66
67	An if rule that has both k and v specified is only applied if a tag
68	exists in the input that matches both. An if rule that has only the k
69	attribute is applied if a tag with that key exists and an if rule that
70	has only the v attribute is applied to all tags with that value.
71
72	For the set and output elements the tag that is created in the input or
73	output tag set uses the k and v attributes specified. If one or both
74	are not specified then the original ones are used.
75
76
77	Routing Profiles
78	----------------
79
80	The default name of the routing profiles XML configuration file is
81	profiles.xml in the same directory as the database files. Other
82	filenames can be specified on the command line using the --tagging
83	option.
84
85	The purpose of this configuration file is to allow easy modification of
86	the routing parameters so that they do not all need to be specified on
87	the command line. In versions of Routino before version 1.4 the default
88	routing parameters (preferred highways, preferred speeds etc) were
89	contained in the source code, now they are in a configuration file.
90	When calculating a route the --profile option selects the named profile
91	from the configuration file.
92
93	Part of the provided profiles.xml file showing the parameters for
94	transport on foot is shown below:
95
96	<?xml version="1.0" encoding="UTF-8" ?>
97	<routino-profiles>
98
99	<profile name="foot" transport="foot">
100	<speeds>
101	...
102	<speed highway="cycleway" kph="4" />
103	<speed highway="path" kph="4" />
104	<speed highway="steps" kph="4" />
105	</speeds>
106	<preferences>
107	...
108	<preference highway="cycleway" percent="95" />
109	<preference highway="path" percent="100" />
110	<preference highway="steps" percent="80" />
111	</preferences>
112	<properties>
113	<property type="paved" percent="50" />
114	<property type="multilane" percent="25" />
115	<property type="bridge" percent="50" />
116	<property type="tunnel" percent="50" />
117	</properties>
118	<restrictions>
119	<oneway obey="0" />
120	<weight limit="0.0" />
121	<height limit="0.0" />
122	<width limit="0.0" />
123	<length limit="0.0" />
124	</restrictions>
125	</profile>
126	<profile name="horse" transport="horse">
127	...
128	</profile>
129	...
130	</routino-profiles>
131
132
133	Output Translations
134	-------------------
135
136	The default name of the output translations XML configuration file is
137	translations.xml in the same directory as the database files. Other
138	filenames can be specified on the command line using the --translations
139	option.
140
141	The generated HTML and GPX output files (described in the next section)
142	are created using the fragments of text that are defined in this file.
143	Additional languages can be added to the file and are selected using
144	the --language option to the router. If no language is specified the
145	first one in the file is used.
146
147	Part of the provided translations.xml file showing some of the English
148	language (en) translations is shown below:
149
150	<?xml version="1.0" encoding="utf-8"?>
151	<routino-translations>
152
153	<language lang="en">
154	...
155	<turn direction="-4" string="Very sharp left" />
156	<turn direction="-3" string="Sharp left" />
157	<turn direction="-2" string="Left" />
158	...
159	<heading direction="-4" string="South" />
160	<heading direction="-3" string="South-West" />
161	<heading direction="-2" string="West" />
162	...
163	<route type="shortest" string="Shortest" />
164	<route type="quickest" string="Quickest" />
165	<output-html>
166	...
167	</output-html>
168	<output-gpx>
169	...
170	</output-gpx>
171	</language>
172	</routino-translations>
173
174
175	--------
176
177	Copyright 2010 Andrew M. Bishop.