{"id":19517442,"url":"https://github.com/cvg/limap","last_synced_at":"2025-05-15T05:07:29.123Z","repository":{"id":149313496,"uuid":"617016210","full_name":"cvg/limap","owner":"cvg","description":"A toolbox for mapping and localization with line features.","archived":false,"fork":false,"pushed_at":"2025-04-09T11:29:26.000Z","size":6198,"stargazers_count":774,"open_issues_count":36,"forks_count":78,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-04-15T03:41:38.494Z","etag":null,"topics":["3d-reconstruction","bundle-adjustment","line-detection","line-mapping","line-matchng","multi-view-geometry","vanishing-points","visual-localization"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cvg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-21T14:36:11.000Z","updated_at":"2025-04-14T15:18:24.000Z","dependencies_parsed_at":"2023-10-22T15:33:03.742Z","dependency_job_id":"a5b89db5-51a3-471c-90f1-922f788feb69","html_url":"https://github.com/cvg/limap","commit_stats":{"total_commits":343,"total_committers":8,"mean_commits":42.875,"dds":"0.13994169096209907","last_synced_commit":"9048e7eb7176653b253e9afee51a401a253509d4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvg%2Flimap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvg%2Flimap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvg%2Flimap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvg%2Flimap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cvg","download_url":"https://codeload.github.com/cvg/limap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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":["3d-reconstruction","bundle-adjustment","line-detection","line-mapping","line-matchng","multi-view-geometry","vanishing-points","visual-localization"],"created_at":"2024-11-11T00:03:25.697Z","updated_at":"2025-05-15T05:07:24.114Z","avatar_url":"https://github.com/cvg.png","language":"C++","readme":"# LIMAP \n\n**The documentations on brief tutorials and APIs are available [here](http://b1ueber2y.me/projects/LIMAP/docs/)**.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./misc/media/supp_qualitative_5x3.png\"\u003e\n\u003c/p\u003e\n\nLIMAP is a toolbox for mapping and localization with line features. The system was initially described in the highlight paper [3D Line Mapping Revisited](https://arxiv.org/abs/2303.17504) at CVPR 2023 in Vancouver, Canada. Contributors to this project are from the [Computer Vision and Geometry Group](https://cvg.ethz.ch/) at [ETH Zurich](https://ethz.ch/en.html).\n\nIn this project, we provide interfaces for various geometric operations on 2D/3D lines. We support off-the-shelf SfM software including [VisualSfM](http://ccwu.me/vsfm/index.html), [Bundler](https://bundler.io/), and [COLMAP](https://colmap.github.io/) to initialize the camera poses to build 3D line maps on the database. The line detectors, matchers, and vanishing point estimators are abstracted to ensure flexibility to support recent advances and future development. \n\n**Next step:** Hybrid incremental SfM is under development and will be included in the next round of release.\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=100% src=\"./misc/media/barn_lsd.gif\" style=\"margin:-300px 0px -300px 0px\"\u003e\n\u003c/p\u003e\n\n## Installation\n\n**Install the dependencies as follows:**\n* Python 3.9/10/11\n* CMake \u003e= 3.17\n* CUDA (for deep learning based detectors/matchers)\n* System dependencies [[Command line](./misc/install/dependencies.md)]\n\nTo install the LIMAP Python package:\n```\ngit submodule update --init --recursive\npython -m pip install -r requirements.txt\npython -m pip install -Ive . \n```\nTo double check if the package is successfully installed:\n```\npython -c \"import limap; print(limap.__version__)\"\n```\n\n## Quickstart\n\n### Example of Line Mapping\nDownload the test scene **(100 images)** with the following command.\n```bash\nbash scripts/quickstart.sh\n```\n\nTo run **Fitnmerge** (line mapping with available depth maps) on Hypersim (visualization is enabled by default):\n```bash\npython runners/hypersim/fitnmerge.py --output_dir outputs/quickstart_fitnmerge\n```\n\nTo run **Line Mapping** (RGB-only) on Hypersim (visualization is enabled by default):\n```bash\npython runners/hypersim/triangulation.py --output_dir outputs/quickstart_triangulation\n```\nTo run **Visualization** of the 3D line maps after the reconstruction:\n```bash\npython visualize_3d_lines.py --input_dir outputs/quickstart_triangulation/finaltracks # add the camera frustums with \"--imagecols outputs/quickstart_triangulation/imagecols.npy\"\n```\n\n[Tips] Options are stored in the config folder: ``cfgs``. You can easily change the options with the Python argument parser. The following shows an example:\n```bash\npython runners/hypersim/triangulation.py --sfm.hloc.descriptor sift --line2d.detector.method lsd \\\n                                         --line2d.visualize --triangulation.IoU_threshold 0.2 \\\n                                         --skip_exists --n_visible_views 5\n```\nIn particular, ``--skip_exists`` is a very useful option to avoid running point-based SfM and line detection/description repeatedly in each pass. \n\nAlso, the combination  ``LSD detector + Endpoints NN matcher`` can be enabled with ``--default_config_file cfgs/triangulation/default_fast.yaml`` for high efficiency (while with non-negligible performance degradation).\n\n### Example of Hybrid Point-Line Localization\nWe provide two query examples for localization from the *Stairs* scene in the [7Scenes](https://www.microsoft.com/en-us/research/project/rgb-d-dataset-7-scenes/) Dataset, where traditional point-based methods normally struggle due to the repeated steps and lack of texture. The examples are provided in `.npy` files: `runners/tests/data/localization/localization_test_data_stairs_[1|2].npy`, which contains the necessary 2D-3D point and line correspondences along with the necessary configurations.\n\nTo run the examples, for instance the first one:\n```bash\npython runners/tests/localization.py --data runners/tests/data/localization/localization_test_data_stairs_1.npy\n```\n\nThe script will print the pose error estimated using point-only (hloc), and the pose error estimated by our hybrid point-line localization framework. In addition, two images will be created in the output folder (default to `outputs/test/localization`) showing the inliers point and line correspondences in hybrid localization projected using the two estimated camera pose (by point-only and point+line) onto the query image with 2D point and line detections marked. An improved accuracy of the hybrid point-line method is expected to be observed.\n\n## Supported line detectors, matchers and VP estimators\n\nIf you wish to use the methods with **separate installation needed** you need to install it yourself with the corresponding guides. This is to avoid potential issues at the LIMAP installation to ensure a quicker start.\n\n**Note**: PR on integration of new features are very welcome.\n\n**The following line detectors are currently supported:**\n- [LSD](https://github.com/iago-suarez/pytlsd)\n- [SOLD2](https://github.com/cvg/SOLD2)\n- [HAWP](https://github.com/cherubicXN/hawp) (separate installation needed [[Guide](misc/install/hawpv3.md)])\n- [TP-LSD](https://github.com/Siyuada7/TP-LSD) (separate installation needed [[Guide](misc/install/tp_lsd.md)]) \n- [DeepLSD](https://github.com/cvg/DeepLSD)\n\n**The following line descriptors/matchers are currently supported:**\n- [LBD](https://github.com/iago-suarez/pytlbd) (separate installation needed [[Guide](misc/install/lbd.md)])\n- [SOLD2](https://github.com/cvg/SOLD2)\n- [LineTR](https://github.com/yosungho/LineTR)\n- [L2D2](https://github.com/hichem-abdellali/L2D2)\n- Endpoint matching with [SuperPoint](https://github.com/magicleap/SuperPointPretrainedNetwork) + Nearest Neighbors\n- Endpoint matching with [SuperPoint](https://github.com/magicleap/SuperPointPretrainedNetwork) + [SuperGlue](https://github.com/magicleap/SuperGluePretrainedNetwork)\n- [GlueStick](https://github.com/cvg/GlueStick)\n\n**The following vanishing point estimators are currently supported:**\n- [JLinkage](https://github.com/B1ueber2y/JLinkage)\n- [Progressive-X](https://github.com/danini/progressive-x) (separation installation needed [[Guide](https://github.com/danini/progressive-x/blob/master/README.md)])\n\n## Citation\nIf you use this code in your project, please consider citing the following paper:\n```bibtex\n@InProceedings{Liu_2023_LIMAP,\n    author = {Liu, Shaohui and Yu, Yifan and Pautrat, Rémi and Pollefeys, Marc and Larsson, Viktor},\n    title = {3D Line Mapping Revisited},\n    booktitle = {Computer Vision and Pattern Recognition (CVPR)},\n    year = {2023},\n}\n```\n\n## Contributors\nThis project is mainly developed and maintained by [Shaohui Liu](https://github.com/B1ueber2y/), [Yifan Yu](https://github.com/MarkYu98), [Rémi Pautrat](https://github.com/rpautrat), and [Viktor Larsson](https://github.com/vlarsson). Issues and contributions are very welcome at any time. \n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvg%2Flimap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcvg%2Flimap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvg%2Flimap/lists"}