{"id":13717371,"url":"https://github.com/naver/kapture","last_synced_at":"2025-05-16T02:07:57.184Z","repository":{"id":37922673,"uuid":"275164995","full_name":"naver/kapture","owner":"naver","description":"kapture is a file format as well as a set of tools for manipulating datasets, and in particular Visual Localization and Structure from Motion data.","archived":false,"fork":false,"pushed_at":"2024-03-11T09:42:25.000Z","size":56602,"stargazers_count":501,"open_issues_count":2,"forks_count":66,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-04-08T12:11:12.241Z","etag":null,"topics":["colmap","image-retrieval","localization","r2d2","sfm","structure-from-motion","visual-features","visual-localization"],"latest_commit_sha":null,"homepage":"","language":"Python","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/naver.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.adoc","funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2020-06-26T13:40:30.000Z","updated_at":"2025-03-28T03:10:30.000Z","dependencies_parsed_at":"2024-01-05T23:56:59.170Z","dependency_job_id":"eea1724a-8d79-4381-aaf8-f6c026e9140c","html_url":"https://github.com/naver/kapture","commit_stats":{"total_commits":838,"total_committers":13,"mean_commits":64.46153846153847,"dds":0.662291169451074,"last_synced_commit":"bd6c4e05b7b9f39db35a41f7d50a9c5504a501b0"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Fkapture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Fkapture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Fkapture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Fkapture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naver","download_url":"https://codeload.github.com/naver/kapture/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254453653,"owners_count":22073617,"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":["colmap","image-retrieval","localization","r2d2","sfm","structure-from-motion","visual-features","visual-localization"],"created_at":"2024-08-03T00:01:21.347Z","updated_at":"2025-05-16T02:07:52.175Z","avatar_url":"https://github.com/naver.png","language":"Python","readme":":sectnums:\n:sectnumlevels: 1\n:toc: macro\n:toclevels: 2\n\nimage::assets/kapture_banner.png[\"KAPTURE\", width=800px]\n\ntoc::[]\n\nimage::https://github.com/naver/kapture/workflows/kapture-main/badge.svg[Continuous Integration Status]\n\n== Overview\n\nKapture is a pivot file format, based on text and binary files, used to describe SfM (Structure From Motion) and more generally sensor-acquired data.\n\nIt can be used to store sensor parameters and raw sensor data:\n\n- cameras\n- images\n- lidar and other sensor data\n\nAs well as computed data:\n\n- 2d features\n- 3d reconstruction\n\nFinally, many popular datasets can directly be downloaded using the convenient https://github.com/naver/kapture/blob/main/doc/tutorial.adoc#download-a-dataset[downloader]!\n\n== Specifications\nThe format specification is detailed in the link:kapture_format.adoc[kapture format specifications document].\n\n== Example File Structure\n\nThis is an example file structure of a dataset in the kapture format.\n\n[source,txt]\n----\nmy_dataset                 # Dataset root path\n├─ sensors/                # Sensor data root path\n│  ├─ sensors.txt          # list of all sensors with their specifications (e.g. camera intrinsics)\n│  ├─ rigs.txt             # geometric relationship between sensors (optional)\n│  ├─ trajectories.txt     # extrinsics (timestamp, sensor, pose)\n│  ├─ records_camera.txt   # all records of type 'camera' (timestamp, sensor and path to image)\n│  ├─ records_SENSOR_TYPE.txt # all records of type SENSOR_TYPE (other sensors, eg: 'magnetic', 'pressure'...)\n│  └─ records_data/            # image and lidar data path\n│     ├─ map/cam_01/00001.jpg  # image path used in records_camera.txt (example)\n│     ├─ map/cam_01/00002.jpg\n│     ├─ map/lidar_01/0001.pcd # lidar data path used in records_lidar.txt\n│     ├─ query/query001.jpg    # image path used in records_camera.txt\n│     ├─ ...\n└─ reconstruction/\n   ├─ keypoints/                       # 2D keypoints files\n   │  ├─ r2d2_WASF-N8_20k              # identify the type of keypoints\n   │  │  ├─ keypoints.txt              # type of keypoint (shape and dtype)\n   │  │  ├─ map/cam_01/00001.jpg.kpt   # keypoints for corresponding image (example)\n   │  │  ├─ query/query001.jpg.kpt     # keypoints for corresponding image (example)\n   │  │  ├─ ...\n   │  ├─ d2_tf                         # identify the type of keypoints\n   │  │  ├─ keypoints.txt              # type of keypoint (shape and dtype)\n   │  │  ├─ keypoints.tar              # instead of regular files, you can use an archive\n   │  │  │  ├─ map/cam_01/00001.jpg.kpt   # keypoints for corresponding image (example)\n   │  │  │  ├─ query/query001.jpg.kpt     # keypoints for corresponding image (example)\n   │  │  │  ├─ ...\n   │  ├─ ...\n   ├─ descriptors/                     # keypoint descriptors files\n   │  ├─ r2d2_WASF-N8_20k              # identify the type of descriptors\n   │  │  ├─ descriptors.txt            # type of descriptor (keypoints type, shape and dtype)\n   │  │  ├─ map/cam_01/00001.jpg.desc  # descriptors for corresponding image (example)\n   │  │  ├─ query/query001.jpg.desc    # descriptors for corresponding image (example)\n   │  │  ├─ ...\n   │  ├─ d2_tf                         # identify the type of descriptors\n   │  │  ├─ descriptors.txt            # type of descriptor\n   │  │  ├─ descriptors.tar            # instead of regular files, you can use an archive\n   │  │  │  ├─ map/cam_01/00001.jpg.desc  # descriptors for corresponding image (example)\n   │  │  │  ├─ query/query001.jpg.desc    # descriptors for corresponding image (example)\n   │  │  │  ├─ ...\n   │  ├─ ...\n   ├─ points3d.txt                  # 3D points of the reconstruction\n   ├─ observations.txt              # 2D/3D points corespondences\n   ├─ matches/                      # matches files.\n   │  ├─ r2d2_WASF-N8_20k           # identify the type of keypoints that are matched\n   │  │  ├─ map/cam_01/00001.jpg.overlapping/cam_01/00002.jpg.matches # example\n   │  │  ├─  ...\n   │  ├─ d2_tf                      # identify the type of keypoints that are matched\n   │  │  ├─ matches.tar             # instead of regular files, you can use an archive\n   │  │  │  ├─ map/cam_01/00001.jpg.overlapping/cam_01/00002.jpg.matches # example\n   │  │  │  ├─  ...\n   │  ├─ ...\n   └─ global_features/                 # global feature files\n      ├─ AP-GeM-LM18                   # identify the type of global_features\n      │  ├─ global_features.txt        # type of global feature\n      │  ├─ map/cam_01/00001.jpg.gfeat # example of global feature for corresponding image\n      │  ├─ query/query001.jpg.gfeat   # example of global feature for corresponding image\n      │  └─ ...\n      ├─ DELG                          # identify the type of global_features\n      │  ├─ global_features.txt        # type of global feature\n      │  ├─ global_features.tar        # instead of regular files, you can use an archive\n      │  │  ├─ map/cam_01/00001.jpg.gfeat # example of global feature for corresponding image\n      │  │  ├─ query/query001.jpg.gfeat   # example of global feature for corresponding image\n      │  │  └─ ...\n      ├─ ...\n----\n\n== Software\n\nThe kapture format is provided with a Python library, as well as several conversion tools.\n\n=== Install\n\n[source,bash]\npip install kapture\n\nor see link:doc/installation.adoc[installation] for more detailed instructions.\n\n=== Using docker\n\nBuild the docker image:\n\n[source,bash]\n----\n# build the docker image : if you have already cloned the repository\ndocker build . -t kapture/kapture\n# OR build the docker image directly from github\ndocker build git://github.com/naver/kapture -t kapture/kapture\n# run unit tests\ndocker run -it --rm kapture/kapture python3 -m unittest discover -s /opt/src/kapture/tests\n----\n\nIf you want to process your own data, you can bind directories between the host and the container using\n`--volume` or `--mount` option (See the https://docs.docker.com/storage/bind-mounts/[docker documentation]).\nThe following example mounts `/path/to/dataset/` from the host to `/dataset` inside the docker.\n\n[source,bash]\n----\ndocker run -it \\\n    --rm \\ # Automatically remove the container when it exits \\\n    --volume /path/to/dataset/:/dataset:ro \\ #read only\n    kapture/kapture\n----\n\n=== kapture Python library\n\nSee the https://github.com/naver/kapture/blob/main/doc/tutorial.adoc#using-kapture-in-your-code[tutorial]\nfor some examples using the kapture Python library.\n\n\n=== kapture tools\n\nIn this repository, you will find a set of *conversion tools* to or from kapture format.\nImport results to kapture format, and conversely, export converts kapture data to other formats.\nDepending of the format, some data might not be converted, either because the other format does not support it (`—`)\nor because its was not implemented (`⨉`). Here is a table summarizing the conversion capabilities:\n\n.conversion capabilities\n|===\n| Format                    | \u003c- -\u003e  | cam  | rig  | img  | trj  | gps  | kpt  | dsc  | gft  | p3D  | obs  | mch\n\n.2+| colmap                 | import |  ✓   |  ✓   |  ✓   |  ✓   |  ⨉   |  ✓   |  ✓   |  —   |  ✓   |  ✓   | (✓)\n                            | export |  ✓   |  ✓   |  ✓   |  ✓   |  ⨉   |  ✓   |  ✓   |  —   |  ✓   |  ✓   | (✓)\n.2+| openmvg                | import |  ✓   |  —   |  ✓   |  ✓   |  ⨉   |  ✓   |  ✓   |  —   |  ✓   |  ✓   |  (✓) \n                            | export |  ✓   |  —   |  ✓   |  ✓   |  ⨉   |  (✓)   |  (✓)   |  —   |  ✓   |  ✓   |  (✓) \n.2+| OpenSfM                | import |  ✓   |  ⨉   |  ✓   |  ✓   |  ✓   |  ✓   |  ✓   |  —   |  ✓   |  ⨉   |  ✓\n                            | export |  ✓   |  ⨉   |  ✓   |  ✓   |  ⨉   |  ✓   |  —   |  ✓   |  —   |  ⨉   |  ✓\n| bundler                   | import |  ✓   |  —   |  ✓   |  ✓   |  —   |  ✓   |  —   |  —   |  ✓   |  ✓   |  — \n| image_folder              | import |  —   |  —   |  ✓   |  —   |  —   |  —   |  —   |  —   |  —   |  —   |  — \n| image_list                | import |  ✓   |  —   |  ✓   |  —   |  —   |  —   |  —   |  —   |  —   |  —   |  — \n| nvm                       | import |  ✓   |  —   |  ✓   |  ✓   |  —   |  ✓   |  —   |  —   |  ✓   |  ✓   |  — \n| IDL_dataset_cvpr17        | import |  ✓   |  —   |  ✓   |  ✓   |  —   |  —   |  —   |  —   |  —   |  —   |  — \n| RobotCar_Seasons          | import |  ✓   |  ✓   |  ✓   |  ✓   |  —   |  ✓   |  —   |  —   |  ✓   |  ✓   |  —\n| ROSbag cameras+trajectory | import | (✓)  | (✓)  |  ✓   |  ✓   |  ⨉   |  —   |  —   |  —   |  —   |  —   |  — \n| SILDa                     | import |  ✓   |  ✓   |  ✓   |  ✓   |  —   |  —   |  —   |  —   |  —   |  —   |  —\n| virtual_gallery           | import |  ✓   |  ✓   |  ✓   |  ✓   |  —   |  —   |  —   |  —   |  —   |  —   |  —\n| stereolabs zed2           | import |  ✓   |  ✓   |  ✓   |  ✓   |  —   |  —   |  —   |  —   |  —   |  —   |  —\n|===\n\n:Notes:\n - `✓`: supported, `(✓)` partially supported, `⨉`: not implemented, `—`: not supported by format.\n - `cam`: handle camera parameters, eg. intrisics\n - `rig`: handle rig structure.\n - `img`: handle the path to images.\n - `trj`: handle trajectories, eg. poses.\n - `kpt`: handle image keypoints locations.\n - `dsc`: handle image keypoints descriptors.\n - `gft`: handle global image feature descriptors.\n - `p3D`: handle 3D point clouds.\n - `obs`: handle observations, ie. 3D-points / 2D keypoints correspondences.\n - `mch`: handle keypoints matches.\n\nlink:https://gist.github.com/jo-chemla/258e6e40d3d6c2220b29518ff3c17c40[Here], you can also find an utility tool for\ncropping input images of a kapture dataset. Thanks Jonathan Chemla for the contribution.\n\n== kapture support in other packages\n\n=== Local Features\n- https://arxiv.org/abs/1906.06195[R2D2] local features can be directly generated in kapture format. See https://github.com/naver/r2d2#feature-extraction-with-kapture-datasets[here]\n- https://arxiv.org/abs/1905.03561[D2-Net] features can also be extracted in kapture format. See instructions https://github.com/mihaidusmanu/d2-net#feature-extraction-with-kapture-datasets[here].\n\n\n=== Global Features\n- https://europe.naverlabs.com/research/computer-vision-research-naver-labs-europe/learning-visual-representations/deep-image-retrieval/[AP-GeM] global feature extractor in kapture format: https://github.com/naver/deep-image-retrieval#feature-extraction-with-kapture-datasets[here]\n\n\n== Datasets\n\nThe kapture package provides conversion tools for several data formats and datasets used in the domain.\nBut it also provides a tool to download datasets already converted to kapture.\nSee the link:doc/tutorial.adoc[kapture tutorial] for instructions to use the dataset downloader.\n\nHere is a list of datasets you can directly download in kapture format with the downloader tool:\n\n* Datasets for the https://www.visuallocalization.net/datasets/[Long Term Visual Localization] benchmark:\n** https://europe.naverlabs.com/blog/first-of-a-kind-large-scale-localization-datasets-in-crowded-indoor-spaces/[NAVER LABS localization datasets]\n** Aachen Day Night v1.1\n** Extended CMU-Seasons\n** RobotCar Seasons v2\n** InLoc (without images)\n** SILDa Weather and Time of Day\n** RIO10\n** ETH-Microsoft\n* https://europe.naverlabs.com/research/3d-vision/virtual-gallery-dataset/[Virtual Gallery] dataset\n\n\n== kapture-localization\n\nCheckout https://github.com/naver/kapture-localization[kapture-localization], our toolbox which contains implementations for various localization related algorithms. \n\n - mapping and localization pipelines with custom features\n - mapping and localization pipelines with SIFT and vocabulary tree matching (default colmap pipeline)\n - image retrieval benchmark (global sfm, local sfm, pose approximation)\n\n== Tutorial\n\nSee the link:doc/tutorial.adoc[kapture tutorial] for a short introduction to:\n\n - conversion tools\n - using kapture in your code\n - dataset download\n\n== Contributing\n\nThere are many ways to contribute to the kapture project:\n\n* provide feedback and suggestions of improvements\n* submit bug reports in the project bug tracker\n* provide a dataset in kapture format that we can add to the downloader tool\n* implement a feature or bug-fix for an outstanding issue\n* add support of kapture format in other software packages (e.g. SfM pipelines...), thus adding support for more datasets\n* provide scripts to create data in kapture format (e.g. local/global feature extraction)\n* propose a new feature and implement it\n\nIf you wish to contribute, please refer to the  link:CONTRIBUTING.adoc[CONTRIBUTING] page.\n\n== License\nSoftware license is detailed in the link:LICENSE[LICENSE] file.\n\n== Contact Us\nYou can contact us through https://github.com/naver/kapture[GitHub], or at kapture at naverlabs + com\n","funding_links":[],"categories":["Datasets and Benchmarks","Open Source Implementations"],"sub_categories":["Tools","Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaver%2Fkapture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaver%2Fkapture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaver%2Fkapture/lists"}