Preparation

Virtual environment

A virtual environment is recommended for every project using MTLDP. All MTLDP packages are installed into the same environment. Python 3.10 is the recommended version (the packages support 3.8 and later). Because the map matcher fmm has to be compiled, Anaconda or Miniconda is the recommended way to manage the environment:

$ conda create -n mtldp python=3.10 -y
$ conda activate mtldp
(mtldp) $

Install mtldp-meta-utils

This package provides mtldp.meta and mtldp.utils and is required by everything else.

$ git clone git@github.com:michigan-traffic-lab/mtldp-meta-utils.git
(mtldp) $ cd mtldp-meta-utils && pip install -e .

The -e (editable) install links the package to the source tree, so that pulling a new version takes effect without reinstalling. Users who never change the source can use pip install ..

Test the installation by importing the data structures and by listing the command line tools:

(mtldp) $ python -c "from mtldp.meta.TrafficNetwork import Node; from mtldp.utils.config import AppRegion; print('ok')"
ok
(mtldp) $ mtldp
Currently available scripts:
        0. Create config file: `create_config_file`
        1. Create folders and download OSM map: `create_region`
Helper scripts:
        0. Plot the region bonding box on map `draw_region_bbox`
        1. Delete trajectories in the folder `delete_processed_trajs`
        2. Copy existing regions with subset of junctions `copy_regions`
        3. Extract and merge OSM maps from source regions `extract_osm_map`
        4. Create sub regions from the master region bbox dict `create_sub_regions`
Please use `[cmd] --help` to get more information about each script.

Every command accepts --help; the full list is in Command line tools of mtldp-meta-utils.

copy_regions, create_sub_regions and extract_osm_map call the osmium command line tool to merge OpenStreetMap files. Install osmium-tool from your package manager or from conda-forge when you plan to use them:

(mtldp) $ conda install -c conda-forge osmium-tool

Install mtldp-preproc (optional)

mtldp.preproc is needed only to process raw data (OpenStreetMap files, vendor GPS deliveries and SPaT work orders). Applications that work on processed data do not need it. Access to the repository may require permission; contact the MTL director (shengyin@umich.edu).

The package depends on the Fast Map Matching library fmm, which is compiled from source. Follow Dependencies for pre-processing (Linux) or Installation of fmm in Windows (Windows) first, then install the package:

$ git clone git@github.com:michigan-traffic-lab/mtldp-preproc.git
(mtldp) $ cd mtldp-preproc && pip install -e .

The package registers the pipeline commands merge_osm, build_traffic_network, parse_spat, split_points, match_points_to_map, process_trajs and eva_trajs_qc (Command line tools of mtldp-preproc). Once it is installed, mtldp lists them as well:

(mtldp) $ mtldp
Currently available scripts:
        0. Create config file: `create_config_file`
        1. Create folders and download OSM map: `create_region`
        1.5. Merge close signalized intersections in OSM map `merge_osm`
        2. Build our network based on OSM map `build_traffic_network`
        3. [Optional] Parse the SPaT dat `parse_spat`
        4. Split trajectories based on date `split_points`
        5. Match trajectories to the map `match_points_to_map`
        6. Calculate trajectories performance index `process_trajs`
        7. Evaluate the quality of processed trajectories `eva_trajs_qc`
...

Install mtldp-review (optional)

The review tool is a small web application (FastAPI back end, Vue front end) that displays the network built for a region and lets you record corrections. It needs npm for the front end and a Mapbox token in ui/.env:

$ git clone git@github.com:michigan-traffic-lab/mtldp-review.git
(mtldp) $ cd mtldp-review && pip install -e . --no-deps
(mtldp) $ mtldp-review -c /path/to/configs/my_region.json

The command rebuilds the front end when needed, starts the server on the first free port from 8000 and opens the browser on the region.