kapture: file format for SfM
Project description
image::assets/kapture_logo.svg["KAPTURE", width=64px]
= kapture: data format :sectnums: :sectnumlevels: 1 :toc: :toclevels: 2
== 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 link:kapture_format.adoc[kapture format specifications document].
== Example File Structure
This is an example file structure of a dataset in the kapture format.
[source,txt]
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:
[source,bash] .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.)
[source,bash] .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:
WARNING: to complete.
.conversion capabilities |=== | Format | <- -> | cam | rig | img | traj | kps | desc | gfeat| p3D | obs | mch
.2+| 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
.2+| 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. |===
:Notes:
cams
: handle camera parameters, eg. intrisicsrig
: 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 link:CONTRIBUTING.adoc[CONTRIBUTING] page.
== License Software license is detailed in the link:LICENSE[LICENSE] file.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.