Improve docs regarding encoded values and for now remove misleading documentation about FlagEncoders, graphhopper#2659

Author: karussell

docs/core/create-new-flagencoder.md

@@ -71,21 +71,36 @@ encoded values are the following (some of their possible values are given in bra
 - surface: (PAVED, DIRT, SAND, GRAVEL, ...)
 - smoothness: (EXCELLENT, GOOD, INTERMEDIATE, ...)
 - toll: (MISSING, NO, HGV, ALL)
+- bike_network, foot_network: (MISSING, INTERNATIONAL, NATIONAL, REGIONAL, LOCAL, OTHER)
+- country: (`MISSING` or the country as a `ISO3166-1:alpha3` code e.g. `DEU`)
+- hazmat: (YES, NO), hazmat_tunnel: (A, B, .., E), hazmat_water: (YES, PERMISSIVE, NO)
+- hgv: (MISSING, YES, DESIGNATED, ...)
+- track_type: (MISSING, GRADE1, GRADE2, ..., GRADE5)
+- urban_density: (RURAL, RESIDENTIAL, CITY)
 
-To learn about all available encoded values you can query the `/info` endpoint.
+
+To learn about all available encoded values you can query the `/info` endpoint
 
 Besides this kind of categories, which can take multiple different string values, there are also some that represent a
-boolean value (they are either true or false for a given edge), like:
+boolean value (they are either true or false for a given road segment), like:
 
 - get_off_bike
 - road_class_link
+- roundabout
+- with postfix `_access` contains the access (as boolean) for a specific vehicle
 
 There are also some that take on a numeric value, like:
 
-- max_speed
-- max_weight
-- max_height
-- max_width
+- average_slope: a decimal for "elevation change" / edge_distance for a road segment; it changes the sign in reverse direction; see also max_slope
+- curvature: "beeline distance" / edge_distance (0..1) e.g. a curvy road is smaller than 1
+- hike_rating, horse_rating, mtb_rating: a number from 0 to 6 for the `sac_scale` in OSM, e.g. 0 means "missing", 1 means "hiking", 2 means "mountain_hiking" and so on
+- lanes: number of lanes
+- max_slope: an unsigned decimal for the maximum slope ("elevation change / distance_i") of an edge with `sum(distance_i)=edge_distance`. Important for longer road segments where ups (or downs) can be much bigger than the average_slope.
+- max_speed: the speed limit from a sign (km/h)
+- max_height (meter), max_width (meter), max_length (meter)
+- max_weight (ton), max_axle_load (in tons)
+- with postfix `_average_speed` contains the average speed (km/h) for a specific vehicle
+- with postfix `_priority` contains the road preference without changing the speed for a specific vehicle (0..1)
 
 In the next section will see how we can use these encoded values to customize GraphHopper's route calculations.
 

docs/core/custom-models.md

@@ -11,7 +11,13 @@ The default cache directory `/tmp/<provider name>` will be used. For large areas
 use a SSD disc, thus you need to specify the cache directory:
 `graph.elevation.cache_dir: /myssd/ele_cache/`
 
-## What to download and where to store it? 
+## Custom Models
+
+The `average_slope` and `max_slope` attributes of a road segment can be used to make your routing
+elevation-aware, i.e. to prefer or avoid, to speed up or slow down your vehicle based on the elevation
+change. See the [custom model](custom-models.md) feature.
+
+## What to download and where to store it?
 
 All should work automatically but you can tune certain settings like the location where the files are 
 downloaded and e.g. if the servers are not reachable, then you set:

docs/core/elevation.md

@@ -1,17 +1,19 @@
 ## Weighting
 
-A weighting allows to create a "weight" for an edge. The weight of an edge reflects the cost of travelling along this edge. 
+Instead of creating a new Weighting implementation is is highly recommended to use the CustomWeighting instead, which is explained in
+the [profiles](profiles.md) and [custom models](custom-models.md) section.
+
+A weighting allows to create a "weight" for an edge. The weight of an edge reflects the cost of travelling along this edge.
 All implementations of [RoutingAlgorithm](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/RoutingAlgorithm.java)
-in GraphHopper calculate the shortest path, which means the path with the [lowest overall cost from A to B](https://en.wikipedia.org/wiki/Shortest_path_problem). 
-The definition of the cost function is up to you, so you can create a cost function (we call this weighting) for the fastest path. 
-GraphHopper will still calculate the path with the lowest cost, but you can define the cost as a mix of distance speed, as shown in the [FastestWeighting](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/weighting/FastestWeighting.java).
+in GraphHopper calculate the shortest path, which means the path with the [lowest overall cost from A to B](https://en.wikipedia.org/wiki/Shortest_path_problem).
+The definition of the cost function is up to you, so you can create a cost function (we call this weighting) for the fastest path.
+GraphHopper will still calculate the path with the lowest cost, but you can define the cost as a mix of distance speed, as shown in the
+[FastestWeighting](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/weighting/FastestWeighting.java).
 
 In order to create a custom weighting you need to do the following:
 
- 1. Implement the Weighting class
- 2. Create a subclass of GraphHopper and override `createWeighting`
- 
-Or use the CustomWeighting feature explained in [profiles](profiles.md).
+ 1. Implement the Weighting class and the WeightingFactory
+ 2. Let the GraphHopper class know about your WeightingFactory via overriding createWeightingFactory
 
 ### Implement your own weighting
 
@@ -23,26 +25,4 @@ a sample can be found in the [AvoidEdgesWeighting](https://github.com/graphhoppe
 If your weights change on a per-request base, like the [BlockAreaWeighting](https://github.com/graphhopper/graphhopper/blob/bbd62fded97be060fc09177f9fae794cea284554/core/src/main/java/com/graphhopper/routing/weighting/BlockAreaWeighting.java),
 you cannot use the 'speed mode', but have to use the 'hybrid mode' or 'flexible mode' (more details [here](https://github.com/graphhopper/graphhopper#technical-overview)).
 If you haven't disabled the 'speed mode' in your config, you have to disable it for the requests by appending `ch.disable=true`
-in the request url.
-
-### Extend GraphHopper
-
-For general information on how to extend GraphHopper have a look [here](low-level-api.md).
- 
-Extending GraphHopper is easy, just need to override the `createWeighting` method of the GraphHopper class. 
-We return a new instance of our custom weighting if the string `my_custom_weighting` is given. Otherwise let the super class handle it:
-
-```java
-class MyGraphHopper extends GraphHopper {
-
-    @Override
-    public Weighting createWeighting(HintsMap hintsMap, FlagEncoder encoder, Graph graph) {
-        String weightingStr = hintsMap.getWeighting().toLowerCase();
-        if ("my_custom_weighting".equals(weightingStr)) {
-            return new MyCustomWeighting(encoder);
-        } else {
-            return super.createWeighting(hintsMap, encoder, graph);
-        }
-    }
-}
-```
+in the request url.

docs/core/weighting.md

@@ -49,14 +49,13 @@ Various topics are explained in more detail separately:
 
  * [Technical overview](./core/technical.md): Technical details about how GraphHopper its calculations are working.
  * [Custom models](./core/custom-models.md): This tutorial explains how to customize an existing vehicle profile to your needs without to know Java.
+ * [Create custom weighting](./core/weighting.md): Documentation regarding Weighting. In almost all situations a custom model should be created instead.
  * [Simple routing](./core/routing.md): Tutorial how to integrate GraphHopper in your Java application (or pick any JVM language)
- * [Create custom weighting](./core/weighting.md): Documentation about how to create a custom weighting class to influence the track calculation.
  * [Import GTFS](../reader-gtfs): Simple steps to get GTFS import and routing done.
  * [LocationIndex](../example/src/main/java/com/graphhopper/example/LocationIndexExample.java): Code about how to get the location index for getting i.e. the nearest edge. 
  * [Hybrid Mode](./core/landmarks.md): Details about speeding up the route calculation via A* and landmarks.
  * [Speed Mode](./core/ch.md): Details about speeding up the route calculations via [Contraction Hierarchies](http://en.wikipedia.org/wiki/Contraction_hierarchies).
  * [Low level API](./core/low-level-api.md): Instructions how to use GraphHopper as a Java library.
- * [Create new FlagEncoder](./core/create-new-flagencoder.md): Documentation to create new routing profiles to influence which ways to favor and how the track-time is calculated.
  * [Custom Areas and Country Rules](./core/custom-areas-and-country-rules.md): Instructions on how to on how to use and create new SpatialRules. SpatialRules are used to enforce country-specific routing rules.
  * [Turn Restrictions](./core/turn-restrictions.md): Details on how to enable and use turn restrictions.
  * [Isochrone generation in Java](./isochrone/java.md): Instruction on how to create isochrones using the low-level Java API.