Metadata-Version: 2.1
Name: mappymatch
Version: 0.4.5
Summary: Package for mapmatching.
Author: National Renewable Energy Laboratory
License: BSD 3-Clause License Copyright (c) 2022, Alliance for Sustainable Energy, LLC
Project-URL: Homepage, https://github.com/NREL/mappymatch
Keywords: GPS,map,match
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: rtree
Requires-Dist: pyproj
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: osmnx
Requires-Dist: networkx
Requires-Dist: igraph
Requires-Dist: folium
Requires-Dist: requests
Requires-Dist: polyline
Provides-Extra: tests
Requires-Dist: black; extra == "tests"
Requires-Dist: ruff; extra == "tests"
Requires-Dist: mypy>=0.981; extra == "tests"
Requires-Dist: types-requests; extra == "tests"
Requires-Dist: pytest; extra == "tests"
Provides-Extra: docs
Requires-Dist: sphinx==4.5.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme==1.0.0; extra == "docs"
Requires-Dist: sphinxemoji==0.2.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: mappymatch[tests]; extra == "dev"
Requires-Dist: mappymatch[docs]; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: interrogate; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pip-tools; extra == "dev"

# mappymatch

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

![Map Matching Animation](docs/source/images/map-matching.gif?raw=true)

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:

- Open Street Maps

## Installation

```console
pip install mappymatch
```

If you have trouble with that, check out [the docs](https://mappymatch.readthedocs.io/en/latest/general/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

Example JupyterLab notebooks making use of mappymatch can be found in the [mappymatch examples repository](https://github.com/NREL/mappymatch-examples).
