Package: kapture
OverviewKapture is a pivot file format, based on text and binary files, used to
describe SfM (Structure From Motion) and more generally sensor-acquired
data.It can be used to store sensor parameters and raw sensor data:camerasimageslidar and other sensor dataAs well as computed data:2d features3d reconstructionFinally, many popular datasets can directly be downloaded using the
convenientdownloader!SpecificationsThe format specification is detailed in thekapture format
specifications document.Example File StructureThis is an example file structure of a dataset in the kapture format.my_dataset                 # Dataset root path
├─ sensors/                # Sensor data root path
│  ├─ sensors.txt          # list of all sensors with their specifications (e.g. camera intrinsics)
│  ├─ rigs.txt             # geometric relationship between sensors (optional)
│  ├─ trajectories.txt     # extrinsics (timestamp, sensor, pose)
│  ├─ records_camera.txt   # all records of type 'camera' (timestamp, sensor and path to image)
│  ├─ records_SENSOR_TYPE.txt # all records of type SENSOR_TYPE (other sensors, eg: 'magnetic', 'pressure'...)
│  └─ records_data/            # image and lidar data path
│     ├─ map/cam_01/00001.jpg  # image path used in records_camera.txt (example)
│     ├─ map/cam_01/00002.jpg
│     ├─ map/lidar_01/0001.pcd # lidar data path used in records_lidar.txt
│     ├─ query/query001.jpg    # image path used in records_camera.txt
│     ├─ ...
└─ reconstruction/
   ├─ keypoints/                       # 2D keypoints files
   │  ├─ r2d2_WASF-N8_20k              # identify the type of keypoints
   │  │  ├─ keypoints.txt              # type of keypoint (shape and dtype)
   │  │  ├─ map/cam_01/00001.jpg.kpt   # keypoints for corresponding image (example)
   │  │  ├─ query/query001.jpg.kpt     # keypoints for corresponding image (example)
   │  │  ├─ ...
   │  ├─ d2_tf                         # identify the type of keypoints
   │  │  ├─ keypoints.txt              # type of keypoint (shape and dtype)
   │  │  ├─ keypoints.tar              # instead of regular files, you can use an archive
   │  │  │  ├─ map/cam_01/00001.jpg.kpt   # keypoints for corresponding image (example)
   │  │  │  ├─ query/query001.jpg.kpt     # keypoints for corresponding image (example)
   │  │  │  ├─ ...
   │  ├─ ...
   ├─ descriptors/                     # keypoint descriptors files
   │  ├─ r2d2_WASF-N8_20k              # identify the type of descriptors
   │  │  ├─ descriptors.txt            # type of descriptor (keypoints type, shape and dtype)
   │  │  ├─ map/cam_01/00001.jpg.desc  # descriptors for corresponding image (example)
   │  │  ├─ query/query001.jpg.desc    # descriptors for corresponding image (example)
   │  │  ├─ ...
   │  ├─ d2_tf                         # identify the type of descriptors
   │  │  ├─ descriptors.txt            # type of descriptor
   │  │  ├─ descriptors.tar            # instead of regular files, you can use an archive
   │  │  │  ├─ map/cam_01/00001.jpg.desc  # descriptors for corresponding image (example)
   │  │  │  ├─ query/query001.jpg.desc    # descriptors for corresponding image (example)
   │  │  │  ├─ ...
   │  ├─ ...
   ├─ points3d.txt                  # 3D points of the reconstruction
   ├─ observations.txt              # 2D/3D points corespondences
   ├─ matches/                      # matches files.
   │  ├─ r2d2_WASF-N8_20k           # identify the type of keypoints that are matched
   │  │  ├─ map/cam_01/00001.jpg.overlapping/cam_01/00002.jpg.matches # example
   │  │  ├─  ...
   │  ├─ d2_tf                      # identify the type of keypoints that are matched
   │  │  ├─ matches.tar             # instead of regular files, you can use an archive
   │  │  │  ├─ map/cam_01/00001.jpg.overlapping/cam_01/00002.jpg.matches # example
   │  │  │  ├─  ...
   │  ├─ ...
   └─ global_features/                 # global feature files
      ├─ AP-GeM-LM18                   # identify the type of global_features
      │  ├─ global_features.txt        # type of global feature
      │  ├─ map/cam_01/00001.jpg.gfeat # example of global feature for corresponding image
      │  ├─ query/query001.jpg.gfeat   # example of global feature for corresponding image
      │  └─ ...
      ├─ DELG                          # identify the type of global_features
      │  ├─ global_features.txt        # type of global feature
      │  ├─ global_features.tar        # instead of regular files, you can use an archive
      │  │  ├─ map/cam_01/00001.jpg.gfeat # example of global feature for corresponding image
      │  │  ├─ query/query001.jpg.gfeat   # example of global feature for corresponding image
      │  │  └─ ...
      ├─ ...SoftwareThe kapture format is provided with a Python library, as well as several
conversion tools.Installpip install kaptureor seeinstallationfor more detailed
instructions.Using dockerBuild the docker image:# build the docker image : if you have already cloned the repository
docker build . -t kapture/kapture
# OR build the docker image directly from github
docker build git://github.com/naver/kapture -t kapture/kapture
# run unit tests
docker run -it --rm kapture/kapture python3 -m unittest discover -s /opt/src/kapture/testsIf you want to process your own data, you can bind directories between
the host and the container using--volumeor--mountoption (See thedocker documentation).
The following example mounts/path/to/dataset/from the host to/datasetinside the docker.docker run -it \
    --rm \ # Automatically remove the container when it exits \
    --volume /path/to/dataset/:/dataset:ro \ #read only
    kapture/kapturekapture Python librarySee thetutorialfor some examples using the kapture Python library.kapture toolsIn this repository, you will find a set ofconversion toolsto or
from kapture format. Import results to kapture format, and conversely,
export converts kapture data to other formats. Depending of the format,
some data might not be converted, either because the other format does
not support it (—) or because its was not implemented (⨉). Here is a
table summarizing the conversion capabilities:conversion capabilitiesFormat← →camrigimgtrjgpskptdscgftp3Dobsmchcolmapimport✓✓✓✓⨉✓✓—✓✓(✓)export✓✓✓✓⨉✓✓—✓✓(✓)openmvgimport✓—✓✓⨉✓✓—✓✓(✓)export✓—✓✓⨉(✓)(✓)—✓✓(✓)OpenSfMimport✓⨉✓✓✓✓✓—✓⨉✓export✓⨉✓✓⨉✓—✓—⨉✓bundlerimport✓—✓✓—✓——✓✓—image_folderimport——✓————————image_listimport✓—✓————————nvmimport✓—✓✓—✓——✓✓—IDL_dataset_cvpr17import✓—✓✓———————RobotCar_Seasonsimport✓✓✓✓—✓——✓✓—ROSbag cameras+trajectoryimport(✓)(✓)✓✓⨉——————SILDaimport✓✓✓✓———————virtual_galleryimport✓✓✓✓———————✓: supported,(✓)partially supported,⨉: not implemented,—: not supported by format.cam: handle camera parameters, eg. intrisicsrig: handle rig structure.img: handle the path to images.trj: handle trajectories, eg. poses.kpt: handle image keypoints locations.dsc: handle image keypoints descriptors.gft: handle global image feature descriptors.p3D: handle 3D point clouds.obs: handle observations, ie. 3D-points / 2D keypoints
correspondences.mch: handle keypoints matches.kapture support in other packagesLocal FeaturesR2D2local features can be
directly generated in kapture format. SeehereD2-Netfeatures can also be
extracted in kapture format. See instructionshere.Global FeaturesAP-GeMglobal feature extractor in kapture format:hereDatasetsThe kapture package provides conversion tools for several data formats
and datasets used in the domain. But it also provides a tool to download
datasets already converted to kapture. See thekapture
tutorialfor instructions to use the dataset
downloader.Here is a list of datasets you can directly download in kapture format
with the downloader tool:Datasets for theLong Term Visual
Localizationbenchmark:NAVER LABS localization
datasetsAachen Day Night v1.1Extended CMU-SeasonsRobotCar Seasons v2InLoc (without images)SILDa Weather and Time of DayRIO10ETH-MicrosoftVirtual
Gallerydatasetkapture-localizationCheckoutkapture-localization,
our toolbox which contains implementations for various localization
related algorithms.mapping and localization pipelines with custom featuresmapping and localization pipelines with SIFT and vocabulary tree
matching (default colmap pipeline)image retrieval benchmark (global sfm, local sfm, pose
approximation)TutorialSee thekapture tutorialfor a short introduction
to:conversion toolsusing kapture in your codedataset downloadContributingThere are many ways to contribute to the kapture project:provide feedback and suggestions of improvementssubmit bug reports in the project bug trackerprovide a dataset in kapture format that we can add to the
downloader toolimplement a feature or bug-fix for an outstanding issueadd support of kapture format in other software packages (e.g. SfM
pipelines…​), thus adding support for more datasetsprovide scripts to create data in kapture format (e.g. local/global
feature extraction)propose a new feature and implement itIf you wish to contribute, please refer to theCONTRIBUTINGpage.LicenseSoftware license is detailed in theLICENSEfile.Contact UsYou can contact us throughGitHub,
or at kapture at naverlabs + com