Metadata-Version: 2.1
Name: kapture
Version: 0.0.9
Summary: kapture: file format for SfM
Home-page: UNKNOWN
Author: naverlabs
Author-email: dl_kapture@naverlabs.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT 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

![KAPTURE](assets/kapture_logo.svg)

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](kapture_format.adoc).

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.

<table>
<caption>conversion capabilities</caption>
<colgroup>
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
</colgroup>
<thead>
<tr class="header">
<th>Format</th>
<th>← →</th>
<th>cam</th>
<th>rig</th>
<th>img</th>
<th>traj</th>
<th>kps</th>
<th>desc</th>
<th>gfeat</th>
<th>p3D</th>
<th>obs</th>
<th>mch</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>colmap</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>partial</p></td>
</tr>
<tr class="even">
<td><p>export</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>partial</p></td>
<td></td>
</tr>
<tr class="odd">
<td><p>openmvg</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="even">
<td><p>export</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td></td>
</tr>
<tr class="odd">
<td><p>bundler</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="even">
<td><p>image_folder</p></td>
<td><p>import</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="odd">
<td><p>image_list</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="even">
<td><p>nvm</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="odd">
<td><p>IDL_dataset_cvpr17</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="even">
<td><p>RobotCar_Seasons</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:question:</p></td>
<td><p>N.A.</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:question:</p></td>
</tr>
<tr class="odd">
<td><p>ROSbag cameras+trajectory</p></td>
<td><p>import</p></td>
<td><p>(N1)</p></td>
<td><p>(N1)</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="even">
<td><p>SILDa</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
<tr class="odd">
<td><p>virtual_gallery</p></td>
<td><p>import</p></td>
<td><p>:ok:</p></td>
<td><p>No</p></td>
<td><p>:ok:</p></td>
<td><p>:ok:</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
<td><p>N.A.</p></td>
</tr>
</tbody>
</table>

-   `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](CONTRIBUTING.adoc) page.

License
-------

Software license is detailed in the [LICENSE](LICENSE) file.


