Fabio/brouter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

profile developers guide: fix typos and whitespace

Browse source
This commit is contained in:
Thomas Waldmann 2019-09-28 13:54:19 +02:00
parent 4be0e456b2
commit ff8562e303
1 changed files with 79 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
misc/readmes/profile_developers_guide.txt
View file

@ -22,7 +22,7 @@ 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 expression the primary value, as A profile must use the primary value in expressions, as
aliases trigger a parse error. E.g. if there is a line aliases trigger a parse error. E.g. if there is a line
in lookups.dat file: in lookups.dat file:
@ -33,9 +33,10 @@ 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
map of germany - these are just informational and map of Germany - these are just informational and
are not processed by BRouter. are not processed by BRouter.
Context-Separation Context-Separation
------------------ ------------------
@ -48,12 +49,12 @@ mark the beginning of each section.
An exception from context separation is the node-context, An exception from context separation is the node-context,
where variables from the way-context of the originating where variables from the way-context of the originating
way can be accessed using the "way:" prefix. For the way can be accessed using the "way:" prefix. For the
variable nodeaccessgranted there's an additonal variable nodeaccessgranted there's an additional
legacy-hack to access it as a loohup value without prefix: legacy-hack to access it as a lookup value without prefix:
if nodeaccessgranted=yes then ... if nodeaccessgranted=yes then ...
while in the genreal case the prefixed expressions are variables: while in the general case the prefixed expressions are variables:
if greater way:costfactor 5 then ... if greater way:costfactor 5 then ...
@ -65,6 +66,7 @@ The variables from the "global" section in the profile
scripts are read-only visible in the "way" and scripts are read-only visible in the "way" and
"node" sections of the scripts. "node" sections of the scripts.
Predefined variables in the profile scripts Predefined variables in the profile scripts
------------------------------------------- -------------------------------------------
@ -128,24 +130,25 @@ the routing engine:
- initialcost - initialcost
The operators of the profile scripts The operators of the profile scripts
------------------------------------ ------------------------------------
The profile scripts use polnic notation (=operator first) The profile scripts use polish notation (operator first).
The "assign" operator is special: it can be used The "assign" operator is special: it can be used
only on the top level of the expression hirarchy only on the top level of the expression hierarchy
and has 2 operands: and has 2 operands:
assign <variable-name> <expression> assign <variable-name> <expression>
It just assigns the expression value to this It just assigns the expression value to this
variable (which can be a predined variable or variable (which can be a predefined variable or
any other variable, which in this case is defined any other variable, which in this case is defined
implicitly). The expression can be a complex expression implicitly). The expression can be a complex expression
using other operators. using other operators.
All other operators can be used recursively to an unlimted All other operators can be used recursively to an unlimited
complexity, which means that each operand can be a composed complexity, which means that each operand can be a composed
expression starting with an operator and so on. expression starting with an operator and so on.
@ -158,12 +161,12 @@ All expressions have one of the following basic forms:
- <3-op-operator> <operand> <operand> <operand> - <3-op-operator> <operand> <operand> <operand>
- A numeric value is just a number, floating point, with "." as - A numeric value is just a number, floating point, with "." as
decimal separtor. Boolean values are treated as numbers as well, decimal separator. Boolean values are treated as numbers as well,
with "0" = false and every nonzero value = true. with "0" = false and every nonzero value = true.
- A lookup match has the form <tag-name>=<value>, e.g. highway=primary - A lookup match has the form <tag-name>=<value>, e.g. highway=primary
Only the primary values can be used in lookup-matches, not aliases. Only the primary values can be used in lookup-matches, not aliases.
The <empty> value is refered to as an empty string, e.g. access= The <empty> value is referred to as an empty string, e.g. access=
- 1 Operand operators are: - 1 Operand operators are:
@ -189,13 +192,13 @@ All expressions have one of the following basic forms:
So the switch expression has a numeric value which is the So the switch expression has a numeric value which is the
true-expression if the boolean expression is true, the true-expression if the boolean expression is true, the
false-expression otherwise false-expression otherwise.
Syntactic Sugar 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:
- "if then else" : "if" can be used instead of the "switch" operator, if the - "if then else" : "if" can be used instead of the "switch" operator, if the
@ -204,7 +207,7 @@ are possible:
if <boolean-expression> then <true-expression> else <false-expression> if <boolean-expression> then <true-expression> else <false-expression>
- Parentheses: each expression can be surrounded by parentheses: ( <expression> ) - Parentheses: each expression can be surrounded by parentheses: ( <expression> )
Please note that the profile syntax, due to the polnic notation, does not Please note that the profile syntax, due to the polish notation, does not
need parentheses, they are always optional. However, if there are parentheses, need parentheses, they are always optional. However, if there are parentheses,
the parser checks if they really match the expression boundaries. the parser checks if they really match the expression boundaries.
@ -217,8 +220,8 @@ are possible:
- boolean constants: "true" and "false" can be used instead of 1 and 0 - boolean constants: "true" and "false" can be used instead of 1 and 0
Please note the the tokenizer always expects blank space to separate Please note that the tokenizer always expects blank space to separate
symbols and expressions so it is not allowed to places parentheses or symbols and expressions so it is not allowed to place parentheses or
the "=" symbol without separating blank space! the "=" symbol without separating blank space!
@ -229,14 +232,15 @@ 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".
Initial cost is used typically for ferry, where you want to apply Initial cost is used typically for a ferry, where you want to apply
a penalty independent of the lenght of the ferry line a penalty independent of the length of the ferry line.
Another useful case may be an initial cost for bicycle mounting/dismounting, 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.
The priority classifier The priority classifier
----------------------- -----------------------
@ -244,21 +248,22 @@ Priorityclassifier is a BRouter numerical parameter
calculated for ways and used for generation of pictogram/voice navigation instructions. calculated for ways and used for generation of pictogram/voice navigation instructions.
Higher values means the more significant (noticeable) way, Higher values means the more significant (noticeable) way,
AFA it can be predicted from OSM data. as far as it can be predicted from OSM data.
To avoid navigation instruction flood, it was decided To avoid a navigation instruction flood, it was decided
the instructions are provided only if: that the instructions are provided only if:
1/ You are supposed to turn at a crossroad/junction 1/ You are supposed to turn at a crossroad/junction
and some other ways have the same or higher Priorityclassifier value. and some other ways having the same or higher Priorityclassifier value.
OR OR
2/ You are supposed to go straight ahead 2/ You are supposed to go straight ahead
and some other ways have the higher Priorityclassifier value. and some other ways having the higher Priorityclassifier value.
The elevation buffer ( From Poutnik's glossary ) The elevation buffer ( From Poutnik's glossary )
------------------- ------------------------------------------------
with related 3 internal BRouter variables:
With related 3 internal BRouter variables:
- elevationpenaltybuffer - elevationpenaltybuffer
- elevationmaxbuffer - elevationmaxbuffer
- elevationbufferreduce - elevationbufferreduce
@ -300,10 +305,10 @@ elevationbufferreduce - default 0(slope%)- is rate of conversion of the buffer c
The elevation to Elevationcost conversion ratio is given by Up/downhillcost. The elevation to Elevationcost conversion ratio is given by Up/downhillcost.
Example: Example:
Let examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5, Let's examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5,
elevationbufferreduce=0.5, cutoffs=1.5, Up/downhillcosts=60 elevationbufferreduce=0.5, cutoffs=1.5, Up/downhillcosts=60.
All slopes within 0 .. 1.5% are swallowed by the cutoff All slopes within 0 .. 1.5% are swallowed by the cutoff.
For slope 1.75%, there will remain 0.25%. For slope 1.75%, there will remain 0.25%.
That saturates the elevationbufferreduce 0.5% by 50%. That gives Way cost That saturates the elevationbufferreduce 0.5% by 50%. That gives Way cost
@ -323,7 +328,6 @@ Example:
giving elevationcost 10*60=600 m/km. giving elevationcost 10*60=600 m/km.
Technical constraints Technical constraints
--------------------- ---------------------
@ -336,8 +340,8 @@ Technical constraints
search area and thus to long processing times. search area and thus to long processing times.
- Forbidden ways or nodes must be treated as very high cost, because - Forbidden ways or nodes must be treated as very high cost, because
there is no "forbidden" value. Technically, values >= 10000. for a there is no "forbidden" value. Technically, values >= 10000 for a
(way-)costfactor, and >=1000000. for a nodes "initalcost" are treated (way-)costfactor, and >= 1000000 for a nodes "initalcost" are treated
as infinity, so please use these as the "forbidden" values. as infinity, so please use these as the "forbidden" values.
- Ways with costfactor >= 10000 are considered as if they did not exist at all. - Ways with costfactor >= 10000 are considered as if they did not exist at all.
@ -347,18 +351,19 @@ Technical constraints
but the navigation hint generator takes them into account. but the navigation hint generator takes them into account.
Developing and debugging scripts Developing and debugging scripts
-------------------------------- --------------------------------
For developing scripts, the "brouter-web" web-application is your For developing scripts, the "brouter-web" web-application is your
friend. You can use that either online at http://brouter/brouter-web friend. You can use that either online at https://brouter.de/brouter-web
or set up a local installation. or set up a local installation.
BRouter-Web has a window at the lower left corner with a "Profile" BRouter-Web has a window at the lower left corner with a "Profile"
and a "Data" tab. Here, you can upload profile scripts and see and a "Data" tab. Here, you can upload profile scripts and see
the individual cost calculations per way-section in the "Data"-tab. the individual cost calculations per way-section in the "Data"-tab.
Activate eventually for the profile debugging "assign processUnusedTags = true"
to see on the Data tab all present OSM tags, not just those used in the tested profile. For profile debugging activate "assign processUnusedTags = true"
to see all present OSM tags on the Data tab, not just those used in the tested profile.
Lookup-Table evolution and the the "major" and "minor" versions Lookup-Table evolution and the the "major" and "minor" versions
@ -370,17 +375,17 @@ and a minor version number. These numbers are also encoded into
the routing data files, taken from the lookups.dat that is used the routing data files, taken from the lookups.dat that is used
to pre-process the routing data files. to pre-process the routing data files.
A major version change is considered to always break compatibiliy A major version change is considered to always break compatibility
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 both directions, using the following rules: compatible in both directions, using the following rules:
- if the data contains a key that is not contained in the lookup - if the data contains a key that is not contained in the lookup
tables, it is ignorned tables, it is ignored
- if the data contains a value that is not contained in the lookup - if the data contains a value that is not contained in the lookup
tables (but it's key is known) that value is treated as "unknown" tables (but its key is known) that value is treated as "unknown"
- if a profile uses a key that is not present in the data, - if a profile uses a key that is not present in the data,
it sees empty (=unset) values for that key it sees empty (=unset) values for that key
@ -392,12 +397,14 @@ 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
tags located between the way-tags and the relation pseudo-tags), tags located between the way-tags and the relation pseudo-tags),
and that values are only appended at the end of the value lists. and that values are only appended at the end of the value lists.
This is because the routing data files adress tags and values This is because the routing data files address tags and values
by their sequence numbers, so changing sequences would produce by their sequence numbers, so changing sequences would produce
garbage data. garbage data.
Other resources Other resources
--------------- ---------------
See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary
as a complementary source about various profile internals. as a complementary source about various profile internals.