Update 'README.md'

README.md

@@ -0,0 +1,95 @@
+### Map generator for "BE Graphes"
+
+To clone this repository:
+
+```
+# You need the --recursive option (--recurse-submodules with Git >= 2.13),
+# you can use https or ssh, it does not matter.
+git clone --recursive https://gitea.typename.fr/INSA/be-graphes-map-generator.git
+
+# Then you need to initialize the repository, this may takes some time as it needs
+# to fetch a shapefile (~500MB) on a remote server.
+cd be-graphes-map-generator
+bash init.sh
+```
+
+If you do not plan on generating maps with coastline for mapsforge (see below), you can use the `--no-shapefile` option
+to avoid the download:
+```
+bash init.sh --no-shapefile
+```
+
+### Folders organization
+
+The two main folders are `inputs` and `outputs`:
+
+- `inputs` mainly contains:
+    - a script `coastline-fix.sh` to merge land/sea polygon (see below) and PBF files;
+    - a directory containing boundinx-box (`bbox`) for specific regions;
+    - a file containing highway filters;
+    - PBF files downloaded organized in folder `$REGION/$REGION.pbf`.
+
+- `outputs` is the default folder for generated output.
+
+### Obtaining PBF files
+
+You can download PBF files for multiple regions on Geofabrik: [https://download.geofabrik.de/index.html](https://download.geofabrik.de/index.html)
+
+You should put the PBF file in subfolders, e.g. if you want to use `bretagne.pbf`, you should save it to:
+
+```
+inputs/bretagne/bretagne.pbf
+```
+
+Doing so will avoid having a messy `inputs` folder due to region-specific files generated by `coastline-fix.sh`.
+
+### Generating maps
+
+Only manual generation is supported as of now:
+
+#### Mapsforge file:
+
+```
+# You do not need to specify a bounding-box if you did not use the coastline fix or
+# do not want it.
+bin/osmosis --rb inputs/bretagne/bretagne_merge.pbf \
+    --mapfile-writer file=outputs/morbihan.mapfg bbox=47.234,-3.598,47.997,-1.648 threads=2
+
+```
+
+#### Binary graph files
+
+```
+# You do not need to specify a bounding box if you do not need it. You can use either "insa2016" or
+# "insa2018" writers, and you should change the map id to your need.
+bin/osmosis --rb inputs/bretagne/bretagne-latest.osm.pbf  \
+    --used-node --bounding-box top=48.1749 left=-1.7709 right=-1.5014 bottom=48.0644 completeWays=yes \
+    --tf reject-relations --tf accept-ways highway=(cat inputs/highway-filter.cmd) natural=coastline --lp \
+    --osm2graph file=outputs/rennes.mapgr writer=insa2018 map-id=0x235
+```
+
+### Fixing coastline
+
+When generating mapsforge file that contains sea, you will need to fix the PBF file prior to running osmosis. 
+The fix is an adaptation from [https://github.com/mapsforge/mapsforge-creator](https://github.com/mapsforge/mapsforge-creator)
+— It basically does the same but does not download PBF or do the final osmosis run for you.
+
+You will first need a PBF file and its associated polygon file, you can get these from [https://download.geofabrik.de/index.html](https://download.geofabrik.de/index.html). You need to put those file in a region folder, e.g. if you want to fix `bretagne`, you should have:
+
+```
+# Do not rename these files!
+inputs/bretagne/bretagne-latest.osm.pbf
+inputs/bretagne/bretagne.poly
+```
+
+You should also have run the `init.sh` script without the `--no-shapefile` option (you should see a folder named `land-polygons-split-4326` in the `inputs` folder).
+
+Once you have the requested files, you can simply run (from the `inputs` folder):
+
+```
+# If you are not already in the inputs folder
+cd inputs
+
+# Change bretagne to whatever region...
+bash coastline-fix.sh bretagne
+```