kapture: file format for SfM
Project description
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.
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.
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.