mappymatch


Namemappymatch JSON
Version 0.5.0 PyPI version JSON
download
home_pageNone
SummaryPackage for mapmatching.
upload_time2024-11-12 23:27:42
maintainerNone
docs_urlNone
authorNational Renewable Energy Laboratory
requires_python>=3.9
licenseBSD 3-Clause License Copyright (c) 2022, Alliance for Sustainable Energy, LLC
keywords gps map match
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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).

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mappymatch",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "GPS, map, match",
    "author": "National Renewable Energy Laboratory",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/8b/97/dfb4fc4d6590d92867c45b55296aef33707be2f0a49be9a89febdc59906f/mappymatch-0.5.0.tar.gz",
    "platform": null,
    "description": "# mappymatch\n\nMappymatch 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.\n\n![Map Matching Animation](docs/source/images/map-matching.gif?raw=true)\n\nThe current matchers are:\n\n- `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.\n- `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.\n- `ValhallaMatcher`: A matcher to ping a [Valhalla](https://www.interline.io/valhalla/) server for map matching results.\n\nCurrently supported map formats are:\n\n- Open Street Maps\n\n## Installation\n\n```console\npip install mappymatch\n```\n\nIf you have trouble with that, check out [the docs](https://mappymatch.readthedocs.io/en/latest/general/install.html) for more detailed install instructions.\n\n## Example Usage\n\nThe current primary workflow is to use [osmnx](https://github.com/gboeing/osmnx) to download a road network and match it using the `LCSSMatcher`.\n\nThe `LCSSMatcher` implements the map matching algorithm described in this paper:\n\n[Zhu, Lei, Jacob R. Holden, and Jeffrey D. Gonder.\n\"Trajectory Segmentation Map-Matching Approach for Large-Scale, High-Resolution GPS Data.\"\nTransportation Research Record: Journal of the Transportation Research Board 2645 (2017): 67-75.](https://doi.org/10.3141%2F2645-08)\n\nusage:\n\n```python\nfrom mappymatch import package_root\nfrom mappymatch.constructs.geofence import Geofence\nfrom mappymatch.constructs.trace import Trace\nfrom mappymatch.maps.nx.nx_map import NxMap\nfrom mappymatch.matchers.lcss.lcss import LCSSMatcher\n\ntrace = Trace.from_csv(package_root() / \"resources/traces/sample_trace_1.csv\")\n\n# generate a geofence polygon that surrounds the trace; units are in meters;\n# this is used to query OSM for a small map that we can match to\ngeofence = Geofence.from_trace(trace, padding=1e3)\n\n# uses osmnx to pull a networkx map from the OSM database\nnx_map = NxMap.from_geofence(geofence)\n\nmatcher = LCSSMatcher(nx_map)\n\nmatches = matcher.match_trace(trace)\n\n# convert the matches to a dataframe\ndf = matches.matches_to_dataframe()\n```\n\n## Example Notebooks\n\nExample JupyterLab notebooks making use of mappymatch can be found in the [mappymatch examples repository](https://github.com/NREL/mappymatch-examples).\n",
    "bugtrack_url": null,
    "license": "BSD 3-Clause License Copyright (c) 2022, Alliance for Sustainable Energy, LLC",
    "summary": "Package for mapmatching.",
    "version": "0.5.0",
    "project_urls": {
        "Homepage": "https://github.com/NREL/mappymatch"
    },
    "split_keywords": [
        "gps",
        " map",
        " match"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a95c7cc25963a735cae9a8dabe9e2959b236b279d76f99ff1595d96268c10992",
                "md5": "375208ebaaf8d894dee891c1c198fc1c",
                "sha256": "581b0d581dc45f8a538bf1823225c2f9fa6c38bae6d56b413e0d0cb7201e4210"
            },
            "downloads": -1,
            "filename": "mappymatch-0.5.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "375208ebaaf8d894dee891c1c198fc1c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 53837,
            "upload_time": "2024-11-12T23:27:40",
            "upload_time_iso_8601": "2024-11-12T23:27:40.544862Z",
            "url": "https://files.pythonhosted.org/packages/a9/5c/7cc25963a735cae9a8dabe9e2959b236b279d76f99ff1595d96268c10992/mappymatch-0.5.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "8b97dfb4fc4d6590d92867c45b55296aef33707be2f0a49be9a89febdc59906f",
                "md5": "6002b60f9960641b3d924fc85953ed13",
                "sha256": "1152537fedaee78f8c3b603da7d3aef5790edc1a574bb1db508958067332e3f1"
            },
            "downloads": -1,
            "filename": "mappymatch-0.5.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6002b60f9960641b3d924fc85953ed13",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 53397,
            "upload_time": "2024-11-12T23:27:42",
            "upload_time_iso_8601": "2024-11-12T23:27:42.702915Z",
            "url": "https://files.pythonhosted.org/packages/8b/97/dfb4fc4d6590d92867c45b55296aef33707be2f0a49be9a89febdc59906f/mappymatch-0.5.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-12 23:27:42",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "NREL",
    "github_project": "mappymatch",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "mappymatch"
}
        
Elapsed time: 2.27015s