doc/html/configuration.html

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

<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">

<title>Routino : Configuration</title>

<!--
 Routino documentation - configuration

 Part of the Routino routing software.

 This file Copyright 2008-2015, 2020 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/.
-->

<link href="style.css" type="text/css" rel="stylesheet">
</head>

<body>

<!-- Header Start -->

<div class="header">

<h1>Routino : Configuration</h1>

</div>

<!-- Header End -->

<!-- Content Start -->

<div class="content">

<h2 id="H_1_1">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 id="H_1_1_1" title="Tagging rules">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="motorcycle" 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.  If the <em>output</em> element is used and the tag already exists
then it is modified.

<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 id="H_1_1_2" title="Profiles">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 id="H_1_1_3" title="Translations">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">

<address>
&copy; Andrew M. Bishop - <a href="http://www.routino.org/">http://www.routino.org/</a>
</address>

</div>

<!-- Footer End -->

</body>

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