Metadata-Version: 2.1
Name: kapture
Version: 0.0.10
Summary: kapture: file format for SfM
Home-page: UNKNOWN
Author: naverlabs
Author-email: kapture@naverlabs.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: numpy-quaternion
Requires-Dist: numba
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: Pillow
Requires-Dist: requests
Requires-Dist: pyyaml
Requires-Dist: wcmatch
Requires-Dist: torch (==1.4.0)
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'

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. 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  link:CONTRIBUTING.adoc[CONTRIBUTING] page.

== License
Software license is detailed in the link:LICENSE[LICENSE] file.



