Merge pull request #637 from zod/docs

Rework pseudo tags docs

docs/Gemfile

@@ -27,3 +27,5 @@ end
 # Performance-booster for watching directories on Windows
 gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
 
+
+gem "webrick", "~> 1.8"

docs/Gemfile.lock

@@ -249,6 +249,7 @@ GEM
       unf_ext
     unf_ext (0.0.8.2)
     unicode-display_width (1.8.0)
+    webrick (1.8.1)
 
 PLATFORMS
   x86_64-linux
@@ -258,6 +259,7 @@ DEPENDENCIES
   tzinfo (~> 1.2)
   tzinfo-data
   wdm (~> 0.1.1)
+  webrick (~> 1.8)
 
 BUNDLED WITH
-   2.4.13
+   2.4.20

docs/_README.md

@@ -0,0 +1,15 @@
+# BRouter Docs
+
+This documentation can be used to generate a static website using [jekyll](https://jekyllrb.com/).
+
+## Dependencies
+
+jekyll uses ruby and therefore installs dependencies using gem. It is recommended to use bundler to manage those dependencies.
+
+`bundle install` installs all dependencies. To update dependencies use `bundle update`.
+
+## Preview
+
+jekyll provides a built-in webserver which can be used for fast feedback during editing.
+
+`bundle exec jekyll serve`

docs/developers/environmental_considerations_and_pseudo_tags.md

@@ -1,49 +1,67 @@
-Environmental considerations (penalties for traffic, noise, town, no river, no forest) are possible due to the creation of pseudo tags during processing OSM data by spatial SQL queries in https://github.com/abrensch/brouter/blob/master/misc/scripts/mapcreation/brouter.sql. During this processing, roads are extended by a 32 m buffer creating 64 m wide lines. Then it is calculated what percentage of such line is at a specific distance to a noise source or within a forest, for example. The percentage is converted to a factor and the factor is assigned to a class. Ways that pass through different environments and are represented by a single OSM way can be problematic because the class is always based on the average environment along an entire OSM way. For traffic, calculations are on another level of complexity.
+---
+parent: Developers
+---
+
+# Environmental considerations
+
+Environmental considerations (penalties for traffic, noise, town, no river, no forest) are possible due to the creation of pseudo tags during processing OSM data by spatial SQL queries in [brouter.sql](https://github.com/abrensch/brouter/blob/master/misc/scripts/mapcreation/brouter.sql). During this processing, roads are extended by a 32 m buffer creating 64 m wide lines. Then it is calculated what percentage of such line is at a specific distance to a noise source or within a forest, for example. The percentage is converted to a factor and the factor is assigned to a class. Ways that pass through different environments and are represented by a single OSM way can be problematic because the class is always based on the average environment along an entire OSM way. For traffic, calculations are on another level of complexity.
+
+### noise_class
 
-### consider_noise, noise_penalty
 For proximity of noisy roads (secondary and higher). The noise factor represents the proportion of a road's buffer area that lies within the 64-meter buffer of noisy roads. This proportion is reduced:
+
 - for motorways and trunk roads with max speed < 105 by 1.5
 - for primary roads 2 times
 - 3 times if maxspeed is 75 - 105 for primary and secondary
 - other secondary roads 5 times
 
-Noise class is roughly proportional to the noise factor:
+`noise_class` is roughly proportional to the noise factor:
 
-noise_factor = noise class
+| `noise_factor` | `noise_class` |
-- < 0.1             =                            '1'
+| -------------- | ------------- |
-- < 0.25            =                          '2'
+| < 0.1          | 1             |
-- < 0.4              =                           '3'
+| < 0.25         | 2             |
-- < 0.55               =                        '4'
+| < 0.4          | 3             |
-- < 0.8                   =                      '5'
+| < 0.55         | 4             |
-- ELSE                     =                    '6'
+| < 0.8          | 5             |
+| ELSE           | 6             |
 
-To be classified as noise class 6, a way must be less than 13 m on average from the middle of the carriageway of a motorway with a maximum speed exceeding 105. For a class 5, the distance must be up to 35 meters.  (1 - noise factor) * 64 m for a given class determines the distance
+To be classified as noise class 6, a way must be less than 13 m on average from the middle of the carriageway of a motorway with a maximum speed exceeding 105. For a class 5, the distance must be up to 35 meters. (1 - noise_factor) \* 64 m for a given class determines the distance
 
-**Max noise class:**
+| highway        | maxspeed | max `noise_class` |
-| Max speed | Motorway, trunk |Primary|Secondary   	|
+| -------------- | -------- | ----------------- |
-|---				|:---:						|:---:	|:---:	|
+| motorway,trunk | > 105    | 6                 |
-| >105   		|6  							|4	  	| 3  	|
+| motorway,trunk | 105      | 5                 |
-| 105				|5		   					|4	   	|3   	|
+| motorway,trunk | 75       | 5                 |
-| 75		  	|5		   					|3 	  	|2   	|
+| primary        | > 105    | 4                 |
+| primary        | 105      | 4                 |
+| primary        | 75       | 3                 |
+| secondary      | > 105    | 3                 |
+| secondary      | 105      | 3                 |
+| secondary      | 75       | 2                 |
 
+### river_class
 
-### consider_river, no_river_penalty
 OSM data recognized as river:
+
 - waterway: river, canal
 - natural: water (except wastewater)
 
 Waterways have 32 m wide buffers. Water areas have 77 m wide buffers.
 
-river_see = river class 
+| `river_see` | `river_class` |
-- < 0.17                  =                  '1'
+| ----------- | ------------- |
-- < 0.35                     =                '2'
+| < 0.1       | 1             |
-- < 0.57                      =              '3'
+| < 0.3       | 2             |
-- < 0.80                       =             '4'
+| < 0.5       | 3             |
-- < 0.95                        =            '5'
+| < 0.8       | 4             |
-- ELSE                            =           '6'
+| < 0.9       | 5             |
+| ELSE        | 6             |
+
+### forest_class
 
-### consider_forest, no_forest_penalty
 OSM data recognized as forest:
+
 - landuse: forest, allotments, flowerbed, orchard, vineyard, recreation_ground, village_green
 - leisure: garden, park, nature_reserve
 
@@ -51,31 +69,34 @@ No forest buffers are used.
 
 Imagine you trace the way with a pencil drawing lines 62 meters wide. Then estimated_forest_class=6 corresponds to the case that at least 98% of the line is in the woodland. This number is called a green factor.
 
-green_factor = forest class
+| `green_factor` | `forest_class` |
-- < 0.1             =                         NULL
+| -------------- | -------------- |
-- < 0.2               =                             '1'
+| < 0.1          | NULL           |
-- < 0.4                 =                           '2'
+| < 0.2          | 1              |
-- < 0.6 		=          '3'
+| < 0.4          | 2              |
-- < 0.8                   =                         '4'
+| < 0.6          | 3              |
-- < 0.98               =                           '5'
+| < 0.8          | 4              |
-- ELSE                    =                        '6'
+| < 0.98         | 5              |
+| ELSE           | 6              |
 
+### town_class
 
-
-### consider_town, town_penalty 
 Town_class is determined by population data from OSM.
 
-Class
+| population         | `town_class` |
-- 1 = 	50-80 	k people
+| ------------------ | ------------ |
-- 2 = 80-150 k people
+| < 80 k people      | 1            |
-- 3 =	150 - 400 k people
+| < 150 k people     | 2            |
-- 4 = 400 - 1,000 k people
+| < 400 k people     | 3            |
-- 5 = 1 - 2 million people
+| < 1 million people | 4            |
-- 6 = > 2 million people
+| < 2 million people | 5            |
+| > 2 million people | 6            |
+
+### traffic_class
 
-### consider_traffic, traffic_penalty
 (modified copy from the sql file).
 OSM data used to estimate the traffic:
+
 - population of towns (+ distance from position to the towns)
 - size of industrial areas (landuse=industrial) and distance to them. Not considered: solar & wind farms.
 - airports international
@@ -83,5 +104,5 @@ OSM data used to estimate the traffic:
 - density of highways (tertiary and higher) calculated on a grid (100 km^2). Traffic decreases when more such roads are available. Exceptions: near junctions between motorways and other roads the traffic increases on these roads.
 - mountain-ranges calculated as density of peaks > 400 m traffic is generally on highways in such regions higher as only generated by the local population or industrial areas
 - calculate traffic from the population (for each segment of type primary secondary tertiary)
-- SUM of (population of each town < 100 km) / ( town-radius + 2500 + dist(segment-position to the town) ** 2 )
+- SUM of (population of each town < 100 km) / ( town-radius + 2500 + dist(segment-position to the town) \*\* 2 )
 - town-radius is calculated as sqrt(population)