doc/html/configuration.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>

<!--
 Routino documentation - configuration

 Part of the Routino routing software.

 This file Copyright 2008-2013 Andrew M. Bishop

 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU Affero General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Affero General Public License for more details.

 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see http://www.gnu.org/licenses/.
-->

<HEAD>
<TITLE>Routino : Configuration</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<LINK href="style.css" type="text/css" rel="stylesheet">
</HEAD>

<BODY>

<!-- Header Start -->

<div class="header" align="center">

<h1>Routino : Configuration</h1>

<hr>
</div>

<!-- Header End -->

<!-- Content Start -->

<div class="content">

<h2><a name="H_1_1"></a>XML Configuration Files</h2>

New in version 1.4 of Routino is 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:
<ul>
  <li>Tagging transformation rules for the <em>planetsplitter</em> program.
  <li>Routing profiles for the <em>router</em> program.
  <li>Output translations for the <em>router</em> program.
</ul>

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.

<h3><a name="H_1_1_1" title="Tagging rules"></a>Tag Transformation Rules</h3>

The default name of the tagging transformation rules XML configuration file
is <em>tagging.xml</em> in the same directory as the generated database files.
Other filenames can be specified on the command line using
the <tt>--tagging</tt> 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.

<p>

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.

<pre class="boxed">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;routino-tagging&gt;

  &lt;way&gt;

    &lt;if k="highway" v="motorway_link"&gt;
      &lt;set v="motorway"/&gt;
    &lt;/if&gt;

    &lt;if k="highway" v="motorway"&gt;
      &lt;output k="highway"/&gt;

      &lt;output k="motorbike"  v="yes"/&gt;
      &lt;output k="motorcar"   v="yes"/&gt;
      &lt;output k="goods"      v="yes"/&gt;
      &lt;output k="hgv"        v="yes"/&gt;
      &lt;output k="psv"        v="yes"/&gt;

      &lt;output k="paved"      v="yes"/&gt;
      &lt;output k="multilane"  v="yes"/&gt;
      &lt;output k="oneway"     v="yes"/&gt;

      &lt;unset k="highway"/&gt;
    &lt;/if&gt;
...
  &lt;way&gt;

&lt;/routino-tagging&gt;
</pre>

The rules all have the same format; an <em>if</em> or <em>ifnot</em> element at
the top level for matching the input and some other elements inside to be used
if there was a match.

<p>

Within the <em>if</em> and <em>ifnot</em> rules any of the rules can be used.
These are <em>if</em>, <em>ifnot</em>, <em>set</em>, <em>unset</em>,
<em>output</em> or <em>logerror</em> elements.

<p>

The rules for matching the <em>if</em> or <em>ifnot</em> elements are the
following:

<ul>
  <li>An <em>if</em> rule that has both <em>k</em> and <em>v</em> specified is
    only matched if a tag exists in the input that matches both.
  <li>An <em>if</em> rule that has only the <em>k</em> attribute is matched if a
    tag with that key exists.
  <li>An <em>if</em> rule that has only the <em>v</em> attribute is matched for
    each tag with that value (i.e. the contents may be used more than once).
  <li>An <em>if</em> rule that has neither attribute specified always matches.
  <li>An <em>ifnot</em> rule that has both <em>k</em> and <em>v</em> specified
    is only matched if no tag exists in the input that matches both.
  <li>An <em>ifnot</em> rule that has only the <em>k</em> attribute is matched
    only if no tag with that key exists.
  <li>An <em>ifnot</em> rule that has only the <em>v</em> attribute is only
    matched if no tag with that value exists.
  <li>An <em>ifnot</em> rule that has neither attribute specified never matches.
</ul>

<p>

For <em>set</em>, <em>unset</em>, <em>output</em> or <em>logerror</em> elements
inside of an <em>if</em> rule an unspecified value for the <em>k</em>
or <em>v</em> attribute is replaced by the values from the tag that matched the
outer <em>if</em> rule.  This makes it simple to delete tags that match a
particular rule without having to specify the parameters more than once.  For
elements inside of an <em>ifnot</em> element an unspecified value for
the <em>k</em> or <em>v</em> attribute is replaced by the values from the
outer <em>ifnot</em> rule.  This means that either the outer <em>ifnot</em>
element or the inner element must specify both <em>k</em> and <em>v</em>
attributes between them.  For nested <em>if</em> or <em>ifnot</em> elements the
outer <em>k</em> and <em>v</em> attributes are not inherited by the inner
elements.

<p>

The <em>set</em> and <em>unset</em> elements either create or delete a tag from
the input data that was read from the file.  If the <em>set</em> element is used
and the tag already exists then it is modified.  The <em>output</em> element
adds a tag to the set that will be used by Routino to determine the data
properties.

<p>

The <em>logerror</em> element will cause an error message to be added to the
error log file that reports that the key and attribute combination are not
recognised.  If the <em>k</em> attribute is specified but not the <em>v</em>
attribute then the tag value that matches the specified key is looked up and
used.  An additional <em>message</em> attribute can be specified to be printed
at the end of the logged error.

<p>
The default logged error message is:
<pre class="boxed">
Node XXX has an unrecognised tag 'key' = 'value' (in tagging rules); ignoring it.
</pre>

<p>
The specified <em>message</em> attribute will replace the final part of the
logged error.


<h3><a name="H_1_1_2" title="Profiles"></a>Routing Profiles</h3>

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

<p>

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 <tt>--profile</tt> option selects the named profile from the configuration
file.

<p>

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

<pre class="boxed">
&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
&lt;routino-profiles&gt;

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


<h3><a name="H_1_1_3" title="Translations"></a>Output Translations</h3>

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

<p>

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 <tt>--language</tt> option to the router.  If no language is specified the
first one in the file is used.

<p>

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

<pre class="boxed">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;routino-translations&gt;

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

</div>

<!-- Content End -->

<!-- Footer Start -->

<div class="footer" align="center">
<hr>

<address>
&copy; Andrew M. Bishop = &lt;amb "at" gedanken.demon.co.uk&gt;
</address>

</div>

<!-- Footer End -->

</BODY>

</HTML>
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2	<HTML>
3
4	<!--
5	Routino documentation - configuration
6
7	Part of the Routino routing software.
8
9	This file Copyright 2008-2013 Andrew M. Bishop
10
11	This program is free software: you can redistribute it and/or modify
12	it under the terms of the GNU Affero General Public License as published by
13	the Free Software Foundation, either version 3 of the License, or
14	(at your option) any later version.
15
16	This program is distributed in the hope that it will be useful,
17	but WITHOUT ANY WARRANTY; without even the implied warranty of
18	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19	GNU Affero General Public License for more details.
20
21	You should have received a copy of the GNU Affero General Public License
22	along with this program. If not, see http://www.gnu.org/licenses/.
23	-->
24
25	<HEAD>
26	<TITLE>Routino : Configuration</TITLE>
27	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
28	<LINK href="style.css" type="text/css" rel="stylesheet">
29	</HEAD>
30
31	<BODY>
32
33	<!-- Header Start -->
34
35	<div class="header" align="center">
36
37	<h1>Routino : Configuration</h1>
38
39	<hr>
40	</div>
41
42	<!-- Header End -->
43
44	<!-- Content Start -->
45
46	<div class="content">
47
48	<h2><a name="H_1_1"></a>XML Configuration Files</h2>
49
50	New in version 1.4 of Routino is the use of configuration files to allow more
51	information to be provided to the programs at run-time. The configuration files
52	that are used are:
53	<ul>
54	<li>Tagging transformation rules for the <em>planetsplitter</em> program.
55	<li>Routing profiles for the <em>router</em> program.
56	<li>Output translations for the <em>router</em> program.
57	</ul>
58
59	In keeping with the nature of the input and output files the configuration files
60	are also XML files. Each of the files uses a custom defined XML schema and an
61	XSD file is provided for each of them.
62
63	<h3><a name="H_1_1_1" title="Tagging rules"></a>Tag Transformation Rules</h3>
64
65	The default name of the tagging transformation rules XML configuration file
66	is <em>tagging.xml</em> in the same directory as the generated database files.
67	Other filenames can be specified on the command line using
68	the <tt>--tagging</tt> option. When processing the input it is possible to have
69	a different set of tagging rules for each file; for example different rules for
70	different countries.
71
72	<p>
73
74	The tagging rules allow modifying the highway tags in the source file so that
75	the routing can be performed on a simpler set of tags. This removes the special
76	case tagging rules from the source code into the configuration file where they
77	can be easily modified. Part of the provided tagging.xml file showing the rules
78	for motorway_link and motorway highway types.
79
80	<pre class="boxed">
81	<?xml version="1.0" encoding="utf-8"?>
82	<routino-tagging>
83
84	<way>
85
86	<if k="highway" v="motorway_link">
87	<set v="motorway"/>
88	</if>
89
90	<if k="highway" v="motorway">
91	<output k="highway"/>
92
93	<output k="motorbike" v="yes"/>
94	<output k="motorcar" v="yes"/>
95	<output k="goods" v="yes"/>
96	<output k="hgv" v="yes"/>
97	<output k="psv" v="yes"/>
98
99	<output k="paved" v="yes"/>
100	<output k="multilane" v="yes"/>
101	<output k="oneway" v="yes"/>
102
103	<unset k="highway"/>
104	</if>
105	...
106	<way>
107
108	</routino-tagging>
109	</pre>
110
111	The rules all have the same format; an <em>if</em> or <em>ifnot</em> element at
112	the top level for matching the input and some other elements inside to be used
113	if there was a match.
114
115	<p>
116
117	Within the <em>if</em> and <em>ifnot</em> rules any of the rules can be used.
118	These are <em>if</em>, <em>ifnot</em>, <em>set</em>, <em>unset</em>,
119	<em>output</em> or <em>logerror</em> elements.
120
121	<p>
122
123	The rules for matching the <em>if</em> or <em>ifnot</em> elements are the
124	following:
125
126	<ul>
127	<li>An <em>if</em> rule that has both <em>k</em> and <em>v</em> specified is
128	only matched if a tag exists in the input that matches both.
129	<li>An <em>if</em> rule that has only the <em>k</em> attribute is matched if a
130	tag with that key exists.
131	<li>An <em>if</em> rule that has only the <em>v</em> attribute is matched for
132	each tag with that value (i.e. the contents may be used more than once).
133	<li>An <em>if</em> rule that has neither attribute specified always matches.
134	<li>An <em>ifnot</em> rule that has both <em>k</em> and <em>v</em> specified
135	is only matched if no tag exists in the input that matches both.
136	<li>An <em>ifnot</em> rule that has only the <em>k</em> attribute is matched
137	only if no tag with that key exists.
138	<li>An <em>ifnot</em> rule that has only the <em>v</em> attribute is only
139	matched if no tag with that value exists.
140	<li>An <em>ifnot</em> rule that has neither attribute specified never matches.
141	</ul>
142
143	<p>
144
145	For <em>set</em>, <em>unset</em>, <em>output</em> or <em>logerror</em> elements
146	inside of an <em>if</em> rule an unspecified value for the <em>k</em>
147	or <em>v</em> attribute is replaced by the values from the tag that matched the
148	outer <em>if</em> rule. This makes it simple to delete tags that match a
149	particular rule without having to specify the parameters more than once. For
150	elements inside of an <em>ifnot</em> element an unspecified value for
151	the <em>k</em> or <em>v</em> attribute is replaced by the values from the
152	outer <em>ifnot</em> rule. This means that either the outer <em>ifnot</em>
153	element or the inner element must specify both <em>k</em> and <em>v</em>
154	attributes between them. For nested <em>if</em> or <em>ifnot</em> elements the
155	outer <em>k</em> and <em>v</em> attributes are not inherited by the inner
156	elements.
157
158	<p>
159
160	The <em>set</em> and <em>unset</em> elements either create or delete a tag from
161	the input data that was read from the file. If the <em>set</em> element is used
162	and the tag already exists then it is modified. The <em>output</em> element
163	adds a tag to the set that will be used by Routino to determine the data
164	properties.
165
166	<p>
167
168	The <em>logerror</em> element will cause an error message to be added to the
169	error log file that reports that the key and attribute combination are not
170	recognised. If the <em>k</em> attribute is specified but not the <em>v</em>
171	attribute then the tag value that matches the specified key is looked up and
172	used. An additional <em>message</em> attribute can be specified to be printed
173	at the end of the logged error.
174
175	<p>
176	The default logged error message is:
177	<pre class="boxed">
178	Node XXX has an unrecognised tag 'key' = 'value' (in tagging rules); ignoring it.
179	</pre>
180
181	<p>
182	The specified <em>message</em> attribute will replace the final part of the
183	logged error.
184
185
186	<h3><a name="H_1_1_2" title="Profiles"></a>Routing Profiles</h3>
187
188	The default name of the routing profiles XML configuration file
189	is <em>profiles.xml</em> in the same directory as the database files. Other
190	filenames can be specified on the command line using the <tt>--tagging</tt>
191	option.
192
193	<p>
194
195	The purpose of this configuration file is to allow easy modification of the
196	routing parameters so that they do not all need to be specified on the command
197	line. In versions of Routino before version 1.4 the default routing parameters
198	(preferred highways, preferred speeds etc) were contained in the source code,
199	now they are in a configuration file. When calculating a route
200	the <tt>--profile</tt> option selects the named profile from the configuration
201	file.
202
203	<p>
204
205	Part of the provided profiles.xml file showing the parameters for transport on
206	foot is shown below:
207
208	<pre class="boxed">
209	<?xml version="1.0" encoding="UTF-8" ?>
210	<routino-profiles>
211
212	<profile name="foot" transport="foot">
213	<speeds>
214	...
215	<speed highway="cycleway" kph="4" />
216	<speed highway="path" kph="4" />
217	<speed highway="steps" kph="4" />
218	</speeds>
219	<preferences>
220	...
221	<preference highway="cycleway" percent="95" />
222	<preference highway="path" percent="100" />
223	<preference highway="steps" percent="80" />
224	</preferences>
225	<properties>
226	<property type="paved" percent="50" />
227	<property type="multilane" percent="25" />
228	<property type="bridge" percent="50" />
229	<property type="tunnel" percent="50" />
230	...
231	</properties>
232	<restrictions>
233	<oneway obey="0" />
234	<weight limit="0.0" />
235	<height limit="0.0" />
236	<width limit="0.0" />
237	<length limit="0.0" />
238	</restrictions>
239	</profile>
240	<profile name="horse" transport="horse">
241	...
242	</profile>
243	...
244	</routino-profiles>
245	</pre>
246
247
248	<h3><a name="H_1_1_3" title="Translations"></a>Output Translations</h3>
249
250	The default name of the output translations XML configuration file
251	is <em>translations.xml</em> in the same directory as the database files. Other
252	filenames can be specified on the command line using the <tt>--translations</tt>
253	option.
254
255	<p>
256
257	The generated HTML and GPX output files (described in the next section) are
258	created using the fragments of text that are defined in this file. Additional
259	languages can be added to the file and are selected using
260	the <tt>--language</tt> option to the router. If no language is specified the
261	first one in the file is used.
262
263	<p>
264
265	Part of the provided translations.xml file showing some of the English language
266	(en) translations is shown below:
267
268	<pre class="boxed">
269	<?xml version="1.0" encoding="utf-8"?>
270	<routino-translations>
271
272	<language lang="en">
273	...
274	<turn direction="-4" string="Very sharp left" />
275	<turn direction="-3" string="Sharp left" />
276	<turn direction="-2" string="Left" />
277	...
278	<heading direction="-4" string="South" />
279	<heading direction="-3" string="South-West" />
280	<heading direction="-2" string="West" />
281	...
282	<route type="shortest" string="Shortest" />
283	<route type="quickest" string="Quickest" />
284	<output-html>
285	...
286	</output-html>
287	<output-gpx>
288	...
289	</output-gpx>
290	</language>
291	</routino-translations>
292	</pre>
293
294	</div>
295
296	<!-- Content End -->
297
298	<!-- Footer Start -->
299
300	<div class="footer" align="center">
301	<hr>
302
303	<address>
304	© Andrew M. Bishop = <amb "at" gedanken.demon.co.uk>
305	</address>
306
307	</div>
308
309	<!-- Footer End -->
310
311	</BODY>
312
313	</HTML>