Left: station-to-station path of a single train through Switzerland obtained from official schedule data. Right: path of the same train map-matched by pfaedle.

Left: station-to-station path of a single bus through Stuttgart obtained from official schedule data. Right: path of the same bus map-matched by pfaedle.

                 _-====-__-=-__-===-__-=======-__
               _(                               _)
            OO(         PFAEDLE                )
         . o  '===-______-===-____-==-__-====='
      .o
     . ______          _______________
   _()_||__|| __o^o___ | [] [] [] [] |
  (           |      | |             |o
 /-OO----OO""="OO--OO"="OO---------OO"
############################################################

pfaedle

Precise OpenStreetMap (OSM) map-matching for public transit schedules (GTFS data). Implementation and evaluation code for our paper Sparse Map-Matching in Public Transit Networks with Turn restrictions.

This is a fork of ad-freiburg/pfaedle that contains several differences from the base repo:

• use of new c++ standards as much as possible
• use new dependency management system named pkg
• reorganized and changed class namings to make things much clearer (for me atleast)
• new gtfs library underneath for handling gtfs feeds (much simpler and lighter)
• use of pugixml instead of pfxml for parsing xml osm data
• enhanced logging support (using spdlog for that)

Requirements

• cmake
• gcc >= 7.5 (or clang >= 7.0)

Building and Installation

Fetch this repository and init submodules:

git clone https://github.com/vesavlad/pfaedle

mkdir build && cd build
cmake ..
make -j

To install, type

make install

General Usage

Generating shapes for a GTFS feed

pfaedle -x <OSM FILE> <GTFS INPUT FOLDER>

A get_shape'd version of the input GTFS feed will be written to ./gtfs-out.

By default, shapes are only calculated for trips that don't have a get_shape in the input feed. To drop all existing shapes, use the -D flag.

For example, you may generate (and replace existing, see -D parameter) shapes for the GTFS dataset for Freiburg like this:

$ wget https://fritz.freiburg.de/csv_Downloads/VAGFR.zip && unzip VAGFR.zip
$ wget http://download.geofabrik.de/europe/germany/baden-wuerttemberg/freiburg-regbez-latest.osm.bz2 && bunzip2 freiburg-regbez-latest.osm.bz2
$ pfaedle -D -x freiburg-regbez-latest.osm .

Generating shapes for a specific MOT

To generate shapes for a specific mot only, use the -m option. Possible values are either tram, bus, coach, rail, subway, ferry, funicular, gondola, trolleybus, all (default) or GTFS vehicle type codes (0, 1, 2, 3, 4, 5, 6, 7, 11).

Multiple values can be specified (comma separated).

OSM filtering

pfaedle comes with the ability to filter OpenStreetMap data. If you specify the -X flag, pfaedle will filter the input OSM file and output a new OSM file which contains exactly the data needed to calculate the shapes for the input GTFS feed and the input configuration.

This can be used to avoid parsing (for example) the entire planet.osm on each run.

via Docker

You can use the vesavlad/pfaedle Docker image by mounting the OSM & GTFS data into the container:

docker run -i --rm \
	# mount OSM data
	--volume /path/to/osm/data:/osm \
	# mount GTFS data
	--volume /path/to/gtfs/data:/gtfs \
	# tell pfaedle where to find the data
	pfaedle -x /osm/osm-data.xml -i /gtfs

Debugging

The following flags may be useful for debugging:

• -T <GTFS TRIP ID> only calculate get_shape for a single trip (specified via its GTFS trip id) and output it as GeoJSON to <dbg-path>/path.json
• --write-graph write the graph used for routing as GeoJSON to <dbg-path>/graph.json
• --write-cgraph if -T is set, write the combination graph used for routing as GeoJSON to <dbg-path>/combgraph.json
• --write-trgraph write the complete network graph to <dbg-path>/trgraph.json

Configuration

A default configuration file pfaedle.cfg can be found in this repo and will be installed with make install. Custom configuration files can be specified with the -c flag. If no -c flag is set, pfaedle will parse and merge the following cfg files in the given order (if present): <install prefix>/etc/pfaedle/pfaedle.cfg, $HOME/.config/pfaedle/pfaedle.cfg, <CWD>/pfaedle.cfg. Values given in later files will overwrite earlier defined values.

Evaluation

You may run an entire evaluation of our testing datasets Vitoria-Gasteiz, Paris, Switzerland and Stuttgart with

mkdir build && cd build
cmake ..
make -j
make eval

Notes:

• this will download, and filter, the entire OSM files for Spain and the Stuttgart region. Make sure you have enough space left on your hard drive.
• in evaluation mode, pfaedle needs significantly more time, because the calculation of the similarity measurements between shapes are expensive
• if you are only interested in the end results of a single dataset, run make <dataset>.lighteval in /eval. For example, make paris.lighteval generates a shaped version of the paris dataset, without doing extensive comparisons to the ground truth.
• similarily, if you want to run the extensive evaluation for a single dataset, run make <dataset>.eval in /eval.

Evaluation requirements

• zlib

On Debianesque systems, type

sudo apt-get install zlib1g-dev

to install the dependencies.