mappymatch - GitLite

KO | EN

gitlite — search

#javascript #ai #go #android #rust #linux #java #windows #awesome #kubernetes #awesome-list #security #pytorch #mcp

mappymatch

(★ 127)

Pure-python package for map matching

File Explorer

Download Latest Version (.zip)

- - deploy-docs.yaml
  - lint-test.yml
  - release.yaml
- CODEOWNERS
- - _convert_examples_to_notebooks.py
  - lcss_example.py
- - map-matching.gif
- .nojekyll
- _config.yml
- _toc.yml
- api-docs.md
- home.md
- install.md
- quick-start.md
- - __init__.py
  - coordinate.py
  - geofence.py
  - match.py
  - road.py
  - trace.py
- - __init__.py
  - map_interface.py
- - __init__.py
  - line_snap.py
  - match_result.py
  - matcher_interface.py
  - osrm.py
  - valhalla.py
- - __init__.py
- - __init__.py
  - crs.py
  - exceptions.py
  - geo.py
  - keys.py
  - process_trace.py
  - url.py
- __about__.py
- __init__.py
- - downtown_denver.geojson
  - osmnx_drive_graph.graphml
  - pull_osm_map.py
  - test_trace.geojson
  - test_trace.gpx
  - test_trace_stationary_points.geojson
  - trace_bad_start.geojson
- __init__.py
- test_coordinate.py
- test_disconnected_components.py
- test_geo.py
- test_geofence.py
- test_lcss_add_match_for_stationary.py
- test_lcss_compress.py
- test_lcss_drop_stationary_points.py
- test_lcss_find_stationary_points.py
- test_lcss_forward_merge.py
- test_lcss_merge.py
- test_lcss_reverse_merge.py
- test_lcss_same_trajectory_scheme.py
- test_match_result.py
- test_osm.py
- test_process_trace.py
- test_trace.py
- test_valhalla.py
.gitattributes
.gitignore
.pre-commit-config.yaml
CLAUDE.md
CONTRIBUTING.md
LICENSE
pixi.lock
pyproject.toml
README.md

# Installation Guide

1. Get the code

git clone https://github.com/NatLabRockies/mappymatch

Downloads the entire project code from GitHub to your computer.

cd mappymatch

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

Python 3 Python is required to use pip.

pip install mappymatch

Installs the package published on PyPI directly — no need to clone the source.

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install mappymatch

Installs the package published on PyPI directly — no need to clone the source.

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# mappymatch

Mappymatch is a pure-python package developed and open sourced by the National Laboratory of the Rockies. It contains a collection of "Matchers" that enable matching a GPS trace (series of GPS coordinates) to a map.

![Map Matching Animation](https://raw.githubusercontent.com/NatLabRockies/mappymatch/main/docs/images/map-matching.gif)

The current matchers are:

- `LCSSMatcher`: A matcher that implements the LCSS algorithm described in this [paper](https://doi.org/10.3141%2F2645-08). Works best with high resolution GPS traces.
- `OsrmMatcher`: A light matcher that pings an OSRM server to request map matching results. See the [official documentation](http://project-osrm.org/) for more info.
- `ValhallaMatcher`: A matcher to ping a [Valhalla](https://www.interline.io/valhalla/) server for map matching results.

Currently supported map formats are:

- OpenStreetMap

## Installation

```console
pip install mappymatch
```

If you have trouble with that, check out [the docs](https://natlabrockies.github.io/mappymatch/install.html) for more detailed install instructions.

## Example Usage

The current primary workflow is to use [osmnx](https://github.com/gboeing/osmnx) to download a road network and match it using the `LCSSMatcher`.

The `LCSSMatcher` implements the map matching algorithm described in this paper:

[Zhu, Lei, Jacob R. Holden, and Jeffrey D. Gonder.
"Trajectory Segmentation Map-Matching Approach for Large-Scale, High-Resolution GPS Data."
Transportation Research Record: Journal of the Transportation Research Board 2645 (2017): 67-75.](https://doi.org/10.3141%2F2645-08)

usage:

```python
from mappymatch import package_root
from mappymatch.constructs.geofence import Geofence
from mappymatch.constructs.trace import Trace
from mappymatch.maps.nx.nx_map import NxMap
from mappymatch.matchers.lcss.lcss import LCSSMatcher

trace = Trace.from_csv(package_root() / "resources/traces/sample_trace_1.csv")

# generate a geofence polygon that surrounds the trace; units are in meters;
# this is used to query OSM for a small map that we can match to
geofence = Geofence.from_trace(trace, padding=1e3)

# uses osmnx to pull a networkx map from the OSM database
nx_map = NxMap.from_geofence(geofence)

matcher = LCSSMatcher(nx_map)

matches = matcher.match_trace(trace)

# convert the matches to a dataframe
df = matches.matches_to_dataframe()
```

## Example Notebooks

Check out the [LCSS Example](https://natlabrockies.github.io/mappymatch/lcss-example.html) for a more detailed example of working with the LCSSMatcher.