Profile developers guide - Technical reference
for BRouter cost-function scripts
==============================================

The tag-value lookup table
--------------------------

Within the routing data files (rd5), tag information
is encoded in a binary bitfield of 64 bit length for
the way tags and the node tags each.

To encode and decode to/from this bitfield, a lookup
table is used that contains all the tags and values
that are considered for encoding.

For each tag there are 2 special values:

- <empty> if the tag is not set or the value is empty 
- "unknown" if the value is not contained in the table

An exception are "boolean tags" with exactly one value
in the lookup table - these are encoded into a single
bit and do not have the "unknown" value - in this case
unknown values are treated as empty.

Each value can have optional "aliases", these alias
values are encoded into the same binary value as the
associated primary value.

For compact encoding, the number of values per
tag in the lookup table should be a power of 2,
including the default values (<empty>, "unknown"),
so typically, a tag has 1, 2, 6, 14 or 30 values.

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
are not processed by BRouter.

Context-Separation
------------------

Way-tags and Node-Tags are treated independently,
so there are different sections in the lookup table
as well as in the profile scripts for each context.
The special tags: "---context:way" and "---context:node"
mark the beginning of each section.

In the profile scripts there is a third context "global"
which contains global configuration which is shared for
all contexts and is accessible by the routing engine.

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
-------------------------------------------

Some variable names are pre-defined and accessed by
the routing engine:

- for the global section these are:

  - 4 elevation configuration parameters:

    - downhillcost
    - downhillcutoff
    - uphillcost
    - uphillcutoff

  - 3 boolean mode-hint flags

    - validForBikes
    - validForFoot
    - validForCars

  - and 2 variables to change the heuristic
    coefficients for the 2 routing passes
    ( <0 disables a routing pass )

   - pass1coefficient
   - pass2coefficient

- for the way section these are

  - turncost
  - initialcost
  - costfactor

- for the node section this is just

  - initialcost

The operators of the profile scripts
------------------------------------

The "assign" operator is special: it can be used
only on the top level of the expression hirarchy
and has 2 operands:

  assign <variable-name> <expression>

It just assigns the expression value to this
variable (which can be a predined 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
complexity, which means that each operand can be a composed
expression starting with an operator and so on.

All expressions have one of the following basic forms:

  - <numeric>
  - <lookup-match>
  - <1-op-operator> <operand>
  - <2-op-operator> <operand> <operand>
  - <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,
  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=

- 1 Operand operators are:

  not <boolean expression>

- 2 Operand operators are:

  or       <boolean expression 1> <boolean expression 2>
  and      <boolean expression 1> <boolean expression 2>
  multiply <numeric expression 1> <numeric expression 2>
  add      <numeric expression 1> <numeric expression 2>
  max      <numeric expression 1> <numeric expression 2>

- 3 Operand operators are:

  switch <boolean-expression> <true-expression> <false-expression>

  So the switch expression has a numeric value which is the
  true-expression if the boolean expression is true, the
  false-expression otherwise


Technical constraints
---------------------

- The costfactor is required to be >= 1, otherwise the cost-cutoff
  logic of the routing algorithm does not work and you get wrong results.

- The profile should be able to find a route with an average costfactor
  not very much larger than one, because otherwise the routing algorithm
  will not find a reasonable cost-cutoff, leading to a very large
  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. Please use 100000 for a (way-)costfactor,
  and 1000000 for a nodes "initalcost", as these are proven values with
  no overflow issues.


Developing and debugging scripts
--------------------------------

For developing scripts, the "Upload profile" funcionality and the
"Export CSV" button of the online version are your friends.
The "Export CSV" gives a (tab-separated) list of all way segments
with all tag values and with the calulated cost (in "cost per km").

These CSV-Data can be imported in Excel using "paste content" function.