Merge pull request #195 from ThomasWaldmann/fix-typos
profile developers guide: fix typos and whitespace
This commit is contained in:
abrensch
GitHub
commit
a5838b5572
1 changed files with 79 additions and 72 deletions
|
|
@ -22,7 +22,7 @@ Each value can have optional "aliases", these alias
|
|||
values are encoded into the same binary value as the
|
||||
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
|
||||
in lookups.dat file:
|
||||
|
||||
|
|
@ -33,9 +33,10 @@ gives an error.
|
|||
|
||||
The numbers in the lookup table are statistical
|
||||
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.
|
||||
|
||||
|
||||
Context-Separation
|
||||
------------------
|
||||
|
||||
|
|
@ -48,12 +49,12 @@ mark the beginning of each section.
|
|||
An exception from context separation is the node-context,
|
||||
where variables from the way-context of the originating
|
||||
way can be accessed using the "way:" prefix. For the
|
||||
variable nodeaccessgranted there's an additonal
|
||||
legacy-hack to access it as a loohup value without prefix:
|
||||
variable nodeaccessgranted there's an additional
|
||||
legacy-hack to access it as a lookup value without prefix:
|
||||
|
||||
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 ...
|
||||
|
||||
|
|
@ -65,6 +66,7 @@ The variables from the "global" section in the profile
|
|||
scripts are read-only visible in the "way" and
|
||||
"node" sections of the scripts.
|
||||
|
||||
|
||||
Predefined variables in the profile scripts
|
||||
-------------------------------------------
|
||||
|
||||
|
|
@ -128,24 +130,25 @@ the routing engine:
|
|||
|
||||
- initialcost
|
||||
|
||||
|
||||
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
|
||||
only on the top level of the expression hirarchy
|
||||
only on the top level of the expression hierarchy
|
||||
and has 2 operands:
|
||||
|
||||
assign <variable-name> <expression>
|
||||
|
||||
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
|
||||
implicitly). The expression can be a complex expression
|
||||
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
|
||||
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>
|
||||
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
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:
|
||||
|
||||
|
|
@ -189,13 +192,13 @@ All expressions have one of the following basic forms:
|
|||
|
||||
So the switch expression has a numeric value which is the
|
||||
true-expression if the boolean expression is true, the
|
||||
false-expression otherwise
|
||||
false-expression otherwise.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
- "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>
|
||||
|
||||
- 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,
|
||||
the parser checks if they really match the expression boundaries.
|
||||
|
||||
|
|
@ -212,13 +215,13 @@ are possible:
|
|||
lookup matches where more than one value is accepted for a key:
|
||||
highway=primary|secondary|tertiary
|
||||
|
||||
- additional "=" symbol for "assign"operations:
|
||||
- additional "=" symbol for "assign" operations:
|
||||
assign <variable-name> = <expression>
|
||||
|
||||
- boolean constants: "true" and "false" can be used instead of 1 and 0
|
||||
|
||||
Please note the the tokenizer always expects blank space to separate
|
||||
symbols and expressions so it is not allowed to places parentheses or
|
||||
Please note that the tokenizer always expects blank space to separate
|
||||
symbols and expressions so it is not allowed to place parentheses or
|
||||
the "=" symbol without separating blank space!
|
||||
|
||||
|
||||
|
|
@ -229,36 +232,38 @@ To trigger the addition of the "initialcost", another variable is used:
|
|||
"initialclassifier" - any change in the value of that variable leads
|
||||
to adding the value of "initialcost".
|
||||
|
||||
Initial cost is used typically for ferry, where you want to apply
|
||||
a penalty independent of the lenght of the ferry line
|
||||
Initial cost is used typically for a ferry, where you want to apply
|
||||
a penalty independent of the length 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.
|
||||
For backward compatibility, if "initialclassifier" = 0, it is replaced
|
||||
by the costfactor.
|
||||
|
||||
|
||||
The priority classifier
|
||||
-----------------------
|
||||
|
||||
Priorityclassifier is a BRouter numerical parameter
|
||||
calculated for ways and used for generation of pictogram/voice navigation instructions.
|
||||
|
||||
Higher values means the more significant(noticeable) way,
|
||||
AFA it can be predicted from OSM data.
|
||||
Higher values means the more significant (noticeable) way,
|
||||
as far as it can be predicted from OSM data.
|
||||
|
||||
To avoid navigation instruction flood, it was decided
|
||||
the instructions are provided only if:
|
||||
To avoid a navigation instruction flood, it was decided
|
||||
that the instructions are provided only if:
|
||||
|
||||
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
|
||||
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 )
|
||||
-------------------
|
||||
with related 3 internal BRouter variables:
|
||||
------------------------------------------------
|
||||
|
||||
With related 3 internal BRouter variables:
|
||||
- elevationpenaltybuffer
|
||||
- elevationmaxbuffer
|
||||
- elevationbufferreduce
|
||||
|
|
@ -296,24 +301,24 @@ elevationmaxbuffer - default 10(m) - is the size of the buffer, above which
|
|||
|
||||
elevationbufferreduce - default 0(slope%)- is rate of conversion of the buffer content
|
||||
above elevationpenaltybuffer to ElevationCost. For a way of length L,
|
||||
the amount of converted elevation is L[km] *elevationbufferreduce[%]*10.
|
||||
the amount of converted elevation is L[km] * elevationbufferreduce[%] * 10.
|
||||
The elevation to Elevationcost conversion ratio is given by Up/downhillcost.
|
||||
|
||||
Example:
|
||||
Let examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5,
|
||||
elevationbufferreduce=0.5, cutoffs=1.5, Up/downhillcosts=60
|
||||
Let's examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5,
|
||||
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%.
|
||||
That saturates the elevationbufferreduce 0.5% by 50%. That gives Way cost
|
||||
to be calculated 50% from costfactor and 50% from Up/downhillcostfactor.
|
||||
Additionally, 0.25% gives 2.5 m per 1km, converted to 2.5*60 = 150m of Elevationcost.
|
||||
Additionally, 0.25% gives 2.5m per 1km, converted to 2.5*60 = 150m of Elevationcost.
|
||||
|
||||
For slope 2.0%, there will remain 0.5%.
|
||||
That saturates the elevationbufferreduce 0.5% by 100%. That gives Way cost
|
||||
to be calculated fully from Up/downhillcostfactor. Additionally,
|
||||
0.5% gives 5 m per 1km, converted to 5*60 = 300m of Elevationcost.
|
||||
0.5% gives 5m per 1km, converted to 5*60 = 300m of Elevationcost.
|
||||
Up to slope 2.0% the buffer value stays at 5m = elevationpenaltybuffer.
|
||||
|
||||
For slope 2.5%, there will remain 1.0% after cutoff subtract,
|
||||
|
|
@ -323,7 +328,6 @@ Example:
|
|||
giving elevationcost 10*60=600 m/km.
|
||||
|
||||
|
||||
|
||||
Technical constraints
|
||||
---------------------
|
||||
|
||||
|
|
@ -336,8 +340,8 @@ Technical constraints
|
|||
search area and thus to long processing times.
|
||||
|
||||
- Forbidden ways or nodes must be treated as very high cost, because
|
||||
there is no "forbidden" value. Technically, values >= 10000. for a
|
||||
(way-)costfactor, and >=1000000. for a nodes "initalcost" are treated
|
||||
there is no "forbidden" value. Technically, values >= 10000 for a
|
||||
(way-)costfactor, and >= 1000000 for a nodes "initalcost" are treated
|
||||
as infinity, so please use these as the "forbidden" values.
|
||||
|
||||
- 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.
|
||||
|
||||
|
||||
|
||||
Developing and debugging scripts
|
||||
--------------------------------
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
|
|
@ -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
|
||||
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.
|
||||
|
||||
A minor version change keeps the routing data files and the lookup-table
|
||||
compatible in both directions, using the following rules:
|
||||
|
||||
- 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
|
||||
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,
|
||||
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
|
||||
tags located between the way-tags and the relation pseudo-tags),
|
||||
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
|
||||
garbage data.
|
||||
|
||||
|
||||
Other resources
|
||||
---------------
|
||||
|
||||
See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary
|
||||
as a complementary source about various profile internals.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue