kapture 0.0.9

kapture: file format for SfM

kapture: data format

Overview

Kapture 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: - cameras

• images - lidar and other sensor data

As well as computed data:

• 2d features

• 3d reconstruction

Specifications

The format specification is detailed in the kapture format specifications document.

Example File Structure

This 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
│  │  ├─ keypoints.txt              # type of keypoint
│  │  ├─ map/cam_01/00001.jpg.kpt   # keypoints for corresponding image (example)
│  │  ├─ query/query001.jpg.kpt     # keypoints for corresponding image (example)
│  │  ├─ ...
│  ├─ descriptors/                  # keypoint descriptors files
│  │  ├─ descriptors.txt            # type of descriptor
│  │  ├─ 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.
│  │  ├─ map/cam_01/00001.jpg.overlapping/cam_01/00002.jpg.matches # example
│  │  ├─ ...

Software

The kapture format is provided with a Python library, as well as several conversion tools.

install

using docker

Build the docker image:

build.

# build the docker image
docker build . -t kapture
# run unit tests
docker run -it --rm kapture python3 -m unittest discover -s /opt/kapture/tests

You can bind directories between the host and the container using --volume or --mount option in order to access to any files and directories on a host machine from the container. (See the docker documentation.)

run.

docker run -it \
    --rm \ # Automatically remove the container when it exits \
    --volume /path/to/dataset/:/dataset:ro \ #read only
    kapture

kapture library

kapture tools

In this repository, you will find several conversion tools to and from the kapture format. Depending on the tool, some data might not be converted. Here is a table summarizing the conversion capabilities:

to complete.

conversion capabilities

Format	← →	cam	rig	img	traj	kps	desc	gfeat	p3D	obs	mch
colmap	import	:ok:	:ok:	:ok:	:ok:	:ok:	:ok:	N.A.	:ok:	:ok:	partial
export	:ok:	:ok:	:ok:	:ok:	:ok:	:ok:	N.A.	:ok:	:ok:	partial
openmvg	import	:ok:	N.A.	:ok:	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
export	:ok:	N.A.	:ok:	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
bundler	import	:ok:	N.A.	:ok:	:ok:	:ok:	N.A.	N.A.	:ok:	:ok:	N.A.
image_folder	import	N.A.	N.A.	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
image_list	import	:ok:	N.A.	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
nvm	import	:ok:	N.A.	:ok:	:ok:	:ok:	N.A.	N.A.	:ok:	:ok:	N.A.
IDL_dataset_cvpr17	import	:ok:	N.A.	:ok:	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
RobotCar_Seasons	import	:ok:	:ok:	:ok:	:ok:	:ok:	:question:	N.A.	:ok:	:ok:	:question:
ROSbag cameras+trajectory	import	(N1)	(N1)	:ok:	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
SILDa	import	:ok:	:ok:	:ok:	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.
virtual_gallery	import	:ok:	No	:ok:	:ok:	N.A.	N.A.	N.A.	N.A.	N.A.	N.A.

• cams: handle camera parameters, eg. intrisics

• rig: handle rig structure.

• img: handle the path to images.

• traj: handle trajectories, eg. poses.

• kpt: handle image keypoints locations.

• decs: handle image keypoints descriptors.

• gfeat: handle global image feature descriptors.

• p3D: handle 3D point clouds.

• obs: handle observations, ie. 3D-points / 2D keypoints correspondences.

• mch: handle keypoints matches.

• note N1: the rig and camera(s) parameters for the corresponding capturing devices must be provided externally in kapture format containing the rigs and sensors files.

Contributing

If you wish to contribute, please refer to the CONTRIBUTING page.

License

Software license is detailed in the LICENSE file.