{"id":13423645,"url":"https://github.com/cyang-kth/fmm","last_synced_at":"2025-05-16T07:05:53.444Z","repository":{"id":38201671,"uuid":"108551291","full_name":"cyang-kth/fmm","owner":"cyang-kth","description":"Fast map matching, an open source framework in C++","archived":false,"fork":false,"pushed_at":"2024-07-09T03:32:58.000Z","size":15601,"stargazers_count":939,"open_issues_count":50,"forks_count":215,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-08T16:09:10.398Z","etag":null,"topics":["fmm","gis","gps","map-match","map-matching","match","openstreetmap","parrallel-map-matching","python","road-network","shapefile","stmatch","trajectory"],"latest_commit_sha":null,"homepage":"https://fmm-wiki.github.io/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyang-kth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.TXT","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-27T13:43:40.000Z","updated_at":"2025-04-08T03:29:33.000Z","dependencies_parsed_at":"2022-07-12T01:22:28.345Z","dependency_job_id":"67c21c45-199b-423e-83ff-4be32a8410ce","html_url":"https://github.com/cyang-kth/fmm","commit_stats":{"total_commits":337,"total_committers":7,"mean_commits":"48.142857142857146","dds":"0.029673590504451064","last_synced_commit":"5cccc608903877b62969e41a58b60197a37a5c01"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyang-kth%2Ffmm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyang-kth%2Ffmm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyang-kth%2Ffmm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyang-kth%2Ffmm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyang-kth","download_url":"https://codeload.github.com/cyang-kth/fmm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485062,"owners_count":22078767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fmm","gis","gps","map-match","map-matching","match","openstreetmap","parrallel-map-matching","python","road-network","shapefile","stmatch","trajectory"],"created_at":"2024-07-31T00:00:39.672Z","updated_at":"2025-05-16T07:05:48.427Z","avatar_url":"https://github.com/cyang-kth.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"img/fmm_social.jpg\"\u003e\n\u003c/div\u003e\n\n| Linux / macOS | Windows | Wiki          | Docs        |\n| ------------- | ------- | ------------- | ----------- |\n| [![Build Status](https://travis-ci.org/cyang-kth/fmm.svg?branch=master)](https://travis-ci.org/github/cyang-kth/fmm) | [![Build status](https://ci.appveyor.com/api/projects/status/8qee5c8iay75j1am?svg=true)](https://ci.appveyor.com/project/cyang-kth/fmm) | [![Wiki](https://img.shields.io/badge/wiki-website-blue.svg)](https://fmm-wiki.github.io/) | [![Documentation](https://img.shields.io/badge/docs-doxygen-blue.svg)](https://cyang-kth.github.io/fmm/) |\n\nFMM is an open source map matching framework integrating hidden Markov models and precomputation. It solves the problem of matching noisy GPS data to a road network. By maximizing performance and functionality, FMM allows for map matching algorithms that are both efrficient and scalable to large volumes of data.\n\nFMM provides Python and C++ APIs and can be used in the command line, in Jupyter notebooks, or in web app.\n\n### Table of Contents\n- [Features](#features)\n- [Screenshots of notebook](#screenshots-of-notebook)\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n- [Documentation](#documentation)\n- [Code docs for developer](#code-docs-for-developer)\n- [Contact and citation](#contact-and-citation)\n\n### Features\n- **High performance**: C++ implementation using Rtree, optimized routing, parallel computing (OpenMP).\n- **Python API**: [jupyter-notebook](example/notebook) and [web app](example/web_demo)\n- **Scalability**: millions of GPS points and millions of road edges.  \n- **Multiple data formats**:\n  - Road network in OpenStreetMap or ESRI shapefile.\n  - GPS data in Point CSV, Trajectory CSV and Trajectory Shapefile ([more details](https://fmm-wiki.github.io/docs/documentation/input/#gps-data)).\n- **Detailed matching information**: traversed path, geometry, individual matched edges, GPS error, etc. More information at [here](https://fmm-wiki.github.io/docs/documentation/output/).\n- **Multiple algorithms**: [FMM](http://www.tandfonline.com/doi/full/10.1080/13658816.2017.1400548) (for small and middle scale networks) and [STMatch](https://dl.acm.org/doi/abs/10.1145/1653771.1653820) (for large scale road networks)\n- **Platform support**: Unix (ubuntu) , Mac and Windows(cygwin environment).\n- **Hexagon match**: :tada: Match to the uber's [h3](https://github.com/uber/h3) Hexagonal Hierarchical Geospatial Indexing System. Check the [demo](example/h3).\n\nWe encourage contribution with feature request, bug report or developping new map matching algorithms using the framework.\n\n### Screenshots of notebook\n\nMap match to OSM road network by drawing\n\n![fmm_draw](https://github.com/cyang-kth/fmm-examples/blob/master/img/fmm_draw.gif?raw=true)\n\nExplore the factor of candidate size k, search radius and GPS error\n\n![fmm_explore](https://github.com/cyang-kth/fmm-examples/blob/master/img/fmm_explore.gif?raw=true)\n\nExplore detailed map matching information\n\n![fmm_detail](https://github.com/cyang-kth/fmm-examples/blob/master/img/fmm_detail.gif?raw=true)\n\nExplore with dual map\n\n![dual_map](https://github.com/cyang-kth/fmm-examples/blob/master/img/dual_map.gif?raw=true)\n\nMap match to hexagon by drawing\n\n![hex_draw](https://github.com/cyang-kth/fmm-examples/blob/master/img/hex_draw.gif?raw=true)\n\nExplore the factor of hexagon level and interpolate\n\n![hex_explore](https://github.com/cyang-kth/fmm-examples/blob/master/img/hex_explore.gif?raw=true)\n\nSource code of these screenshots are available at https://github.com/cyang-kth/fmm-examples.\n\n### Requirements\n- C++ Compiler supporting c++11 and OpenMP\n- CMake \u003e=3.5: provides cross platform building tools\n- GDAL \u003e= 2.2: IO with ESRI shapefile, Geometry data type\n- Boost Graph \u003e= 1.54.0: routing algorithms used in UBODT Generator\n- Boost Geometry \u003e= 1.54.0: Rtree, Geometry computation\n- Boost Serialization \u003e= 1.54.0: Serialization of UBODT in binary format\n- ~~Libosmium: a library for reading OpenStreetMap data. Requires expat and bz2.~~ (The direct input with OSM file is removed since the raw dataset may contain\ntopology errors. It is suggested to use shapefile input downloaded from osmnx.)\n- swig: used for building Python bindings\n\n### Getting Started\nThese instructions are for the Ubuntu platform. For installation on Windows and Mac, refer to the [installation instructions](https://fmm-wiki.github.io/docs/installation/) here.\n\n1. **Install Requirements**\n    - Update the ppa to install the required version (\u003e=2.2) of GDAL.\n    \n      ```shell\n      sudo add-apt-repository ppa:ubuntugis/ppa\n      sudo apt-get -q update\n      ```\n    - Then, install all the requirements with\n\n      ```shell\n      sudo apt-get install libboost-dev libboost-serialization-dev \\\n      gdal-bin libgdal-dev make cmake libbz2-dev libexpat1-dev swig python-dev\n      ```\n\n2. **Install C++ program and Python bindings**\n    - Build and install the program with cmake.\n\n      ```shell\n      # Under the project folder\n      mkdir build\n      cd build\n      cmake ..\n      make -j4\n      sudo make install\n      ```\n      This will build executable files under the `build` folder, which are installed to `/usr/local/bin`:\n      - `ubodt_gen`: the Upper bounded origin destination table (UBODT) generator (precomputation) program\n      - `fmm`: the program implementing the fast map matching algorithm\n      - `stmatch`: the program implementing the STMATCH algorithm, no precomputation needed\n      \n      It will also create a folder `python` under the build path, which contains fmm bindings(`fmm.py` and `_fmm.so`) that are installed into the Python site-packages location (e.g., `/usr/lib/python2.7/dist-packages`).\n      \n3. **Verification of Installation**\n    - Run command line map matching\n      Open a new terminal and type `fmm`. You should see the following output:\n      \n      ```shell\n      ------------ Fast map matching (FMM) ------------\n      ------------     Author: Can Yang    ------------\n      ------------   Version: 2020.01.31   ------------\n      ------------     Applicaton: fmm     ------------\n      A configuration file is given in the example folder\n      Run `fmm config.xml` or with arguments\n      fmm argument lists:\n      --ubodt (required) \u003cstring\u003e: Ubodt file name\n      --network (required) \u003cstring\u003e: Network file name\n      --gps (required) \u003cstring\u003e: GPS file name\n      --output (required) \u003cstring\u003e: Output file name\n      --network_id (optional) \u003cstring\u003e: Network id name (id)\n      --source (optional) \u003cstring\u003e: Network source name (source)\n      --target (optional) \u003cstring\u003e: Network target name (target)\n      --gps_id (optional) \u003cstring\u003e: GPS id name (id)\n      --gps_geom (optional) \u003cstring\u003e: GPS geometry name (geom)\n      --candidates (optional) \u003cint\u003e: number of candidates (8)\n      --radius (optional) \u003cdouble\u003e: search radius (300)\n      --error (optional) \u003cdouble\u003e: GPS error (50)\n      --pf (optional) \u003cdouble\u003e: penalty factor (0)\n      --log_level (optional) \u003cint\u003e: log level (2)\n      --output_fields (optional) \u003cstring\u003e: Output fields\n        opath,cpath,tpath,ogeom,mgeom,pgeom,\n        offset,error,spdist,tp,ep,all\n      For xml configuration, check example folder\n      ------------    Program finished     ------------\n      ```\n  \n    - Run python script\n      To verify that the Python bindings are working:\n  \n      ```shell\n      # Change to the parent folder which contains fmm_test.py\n      cd ../example/python\n      python fmm_test.py\n      ```\n\n    Refer to the [Q\u0026A](https://fmm-wiki.github.io/docs/installation/qa) for any installation errors.\n\n### Documentation\n\n- Check [https://fmm-wiki.github.io/](https://fmm-wiki.github.io/) for installation, documentation.\n- Check [example](example) for simple examples of fmm.\n- :tada: Check [https://github.com/cyang-kth/fmm-examples](https://github.com/cyang-kth/fmm-examples)\nfor interactive map matching in notebook.\n\n### Code docs for developer\n\nCheck [https://cyang-kth.github.io/fmm/](https://cyang-kth.github.io/fmm/)\n\n### Contact and citation\n\nCan Yang, Ph.D. student at KTH, Royal Institute of Technology in Sweden\n\nEmail: cyang(at)kth.se\n\nHomepage: https://people.kth.se/~cyang/\n\nFMM originates from an implementation of this paper [Fast map matching, an algorithm integrating hidden Markov model with precomputation](http://www.tandfonline.com/doi/full/10.1080/13658816.2017.1400548). A post-print version of the paper can be downloaded at [link](https://people.kth.se/~cyang/bib/fmm.pdf). Substaintial new features have been added compared with the original paper.  \n\nPlease cite fmm in your publications if it helps your research:\n\n    Can Yang \u0026 Gyozo Gidofalvi (2018) Fast map matching, an algorithm\n    integrating hidden Markov model with precomputation, International Journal of Geographical Information Science, 32:3, 547-570, DOI: 10.1080/13658816.2017.1400548\n\nBibtex file\n\n```bibtex\n@article{Yang2018FastMM,\n  title={Fast map matching, an algorithm integrating hidden Markov model with precomputation},\n  author={Can Yang and Gyozo Gidofalvi},\n  journal={International Journal of Geographical Information Science},\n  year={2018},\n  volume={32},\n  number={3},\n  pages={547 - 570}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyang-kth%2Ffmm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyang-kth%2Ffmm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyang-kth%2Ffmm/lists"}