be-graphes-map-generator/README.md

### Map generator for "BE Graphes"

The purpose of this repository is to ease the process of generating graph and mapforge file that are consistent (using the same OpenStreetMap data).

### How to start?

To clone this repository:

```bash
# 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
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;
  - multiple polygon (`.poly`) and bounding-box (`.bbox`) files for specific regions;
  - PBF files downloaded organized in folder `$REGION/$REGION.pbf`.

- `outputs` is the default folder for generated output.

### Generating maps

This project can be used to generate two types of files:

- Graph file (`.mapgr`) containing graph information (see
  [OSM2Graph](https://github.com/Holt59/OSM2Graph));
- Mapsforge file (`.mapfg`) containing [mapsforge](https://github.com/mapsforge/mapsforge)
  data to display graph in a more visual way.

The process to generate the Mapsforge file is more complex than the one to generate graph file,
and it will often take much more time. Fortunately, it is often **not necessary** to generate
the Mapsforge file, because pre-generated files exist for most countries and regions.

Before generating the Mapsforge file, check if a file corresponding to the region you want
exists on the following server:
[http://download.mapsforge.org/maps/v4/](http://download.mapsforge.org/maps/v4/)

The hierarchy of this server is similar to [Geofabrik](http://download.geofabrik.de/), which
is the main source for our PBF files.

#### Step 1 - Obtaining a PBF file.

The first step is to a PBF files containining the region you want:

- Download a complete region from Geofabrik: [http://download.geofabrik.de/](http://download.geofabrik.de/)
- If necessary, chop a region previously downloaded:

_Using a bounding box:_

```bash
bin/osmosis --rb inputs/europe/france/bretagne/bretagne.osm.pbf \ # Specify your input PBF
            --bounding-box bottom=47.160000 left=-3.855000 top=48.330000 right=-1.915000 completeWays=yes \ # Specify the bounding bo
            --write-pbf inputs/europe/france/bretagne/morbihan.pbf # Specify the output file
```

_Using a polygon:_

```bash
bin/osmosis --rb inputs/europe/france/bretagne/bretagne.osm.pbf \ # Specify your input PBF
            --bounding-polygon file=inputs/europe/france/bretagne/morbihan.poly completeWays=yes \ # Specify your bounding polygon
            --write-pbf file=inputs/europe/france/bretagne/morbihan.pbf # Specify your output file
```

The `inputs` directory contains bounding-box (`.bbox`) and bounding polygon (`.poly`) for some
regions. You can find polygon for a lots of region here:
[http://polygons.openstreetmap.fr/index.py](http://polygons.openstreetmap.fr/index.py)
(to find the id of the relation, search it on openstreetmap, e.g.
[https://www.openstreetmap.org/relation/7447](https://www.openstreetmap.org/relation/7447)).

#### Step 1 Bis - Fixing coastlines and sea.

**Important**: You can skip this step if your region does not contain sea or big inner
lakes, or if you do not want to generate the corresponding Mapsforge file.

You will need GDAL for this section, and the python bindings, you can usually install them
using a package manager:

```bash
# pip (better with a venv!)
pip install GDAL>=3

# Debian
sudo apt install gdal python-gdal

# CentOS
sudo yum install gdal gdal-python
```

We need to add sea information to the PBF file to generate a correct mapsforge map. To do so,
a script `coastline-fix.sh` is provided. Run it simply:

```bash
cd inputs
./coastline-fix.sh europe/france/bretagne/morbihan.pbf
```

To apply the fix, you need a polygon file (`morbihan.poly` — not another name), in the
same directory as the PBF or in the `inputs/bbox` directory (recommended).

This script will generate multiple intermediate files, but only two are importants:

- `inputs/europe/france/bretagne/morbihan.bbox`, actual bounding-box of the PBF file —
  This will overwrite the old bounding-box if there was one.
- `inputs/europe/france/bretagne/morbihan_merge.pbf`, merged file that you should use as input
  for mapsforge.

#### Step 2 - Generate graph & Mapsforge files

To generate both the graph file and the Mapsforge file corresponding to your input PBF,
you simply need to run the `generate.sh` script:

```bash
bash generate.sh inputs/europe/france/bretagne/bretagne.osm.pbf \
                 --id FR-E --name "Bretagne" \
                 --output outputs/bretagne
```

This command will generate two files: `outputs/bretagne.mapgr` and `outputs/bretagne.mapfg`,
you should not add the file extension when specifying `--output`.

You can get help about `generate.sh` by running:

```bash
bash generate.sh --help
```

If you use a merged file (`_merge.pbf`) file as input, you need to specify the corresponding
bounding-box:

```bash
bash generate.sh inputs/europe/france/bretagne/morbihan_merge.pbf \
                 --bounding-box inputs/europe/france/bretagne/morbihan.bbox \
                 --id FR-56 --name "Morbihan" \
                 --output outputs/morbihan
```

The script will automatically find the original file (`morbihan.pbf`) and use it to generate
the graph file (using the merged file can generate unexpected result... ).

If the input PBF file correspond to a region that has been cropped, it is better to specify
the polygon or bounding-box used for the generation of the PBF:

```bash
bash generate.sh inputs/europe/france/bretagne/morbihan_merge.pbf \
                 --bounding-box inputs/europe/france/bretagne/morbihan.bbox \
                 --bounding-polygon inputs/europe/france/bretagne/morbihan.poly \
                 --id FR-56 --name "Morbihan" \
                 --output outputs/morbihan
```

If both the `--bounding-box` and `--bounding-polygon` option are specified, the bounding-box
will be ignored for the generation of the graph file (the `--bounding-polygon` option has no
effect for the generation of the Mapsforge file).

You can generate only the graph file (`--graph-only`) or the Mapsforge file
(`--mapsforge-only`). With `--mapsforge-only`, the `--id` and `--name` options are not
required.