profile_developers_guide update

This commit is contained in:
Arndt Brenschede 2019-09-21 11:15:58 +02:00
parent 7a38a0d041
commit 76e4ef8cab

View file

@ -1,12 +1,12 @@
Profile developers guide - Technical reference Profile developers guide - Technical reference
for BRouter cost-function scripts for BRouter profile scripts
============================================== ==============================================
The tag-value lookup table The tag-value lookup table
-------------------------- --------------------------
Within the routing data files (rd5), tag information Within the routing data files (rd5), tag information
is encoded in a binary bitfield for the way tags and is encoded in a binary bitstream for the way tags and
the node tags each. the node tags each.
To encode and decode to/from this bitfield, a lookup To encode and decode to/from this bitfield, a lookup
@ -22,12 +22,14 @@ Each value can have optional "aliases", these alias
values are encoded into the same binary value as the values are encoded into the same binary value as the
associated primary value. associated primary value.
A profile must use expresion tag=the_first_tagvalue_alias, A profile must use expression the primary value, as
as other alliases trigger an error. aliases trigger a parse error. E.g. if there is a line
E.g. if there is a line in lookups.dat file in lookups.dat file:
"bicycle;0001245560 yes allowed"
a profile must use "bicycle=yes", bicycle;0001245560 yes allowed
as "bicycle=allowed gives an error".
then a profile must use "bicycle=yes", as "bicycle=allowed"
gives an error.
The numbers in the lookup table are statistical The numbers in the lookup table are statistical
information on the frequency of the values in the information on the frequency of the values in the
@ -43,10 +45,17 @@ as well as in the profile scripts for each context.
The special tags: "---context:way" and "---context:node" The special tags: "---context:way" and "---context:node"
mark the beginning of each section. mark the beginning of each section.
The only exception from context separation is a single An exception from context separation is the node-context,
bit information "nodeaccessgranted" which is automatically where variables from the way-context of the originating
carried from the way context to the terminating node way can be accessed using the "way:" prefix. For the
of the way section. variable nodeaccessgranted there's an additonal
legacy-hack to access it as a loohup value without prefix:
if nodeaccessgranted=yes then ...
while in the genreal case the prefixed expressions are variables:
if greater way:costfactor 5 then ...
In the profile scripts there is a third context "global" In the profile scripts there is a third context "global"
which contains global configuration which is shared for which contains global configuration which is shared for
@ -183,8 +192,8 @@ All expressions have one of the following basic forms:
false-expression otherwise false-expression otherwise
Syntactic Alternatives Syntactic Sugar
---------------------- ---------------
To improve the readablity of the profile-scripts, some syntactic variations To improve the readablity of the profile-scripts, some syntactic variations
are possible: are possible:
@ -220,7 +229,10 @@ To trigger the addition of the "initialcost", another variable is used:
"initialclassifier" - any change in the value of that variable leads "initialclassifier" - any change in the value of that variable leads
to adding the value of "initialcost". to adding the value of "initialcost".
A useful case may be an initial cost for bicycle mounting/dismounting, Initial cost is used typically for ferry, where you want to apply
a penalty independent of the lenght of the ferry line
Another useful case may be an initial cost for bicycle mounting/dismounting,
having set an initialclassifier for ways without bicycle access, with high initialcost. having set an initialclassifier for ways without bicycle access, with high initialcost.
For backward compatibility, if "initialclassifier" = 0, it is replaced For backward compatibility, if "initialclassifier" = 0, it is replaced
by the costfactor. by the costfactor.
@ -362,24 +374,19 @@ A major version change is considered to always break compatibiliy
between the routing datafiles and the lookup table. between the routing datafiles and the lookup table.
A minor version change keeps the routing data files and the lookup-table A minor version change keeps the routing data files and the lookup-table
compatible in the following way: compatible in both directions, using the following rules:
If the minor version from the routing data file is equal OR LARGER - if the data contains a key that is not contained in the lookup
than the minor version in the lookup table, everything is o.k. tables, it is ignorned
This is the case, if you get updated data files, but don't update
the lookup-table of your local installation.
If the lookup-tables's minor version is larger than that in the the - if the data contains a value that is not contained in the lookup
data files, you will get an error message. tables (but it's key is known) that value is treated as "unknown"
Note that for an update of the Android app, your local lookup-table is NOT - if a profile uses a key that is not present in the data,
replaced by the new version. The new lookup table is contained inside it sees empty (=unset) values for that key
the APK, but is not automatically copied to your sd-card if there
is already a local installation. This is to prevent invalidating - if a profile uses a value that is not present in the data,
your routing data files due to software updates. However, in order lookup matches for that value are always false.
to make use of the new tags and values in a new software version, you
have to delete (or rename) your "profiles2" directory, so the new
content from the APK file is copied to the sd-card at next start.
For a minor version change it is required that tags are only For a minor version change it is required that tags are only
appended at the end of the table (or replace one of the dummy appended at the end of the table (or replace one of the dummy
@ -393,6 +400,4 @@ Other resources
--------------- ---------------
See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary
as a complementary unofficial source as a complementary source about various profile internals.
about various profile internals.