From 76e4ef8cab4c6566c442e83c06fd80c8c71b058b Mon Sep 17 00:00:00 2001 From: Arndt Brenschede Date: Sat, 21 Sep 2019 11:15:58 +0200 Subject: [PATCH] profile_developers_guide update --- misc/readmes/profile_developers_guide.txt | 71 ++++++++++++----------- 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/misc/readmes/profile_developers_guide.txt b/misc/readmes/profile_developers_guide.txt index b94c817..a72b8bf 100644 --- a/misc/readmes/profile_developers_guide.txt +++ b/misc/readmes/profile_developers_guide.txt @@ -1,12 +1,12 @@ Profile developers guide - Technical reference -for BRouter cost-function scripts +for BRouter profile scripts ============================================== The tag-value lookup table -------------------------- 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. 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 associated primary value. -A profile must use expresion tag=the_first_tagvalue_alias, -as other alliases trigger an error. -E.g. if there is a line in lookups.dat file -"bicycle;0001245560 yes allowed" -a profile must use "bicycle=yes", -as "bicycle=allowed gives an error". +A profile must use expression the primary value, as +aliases trigger a parse error. E.g. if there is a line +in lookups.dat file: + +bicycle;0001245560 yes allowed + +then a profile must use "bicycle=yes", as "bicycle=allowed" +gives an error. The numbers in the lookup table are statistical 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" mark the beginning of each section. -The only exception from context separation is a single -bit information "nodeaccessgranted" which is automatically -carried from the way context to the terminating node -of the way 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: + + 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" which contains global configuration which is shared for @@ -183,8 +192,8 @@ All expressions have one of the following basic forms: false-expression otherwise -Syntactic Alternatives ----------------------- +Syntactic Sugar +--------------- To improve the readablity of the profile-scripts, some syntactic variations 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 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. For backward compatibility, if "initialclassifier" = 0, it is replaced 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. 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 -than the minor version in the lookup table, everything is o.k. -This is the case, if you get updated data files, but don't update -the lookup-table of your local installation. +- if the data contains a key that is not contained in the lookup + tables, it is ignorned -If the lookup-tables's minor version is larger than that in the the -data files, you will get an error message. +- 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" -Note that for an update of the Android app, your local lookup-table is NOT -replaced by the new version. The new lookup table is contained inside -the APK, but is not automatically copied to your sd-card if there -is already a local installation. This is to prevent invalidating -your routing data files due to software updates. However, in order -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. +- if a profile uses a key that is not present in the data, + it sees empty (=unset) values for that key + +- if a profile uses a value that is not present in the data, + lookup matches for that value are always false. 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 @@ -393,6 +400,4 @@ Other resources --------------- See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary -as a complementary unofficial source -about various profile internals. - +as a complementary source about various profile internals.