| Name | instance-matching JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | HD-map instance extraction & matching toolkit |
| upload_time | 2025-07-14 01:24:19 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2025 JinHwan Jeon
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
hd-map
instance matching
lanelet
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Instance-Matching
[](LICENSE)
[](https://doi.org/10.5281/zenodo.15861414)
**Instance-Matching** is a lightweight Python toolkit for extracting, matching, evaluating and visualizing correspondences between high-definition map lane-level instances (center-lines and lane-dividers) and per-frame local inference results.
## 📦 Installation
```bash
# 0) Create and activate a virtual environment
conda create -n test python=3.9
conda activate test
# 1) Install numpy (1.24 version for python 3.9)
conda install -c conda-forge numpy=1.24
# 2) Install system dependencies (required for cyipopt)
conda install -c conda-forge pkg-config ipopt
# 3a) Install from PyPI
pip install instance-matching
# 3b) For development, clone and install in editable mode
git clone git@github.com:wjswlsghks98/instance-matching.git
cd instance-matching
pip install --editable .
````
---
## 📂 Data Preparation
For performing evaluation of instance matching module, first download data files from the [Zenodo repository](https://doi.org/10.5281/zenodo.15860891).
Running evaluation of this package expects `.osm` and preprocessed `.pkl` files under a `data/` directory at the project root:
```
instance-matching/
├── data/
│ ├── boston-seaport.osm
│ ├── boston-seaport.pkl
│ ├── singapore-hollandvillage.osm
│ ├── singapore-hollandvillage.pkl
│ └── …
```
---
## 🚀 Quick Start
### 1) Create `config.yaml`
```yaml
mode: matching
map_names:
- boston-seaport
map_origins:
boston-seaport: [42.336849169438615, -71.05785369873047]
singapore-hollandvillage: [1.2993652317780957, 103.78217697143555]
singapore-onenorth: [1.2882100868743724, 103.78475189208984]
singapore-queenstown: [1.2782562240223188, 103.76741409301758]
match:
mode: ablation # ablation, geom, topo, geom-topo, fusion-base, fusion, gromov-wasserstein
eval_mode: comparison # comparison or forward
params:
padding_cost: 10
weights: [1.0, 1.0, 1.0, 1.0, 1.0]
verbose: iter-detailed
precompute: false
```
### 2) Run via CLI
```bash
instance-matching run --config config.yaml
```
### 3) Run via Python API
```python
import yaml
from instance_matching import run_evaluation
cfg = yaml.safe_load(open("config.yaml"))
run_evaluation(cfg)
```
---
## 🔧 Core Modules
* **`cli.py`** – command-line entry point (`run --config …`)
* **`evaluator.py`** – orchestration of extract, match, evaluate (`run_evaluation`)
* **`extractor.py`** – GT & local instance extraction (`extract_local_instances`, etc.)
* **`reporter.py`** – aggregation & terminal reporting (`Reporter` class)
* **`visualizer.py`**– plotting utilities (`plot`)
* **`matcher/`** – matching algorithms:
* `InstanceMatcher` for optimization-based matching
* `GromovWasserstein` for GW-based matching
* **`utils.py`** – sampling, distance, adjacency helper functions
---
## 📖 Usage Example
```python
from shapely.geometry import Polygon
from instance_matching import (
extract_local_instances,
Reporter,
InstanceMatcher,
)
# 1) Load full GT instances (e.g. from pickle)
# user defined loading function is needed (for examples, look src/evaluator.py)
full = load_full_instances("data/boston-seaport.pkl")
# 2) Sample per-frame local instances
perception_box = Polygon([...])
local = extract_local_instances(full, perception_box, noise_std=0.3, offset_std=0.3)
# 3) Match
matcher = InstanceMatcher(full, local, config["match"])
report = matcher.match()
# 4) Aggregate & print
rep = Reporter(mode="matching")
rep.update("boston-seaport", [report])
rep.print("boston-seaport", trip_iter=1, tripN=1, frame_iter=1, frameN=1)
```
## 📄 License
This project is licensed under the **MIT License** – see [LICENSE](LICENSE).
## Cite
If you are using our work in your study, please cite our paper
```
@ARTICLE{Jeon2025InstanceMatching,
author={Jeon, Jinhwan and Choi, Seibum B.},
journal={IEEE Transactions on Intelligent Transportation Systems},
title={Instance-Level Graph Matching of HD Map Elements},
year={2025},
volume={},
number={},
pages={**},
keywords={**},
doi={**}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "instance-matching",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "hd-map, instance matching, lanelet",
"author": null,
"author_email": "Jinhwan Jeon <jordan98@kaist.ac.kr>",
"download_url": "https://files.pythonhosted.org/packages/44/a7/dd16cc54d6e2e046a4ef096c2789471ecdad56a2fa39617e8c4b40e98dd3/instance_matching-1.0.1.tar.gz",
"platform": null,
"description": "\n# Instance-Matching\n\n[](LICENSE)\n[](https://doi.org/10.5281/zenodo.15861414)\n\n**Instance-Matching** is a lightweight Python toolkit for extracting, matching, evaluating and visualizing correspondences between high-definition map lane-level instances (center-lines and lane-dividers) and per-frame local inference results.\n\n\n## \ud83d\udce6 Installation\n\n```bash\n# 0) Create and activate a virtual environment\nconda create -n test python=3.9\nconda activate test\n\n# 1) Install numpy (1.24 version for python 3.9)\nconda install -c conda-forge numpy=1.24\n\n# 2) Install system dependencies (required for cyipopt)\nconda install -c conda-forge pkg-config ipopt\n\n# 3a) Install from PyPI\npip install instance-matching\n\n# 3b) For development, clone and install in editable mode\ngit clone git@github.com:wjswlsghks98/instance-matching.git\ncd instance-matching\npip install --editable .\n````\n\n---\n\n## \ud83d\udcc2 Data Preparation\n\nFor performing evaluation of instance matching module, first download data files from the [Zenodo repository](https://doi.org/10.5281/zenodo.15860891).\n\nRunning evaluation of this package expects `.osm` and preprocessed `.pkl` files under a `data/` directory at the project root:\n\n```\ninstance-matching/\n\u251c\u2500\u2500 data/\n\u2502 \u251c\u2500\u2500 boston-seaport.osm\n\u2502 \u251c\u2500\u2500 boston-seaport.pkl\n\u2502 \u251c\u2500\u2500 singapore-hollandvillage.osm\n\u2502 \u251c\u2500\u2500 singapore-hollandvillage.pkl\n\u2502 \u2514\u2500\u2500 \u2026\n```\n\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### 1) Create `config.yaml`\n\n```yaml\nmode: matching\n\nmap_names:\n - boston-seaport\n\nmap_origins:\n boston-seaport: [42.336849169438615, -71.05785369873047]\n singapore-hollandvillage: [1.2993652317780957, 103.78217697143555]\n singapore-onenorth: [1.2882100868743724, 103.78475189208984]\n singapore-queenstown: [1.2782562240223188, 103.76741409301758]\n\nmatch:\n mode: ablation # ablation, geom, topo, geom-topo, fusion-base, fusion, gromov-wasserstein\n eval_mode: comparison # comparison or forward\n params:\n padding_cost: 10\n weights: [1.0, 1.0, 1.0, 1.0, 1.0]\n verbose: iter-detailed\n precompute: false\n```\n\n### 2) Run via CLI\n\n```bash\ninstance-matching run --config config.yaml\n```\n\n### 3) Run via Python API\n\n```python\nimport yaml\nfrom instance_matching import run_evaluation\n\ncfg = yaml.safe_load(open(\"config.yaml\"))\nrun_evaluation(cfg)\n```\n\n---\n\n## \ud83d\udd27 Core Modules\n\n* **`cli.py`** \u2013 command-line entry point (`run --config \u2026`)\n* **`evaluator.py`** \u2013 orchestration of extract, match, evaluate (`run_evaluation`)\n* **`extractor.py`** \u2013 GT & local instance extraction (`extract_local_instances`, etc.)\n* **`reporter.py`** \u2013 aggregation & terminal reporting (`Reporter` class)\n* **`visualizer.py`**\u2013 plotting utilities (`plot`)\n* **`matcher/`** \u2013 matching algorithms:\n\n * `InstanceMatcher` for optimization-based matching\n * `GromovWasserstein` for GW-based matching\n* **`utils.py`** \u2013 sampling, distance, adjacency helper functions\n\n---\n\n## \ud83d\udcd6 Usage Example\n\n```python\nfrom shapely.geometry import Polygon\nfrom instance_matching import (\n extract_local_instances,\n Reporter,\n InstanceMatcher,\n)\n\n# 1) Load full GT instances (e.g. from pickle)\n# user defined loading function is needed (for examples, look src/evaluator.py)\nfull = load_full_instances(\"data/boston-seaport.pkl\")\n\n# 2) Sample per-frame local instances\nperception_box = Polygon([...])\nlocal = extract_local_instances(full, perception_box, noise_std=0.3, offset_std=0.3)\n\n# 3) Match\nmatcher = InstanceMatcher(full, local, config[\"match\"])\nreport = matcher.match()\n\n# 4) Aggregate & print\nrep = Reporter(mode=\"matching\")\nrep.update(\"boston-seaport\", [report])\nrep.print(\"boston-seaport\", trip_iter=1, tripN=1, frame_iter=1, frameN=1)\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the **MIT License** \u2013 see [LICENSE](LICENSE).\n\n## Cite\n\nIf you are using our work in your study, please cite our paper\n```\n@ARTICLE{Jeon2025InstanceMatching,\nauthor={Jeon, Jinhwan and Choi, Seibum B.},\njournal={IEEE Transactions on Intelligent Transportation Systems}, \ntitle={Instance-Level Graph Matching of HD Map Elements}, \nyear={2025},\nvolume={},\nnumber={},\npages={**},\nkeywords={**},\ndoi={**}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 JinHwan Jeon\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "HD-map instance extraction & matching toolkit",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/wjswlsghks98/instance-matching",
"Issue Tracker": "https://github.com/wjswlsghks98/instance-matching/issues",
"Source": "https://github.com/wjswlsghks98/instance-matching"
},
"split_keywords": [
"hd-map",
" instance matching",
" lanelet"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c58bf6e508638df49a041e4aca770e50a879375ff6f61e53efe48e15d084202",
"md5": "545ddedcea34ce91aacfba367657612e",
"sha256": "284ef1ec698757c8c0f171fe4ba6feb848acc790a2091d25a731fa61935a4cc3"
},
"downloads": -1,
"filename": "instance_matching-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "545ddedcea34ce91aacfba367657612e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 32338,
"upload_time": "2025-07-14T01:24:17",
"upload_time_iso_8601": "2025-07-14T01:24:17.815548Z",
"url": "https://files.pythonhosted.org/packages/0c/58/bf6e508638df49a041e4aca770e50a879375ff6f61e53efe48e15d084202/instance_matching-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "44a7dd16cc54d6e2e046a4ef096c2789471ecdad56a2fa39617e8c4b40e98dd3",
"md5": "e9979d295cd7a059572fe5327e32cc5a",
"sha256": "62ac1379d1fdf51f6efc0fe7a4a44b784cfac78e196fa0092f7dd538c7f2ff69"
},
"downloads": -1,
"filename": "instance_matching-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e9979d295cd7a059572fe5327e32cc5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 30147,
"upload_time": "2025-07-14T01:24:19",
"upload_time_iso_8601": "2025-07-14T01:24:19.697185Z",
"url": "https://files.pythonhosted.org/packages/44/a7/dd16cc54d6e2e046a4ef096c2789471ecdad56a2fa39617e8c4b40e98dd3/instance_matching-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 01:24:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wjswlsghks98",
"github_project": "instance-matching",
"github_not_found": true,
"lcname": "instance-matching"
}
